From 053d699d5c49d2767aad7cb5b65d665a20c62200 Mon Sep 17 00:00:00 2001 From: Soren Ptak Date: Sat, 2 Sep 2023 16:09:32 -0700 Subject: [PATCH] Update the README file --- README.md | 105 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 77 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index d6baf7e..12dc9b9 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,86 @@ ## coreSNTP Library -This repository contains the coreSNTP library, a client library to use Simple Network Time Protocol (SNTP) to synchronize device clocks with internet time. This library implements the SNTPv4 specification defined in [RFC 4330](https://tools.ietf.org/html/rfc4330). - -An SNTP client can request time from both NTP and SNTP servers. According to the SNTPv4 specification, "_To an NTP or SNTP server, NTP and SNTP clients are indistinguishable; to an NTP or SNTP client, NTP and SNTP servers are indistinguishable._", thereby, allowing SNTP clients to request time from NTP servers. - -This library has gone through code quality checks including verification that no function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8, and checks against deviations from mandatory rules in the [MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This library has also undergone both static code analysis from [Coverity static analysis](https://scan.coverity.com/), and validation of memory safety through the [CBMC automated reasoning tool](https://www.cprover.org/cbmc/). - -See memory requirements for this library [here](./docs/doxygen/include/size_table.md). - -**coreSNTP v1.2.0 [source code](https://github.com/FreeRTOS/coreSNTP/tree/v1.2.0/source) is part of the [FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) release.** +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreSNTP/)** + +This repository contains the coreSNTP library, a client library to use Simple +Network Time Protocol (SNTP) to synchronize device clocks with internet time. +This library implements the SNTPv4 specification defined in +[RFC 4330](https://tools.ietf.org/html/rfc4330). + +An SNTP client can request time from both NTP and SNTP servers. According to the +SNTPv4 specification, "_To an NTP or SNTP server, NTP and SNTP clients are +indistinguishable; to an NTP or SNTP client, NTP and SNTP servers are +indistinguishable._", thereby, allowing SNTP clients to request time from NTP +servers. + +This library has gone through code quality checks including verification that no +function has a +[GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) +score over 8, and checks against deviations from mandatory rules in the +[MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA +C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This +library has also undergone both static code analysis from +[Coverity static analysis](https://scan.coverity.com/), and validation of memory +safety through the +[CBMC automated reasoning tool](https://www.cprover.org/cbmc/). + +See memory requirements for this library +[here](./docs/doxygen/include/size_table.md). + +**coreSNTP v1.2.0 +[source code](https://github.com/FreeRTOS/coreSNTP/tree/v1.2.0/source) is part +of the +[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) +release.** ### Documentation -The API reference documentation for the coreSNTP library version released in [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) can be viewed from the [freertos.org website](https://freertos.org/coresntp/index.html). +The API reference documentation for the coreSNTP library version released in +[FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) can be viewed from the +[freertos.org website](https://freertos.org/coresntp/index.html). ## Cloning this repository -This repo uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring in dependent components. + +This repo uses +[Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring +in dependent components. To clone using HTTPS: + ``` git clone https://github.com/FreeRTOS/coreSNTP.git --recurse-submodules ``` + Using SSH: + ``` git clone git@github.com:FreeRTOS/coreSNTP.git --recurse-submodules ``` -If you have downloaded the repo without using the `--recurse-submodules` argument, you need to run: +If you have downloaded the repo without using the `--recurse-submodules` +argument, you need to run: + ``` git submodule update --init --recursive ``` ## Building the library -You can build the coreSNTP source files that are in the [source](source/) directory, and add [source/include](source/include) to your compiler's include path. +You can build the coreSNTP source files that are in the [source](source/) +directory, and add [source/include](source/include) to your compiler's include +path. -If using CMake, the [coreSntpFilePaths.cmake](coreSntpFilePaths.cmake) file contains the above information of the source files and the header include path from this repository. +If using CMake, the [coreSntpFilePaths.cmake](coreSntpFilePaths.cmake) file +contains the above information of the source files and the header include path +from this repository. ## Reference Example -A reference example of using the coreSNTP library can be viewed in the `FreeRTOS/FreeRTOS` repository [here](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator). -The demo application showcases use of the library in order to create an SNTP client for periodic time synchronization of the system clock. +A reference example of using the coreSNTP library can be viewed in the +`FreeRTOS/FreeRTOS` repository +[here](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator). +The demo application showcases use of the library in order to create an SNTP +client for periodic time synchronization of the system clock. ## Building Unit Tests @@ -48,7 +88,9 @@ The unit tests for the library use CMock/Unity unit testing framework. ### Checkout CMock Submodule -To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule: +To build unit tests, the submodule dependency of CMock is required. Use the +following command to clone the submodule: + ``` git submodule update --checkout --init --recursive test/unit-test/CMock ``` @@ -56,16 +98,19 @@ git submodule update --checkout --init --recursive test/unit-test/CMock ### Unit Test Platform Prerequisites - For running unit tests - - **C90 compiler** like gcc - - **CMake 3.13.0 or later** - - **Ruby 2.0.0 or later** is additionally required for the CMock test framework (that we use). -- For running the coverage target, **gcov** and **lcov** are additionally required. + - **C90 compiler** like gcc + - **CMake 3.13.0 or later** + - **Ruby 2.0.0 or later** is additionally required for the CMock test + framework (that we use). +- For running the coverage target, **gcov** and **lcov** are additionally + required. ### Steps to build **Unit Tests** -1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule)) +1. Go to the root directory of this repository. (Make sure that the **CMock** + submodule is cloned as described [above](#checkout-cmock-submodule)) -1. Run the *cmake* command: `cmake -S test -B build -DBUILD_UNIT_TESTS=ON` +1. Run the _cmake_ command: `cmake -S test -B build -DBUILD_UNIT_TESTS=ON` 1. Run this command to build the library and unit tests: `make -C build all` @@ -73,19 +118,22 @@ git submodule update --checkout --init --recursive test/unit-test/CMock 1. Run `cd build && ctest` to execute all tests and view the test run summary. - ## CBMC proofs -To learn more about CBMC and proofs specifically, review the training material [here](https://model-checking.github.io/cbmc-training). +To learn more about CBMC and proofs specifically, review the training material +[here](https://model-checking.github.io/cbmc-training). The `test/cbmc/proofs` directory contains CBMC proofs. -In order to run these proofs you will need to install CBMC and other tools by following the instructions [here](https://model-checking.github.io/cbmc-training/installation.html). +In order to run these proofs you will need to install CBMC and other tools by +following the instructions +[here](https://model-checking.github.io/cbmc-training/installation.html). ## Generating documentation The Doxygen references were created using Doxygen version 1.9.2. To generate the -Doxygen pages, please run the following command from the root of this repository: +Doxygen pages, please run the following command from the root of this +repository: ```shell doxygen docs/doxygen/config.doxyfile @@ -93,7 +141,8 @@ doxygen docs/doxygen/config.doxyfile ## Contributing -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on +contributing. ## License