diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt new file mode 100644 index 0000000..e670988 --- /dev/null +++ b/.github/.cSpellWords.txt @@ -0,0 +1,28 @@ +CBMC +CMAC +CMOCK +CMock +CRYP +Cbmc +Cmock +Coverity +DCMOCK +DNDEBUG +MISRA +Misra +RSTR +SNTP +Sntp +TRNG +cbmc +converttounixtime +coverity +ctest +fracs +lcov +lums +misra +sinclude +sntp +utest +xlarge diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 078b33d..a28d886 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,7 +10,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build Library in Debug mode run: | cmake -S test -B build/ \ @@ -29,7 +29,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build Code Example used in Doxygen run: | cmake -S test -B Build -DBUILD_CODE_EXAMPLE=ON @@ -38,7 +38,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build Library and Unit Tests with Sanitizer run: | CFLAGS="-O0 -Wall -Wexta -Werror" @@ -67,7 +67,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build run: | sudo apt-get install -y lcov sed @@ -92,39 +92,42 @@ jobs: - name: Check Coverage uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main with: - path: ./build/coverage.info + coverage-file: ./build/coverage.info complexity: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check complexity uses: FreeRTOS/CI-CD-Github-Actions/complexity@main with: path: ./ + spell-check: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Run spellings check uses: FreeRTOS/CI-CD-Github-Actions/spellings@main with: path: ./ + formatting: - runs-on: ubuntu-latest + runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check formatting uses: FreeRTOS/CI-CD-Github-Actions/formatting@main with: path: ./ exclude-dirs: .git + git-secrets: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Checkout awslabs/git-secrets - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: awslabs/git-secrets ref: master @@ -135,26 +138,34 @@ jobs: run: | git-secrets --register-aws git-secrets --scan + link-verifier: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: Setup Python for link verifier action - uses: actions/setup-python@v2 - with: - python-version: '3.8' + - uses: actions/checkout@v3 - name: Check Links env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - uses: FreeRTOS/CI-CD-GitHub-Actions/link-verifier@main + uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main + + verify-manifest: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + - name: Run manifest verifier + uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@main with: path: ./ - exclude-dirs: cbmc - include-file-types: .c,.h,.dox + fail-on-incorrect-version: true + doxygen: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Run doxygen build uses: FreeRTOS/CI-CD-Github-Actions/doxygen@main with: @@ -162,17 +173,18 @@ jobs: memory_statistics: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Install Python3 - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: - python-version: '3.7.x' + python-version: "3.7.x" - name: Measure sizes uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main with: - config: .github/memory_statistics_config.json - check_against: docs/doxygen/include/size_table.md + config: .github/memory_statistics_config.json + check_against: docs/doxygen/include/size_table.md proof_ci: + if: ${{ github.event.pull_request }} runs-on: cbmc_ubuntu-latest_16-core steps: - name: Set up CBMC runner diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 0000000..8257add --- /dev/null +++ b/.github/workflows/formatting.yml @@ -0,0 +1,23 @@ +name: Format Pull Request Files + +on: + issue_comment: + types: [created] + +env: + bashPass: \033[32;1mPASSED - + bashInfo: \033[33;1mINFO - + bashFail: \033[31;1mFAILED - + bashEnd: \033[0m + +jobs: + Formatting: + name: Run Formatting Check + if: ${{ github.event.issue.pull_request }} && + ( ( github.event.comment.body == '/bot run uncrustify' ) || + ( github.event.comment.body == '/bot run formatting' ) ) + runs-on: ubuntu-20.04 + steps: + - name: Apply Formatting Fix + uses: FreeRTOS/CI-CD-Github-Actions/formatting-bot@main + id: check-formatting diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index eeead2e..c33fb1c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,7 +22,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Check if tag exists run: | git fetch origin @@ -49,7 +49,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} - name: Configure git identity @@ -87,7 +87,7 @@ jobs: - name: Install ZIP tools run: sudo apt-get install zip unzip - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} path: coreSNTP 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 diff --git a/cspell.config.yaml b/cspell.config.yaml new file mode 100644 index 0000000..911ce1d --- /dev/null +++ b/cspell.config.yaml @@ -0,0 +1,31 @@ +--- +$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json +version: '0.2' +# Allows things like stringLength +allowCompoundWords: true + +# Read files not to spell check from the git ignore +useGitignore: true + +# Language settings for C +languageSettings: + - caseSensitive: false + enabled: true + languageId: c + locale: "*" + +# Add a dictionary, and the path to the word list +dictionaryDefinitions: + - name: freertos-words + path: '.github/.cSpellWords.txt' + addWords: true + +dictionaries: + - freertos-words + +# Paths and files to ignore +ignorePaths: + - 'dependency' + - 'docs' + - 'ThirdParty' + - 'History.txt' diff --git a/lexicon.txt b/lexicon.txt deleted file mode 100644 index 8d9e2a1..0000000 --- a/lexicon.txt +++ /dev/null @@ -1,262 +0,0 @@ -actualabsdiff -aes -alarmservernotsynchronized -api -apis -ascii -auth -authcodesize -authintf -aws -backoff -beforelooptime -blocktimems -br -buffersize -bytesorerror -bytesremaining -bytessent -bytestorecv -bytestorecv -bytestosend -bytestosend -cbmc -clienttime -clienttimesec -clienttxtime -clockfreqtolerance -clockoffsetms -cmac -com -config -configpagestyle -configs -const -copydoc -coresntp -coverity -css -currenttimelist -de -deamon -december -defgroup -deserialization -deserialize -deserializer -deserializeresponse -deserializing -desiredaccuracy -diff -dns -doxygen -endcode -endian -endif -enum -expectedbytestosend -expectedinterval -expectedtxtime -faqs -feb -firstorderdiff -fracs -fracsinnetorder -fracsinnetorder -freertos -gcc -getsystemtimefunc -getsystemtimefunc -gettimefunc -github -gov -hsm -html -htonl -https -ietf -ifdef -ifndef -inc -ingroup -inlooptime -int -iot -ip -iso -jan -january -june -kod -lastrequesttime -leapsecondinfo -leapversionmode -logdebug -logerror -loginfo -logwarn -lsb -mainpage -md -mdash -misra -mit -mtu -networkcontext -networkinterfacereceivestub -networkinterfacesendstub -nist -noleapsecond -noninfringement -ntp -ntpv -numofservers -oldertime -org -origintime -overflown -packetsize -param -pauthcodesize -pauthcodesize -pauthintf -pauthintf -pbuffer -pclientrxtime -pclienttime -pclienttxtime -pclockoffset -pcontext -pcurrenttime -phasresponsetimedout -pkcs -pml -pnetworkbuffer -pnetworkbuffer -pnetworkcontext -pnetworkcontext -pnetworkintf -png -poldertime -positivediff -posix -ppacket -pparsedresponse -ppm -ppollinterval -preadstarttime -prequestpacket -prequesttime -prequesttxtime -presponsebuffer -presponsecode -presponsedata -presponsepacket -presponserxtime -printf -pserveraddr -pservername -pserverrxtime -pservertime -pservertxtime -psntptime -ptime -ptimeserver -ptimeservers -ptr -ptransportintf -pudptransportintf -punixtimemicrosecs -punixtimesecs -pusercontext -pwordmemory -randomnum -randomnumber -receivetime -recv -recvfrom -refid -reftime -rejectedresponsecode -resolvednsfunc -responsesize -responsetimeoutms -retryable -rfc -rootdelay -rootdisp -rootdispersion -rstr -rx -sdk -secsinnetorder -secsinnetorder -sendsntppacket -sendto -serializerequest -serveraddr -servernamelen -serverport -serverresponsetimeoutms -servertime -servertimesec -servertxtime -setsystemtimeatindex -setsystemtimefunc -signedfirstorderdiffrecv -signedfirstorderdiffsend -sizeof -sntp -sntpauthcontext -sntpbuffertoosmall -sntpclockoffsetoverflow -sntperrorautherror -sntperrorauthfailure -sntperrorbadparameter -sntperrorbuffertoosmall -sntperrorchangeserver -sntperrorcontextnotinitialized -sntperrordnsfailure -sntperrornetworkfailure -sntperrorresponsetimeout -sntperrorsendtimeout -sntperrortimenotsupported -sntpinvalidresponse -sntpnoresponse -sntpnoresponsereceived -sntppacketsize -sntprejectedresponse -sntprejectedresponsechangeserver -sntprejectedresponseothercode -sntprejectedresponseretrywithbackoff -sntpservernotauthenticated -sntpsuccess -sntptimestamp -sntpv -sntpzeropollinterval -spdx -startingpos -startingpos -struct -sublicense -testbuffer -testclockoffsetcalculation -timebeforeloop -timediffsec -timeoutms -timeserver -transmittime -trng -tx -typename -udp -udprecvretcodes -udpsendretcodes -uint -unix -utc -validateserverauth -wordmemory -wordval -www -xffff diff --git a/test/cbmc/proofs/Sntp_CalculatePollInterval/README.md b/test/cbmc/proofs/Sntp_CalculatePollInterval/README.md index 287de56..0487840 100644 --- a/test/cbmc/proofs/Sntp_CalculatePollInterval/README.md +++ b/test/cbmc/proofs/Sntp_CalculatePollInterval/README.md @@ -14,7 +14,7 @@ To run the proof. * Run `make`. * Open html/index.html in a web browser. -To use [`arpa`](https://github.com/awslabs/aws-proof-build-assistant) to simplify writing Makefiles. +To use [`arpa`](https://awslabs.github.io/aws-proof-build-assistant) to simplify writing Makefiles. ------------- * Run `make arpa` to generate a Makefile.arpa that contains relevant build information for the proof. diff --git a/test/cbmc/proofs/Sntp_ConvertToUnixTime/README.md b/test/cbmc/proofs/Sntp_ConvertToUnixTime/README.md index 3bf0834..9c887c2 100644 --- a/test/cbmc/proofs/Sntp_ConvertToUnixTime/README.md +++ b/test/cbmc/proofs/Sntp_ConvertToUnixTime/README.md @@ -14,7 +14,7 @@ To run the proof. * Run `make`. * Open html/index.html in a web browser. -To use [`arpa`](https://github.com/awslabs/aws-proof-build-assistant) to simplify writing Makefiles. +To use [`arpa`](https://awslabs.github.io/aws-proof-build-assistant) to simplify writing Makefiles. ------------- * Run `make arpa` to generate a Makefile.arpa that contains relevant build information for the proof. diff --git a/test/cbmc/proofs/Sntp_DeserializeResponse/README.md b/test/cbmc/proofs/Sntp_DeserializeResponse/README.md index c6ac66c..10c3038 100644 --- a/test/cbmc/proofs/Sntp_DeserializeResponse/README.md +++ b/test/cbmc/proofs/Sntp_DeserializeResponse/README.md @@ -11,7 +11,7 @@ To run the proof. * Run `make`. * Open html/index.html in a web browser. -To use [`arpa`](https://github.com/awslabs/aws-proof-build-assistant) to simplify writing Makefiles. +To use [`arpa`](https://awslabs.github.io/aws-proof-build-assistant) to simplify writing Makefiles. ------------- * Run `make arpa` to generate a Makefile.arpa that contains relevant build information for the proof. diff --git a/test/cbmc/proofs/Sntp_ReceiveTimeResponse/README.md b/test/cbmc/proofs/Sntp_ReceiveTimeResponse/README.md index 5d6e85d..229e4f6 100644 --- a/test/cbmc/proofs/Sntp_ReceiveTimeResponse/README.md +++ b/test/cbmc/proofs/Sntp_ReceiveTimeResponse/README.md @@ -11,7 +11,7 @@ To run the proof. * Run `make`. * Open html/index.html in a web browser. -To use [`arpa`](https://github.com/awslabs/aws-proof-build-assistant) to simplify writing Makefiles. +To use [`arpa`](https://awslabs.github.io/aws-proof-build-assistant) to simplify writing Makefiles. ------------- * Run `make arpa` to generate a Makefile.arpa that contains relevant build information for the proof. diff --git a/test/cbmc/proofs/Sntp_SerializeRequest/README.md b/test/cbmc/proofs/Sntp_SerializeRequest/README.md index 0a5122e..8e3991f 100644 --- a/test/cbmc/proofs/Sntp_SerializeRequest/README.md +++ b/test/cbmc/proofs/Sntp_SerializeRequest/README.md @@ -14,7 +14,7 @@ To run the proof. * Run `make`. * Open html/index.html in a web browser. -To use [`arpa`](https://github.com/awslabs/aws-proof-build-assistant) to simplify writing Makefiles. +To use [`arpa`](https://awslabs.github.io/aws-proof-build-assistant) to simplify writing Makefiles. ------------- * Run `make arpa` to generate a Makefile.arpa that contains relevant build information for the proof.