diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt new file mode 100644 index 00000000..295e25d6 --- /dev/null +++ b/.github/.cSpellWords.txt @@ -0,0 +1,26 @@ +CBMC +CBOR +CMOCK +CMock +Cmock +Coverity +DNDEBUG +DUNITY +EFFF +MISRA +MQTT +Misra +Wunused +cbmc +cbor +cmock +coverity +ctest +dfcc +isystem +lcov +misra +searcht +sinclude +strn +utest diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 580d44b2..e39af014 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 run: | sudo apt-get install -y lcov sed @@ -34,46 +34,51 @@ 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: ./ + 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: 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-20.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check formatting uses: FreeRTOS/CI-CD-Github-Actions/formatting@main with: path: ./ + 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 @@ -84,11 +89,12 @@ jobs: run: | git-secrets --register-aws git-secrets --scan + custom-standard-c-headers: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build run: | mkdir -p override-include @@ -99,22 +105,50 @@ jobs: -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='-Wall -Wextra -I../override-include' make -C build/ coverity_analysis + memory_statistics: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: - submodules: 'recursive' + submodules: "recursive" - name: Install Python3 - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: - python-version: '3.11.0' + python-version: "3.11.0" - 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 + + link-verifier: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Check Links + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main + with: + path: ./ + + 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: ./ + fail-on-incorrect-version: true + proof_ci: + if: ${{ github.event.pull_request }} runs-on: cbmc_ubuntu-latest_64-core steps: - name: Set up CBMC runner diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 00000000..8257adda --- /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 131ef47b..9c812304 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -16,7 +16,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 @@ -53,7 +53,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: coreJSON diff --git a/MISRA.md b/MISRA.md index f186e515..3e54faa1 100644 --- a/MISRA.md +++ b/MISRA.md @@ -26,6 +26,6 @@ _Ref 14.3.1_ - MISRA C-2012 Rule 14.3 False positive as the static analysis tool believes i can never be larger than SIZE_MAX - HEX_ESCAPE_LENGTH. This can be proven as a bug by setting i to be 18446744073709551615UL at initial assignment, then require - start != NULL before assigning the vaue of i to start. This creates a case + start != NULL before assigning the value of i to start. This creates a case where i should be large enough to hit the else statement, but the tool still flags this as invariant. diff --git a/README.md b/README.md index b299c764..196fe5ef 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,37 @@ ## coreJSON Library -This repository contains the coreJSON library, a parser that strictly enforces the ECMA-404 JSON standard and is suitable for low memory footprint embedded devices. The coreJSON library is distributed under the [MIT Open Source License](LICENSE). - -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). - -**coreJSON v3.2.0 [source code](https://github.com/FreeRTOS/coreJSON/tree/v3.2.0/source) is part of the [FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) release.** - -**coreJSON v3.0.0 [source code](https://github.com/FreeRTOS/coreJSON/tree/v3.0.0/source) is part of the [FreeRTOS 202012.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.00-LTS) release.** +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreJSON/)** + +This repository contains the coreJSON library, a parser that strictly enforces +the ECMA-404 JSON standard and is suitable for low memory footprint embedded +devices. The coreJSON library is distributed under the +[MIT Open Source License](LICENSE). + +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). + +**coreJSON v3.2.0 +[source code](https://github.com/FreeRTOS/coreJSON/tree/v3.2.0/source) is part +of the +[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) +release.** + +**coreJSON v3.0.0 +[source code](https://github.com/FreeRTOS/coreJSON/tree/v3.0.0/source) is part +of the +[FreeRTOS 202012.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.00-LTS) +release.** ## Reference example @@ -26,16 +49,16 @@ int main() size_t queryKeyLength = sizeof( queryKey ) - 1; char * value; size_t valueLength; - + // Calling JSON_Validate() is not necessary if the document is guaranteed to be valid. result = JSON_Validate( buffer, bufferLength ); - + if( result == JSONSuccess ) { result = JSON_Search( buffer, bufferLength, queryKey, queryKeyLength, &value, &valueLength ); } - + if( result == JSONSuccess ) { // The pointer "value" will point to a location in the "buffer". @@ -51,21 +74,34 @@ int main() return 0; } ``` -A search may descend through nested objects when the `queryKey` contains matching key strings joined by a separator, `.`. In the example above, `bar` has the value `{"foo":"xyz"}`. Therefore, a search for query key `bar.foo` would output `xyz`. + +A search may descend through nested objects when the `queryKey` contains +matching key strings joined by a separator, `.`. In the example above, `bar` has +the value `{"foo":"xyz"}`. Therefore, a search for query key `bar.foo` would +output `xyz`. ## Building coreJSON -A compiler that supports **C90 or later** such as *gcc* is required to build the library. +A compiler that supports **C90 or later** such as _gcc_ is required to build the +library. + +Additionally, the library uses 2 header files introduced in ISO C99, `stdbool.h` +and `stdint.h`. For compilers that do not provide this header file, the +[source/include](source/include) directory contains +[stdbool.readme](source/include/stdbool.readme) and +[stdint.readme](source/include/stdint.readme), which can be renamed to +`stdbool.h` and `stdint.h` respectively. -Additionally, the library uses 2 header files introduced in ISO C99, `stdbool.h` and `stdint.h`. For compilers that do not provide this header file, the [source/include](source/include) directory contains [stdbool.readme](source/include/stdbool.readme) and [stdint.readme](source/include/stdint.readme), which can be renamed to `stdbool.h` and `stdint.h` respectively. +For instance, if the example above is copied to a file named `example.c`, _gcc_ +can be used like so: -For instance, if the example above is copied to a file named `example.c`, *gcc* can be used like so: ```bash gcc -I source/include example.c source/core_json.c -o example ./example ``` -*gcc* can also produce an output file to be linked: +_gcc_ can also produce an output file to be linked: + ```bash gcc -I source/include -c source/core_json.c ``` @@ -73,19 +109,23 @@ gcc -I source/include -c source/core_json.c ## Documentation ### Existing documentation -For pre-generated documentation, please see the documentation linked in the locations below: -| Location | -| :-: | +For pre-generated documentation, please see the documentation linked in the +locations below: + +| Location | +| :------------------------------------------------------------------------------------------------------------------: | | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) | -| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreJSON/docs/doxygen/output/html/index.html) | +| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreJSON/docs/doxygen/output/html/index.html) | -Note that the latest included version of the coreJSON library may differ across repositories. +Note that the latest included version of the coreJSON library may differ across +repositories. ### 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 @@ -94,9 +134,16 @@ doxygen docs/doxygen/config.doxyfile ## Building unit tests ### Checkout Unity Submodule -By default, the submodules in this repository are configured with `update=none` in [.gitmodules](.gitmodules), to avoid increasing clone time and disk space usage of other repositories (like [amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this repository). -To build unit tests, the submodule dependency of Unity is required. Use the following command to clone the submodule: +By default, the submodules in this repository are configured with `update=none` +in [.gitmodules](.gitmodules), to avoid increasing clone time and disk space +usage of other repositories (like +[amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this +repository). + +To build unit tests, the submodule dependency of Unity is required. Use the +following command to clone the submodule: + ``` git submodule update --checkout --init --recursive test/unit-test/Unity ``` @@ -104,18 +151,20 @@ git submodule update --checkout --init --recursive test/unit-test/Unity ### 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 Unity test framework (that we use). + - C90 compiler like gcc + - CMake 3.13.0 or later + - Ruby 2.0.0 or later is additionally required for the Unity test framework + (that we use). - For running the coverage target, gcov is additionally required. ### Steps to build Unit Tests -1. Go to the root directory of this repository. (Make sure that the **Unity** submodule is cloned as described [above](#checkout-unity-submodule).) +1. Go to the root directory of this repository. (Make sure that the **Unity** + submodule is cloned as described [above](#checkout-unity-submodule).) 1. Create build directory: `mkdir build && cd build` -1. Run *cmake* while inside build directory: `cmake -S ../test` +1. Run _cmake_ while inside build directory: `cmake -S ../test` 1. Run this command to build the library and unit tests: `make all` @@ -125,12 +174,16 @@ git submodule update --checkout --init --recursive test/unit-test/Unity ## CBMC -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). ## Contributing -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on +contributing. diff --git a/cspell.config.yaml b/cspell.config.yaml new file mode 100644 index 00000000..911ce1d8 --- /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 76e9d349..00000000 --- a/lexicon.txt +++ /dev/null @@ -1,128 +0,0 @@ -abc -api -arraysearch -ascii -bf -bmp -br -buf -bufferlength -cbmc -colspan -com -cond -const -copydoc -corejson -coverity -dbff -dc -defgroup -df -dfff -diffblue -ecma -ef -endcode -endcond -endif -enum -enums -fb -fc -fd -fe -ff -ffff -freertos -foo -gcc -github -html -https -ifndef -inc -ingroup -int -io -iot -iso -json -jsonarray -jsonbadparameter -jsonfalse -jsonillegaldocument -jsoninvalid -jsonmaxdepthexceeded -jsonnotfound -jsonnull -jsonnullparameter -jsonnumber -jsonobject -jsonpartial -jsonstatus -jsonstring -jsonsuccess -jsontrue -jsontype -keylength -len -longjmp -mainpage -md -microcontrollers -min -misra -mit -msb -multibyte -nb -nextkeyvaluepair -noninfringement -nul -objectsearch -os -outkey -outkeylength -outlength -outpair -outtype -outvalue -outvaluelength -param -printf -queryindex -querylength -requirelowsurrogate -rm -sizeof -skipanyliteral -skiparrayscalars -skipcollection -skipdecimals -skipdigits -skipescape -skipexponent -skipgeneric -skiphexescape -skipnumber -skipobjectscalars -skipspace -skipspaceandcomma -skipstring -skiputf -spdx -stderr -struct -sublicense -td -toolchain -tr -uint -unescaped -unicode -unwindings -utf -valuelength -xxxxxx -xyz