|
1 | 1 | ## coreSNTP Library
|
2 | 2 |
|
3 |
| -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). |
4 |
| - |
5 |
| -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. |
6 |
| - |
7 |
| -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/). |
8 |
| - |
9 |
| -See memory requirements for this library [here](./docs/doxygen/include/size_table.md). |
10 |
| - |
11 |
| -**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.** |
| 3 | +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreSNTP/)** |
| 4 | + |
| 5 | +This repository contains the coreSNTP library, a client library to use Simple |
| 6 | +Network Time Protocol (SNTP) to synchronize device clocks with internet time. |
| 7 | +This library implements the SNTPv4 specification defined in |
| 8 | +[RFC 4330](https://tools.ietf.org/html/rfc4330). |
| 9 | + |
| 10 | +An SNTP client can request time from both NTP and SNTP servers. According to the |
| 11 | +SNTPv4 specification, "_To an NTP or SNTP server, NTP and SNTP clients are |
| 12 | +indistinguishable; to an NTP or SNTP client, NTP and SNTP servers are |
| 13 | +indistinguishable._", thereby, allowing SNTP clients to request time from NTP |
| 14 | +servers. |
| 15 | + |
| 16 | +This library has gone through code quality checks including verification that no |
| 17 | +function has a |
| 18 | +[GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) |
| 19 | +score over 8, and checks against deviations from mandatory rules in the |
| 20 | +[MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA |
| 21 | +C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This |
| 22 | +library has also undergone both static code analysis from |
| 23 | +[Coverity static analysis](https://scan.coverity.com/), and validation of memory |
| 24 | +safety through the |
| 25 | +[CBMC automated reasoning tool](https://www.cprover.org/cbmc/). |
| 26 | + |
| 27 | +See memory requirements for this library |
| 28 | +[here](./docs/doxygen/include/size_table.md). |
| 29 | + |
| 30 | +**coreSNTP v1.2.0 |
| 31 | +[source code](https://github.com/FreeRTOS/coreSNTP/tree/v1.2.0/source) is part |
| 32 | +of the |
| 33 | +[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) |
| 34 | +release.** |
12 | 35 |
|
13 | 36 | ### Documentation
|
14 | 37 |
|
15 |
| -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). |
| 38 | +The API reference documentation for the coreSNTP library version released in |
| 39 | +[FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) can be viewed from the |
| 40 | +[freertos.org website](https://freertos.org/coresntp/index.html). |
16 | 41 |
|
17 | 42 | ## Cloning this repository
|
18 |
| -This repo uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring in dependent components. |
| 43 | + |
| 44 | +This repo uses |
| 45 | +[Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring |
| 46 | +in dependent components. |
19 | 47 |
|
20 | 48 | To clone using HTTPS:
|
| 49 | + |
21 | 50 | ```
|
22 | 51 | git clone https://github.com/FreeRTOS/coreSNTP.git --recurse-submodules
|
23 | 52 | ```
|
| 53 | + |
24 | 54 | Using SSH:
|
| 55 | + |
25 | 56 | ```
|
26 | 57 | git clone [email protected]:FreeRTOS/coreSNTP.git --recurse-submodules
|
27 | 58 | ```
|
28 | 59 |
|
29 |
| -If you have downloaded the repo without using the `--recurse-submodules` argument, you need to run: |
| 60 | +If you have downloaded the repo without using the `--recurse-submodules` |
| 61 | +argument, you need to run: |
| 62 | + |
30 | 63 | ```
|
31 | 64 | git submodule update --init --recursive
|
32 | 65 | ```
|
33 | 66 |
|
34 | 67 | ## Building the library
|
35 | 68 |
|
36 |
| -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. |
| 69 | +You can build the coreSNTP source files that are in the [source](source/) |
| 70 | +directory, and add [source/include](source/include) to your compiler's include |
| 71 | +path. |
37 | 72 |
|
38 |
| -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. |
| 73 | +If using CMake, the [coreSntpFilePaths.cmake](coreSntpFilePaths.cmake) file |
| 74 | +contains the above information of the source files and the header include path |
| 75 | +from this repository. |
39 | 76 |
|
40 | 77 | ## Reference Example
|
41 | 78 |
|
42 |
| -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). |
43 |
| -The demo application showcases use of the library in order to create an SNTP client for periodic time synchronization of the system clock. |
| 79 | +A reference example of using the coreSNTP library can be viewed in the |
| 80 | +`FreeRTOS/FreeRTOS` repository |
| 81 | +[here](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator). |
| 82 | +The demo application showcases use of the library in order to create an SNTP |
| 83 | +client for periodic time synchronization of the system clock. |
44 | 84 |
|
45 | 85 | ## Building Unit Tests
|
46 | 86 |
|
47 | 87 | The unit tests for the library use CMock/Unity unit testing framework.
|
48 | 88 |
|
49 | 89 | ### Checkout CMock Submodule
|
50 | 90 |
|
51 |
| -To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule: |
| 91 | +To build unit tests, the submodule dependency of CMock is required. Use the |
| 92 | +following command to clone the submodule: |
| 93 | + |
52 | 94 | ```
|
53 | 95 | git submodule update --checkout --init --recursive test/unit-test/CMock
|
54 | 96 | ```
|
55 | 97 |
|
56 | 98 | ### Unit Test Platform Prerequisites
|
57 | 99 |
|
58 | 100 | - For running unit tests
|
59 |
| - - **C90 compiler** like gcc |
60 |
| - - **CMake 3.13.0 or later** |
61 |
| - - **Ruby 2.0.0 or later** is additionally required for the CMock test framework (that we use). |
62 |
| -- For running the coverage target, **gcov** and **lcov** are additionally required. |
| 101 | + - **C90 compiler** like gcc |
| 102 | + - **CMake 3.13.0 or later** |
| 103 | + - **Ruby 2.0.0 or later** is additionally required for the CMock test |
| 104 | + framework (that we use). |
| 105 | +- For running the coverage target, **gcov** and **lcov** are additionally |
| 106 | + required. |
63 | 107 |
|
64 | 108 | ### Steps to build **Unit Tests**
|
65 | 109 |
|
66 |
| -1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule)) |
| 110 | +1. Go to the root directory of this repository. (Make sure that the **CMock** |
| 111 | + submodule is cloned as described [above](#checkout-cmock-submodule)) |
67 | 112 |
|
68 |
| -1. Run the *cmake* command: `cmake -S test -B build -DBUILD_UNIT_TESTS=ON` |
| 113 | +1. Run the _cmake_ command: `cmake -S test -B build -DBUILD_UNIT_TESTS=ON` |
69 | 114 |
|
70 | 115 | 1. Run this command to build the library and unit tests: `make -C build all`
|
71 | 116 |
|
72 | 117 | 1. The generated test executables will be present in `build/bin/tests` folder.
|
73 | 118 |
|
74 | 119 | 1. Run `cd build && ctest` to execute all tests and view the test run summary.
|
75 | 120 |
|
76 |
| - |
77 | 121 | ## CBMC proofs
|
78 | 122 |
|
79 |
| -To learn more about CBMC and proofs specifically, review the training material [here](https://model-checking.github.io/cbmc-training). |
| 123 | +To learn more about CBMC and proofs specifically, review the training material |
| 124 | +[here](https://model-checking.github.io/cbmc-training). |
80 | 125 |
|
81 | 126 | The `test/cbmc/proofs` directory contains CBMC proofs.
|
82 | 127 |
|
83 |
| -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). |
| 128 | +In order to run these proofs you will need to install CBMC and other tools by |
| 129 | +following the instructions |
| 130 | +[here](https://model-checking.github.io/cbmc-training/installation.html). |
84 | 131 |
|
85 | 132 | ## Generating documentation
|
86 | 133 |
|
87 | 134 | The Doxygen references were created using Doxygen version 1.9.2. To generate the
|
88 |
| -Doxygen pages, please run the following command from the root of this repository: |
| 135 | +Doxygen pages, please run the following command from the root of this |
| 136 | +repository: |
89 | 137 |
|
90 | 138 | ```shell
|
91 | 139 | doxygen docs/doxygen/config.doxyfile
|
92 | 140 | ```
|
93 | 141 |
|
94 | 142 | ## Contributing
|
95 | 143 |
|
96 |
| -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. |
| 144 | +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on |
| 145 | +contributing. |
97 | 146 |
|
98 | 147 | ## License
|
99 | 148 |
|
|
0 commit comments