diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 00000000000..e3aa3770aba --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,143 @@ +name: Build & Deploy Docs + +# Controls when the workflow will run +on: + push: + branches: [ "release" ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v3 + + - name: Setup Python + uses: actions/setup-python@v2.3.3 + with: + cache: pip + + - name: Install mkdocs + run: pip install mkdocs + + - name: Doxygen (MAX32520) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32520_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32650) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32650_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32655) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32655_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32660) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32660_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32665) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32665_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32670) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32670_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32672) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32672_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32675) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32675_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX32680) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max32680_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX78000) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max78000_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Doxygen (MAX78002) + uses: mattnotmitt/doxygen-action@1.9.4 + with: + # Path to Doxyfile + doxyfile-path: max78002_Doxyfile + # Working directory + working-directory: Libraries/PeriphDrivers/Documentation + + - name: Build User Guide + run: | # Build Documentation Folder and run mkdocs + SOURCE=Libraries/PeriphDrivers/Documentation + DEST=Documentation/$SOURCE + + echo "Copying Periph Driver APIs..." + mkdir -p $DEST/MAX32520 && cp -r $SOURCE/MAX32520 $DEST/ + mkdir -p $DEST/MAX32650 && cp -r $SOURCE/MAX32650 $DEST/ + mkdir -p $DEST/MAX32655 && cp -r $SOURCE/MAX32655 $DEST/ + mkdir -p $DEST/MAX32660 && cp -r $SOURCE/MAX32660 $DEST/ + mkdir -p $DEST/MAX32665 && cp -r $SOURCE/MAX32665 $DEST/ + mkdir -p $DEST/MAX32670 && cp -r $SOURCE/MAX32670 $DEST/ + mkdir -p $DEST/MAX32672 && cp -r $SOURCE/MAX32672 $DEST/ + mkdir -p $DEST/MAX32675 && cp -r $SOURCE/MAX32675 $DEST/ + mkdir -p $DEST/MAX32680 && cp -r $SOURCE/MAX32680 $DEST/ + mkdir -p $DEST/MAX78000 && cp -r $SOURCE/MAX78000 $DEST/ + mkdir -p $DEST/MAX78002 && cp -r $SOURCE/MAX78002 $DEST/ + + echo "Copying any root markdown files into Documentation..." + cp -r *.md Documentation/ + + mkdocs build + + - name: Publish + uses: JamesIves/github-pages-deploy-action@v4.3.0 + with: + branch: gh-pages # The branch the action should deploy to. + folder: docs # Deploy the built docs folder diff --git a/.gitignore b/.gitignore index 54f5c0f2f36..280a6f1a901 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,9 @@ Examples/*/*/*/buildrv .vscode/settings.json Libraries/PeriphDrivers/bin/MAX78000/softfp/libPeriphDriver_softfp.a Libraries/PeriphDrivers/bin/MAX78000/softfp_riscv/libPeriphDriver_softfp.a +Libraries/PeriphDrivers/Documentation/MAX* +docs +Documentation/Libraries Examples/MAX78000/PowerTest __pycache__ msdk-internal @@ -14,6 +17,7 @@ Tools/GNUTools Tools/OpenOCD Tools/xPack Tools/OpenOCD +Tools/MSYS2 *.o *.d /**/make.log diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e04c3d51c24..00000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,241 +0,0 @@ -# Analog Devices MSDK Development and Contribution Guidelines - -## Development Flow - -Development for the MSDK also follows the official [GitHub development flow guidelines](https://docs.github.com/en/get-started/quickstart/github-flow). - -For beginners, [learngitbranching.js.org](https://learngitbranching.js.org/) is a great hands-on starting resource. - -## Contribution Guidelines - -The MSDK follows the [GitHub contribution guidelines](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). - -External contributions from outside the [Analog Devices organization](https://github.com/Analog-Devices-MSDK) should be made via a Pull Request opened from a fork. Internal contributions should also preferrably use a fork where possible. - -If a direct branch on the mainline MSDK repo is made, the following branch naming conventions should be used when possible: - -* Bugfix/ticket: `fix/branchname` - * For Jira tickets, it's recommended to use `fix/ticketnumber` so that the branch gets automatically tracked. Ex: `fix/MSDK-670` -* New feature: `feature/branchname` -* Generic development branch: `dev/branchname` -* New and/or modified example branch: `example/branchname` - -## Style Guide - -The MSDK code-base, for the most-part, follows the [Linux Kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html#linux-kernel-coding-style) _and_ [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with the following exception(s): - -* Indentations are 4 spaces. - -Formatting and styling is enforced via [clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) **version 14** and [cpplint](https://github.com/cpplint/cpplint), which automatically run checks against all PRs. A PR cannot be merged until it passes these checks. - -### Running the Linter & Formatter - -Both utilities can be run locally. cpplint should be run first, then clang-format. Additionally, both should be run from the root directory of the MSDK repo so that their config files are loaded properly. - -clang-format rules are loaded from [.clang-format](.clang-format) and cpplint rules are loaded from [CPPLINT.cfg](CPPLINT.cfg). - -#### cpplint - -[cpplint](https://github.com/cpplint/cpplint) enforces good code practices by scanning for common mistakes and ensuring certain higher-level code patterns are followed. It's a good idea to resolve the errors found by cpplint before before running clang-format, which deals with lower-level code styling and syntax patterns. - -1. `cd` into the root directory of the MSDK repo. - -2. Run cpplint. - - To run cpplint on a **file**, use `cpplint `. - - ```shell - $ cpplint Examples/MAX78000/Hello_World/main.c - Done processing Examples/MAX78000/Hello_World/main.c - ``` - - To recursively run cpplint on an **entire directory**, use `cpplint --recursive `. - - ```shell - $ cpplint --recursive Examples/MAX78000 - - Examples/MAX78000/ADC/example_config.h:1: #ifndef header guard has wrong style, please use: EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_ [build/header_guard] [5] - Examples/MAX78000/ADC/example_config.h:14: #endif line should be "#endif // EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_" [build/header_guard] [5] - Done processing Examples/MAX78000/ADC/example_config.h - Done processing Examples/MAX78000/ADC/main.c - Done processing Examples/MAX78000/AES/main.c - Done processing Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c - ... - ``` - -3. Resolve any errors. - -4. `git add` and `git commit` any changes to your code. - -#### clang-format - -[clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) is a code formatter and style checker that enforces a common style for the code-base. -**The MSDK uses version 14**, which is sometimes not available by default on some Linux distributions. It can be retrieved from [https://apt.llvm.org/](https://apt.llvm.org/). - -1. `cd` into the root directory of the MSDK repo. - -2. Run clang-format. - - The `--style=file --Werror --verbose` options are shared across all runs. - - To run a clang-format _check_ on a file, use the `-n` "dry-run" flag. - - `clang-format-14 --style=file --Werror --verbose -n ` - - For example: - - ```shell - $ clang-format-14 --style=file --Werror --verbose -n Examples/MAX78000/CRC/main.c - - Formatting [1/1] Examples/MAX78000/CRC/main.c - Examples/MAX78000/CRC/main.c:86:40: error: code should be clang-formatted [-Wclang-format-violations] - for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } - ^ - ``` - - To _apply_ the formatter to automatically format a file, use the `-i` flag. - - `clang-format-14 --style=file --Werror --verbose -i ` - - For example: - - ```shell - clang-format-14 --style=file --verbose -i Examples/MAX78000/CRC/main.c - Formatting [1/1] Examples/MAX78000/CRC/main.c - ``` - - This will apply the formatter and overwrite the file. Check the formatter's work using `git diff`. - - ```diff - diff --git a/Examples/MAX78000/CRC/main.c b/Examples/MAX78000/CRC/main.c - index 1dda1feed..c16ceb962 100644 - --- a/Examples/MAX78000/CRC/main.c - +++ b/Examples/MAX78000/CRC/main.c - @@ -83,7 +83,9 @@ void Test_CRC(int asynchronous) - - printf(asynchronous ? "TEST CRC ASYNC\n" : "TEST CRC SYNC\n"); - - - for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } - + for (i = 0; i < DATA_LENGTH; i++) { - + array[i] = i; - + } - ``` - - To apply the formatter to multiple files, the `*` and `**` wildcard characters can be used. `*` matches any file or folder, and `**` _recursively_ matches any file or folder. - - To recursively run clang-format on all C files in an entire directory, use: - - `clang-format-14 --style=file --verbose -n /**/*.c`. - - For example: - - ```shell - $ clang-format-14 --style=file --verbose -i Examples/MAX78000/ARM-DSP/**/*.c - - Formatting [1/24] Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c - Formatting [2/24] Examples/MAX78000/ARM-DSP/arm_class_marks_example/arm_class_marks_example_f32.c - Formatting [3/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/arm_convolution_example_f32.c - Formatting [4/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/math_helper.c - Formatting [5/24] Examples/MAX78000/ARM-DSP/arm_dotproduct_example_f32/arm_dotproduct_example_f32.c - ... - ``` - - ... which runs the formatter for all C files in the `Examples/MAX78000/ARM-DSP` directory _and all its subdirectories_. It should be noted that `**` is not supported on native Windows, but `*` is. - -4. `git add` and `git commit` any changes to your code. Now, it's ready for a PR! The same checks will be automatically run against any PRs that are opened in the MSDK, and they must pass before the code can be approved. - -## Examples - -### Updating and Adding Examples - -1. First, ensure that the example project has been linted and formatted to follow the [Style Guide](#style-guide) - -2. Copy the example project into the [Examples](https://github.com/Analog-Devices-MSDK/msdk/tree/main/Examples) folder of the SDK for the applicable target microcontrollers. - -3. `git add` and `git commit` the Example project. Use a commit message such as "Add xxx Example" - -4. Run the [MSDKGen](https://github.com/Analog-Devices-MSDK/MSDKGen) utility to ensure the example project's support files are updated to the latest version. - - If you are coming from the **_legacy_ Makefile system** (no project.mk) it's best to migrate the old Makefile in its own commit... - - 1. Generate the new Makefile first using the `--no-vscode`, `--no-eclipse`, and `--backup` options. Ex: - - ```shell - python msdkgen.py update-all --projects yourprojectname --no-vscode --no-eclipse --overwrite --backup - ``` - - 2. A project.mk file will be added, and the old Makefile will be replaced but _backed up_ to a file called `Makefile-backup.mk`. - - 3. Migrate any project-specific build settings to project.mk. Documentation on the project.mk system can be found [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop). - - 4. `git add` and `git commit` the new Makefile and project.mk files. Delete the backup file. - - 5. Run a full `update-all`, which will then update the VSCode and Eclipse files as well. - - Otherwise, if the project is already running a [project.mk](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) file then a full `update-all` command can be used. - - Ex: - - ```shell - python msdkgen.py update-all --projects yourprojectname --overwrite - ``` - -5. If the updated files break any projects they can be restored to the previously working version using the `git restore` command. - - For example, the command below will restore all files in your current working directory. - - ```shell - git restore ** - ``` - - The `git diff` command can also be used to inspect local changes to help identify the root cause. Ex: - - ```shell - git diff ./ - ``` - - If MSDKGen breaks a previously working project _that has already been migrated to the project.mk build system_ please report it to the [MSDKGen Issue Tracker](https://github.com/Analog-Devices-MSDK/MSDKGen/issues) - -## Libraries - -Libraries should be added to the [Libraries](Libraries) sub-folder of the MSDK. - -* All libraries should include a `libraryname.mk` file that can be added to [libs.mk](Libraries/libs.mk) via a toggle-switch. The filename should match the name of library as closely as possible, and expose any required [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration). - -* If necessary, a library may also include a "core" Makefile or set of Makefiles to build it as a standalone static library file. The naming convention is `lib.a`. - -### Self-Locating Makefile - -The first thing that the `libraryname.mk` file should do is locate its own directory and store it in a variable. The code snippet can be used to achieve this. - -```Makefile -ifeq "$(LIBRARYNAME_DIR)" "" -# If LIBRARYNAME_DIR is not specified, this Makefile will locate itself. -LIBRARYNAME_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) -endif -``` - -All filepaths for the library should then use this `$(LIBRARYNAME_DIR)`-type variable as their "root" for all filepaths. This is a safe and reliable way to self-reference internal library files. - -For an example, see the [periphdriver.mk](Libraries/PeriphDrivers/periphdriver.mk) file. - -### Simple Libraries - -For simple libraries, it may be sufficient to just add the library's source files to the build using `VPATH` and `IPATH`. - -For example: - -```Makefile -IPATH += $(LIBRARY_NAME_DIR)/include -VPATH += $(LIBRARY_NAME_DIR)/src -SRCS += libfile1.c -SRCS += libfile2.c -``` - -An example of this is [MiscDrivers](Libraries/MiscDrivers/), which is a simple source-file-only library. It gets its source code selectively added to the build via [board.mk](Libraries/Boards/MAX78000/EvKit_V1/board.mk) files. - -### Advanced Libraries - -More advanced libraries (including those with a large number of source files) should include a rule to build as a static library file with a [recursive Make call](https://www.gnu.org/software/make/manual/make.html#Recursion). - -This type of library should also set up the appropriate [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) to include that static library to the build. diff --git a/Documentation/CONTRIBUTING.md b/Documentation/CONTRIBUTING.md new file mode 100644 index 00000000000..78962fa7dfe --- /dev/null +++ b/Documentation/CONTRIBUTING.md @@ -0,0 +1,245 @@ +# Analog Devices MSDK Development and Contribution Guidelines + +## Development Flow + +Development for the MSDK also follows the official [GitHub development flow guidelines](https://docs.github.com/en/get-started/quickstart/github-flow). + +For beginners, [learngitbranching.js.org](https://learngitbranching.js.org/) is a great hands-on starting resource. + +## Contribution Guidelines + +The MSDK follows the [GitHub contribution guidelines](https://docs.github.com/en/get-started/quickstart/contributing-to-projects). + +External contributions from outside the [Analog Devices organization](https://github.com/Analog-Devices-MSDK) should be made via a Pull Request opened from a fork. Internal contributions should also preferrably use a fork where possible. + +If a direct branch on the mainline MSDK repo is made, the following branch naming conventions should be used when possible: + +- Bugfix/ticket: `fix/ticketnumber` +- New feature: `feature/branchname` +- Generic development branch: `dev/branchname` +- New and/or modified example branch: `example/branchname` + +## Style Guide + +The MSDK code-base, for the most-part, follows the [Linux Kernel coding style](https://www.kernel.org/doc/html/v4.10/process/coding-style.html#linux-kernel-coding-style) _and_ [Google's C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with the following exception(s): + +- Indentations are 4 spaces. + +Formatting and styling is enforced via [clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) **version 14** and [cpplint](https://github.com/cpplint/cpplint), which automatically run checks against all PRs. A PR cannot be merged until it passes these checks. + +### Running the Linter & Formatter + +Both utilities can be run locally. cpplint should be run first, then clang-format. Additionally, both should be run from the root directory of the MSDK repo so that their config files are loaded properly. + +clang-format rules are loaded from the **.clang-format** and cpplint rules are loaded from **CPPLINT.cfg** in the root directory of the repo. As a result, the utilities must also be run from the root directory of the repo. + +#### cpplint + +[cpplint](https://github.com/cpplint/cpplint) enforces good code practices by scanning for common mistakes and ensuring certain higher-level code patterns are followed. It's a good idea to resolve the errors found by cpplint before before running clang-format, which deals with lower-level code styling and syntax patterns. + +1. `cd` into the root directory of the MSDK repo. + +2. Run cpplint. + + To run cpplint on a **file**, use `cpplint `. + + $ cpplint Examples/MAX78000/Hello_World/main.c + Done processing Examples/MAX78000/Hello_World/main.c + + To recursively run cpplint on an **entire directory**, use `cpplint --recursive `. + + $ cpplint --recursive Examples/MAX78000 + + Examples/MAX78000/ADC/example_config.h:1: #ifndef header guard has wrong style, please use: EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_ [build/header_guard] [5] + Examples/MAX78000/ADC/example_config.h:14: #endif line should be "#endif // EXAMPLES_MAX78000_ADC_EXAMPLE_CONFIG_H_" [build/header_guard] [5] + Done processing Examples/MAX78000/ADC/example_config.h + Done processing Examples/MAX78000/ADC/main.c + Done processing Examples/MAX78000/AES/main.c + Done processing Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c + ... + +3. Resolve any errors. + +4. `git add` and `git commit` any changes to your code. + +#### clang-format + +[clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) is a code formatter and style checker that enforces a common style for the code-base. +**The MSDK uses version 14**, which is sometimes not available by default on some Linux distributions. It can be retrieved from [https://apt.llvm.org/](https://apt.llvm.org/). + +1. `cd` into the root directory of the MSDK repo. + +2. Run clang-format. + + To run a clang-format **_check_** on a file, use the `-n` "dry-run" flag. + + `clang-format-14 --style=file --Werror --verbose -n ` + + For example: + + $ clang-format-14 --style=file --Werror --verbose -n Examples/MAX78000/CRC/main.c + + Formatting [1/1] Examples/MAX78000/CRC/main.c + Examples/MAX78000/CRC/main.c:86:40: error: code should be clang-formatted [-Wclang-format-violations] + for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } + ^ + + To _apply_ the formatter to automatically format a file, use the `-i` flag. + + `clang-format-14 --style=file --Werror --verbose -i ` + + For example: + + $ clang-format-14 --style=file --verbose -i Examples/MAX78000/CRC/main.c + Formatting [1/1] Examples/MAX78000/CRC/main.c + + This will apply the formatter and overwrite the file. Check the formatter's work using `git diff`. + + :::diff + $ diff --git a/Examples/MAX78000/CRC/main.c b/Examples/MAX78000/CRC/main.c + index 1dda1feed..c16ceb962 100644 + --- a/Examples/MAX78000/CRC/main.c + +++ b/Examples/MAX78000/CRC/main.c + @@ -83,7 +83,9 @@ void Test_CRC(int asynchronous) + + printf(asynchronous ? "TEST CRC ASYNC\n" : "TEST CRC SYNC\n"); + + - for (i = 0; i < DATA_LENGTH; i++) { array[i] = i; } + + for (i = 0; i < DATA_LENGTH; i++) { + + array[i] = i; + + } + + To apply the formatter to multiple files, the `*` and `**` wildcard characters can be used. `*` matches any file or folder, and `**` _recursively_ matches any file or folder. + + To recursively run clang-format on all C files in an entire directory, use: + + `clang-format-14 --style=file --verbose -n /**/*.c`. + + For example: + + $ clang-format-14 --style=file --verbose -i Examples/MAX78000/ARM-DSP/**/*.c + + Formatting [1/24] Examples/MAX78000/ARM-DSP/arm_bayes_example/arm_bayes_example_f32.c + Formatting [2/24] Examples/MAX78000/ARM-DSP/arm_class_marks_example/arm_class_marks_example_f32.c + Formatting [3/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/arm_convolution_example_f32.c + Formatting [4/24] Examples/MAX78000/ARM-DSP/arm_convolution_example/math_helper.c + Formatting [5/24] Examples/MAX78000/ARM-DSP/arm_dotproduct_example_f32/arm_dotproduct_example_f32.c + ... + + ... which runs the formatter for all C files in the `Examples/MAX78000/ARM-DSP` directory _and all its subdirectories_. It should be noted that `**` is not supported on native Windows, but `*` is. + +3. `git add` and `git commit` any changes to your code. Now, it's ready for a PR! The same checks will be automatically run against any PRs that are opened in the MSDK, and they must pass before the code can be approved. + +## Contributing Examples + +1. First, ensure that the example project has been linted and formatted to follow the [Style Guide](#style-guide) + +2. Copy the example project into the [Examples](https://github.com/Analog-Devices-MSDK/msdk/tree/main/Examples) folder of the SDK for the applicable target microcontrollers. + +3. `git add` and `git commit` the Example project. **Commit your project files before running MSDKGen.** + +4. Run the [MSDKGen](https://github.com/Analog-Devices-MSDK/MSDKGen) utility to ensure the example project's support files are updated to the latest version. + + python msdkgen.py update-all --projects yourprojectname --overwrite + +5. Re-test the project if applicable. + +6. If the updated files break any projects they can be restored to the previously working version using the `git restore` command. + + For example, the command below will restore all files in your current working directory. + + git restore ** + + The `git diff` command can also be used to inspect local changes to help identify the root cause. Ex: + + git diff ./ + +## Contributing Libraries + +Libraries should be added to the [Libraries](Libraries) sub-folder of the MSDK. + +- All libraries should include a `libraryname.mk` file that can be added to `Libraries/libs.mk` via a toggle-switch. The filename should match the name of library as closely as possible, and expose any required [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration). + +- If necessary, a library may also include a "core" Makefile or set of Makefiles to build it as a standalone static library file. The naming convention is `lib.a`. + +### Self-Locating Makefile + +The first thing that the `libraryname.mk` file should do is locate its own directory and store it in a variable. The code snippet can be used to achieve this. + + :::Makefile + ifeq "$(LIBRARYNAME_DIR)" "" + # If LIBRARYNAME_DIR is not specified, this Makefile will locate itself. + LIBRARYNAME_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST)))) + endif + +All filepaths for the library should then use this `$(LIBRARYNAME_DIR)`-type variable as their "root" for all filepaths. This is a safe and reliable way to self-reference internal library files. + +For an example, see the `Libraries/PeriphDrivers/periphdriver.mk` file. + +### Simple Libraries + +For simple libraries, it may be sufficient to just add the library's source files to the build using `VPATH` and `IPATH`. + +For example: + + :::Makefile + IPATH += $(LIBRARY_NAME_DIR)/include + VPATH += $(LIBRARY_NAME_DIR)/src + SRCS += libfile1.c + SRCS += libfile2.c + +An example of this is [MiscDrivers](Libraries/MiscDrivers/), which is a simple source-file-only library. It gets its source code selectively added to the build via `Libraries/Boards/MAX78000/EvKit_V1/board.mk` files. + +### Advanced Libraries + +More advanced libraries (including those with a large number of source files) should include a rule to build as a static library file with a [recursive Make call](https://www.gnu.org/software/make/manual/make.html#Recursion). + +This type of library should also set up the appropriate [configuration variables](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) to include that static library to the build. + +## Contributing Documentation + +### Code Maintainers + +MSDK code should be documented using Doxygen syntax on all public functions, data structures, and variables. See the [**DoxyGen Manual**](https://www.doxygen.nl/manual/docblocks.html) for more details on syntax for C-like languages. + +DoxyGen is automatically run across the MSDK code as part of the User Guide's build process. A Peripheral API reference is generated for each target microcontroller using the Doxygen files located in `Libraries/PeriphDrivers/Documentation`, and the output is packaged as a sub-component of the User Guide when it's built. For code maintainers no action is needed other than maintaining up to date Doxygen documentation for all source code. + +### User Guide + +An MSDK User Guide is maintained in the [USERUIDE.md](USERGUIDE.md) file. This document contains higher-level usage info for the MSDK. If a part, IDE, or library is supported by the MSDK then there should be some relevant info in the User Guide covering its setup, configuration, and usage. + +When writing markdown links, relative paths should always be used. Additionally, links to local files on the user's filesystem **cannot** be used, since the online copy of the docs will throw a 404 on them. See [Writing Your Docs](https://www.mkdocs.org/user-guide/writing-your-docs/) for more details. + +Static resources such as images should be placed in the `res` folder. + +### Building the Documentation + +#### Local Builds + +The `Documentation/build.py` script can be used to build the MSDK User Guide and supporting documentation locally. This script: + +- Builds all the Peripheral API references using Doxygen and copies them into `Documentation` +- Copies any markdown files in the root of the repo into the `Documentation` folder. +- Copies the `res` (resources) folder into `Documentation` +- Builds the MSDK User Guide using [Mkdocs](https://www.mkdocs.org/), which packages everything in `Documentation` into a static HTML/CSS/JavaScript site. + +To **build** the docs: + +1. Install Python 3 +2. `pip install -r Documentation/requirements.txt` +3. `python Documentation/build.py` +4. The site will be built in the `docs` folder of the repo. + +To **preview** the generated site: + +`mkdocs serve` + +This will open a localhost test server with live re-loading. + +To **configure** the generated site, use `mkdocs.yml`. See [Mkdocs Configuration](https://www.mkdocs.org/user-guide/configuration/) for more details. + +#### Auto Builds and Deployment + +The **"Build & Deploy Docs"** Github Action will perform all the local steps above. Additionally, it will deploy the static site to the `gh-pages` branch of the repository for use with [Github Pages](https://pages.github.com/). When the `gh-pages` branch is updated, Pages will refresh the online copy of the documentation within ~5-10 mins. + +This auto-deploy procedure is triggered on every push to the `release` branch. diff --git a/Documentation/USERGUIDE.md b/Documentation/USERGUIDE.md new file mode 100644 index 00000000000..956289166ca --- /dev/null +++ b/Documentation/USERGUIDE.md @@ -0,0 +1,1619 @@ +# Analog Devices MSDK User Guide + +[TOC] + +## Overview + +The Maxim Microcontrollers SDK (MSDK), now a part of [Analog Devices](https://www.analog.com/en/index.html), contains the necessary software and tools to develop firmware for the [MAX32xxx and MAX78xxx Microcontrollers](https://www.analog.com/en/parametricsearch/10984). That includes register files and system startup files to enable low-level development for its [supported parts](#supported-parts). It also provides higher level peripheral driver APIs (written in C) alongside various utilities, third-party libraries, Board Support Packages (BSPs) and a set of example programs for each microcontroller. + +Additionally, a GCC-based toolchain is included and builds are managed by a system of Makefiles (See [GNU Make](https://www.gnu.org/software/make/manual/)). Flashing and debugging are enabled by a [custom fork of OpenOCD](https://github.com/Analog-Devices-MSDK/openocd). The MSDK's toolchain and build system offers a Command Line Interface (CLI), and project files for [supported development environments](#supported-development-environments) are maintained that build on top of that CLI. + +This document describes the MSDK's installation, setup, and usage. + +### Supported Operating Systems + +- Windows (Windows 10 only) + +- Linux (Ubuntu only) + +- MacOS + +### Supported Parts + +The following microcontrollers and evaluation platforms are officially supported by the MSDK. + +* [**MAX32520**](https://www.analog.com/en/products/max32520.html): ChipDNA Secure Microcontroller with Secure Boot for IoT Applications + + - [MAX32520-KIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32520-kit.html) + + - [MAX32520FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32520fthr.html) + + +--- + +* [**MAX32570**](https://www.analog.com/en/products/max32570.html): Low-Power Arm Cortex-M4 Microcontroller with Contactless Radio for Secure Applications **(Available by NDA only**) + + - [MAX32570-QNKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32570-qnkit.html) + + - [MAX32570-MNKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32570-mnkit.html) + + +--- + +* [**MAX32650**](https://www.analog.com/en/products/max32650.html): Ultra-Low-Power Arm Cortex-M4 with FPU-Based Microcontroller (MCU) with 3MB Flash and 1MB SRAM + + - [MAX32650-EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32650-evkit.html) + + - [MAX32650FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32650fthr.html) + + +--- + +* [**MAX32655**](https://www.analog.com/en/products/max32655.html): Low-Power, Arm Cortex-M4 Processor with FPU-Based Microcontroller and Bluetooth 5.2 + + - [MAX32655EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32655evkit.html) + + - [MAX32655FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32655fthr.html) + + +--- + +* [**MAX32660**](https://www.analog.com/en/products/max32660.html): Tiny, Ultra-Low-Power Arm Cortex-M4 Processor with FPU-Based Microcontroller (MCU) with 256KB Flash and 96KB SRAM + + - [MAX32660-EVSYS](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32660-evsys.html) + + +--- + +* **MAX32662** **(Not Yet Publicly Available)** + - MAX32662EVKIT **(Not Yet Publicly Available)** + + +--- + +* [**MAX32665-MAX32668 Family**](https://www.analog.com/en/products/max32665.html): Low-Power ARM Cortex-M4 with FPU-Based Microcontroller with Bluetooth 5 for Wearables + + - [MAX32666EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32666evkit.html) + + - [MAX32666FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32666fthr.html) + + - MAX32666FTHR2 (Product Page Not Yet Available) + + +--- + +* [**MAX32670**](https://www.analog.com/en/products/max32670.html): High-Reliability, Ultra-Low-Power Microcontroller Powered by Arm Cortex-M4 Processor with FPU for Industrial and IoT + + - [MAX32670EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32670evkit.html) + + +--- + +* [**MAX32672**](https://www.analog.com/en/products/max32672.html): High-Reliability, Tiny, Ultra-Low-Power Arm Cortex-M4F Microcontroller with 12-Bit 1MSPS ADC + + - [MAX32672EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32672evkit.html) + + +--- + +* [**MAX32675**](https://www.analog.com/en/products/max32675.html): Ultra-Low-Power Arm Cortex-M4F with Precision Analog Front-End for Industrial and Medical Sensors + + - [MAX32675EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32675evkit.html) + + - MAX32675FTHR (Product Page Not Yet Available) + + +--- + +* [**MAX32680**](https://www.analog.com/en/products/max32680.html): Ultra-Low-Power Arm Cortex-M4F with Precision Analog Front-End and Bluetooth LE 5.2 + + - [MAX32680EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32680evkit.html) + + +--- + +* MAX32690 **(Not Yet Publicly Available)** + - MAX32690EVKIT **(Not Yet Publicly Available)** + + +--- + +* [**MAX78000**](https://www.analog.com/en/products/max78000.html): Artificial Intelligence Microcontroller with Ultra-Low-Power Convolutional Neural Network Accelerator + + - [MAX78000EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000evkit.html) + + - [MAX78000FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000fthr.html) + + - [MAXREFDES178](https://www.analog.com/en/design-center/reference-designs/maxrefdes178.html) + + +--- + +* [**MAX78002**](https://www.analog.com/en/products/max78002.html): Artificial Intelligence Microcontroller with Low-Power Convolutional Neural Network Accelerator + + - [MAX78002EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78002evkit.html) + + +--- + +### Supported Development Environments + +- Visual Studio Code +- Eclipse +- IAR +- Keil +- Command-line Development + - Supported shells (Windows): + - [MSYS2](https://www.msys2.org/) + + - Supported shells (Ubuntu & MacOS): + - [Bash](https://tiswww.case.edu/php/chet/bash/bashtop.html) + - [Zsh](https://www.zsh.org/) + +### Supported Languages + +- C +- Assembly (ARM and/or RISC-V instruction set depending on microcontroller) + +## Installation + +### Prerequisites + +- Administrator rights +- (On MacOS) - [Homebrew](https://brew.sh/) + +### Download + +The MSDK installer is available for supported Operating Systems via the links below. + +- [Windows 10](https://www.analog.com/en/design-center/evaluation-hardware-and-software/software/software-download.html?swpart=sfw0010820a) + +- [Linux (Ubuntu)](https://www.analog.com/en/design-center/evaluation-hardware-and-software/software/software-download.html?swpart=sfw0018720a) + + - This file must be made executable before it can be run (`chmod +x MaximMicrosSDK_linux.run`). Alternatively, set `Allow executing as program” in the Ubuntu GUI. + + ![Figure 1](res/Fig1.jpg) + +- [MacOS](https://www.analog.com/en/design-center/evaluation-hardware-and-software/software/software-download.html?swpart=sfw0018610a) + + - On MacOS the installer is distributed inside of a .dmg disk image file. Double click the downloaded file to mount it. Afterwards, the installer executable will be made available inside the mounted drive. + +### Setup + +1. [Download](#download) the installer executable to an accessible location and launch it. + +2. Click **Next** to proceed from the Welcome screen. + +3. Choose the installation location. By default, the MSDK will install to the `MaximSDK` folder off of the root of your filesystem. It's recommended to install to the default location. + + ![Figure 2](res/Fig2.jpg) + +4. Select the components to install. It's recommended to install all components. + + ![Figure 3](res/Fig3.jpg) + +5. Continue to the installation page, and click **install** to begin. Installation can be safely cancelled at any time. + + ![Figure 6](res/Fig6.jpg) + + ![Figure 7](res/Fig7.jpg) + +6. Click Finish to complete the installation. + + ![Figure 8](res/Fig8.jpg) + +7. You should now see the contents of the installation directory populated with the MSDK. + **Note:** On MacOS, some [additional steps](#completing-the-installation-on-macos) are required. + + ![Figure 10](res/Fig10.jpg) + +#### Completing the Installation on MacOS + +On MacOS, some additional missing packages must be manually installed via [Homebrew](https://brew.sh/). + +**For non-M1 platforms:** + +1. Follow the instructions on the [Homebrew home page](https://brew.sh/) to install Homebrew on your system. + +2. Then, open a terminal and run the command... + + brew install libusb-compat libftdi hidapi libusb + +**For M1 platforms**: + +The MSDK's OpenOCD binaries ship pre-compiled for Intel Silicon (i386). As a result, you should use a [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) terminal on M1 platforms to install the _i386 version_ of Homebrew and retrieve OpenOCD's dependencies with it. This ensures OpenOCD gets the packages with the architecture it needs. From there, Rosetta will handle the rest and allow running the binaries on the M1 platform's arm64 architecture. + +The i386 version of Homebrew can be installed in parallel with the arm64 version, and typically installs into a separate filesystem. + +1. Open a terminal and update Rosetta. + + softwareupdate --install-rosetta --agree-to-license + +2. Close the terminal. + +3. Run a new terminal in Rosetta: + + 1. Go to Finder > Applications and find your Terminal + + 2. Right-Click Terminal and Duplicate it. Rename it to "Terminal i386". + + 3. Rich-Click "Terminal i386" > Get Info > Enable "Open using Rosetta" + + 4. Launch the new "Terminal i386" and type `arch` to verify that it says `i386` now. + +4. From your Rosetta terminal follow the instructions on the [Homebrew home page](https://brew.sh/) to install Homebrew on your system. + +5. Verify the correct version of Homebrew is running from your Rosetta terminal using the `which brew` command. This should return a path beginning with `/usr/local`. + + **Note:** On systems with multiple or pre-existing Homebrew installations, the arm64 version of Homebrew may still take precendence over the newly installed x86_64 version. If `which brew` contains `/opt/homebrew` instead, you may need to edit your terminal profile's startup script. Alternatively, you can run the correct Homebrew binary directly using its absolute path. + +6. Run the command... + + :::bash + brew install libusb-compat libftdi hidapi libusb + + (or, if you need to use the absolute path) + + :::shell + /usr/local/homebrew/bin/brew install libusb-compat libftdi hidapi libusb + +### Maintenance + +An MSDK installation contains a `MaintenanceTool` executable program in the root directory. This program can be used to retrieve updates, manage components, and uninstall the MSDK. + +![Figure 11](res/Fig11.jpg) + +#### Updates + +MSDK updates are typically released on a quarterly basis, and the Maintenance Tool will retrieve the latest release when **Update components** is run. + +#### Development Resources + +Development copies of the MSDK resources can be obtained via [Github](https://github.com/Analog-Devices-MSDK/msdk), and instructions on how to work from the development repository can be found in the repository's [README](https://github.com/Analog-Devices-MSDK/msdk/blob/main/README.md). + +#### Older Versions and Offline Installer + +Older versions of the MSDK are available as an **_offline installer_** for each release tag. They are available on the [Releases page](https://github.com/Analog-Devices-MSDK/msdk/releases) of the MSDK Github and can be used to roll back to a specific MSDK release. + +## Getting Started + +The MSDK is designed for both evaluation and end-application development. The typical **evaluation** cycle usually involves setting up the development environment, running demos, and exercising the peripheral driver API on an _evaluation platform_. The typical **development** cycle typically involves building a prototype application on an _evaluation platform_ first, then porting the application to a custom board. This section describes how to get started with the MSDK focusing on the _evaluation_ cycle. + +**First**, review the [Key Concepts](#key-concepts) below. Then, proceed to the section for your preferred IDE. Each of these sub-sections is written as a self-contained quick-start with links to additional documentation on important topics. + +- [Getting Started with Visual Studio Code](#getting-started-with-visual-studio-code) +- [Getting Started with Eclipse](#getting-started-with-eclipse) +- [Getting Started with Command-Line Development](#getting-started-with-command-line-development) + +### Key Concepts + +The MSDK offers support for multiple development environments to support the user's preference. Regardless of which is used, there are a few key concepts to keep in mind. + +- **Target Microcontroller**: The _target microcontroller_ refers to the base part number of the microcontroller being used for development. The MSDK contains register-level support and startup files for each of its [supported parts](#supported-parts), and it's important to note that support files for a target microcontroller and its _Board Support Packages_ are distinct from each other. + + For example, if the [MAX78000EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000evkit.html) _or_ [MAX78000FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000fthr.html) is being used, the _Target Microcontroller_ is the MAX78000. + +- **Board Support Package (BSP)**: The MSDK supports evaluation platforms for target microcontrollers via _Board Support Packages_. For microcontrollers with multiple evaluation platforms, multiple BSPs are available. These can be found in the `Libraries/Boards` folder of the MSDK installation. + + By default, most projects in the MSDK come pre-configured for the "EVKIT"-type BSP, which is generally the largest "traditional" evaluation platform for that device. It's important to note that the active BSP may need to be reconfigured for a project, and this is done slightly differently for each development environment. This is covered in more detail below. + +- **System Environment**: Your system's _environment_ is a broad term that encapsulates the programs and variables that are available to your system's shell on the command-line. It's expected that the user has some basic familiarity with this concept. + +- **System Path**: Your system's _Path_ is a special environment variable that tells it where to search for program binaries. It's also expected that the user has some familiarity with this concept, and how to modify the system Path if necessary. + +- **Build Configuration vs Project Configuration**: An MSDK project is primarily made up of two complementary systems: The _Build System_ and the _Project Management System_. These systems each offer their own configuration interfaces, and it's important to note what each is used for. + + The **Build System** manages the compilation of source code into program binaries and offers a **Command-Line Interface (CLI)** for setting **Build Configuration Variables**. + + The **Project Management System** offers a higher level user interface (typically with a GUI) to manage the tools for **editing** source code, **flashing** program binaries, and **debugging** them on hardware. The Project Management System sits _on top_ of the build system's _CLI_ and uses it to manage fundamental aspects of the build such as: + + - Setting the _Target Microcontroller_ + - Setting the _Board Support Package_ + - Configuring the _Environment_ and _System Path_ for use with the MSDK toolchain + +- **Integrated Development Environment (IDE)**: An IDE combines the _Build System_ and _Project Management_ systems and typically features a Graphical User Interface (GUI) and other development features. The abbreviation is used frequently in the document. + +### Getting Started with Visual Studio Code + +The MSDK includes Visual Studio Code (“VS Code”) support via the [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim) project. + +This section walks through setup, opening, and running an example project with VS Code. This material is also available in video form targeting the MAX78000 in ["Understanding Artificial Intelligence Episode 8.5 - Visual Studio Code"](https://www.analog.com/en/education/education-library/videos/6313212752112.html). For full documentation, see the [Visual Studio Code](#visual-studio-code) section of this User Guide. + +#### Setup (VS Code) + +The setup below only needs to be done once per MSDK [installation](#installation). + +1. Download & install Visual Studio Code for your OS [here](https://code.visualstudio.com/Download). + +2. Launch Visual Studio Code. + +3. Install the Microsoft [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + +4. Use **`CTRL + SHIFT + P`** (or **`COMMAND + SHIFT + P`** on MacOS) to open the developer prompt. + +5. Type "open settings json" and select the **"Preferences: Open Settings (JSON)"** option. + + ![Open Settings JSON Command](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/open_settings_json.jpg) + +6. Add the entries below into your user settings.json file. + + :::json + // There may be other settings up here... + + "MAXIM_PATH":"C:/MaximSDK", // Set this to the installed location of the MaximSDK. Only use forward slashes '/' when setting this path! + "update.mode": "manual", + "extensions.autoUpdate": false, + + // There may be other settings down here... + +7. Save your changes to the file with **`CTRL + S`** and restart VS Code. + +#### Opening Example Projects + +Visual Studio Code is built around a "working directory" paradigm. The editor is always rooted in a working directory, and the main mechanism for changing that directory is **File -> Open Folder...** + +![File -> Open Folder](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/file_openfolder.JPG) + +As a result, you'll notice that there is no "New Project" mechanism. A "project" in VS Code is simply a folder. It will look inside of the opened folder for a `.vscode` _sub_-folder to load project-specific settings from. + +![Example Directory Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/opening_projects_2.jpg) + +_(Note: You may need to enable viewing of hidden items in your file explorer to see the .vscode sub-folder)._ + +To open a project: + +1. Launch Visual Studio Code. + +2. Select **File -> Open Folder...** + +3. Navigate to an example project for the target microcontroller in the MSDK's [Examples folder](Examples) and open it with **Select Folder**. + +4. VS Code will prompt for trust the first time. Select _Trust folder and enable all features_ + + ![Trust Prompt](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/workspaceTrustPrompt.JPG) + +5. The opened project should look something like this. + + ![Figure 16](res/Fig16.jpg) + +6. Set the **Board Support Package** to match your evaluation platform. In VS Code, this is done by editing the `.vscode/settings.json` file and setting the `"board"` project configuration option. + + See [Board Support Packages](#board-support-packages) for more details. + + ![Figure 17](res/Fig17.jpg) + +7. Save your changes to `settings.json` with `CTRL+S`. + +8. Reload the VS Code window. A reload is necessary after changing any options in `settings.json` to force it to re-index its Intellisense engine. + + VS Code can be conveniently re-loaded with the **Reload Window** developer command accessed with **`CTRL + SHIFT + P`** (or **`COMMAND + SHIFT + P`** on MacOS). + + ![Reload window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/reload_window.JPG) + +#### Building and Running a Project + +Once a project is opened 4 available [build tasks](https://github.com/Analog-Devices-MSDK/VSCode-Maxim#build-tasks) will become available via **Terminal > Run Build task...** or the shortcut **`Ctrl+Shift+B`**. These are the primary interface to the build system. + +![Build Tasks Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/buildtasks.JPG) + +1. Run the **"build"** task to compile the project for the configured _Target Microcontroller_ and _BSP_. Notice the `TARGET` and `BOARD` Build Configuration Variables being set on the command-line, and the program binary successfully compiled into the `.elf` program binary in the **build** sub-folder of the project. + + ![Figure 18](res/Fig18.jpg) + +2. Connect a debug adapter between the host PC and the evaluation platform. For more detailed instructions on this hardware setup refer to the evaluation platforms Datasheet and Quick-Start Guide. + +3. Run the **`flash`** build task. Running this task will automatically build the project if needed, flash the program binary, and halt the program execution to await a debugger connection. + + ![Figure 19](res/Fig19.jpg) + +4. Open the **Run and Debug** window (**`CTRL+SHIFT+D`**) and launch the debugger (**`F5`**). + + ![Figure 20](res/Fig20.jpg) + +5. Verify the program counter enters `main` successfully. + + ![Figure 21](res/Fig21.jpg) + +6. Press **Continue** (**`F5`**) to run the program. + + ![Debugger Control Bar Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_bar.JPG) + + Continue | Step Over | Step Into | Step Out | Restart | Stop + +7. Exercise the debugger, and press stop to disconnect when finished. + +--- + +### Getting Started with Eclipse + +The only setup required to use Eclipse is to ensure that the “Eclipse” component has been selected during the [MSDK installation](#installation). If the MSDK is already installed the Eclipse can be retrieved using the [Maintenance Tool](#maintenance). + +This section is an Eclipse "quick-start" that walks through creating, building, and running a project. For full documentation, see the [Eclipse](#eclipse) section of this User Guide. + +#### Creating a New Project + +1. [Launch](#running-eclipse) Eclipse. + +2. Ensure that the Eclipse is set to the **C/C++ perspective** in the top right corner. Otherwise, the new project wizard will not show up. + +3. Navigate to **File -> New -> Maxim Microcontrollers**. + + ![Figure 31](res/Fig31.jpg) + +4. Enter the project name and hit **Next**. + + ![Figure 32](res/Fig32.jpg) + +5. Follow the new project wizard. + + - Chip type selects the _Target Microcontroller_ + - Board type selects the [_Board Support Package (BSP)_](#board-support-packages) + - Example type selects the example project to be copied as the template for the new project. + - Adapter type selects the debug adapter to use. + + ![Figure 33](res/Fig33.jpg) + +6. Select **Finish** to create the new project. + +#### Importing Examples + +1. [Launch](#running-eclipse) Eclipse. + +2. Use **File -> Import** to open the import wizard. + +3. Select **General -> Existing Projects into Workspace** and hit **Next**. + + ![Figure 23](res/Fig23.jpg) + +4. **Browse** to the [`Examples`](Examples) folder in the MSDK installation for your target microcontroller and select the example projects to import into the workspace. + + ![Figure 24](res/Fig24.jpg) + +5. Ensure that **Copy projects into workspace** is selected. This will copy the projects out of the MSDK, and leave the originals unmodified. + +6. Select **Finish** to import the project(s). + +7. The projects should now show up in the Project Explorer. + + ![Figure 25](res/Fig25.jpg) + + +#### Building and Running Examples + +1. Ensure that the Eclipse is set to the **C/C++ perspective** (top right). + +2. Select the correct project in the **Launch Configuration** dropdown and ensure it's set to **Debug** mode. + +3. Use the **Build** hammer button (top left) to build the project. + + ![Figure 27](res/Fig27.jpg) + +4. Use the **Debug** button (top left) to flash the program binary and connect the debugger. + + ![Figure 28](res/Fig28.jpg) + +5. The Eclipse view will switch to debug mode, and the debugger will break on entry into main. + + ![Figure 29](res/Fig29.jpg) + +6. **Resume** the program (**`F8`**) using the top control bar and exercise the debugger. + + ![Figure 30](res/Fig30.jpg) + +7. **Terminate** the debugger (**`CTRL+F2`**) when finished. + +--- + +### Getting Started with Command-Line Development + +This section demonstrates how to build MSDK example projects for on the command line. It also demonstrates how to flash and debug over the command-line. The [MAX78002EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78002evkit.html) will be used as an example, but the same concepts apply to all parts. + +For more detailed documentation, see the [Command-Line Development](#command-line-development) section of this User Guide. + +#### Setup (Command-Line) + +##### Windows + +On Windows, the MinGW shortcut should be used to launch a MSYS2/MinGW terminal. Alternatively, the `Tools/MSYS2/msys.bat` file can be launched directly. + +![Figure 22](res/Fig22.jpg) + +##### Linux/MacOS + +1. On Linux and MacOS, copy the following contents into your shell's terminal profile/startup script. Depending on your system and shell this could be `~/.profile`, `~/.zprofile`, `~/.bashrc`, `~/.zshrc`, etc. + + # Set MAXIM_PATH to point to the MSDK + export MAXIM_PATH=#changeme! + + # Add Arm Embedded GCC to path (v10.3) + export ARM_GCC_ROOT=$MAXIM_PATH/Tools/GNUTools/10.3 + export PATH=$ARM_GCC_ROOT/bin:$PATH + + # Add xPack RISC-V GCC to path (v10.2) + export XPACK_GCC_ROOT=$MAXIM_PATH/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2 + export PATH=$XPACK_GCC_ROOT/bin:$PATH + + # Add OpenOCD to path + export OPENOCD_ROOT=$MAXIM_PATH/Tools/OpenOCD + export PATH=$OPENOCD_ROOT:$PATH + +2. Change `export MAXIM_PATH=#changeme!` to the installation location of the MSDK. This will make the toolchain accessible from the command-line by adding it to your *system's path*. + + # Set MAXIM_PATH environment variable + export MAXIM_PATH=$HOME/MaximSDK + +##### Verification + +The following commands can be used to verify that the toolchain is accessible. They should display version numbers successfully. + +- `arm-none-eabi-gcc -v` +- `arm-none-eabi-gdb -v` +- `make -v` +- `openocd -v` + +#### Building and Running an Example + +1. First, copy an [example project](Examples) to an accessible directory outside of the SDK. It is strongly recommended to keep the MSDK examples unmodified in case they need to be referenced again later. + +2. Launch your terminal. On Windows, use the MinGW shortcut or `Tools/MSYS2/msys.bat` file to launch the MSYS2 terminal. + +3. `cd` into the location of the copied example project. + +4. Run the following command to build the example: + + make -r -j + + - `-r` is an option that improves build speed. + - `-j` enables parallel execution of the build in the maximum number of threads. + + Expected output: + + :::bash + Loaded project.mk + CC main.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/Source/board.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/stdio.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/LED/led.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/PushButton/pb.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Display/adafruit_3315_tft.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Touchscreen/adafruit_3315_touch.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Camera/camera.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Camera/mipi_camera.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Camera/ov7692.c + CC /home/msdk/Libraries/Boards/MAX78002/EvKit_V1/../../../MiscDrivers/Camera/sccb.c + AS /home/msdk/Libraries/CMSIS/Device/Maxim/MAX78002/Source/GCC/startup_max78002.S + CC /home/msdk/Libraries/CMSIS/Device/Maxim/MAX78002/Source/heap.c + CC /home/msdk/Libraries/CMSIS/Device/Maxim/MAX78002/Source/system_max78002.c + LD /home/msdk/Examples/MAX78002/Hello_World/build/max78002.elf + arm-none-eabi-size --format=berkeley /home/msdk/Examples/MAX78002/Hello_World/build/max78002.elf + text data bss dec hex filename + 35708 2504 1156 39368 99c8 /home/msdk/Examples/MAX78002/Hello_World/build/max78002.elf + +5. Connect a debug adapter between the host PC and the evaluation platform. For more detailed instructions on this hardware setup refer to the evaluation platforms Datasheet and Quick-Start Guide. + +6. Run the command below to launch an **OpenOCD _server_**, **flash** the program binary, and **halt** the program execution. + + openocd -s $MAXIM_PATH/Tools/OpenOCD/scripts -f interface/cmsis-dap.cfg -f target/max78002.cfg -c "program build/max78002.elf verify; init; reset halt" + + Expected output: + + :::bash + Open On-Chip Debugger 0.11.0+dev-g4cdaa275b (2022-03-02-09:57) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + DEPRECATED! use 'adapter driver' not 'interface' + Info : CMSIS-DAP: SWD supported + Info : CMSIS-DAP: Atomic commands supported + Info : CMSIS-DAP: Test domain timer supported + Info : CMSIS-DAP: FW Version = 0256 + Info : CMSIS-DAP: Serial# = 044417016af50c6500000000000000000000000097969906 + Info : CMSIS-DAP: Interface Initialised (SWD) + Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1 + Info : CMSIS-DAP: Interface ready + Info : clock speed 2000 kHz + Info : SWD DPIDR 0x2ba01477 + Info : max32xxx.cpu: Cortex-M4 r0p1 processor detected + Info : max32xxx.cpu: target has 6 breakpoints, 4 watchpoints + Info : starting gdb server for max32xxx.cpu on 3333 + Info : Listening on port 3333 for gdb connections + Info : SWD DPIDR 0x2ba01477 + target halted due to debug-request, current mode: Thread + xPSR: 0x81000000 pc: 0x0000fff4 msp: 0x20003ff0 + ** Programming Started ** + ** Programming Finished ** + ** Verify Started ** + ** Verified OK ** + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + # Note: OpenOCD is now waiting for a GDB client + +7. Launch a **_new_ separate terminal**. On Windows, use the MinGW shortcut or `Tools/MSYS2/msys.bat` file to launch the MSYS2 terminal. + +8. `cd` into the location of the copied example project. + +9. Run the following command to launch a **GDB *client***. + + arm-none-eabi-gdb --se=build/max78002.elf + + - `--se` sets the symbol and executable file to the compiled program file. By default, the output filename matches the target microcontroller. + + Expected output: + + :::bash + GNU gdb (GNU Arm Embedded Toolchain 10.3-2021.10) 10.2.90.20210621-git + Copyright (C) 2021 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "--host=i686-w64-mingw32 --target=arm-none-eabi". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + . + Find the GDB manual and other documentation resources online at: + . + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from build/max78002.elf... + (gdb) + +10. Connect the GDB Client to the OpenOCD server with the following command. + + target extended-remote localhost:3333 + + Expected output: + + :::bash + Remote debugging using localhost:3333 + 0x0000fff4 in ?? () # Note: ?? may be present at this stage, which is OK. + +11. Reset the target microcontroller. + + monitor reset halt + + Expected output: + + :::bash + SWD DPIDR 0x2ba01477 + target halted due to debug-request, current mode: Thread + xPSR: 0x81000000 pc: 0x0000fff4 msp: 0x20003ff0 + +12. Set a breakpoint on main. + + b main + + Expected output: + + :::bash + Breakpoint 1 at 0x10000224: file main.c, line 62. + Note: automatically using hardware breakpoints for read-only addresses. + +13. Continue the debugger. + + continue + + Expected output (for the Hello World example): + + :::bash + Continuing. + + Breakpoint 1, main () at main.c:62 + 62 printf("Hello World!\n"); + +14. (Optional) Continue exercising the debugger. + + Run `help` for GDB help, or see [Common GDB Commands](#common-gdb-commands). + +15. Quit GDB. + + quit + + Expected output: + + :::shell + A debugging session is active. + + Inferior 1 [Remote target] will be detached. + + Quit anyway? (y or n) [answered Y; input not from terminal] + Detaching from program: C:\Users\User\codespace\Hello_World\build\max78002.elf, Remote target + [Inferior 1 (Remote target) detached] + +16. In the terminal window running the OpenOCD _server_, press `CTRL + C` to issue the shutdown command and quit. + +## Development Guide + +As discussed in [Key Concepts](#key-concepts), an MSDK project is primarily made up of two distinct systems: The **_Build System_** and the _**Project Management System**_. [Getting Started](#getting-started) demonstrates the basic usage and configuration of these systems, while this section offers a more detailed reference. + +MSDK development primarily involves using the Project Management System, which offers a higher level user interface (typically with a GUI) that manages the tools for **editing** source code, **flashing** program binaries, and **debugging** for the MSDK's [supported IDEs](#supported-development-environments). Additionally, the Project Management System sits _on top_ of the [Build System](#build-system)'s _CLI_, allowing it to manage fundamental build variables aspects of development such as: + +- Setting the _Target Microcontroller_ (`TARGET` _[Build Configuration Variable](#build-configuration-variables-reference-table)_) +- Setting the _Board Support Package_ (`BOARD` _[Build Configuration Variable](#build-configuration-variables-reference-table)_) +- Configuring the _Environment_ and _System Path_ for use with the MSDK toolchain (`MAXIM_PATH` _[Build Configuration Variable](#build-configuration-variables-reference-table)_) + +### Board Support Packages + +The role of a Board Support Package (BSP) is to provide a hardware abstraction layer for board-level initialization code such as initializing and assigning UART instances, pushbuttons, LEDs, external peripheral devices, TFT displays, and other board-specific hardware. The MSDK's available Board Support Packages (BSPs) can be found in the `Libraries/Boards` folder for each _Target Microcontroller_. + +![Figure 34](res/Fig34.jpg) + +The name of the BSP is the name of the folder. For example, the MAX78000 supports the `Aud01_RevA`, `EvKit_V1`, `FTHR_RevA`, and `MAXREFDES178` BSPs. However, it is not always clear how these BSP names match the part numbers for different evaluation kits. The table below can be used to match an external part number with an MSDK BSP. + +| External Part Number | `BOARD` | +| ------------------------------------------------------------ | -------------- | +| [MAX32520-KIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32520-kit.html) | `EvKit_V1` | +| [MAX32520FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32520fthr.html) | `MAX32520FTHR` | +| [MAX32650-EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32650-evkit.html) | `EvKit_V1` | +| [MAX32650FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32650fthr.html) | `FTHR_APPS_A` | +| [MAX32655EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32655evkit.html) | `EvKit_V1` | +| [MAX32655FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32655fthr.html) | `FTHR_Apps_P1` | +| [MAX32660-EVSYS](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32660-evsys.html) | `EvKit_V1` | +| MAX32662EVKIT | `EvKit_V1` | +| [MAX32666EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32666evkit.html) | `EvKit_V1` | +| [MAX32666FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32666fthr.html) | `FTHR` | +| MAX32666FTHR2 | `FTHR2` | +| [MAX32670EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32670evkit.html) | `EvKit_V1` | +| [MAX32672EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32672evkit.html) | `EvKit_V1` | +| [MAX32672FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32672fthr.html) | `FTHR` | +| [MAX32675EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32675evkit.html) | `EvKit_V1` | +| MAX32675FTHR | `FTHR_Apps_B` | +| [MAX32680EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max32680evkit.html) | `EvKit_V1` | +| MAX32690EVKIT | `EvKit_V1` | +| [MAX78000EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000evkit.html) | `EvKit_V1` | +| [MAX78000FTHR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78000fthr.html) | `FTHR_RevA` | +| [MAXREFDES178](https://www.analog.com/en/design-center/reference-designs/maxrefdes178.html) | `MAXREFDES178` | +| [MAX78002EVKIT](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/max78002evkit.html) | `EvKit_V1` | + +To set the BSP for a project: + +- In **VS Code**: [How to Set the BSP (VS Code)](#how-to-set-the-bsp-vs-code) +- In **Eclipse**: [How to Set the BSP (Eclipse)](#how-to-set-the-bsp-eclipse) +- **Command-Line** Development: [How to Set the BSP (Command-Line)](#how-to-set-the-bsp-command-line) + +### Visual Studio Code + +Support for [Visual Studio Code](https://code.visualstudio.com/) is maintained for the MSDK and developed on the [VSCode-Maxim](https://github.com/Analog-Devices-MSDK/VSCode-Maxim) Github repository. This section augments the VSCode-Maxim [README](https://github.com/Analog-Devices-MSDK/VSCode-Maxim) with more detailed usage info and insight. + +#### Setup (VS Code) + +The setup below only needs to be done once per MSDK [installation](#installation). + +1. Download & install Visual Studio Code for your OS [here](https://code.visualstudio.com/Download). + +2. Launch Visual Studio Code. + +3. Install the Microsoft [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + +4. Use **`CTRL + SHIFT + P`** (or **`COMMAND + SHIFT + P`** on MacOS) to open the developer prompt. + +5. Type "open settings json" and select the **"Preferences: Open Settings (JSON)"** option (_not_ "Preferences: Open _Default_ Settings (JSON)"). This will open your **user** settings.json file in VS Code's editor. + + ![Open Settings JSON Command](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/open_settings_json.jpg) + +6. Add the entries below into your **_user settings.json_** file. + + :::json + { + // There may be other settings up here... + + "MAXIM_PATH":"C:/MaximSDK", // Set this to the installed location of the MaximSDK. Only use forward slashes '/' when setting this path! + "update.mode": "manual", + "extensions.autoUpdate": false, + + // There may be other settings down here... + } + +7. Save your changes to the file with **`CTRL + S`** and restart VS Code. + +#### Opening Example Projects + +Visual Studio Code is built around a "working directory" paradigm. The editor is always rooted in a working directory, and the main mechanism for changing that directory is **File -> Open Folder...** + +![File -> Open Folder](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/file_openfolder.JPG) + +As a result, you'll notice that there is no "New Project" mechanism. A "project" in VS Code is simply a folder. It will look inside of the opened folder for a `.vscode` _sub_-folder to load project-specific settings from. + +![Example Directory Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/opening_projects_2.jpg) + +_(Note: You may need to enable viewing of hidden items in your file explorer to see the .vscode sub-folder)._ + +To open a project: + +1. Launch Visual Studio Code. + +2. Select **File -> Open Folder...** + +3. Navigate to an example project for the target microcontroller in the MSDK's [Examples folder](Examples) and open it with **Select Folder**. + +4. VS Code will prompt for trust the first time. Select _**Trust folder and enable all features**_. + + ![Trust Prompt](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/workspaceTrustPrompt.JPG) + +5. The opened project should look something like this. + + ![Figure 16](res/Fig16.jpg) + +6. (Optional) Set the **Board Support Package** to match your evaluation platform if necessary. Projects default to the **"EVKIT"** BSP for the target microcontroller. See [How to Set the BSP (VS Code)](#how-to-set-the-bsp-vs-code) below. + +#### How to Set the BSP (VS Code) + +To set the BSP for a project: + +1. Set the `"board"` [project configuration](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/main#project-configuration) option in `.vscode/settings.json`, which maps to the `BOARD` _[Build Configuration Variable](#build-configuration-variables-reference-table)_. + + See [Board Support Packages](#board-support-packages) for a table of possible values. + + ![Figure 17](res/Fig17.jpg) + +2. Reload the VS Code window to re-index its Intellisense engine. + + VS Code can be conveniently re-loaded with the **Reload Window** developer command accessed with **`CTRL + SHIFT + P`** (or **`COMMAND + SHIFT + P`** on MacOS). + + ![Reload window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/reload_window.JPG) + +#### Building a Project + +Once a project is opened 4 available [build tasks](https://github.com/Analog-Devices-MSDK/VSCode-Maxim#build-tasks) will become available via **Terminal > Run Build task...** or the shortcut **`Ctrl+Shift+B`**. + +![Build Tasks Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/buildtasks.JPG) + +Run the **"build"** task to compile the project for the configured _Target Microcontroller_ and _BSP_. Notice the **`TARGET`**, **`BOARD`** , and **`PROJECT`** Build Configuration Variables being set on the command-line, and the program binary successfully compiled into the `.elf` program binary in the **build** sub-folder of the project. + +![Figure 18](res/Fig18.jpg) + +To **clean** a project, run the **clean** [build task](https://github.com/Analog-Devices-MSDK/VSCode-Maxim#build-tasks). This will wipe the contents of the build folder entirely. Additionally, the **clean-periph** task can be used to clean the project _and_ the peripheral drivers. + +#### Flashing and Debugging + +This section assumes a debugger is connected between the host PC and the evaluation platform. For more detailed instructions on this hardware setup refer to the evaluation platforms Datasheet and Quick-Start Guide, which are available on the evaluation platform's product page. + +##### Arm Core Debugging + +1. Run the **`flash`** [build task](https://github.com/Analog-Devices-MSDK/VSCode-Maxim#build-tasks). Running this task will automatically build the project if needed, flash the program binary, and halt the program execution to await a debugger connection. + + **Flashing does not happen automatically when launching the debugger**. This is an intentional design choice for VS Code to allow the debugger to quickly restart the program under debug without a lengthy re-flash procedure. + + ![Figure 19](res/Fig19.jpg) + +2. Open the **Run and Debug** window (**`CTRL+SHIFT+D`**) and launch the debugger (**`F5`**). Use the **_Arm M4_** profile. + + ![Figure 20](res/Fig20.jpg) + +3. Verify the program counter enters `main` successfully. + + ![Figure 21](res/Fig21.jpg) + +4. Press **Continue** (**`F5`**) to run the program. The debugger control bar can be used to exercise the debugger further. + + ![Debugger Control Bar Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_bar.JPG) + + Continue | Step Over | Step Into | Step Out | Restart | Stop + +##### Breakpoints + +Breakpoints can be set by clicking next to a line number in VS Code's editor. They are removed by clicking on them again. + +![Figure 35](res/Fig35.jpg) + +Additionally _conditional_ breakpoints can be added by _right-clicking_ on a line. + +![Figure 36](res/Fig36.jpg) + +The condition and condition type can be modified with the dropdown. This is useful for setting breakpoint on a certain value in a `for` loop iterator or when a specific bit in a register is set, for example. + +![Figure 37](res/Fig37.jpg) + +##### Peripheral Browsing + +A peripheral browser lets you quickly view the formatted register-level contents of the peripheral blocks on a target microcontroller under debug. Currently, VSCode-Maxim does not feature a true peripheral browser. Instead, *watch expressions* can be used to inspect peripherals at the register level. + +![image](https://user-images.githubusercontent.com/38844790/177819220-b9524b70-b279-4b16-bdb0-da37e1a1f556.png) + +Watch expressions can be set for all registers. (For example, the `sysctrl` register below). + +![image](https://user-images.githubusercontent.com/38844790/177819247-ccf90782-e1e6-44f2-8605-c39fc15c09a6.png) + +- Adding **`,b`** lets you print out the value in **binary** +- Adding **`,x`** prints the value in **hex**. +- Standard **logical** and **bitwise** operations are supported inside the watch expression. +- **Register** and **variable** values can be **modified** through these same watch-points. _(Right click -> Set Value)_ + +It should be noted that the debugger's watch-points are *contextual*, meaning that its symbol look-ups will depend on the active point in your program. + +##### Dual Core Debugging + +For microcontrollers with _both_ an Arm M4 and a RISC-V core, the _GDB (RISC-V)_ launch profile is provided to enable RISC-V debugging. The RISC-V core requires setup and handoff from the Arm M4 core. As a result, this is an advanced configuration requiring a unique combination of the project's source code, Makefiles, and VSCode-Maxim project settings. Such projects are appended with the `-riscv` suffix in the project's folder name. + +This section demonstrates how to debug `-riscv` projects in VS Code using the [mnist-riscv](Examples/MAX78000/CNN/mnist-riscv) project for the MAX78000 as an example. + +1. Connect _both_ your Arm (SWD) and RISC-V (JTAG) debuggers. VSCode-Maxim projects come pre-configured to use the [ARM-USB-OCD-H](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-OCD-H/) + [ARM-JTAG-20-10](https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/) adapters for the RISC-V JTAG port. Ex: + + ![Debugger-EvKIT Connections](https://user-images.githubusercontent.com/38844790/190749647-f4ef066a-afcc-4749-bb9c-53c7e33e2cf9.jpg) + +2. Make sure your Olimex debugger drivers are installed correctly. Sometimes they need to be updated using the "zadig" tool. See Section 3.3.3 of the [Olimex User Manual](https://www.olimex.com/Products/ARM/JTAG/_resources/ARM-USB-OCD_and_OCD_H_manual.pdf), and use the [Zadig](https://zadig.akeo.ie/) tool to install WinUSB drivers. + +3. Download the [max78000_riscv.cfg](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/files/9587266/max78000_riscv.zip) file and place it inside the `Tools/OpenOCD/scripts/target` folder of your MSDKinstallation. + +4. [Open](#opening-example-projects) the project in VS Code. + +5. Run the "Flash" task. + + ![image](https://user-images.githubusercontent.com/38844790/168398354-2ac2961b-6d45-4f84-8805-0ab5339a4b98.png) + +6. Launch the debugger using the **GDB (Arm M4)** profile **first**: + + ![image](https://user-images.githubusercontent.com/38844790/168398415-147a3a96-1a7d-4057-8a32-0dfaf2d378c1.png) + + ... which should hit the breakpoint in `main.c`... + ![image](https://user-images.githubusercontent.com/38844790/168398503-0f2ae9c1-f535-4d41-aed9-9d9e19b16303.png) + +7. **Continue** the debugger. The code in `main.c` will boot up the RISC-V core. You can optionally set a breakpoint on `WakeISR` to see when the RISC-V core has signaled it's ready. + + ![image](https://user-images.githubusercontent.com/38844790/168398665-9486e1b6-73bd-481e-a4b5-15dd44c7d7b9.png) + +8. Now, switch the debugger profile to the **GDB (RISC-V) profile** and launch it. This will launch an additional instance on a separate port and connect to the Olimex adapter. + + ![image](https://user-images.githubusercontent.com/38844790/168398707-b6771bf3-b6bf-47a2-b963-b0b9fc003ca4.png) + + The "Signal 0" exception below is a known issue caused by a reset bug on the RISC-V core. The exception message is harmless and can be safely ignored. + + ![image](https://user-images.githubusercontent.com/38844790/168399130-95fe7539-fb46-4c06-a268-6b720403b539.png) + +9. From here, the debugger should be fully functional. The Arm vs RISC-V debugger instance can be selected with the dropdown on the debugger control bar. + + ![image](https://user-images.githubusercontent.com/38844790/168399419-d0488a0e-2068-4cc7-9108-0a296fdc04b4.png) + +--- + +### Eclipse + +#### Running Eclipse + +Eclipse _must_ be launched via the **Eclipse MaximSDK** shortcut which points to the `Tools/Eclipse/cdt/eclipse(.bat/.sh)` file. This file can be used directly to launch Eclipse as well. It calls`setenv(.bat/.sh)` script in the root directory of the MSDK to properly configure Eclipse's system environment for use with the toolchain. + +![Figure 22](res/Fig22.jpg) + +When Eclipse is launched, it will prompt for a **_workspace_** location. This is a local folder that Eclipse will copy its projects into. + +![Figure 39](res/Fig39.jpg) + +#### Creating a New Project + +1. [Launch](#running-eclipse) Eclipse. + +2. Ensure that the Eclipse is set to the **C/C++ perspective** in the top right corner. Otherwise, the new project wizard will not show up. + +3. Navigate to **File -> New -> Maxim Microcontrollers**. + + ![Figure 31](res/Fig31.jpg) + +4. Enter the project name and hit **Next**. + + ![Figure 32](res/Fig32.jpg) + +5. Follow the new project wizard. + + - Chip type selects the _Target Microcontroller_ + - Board type selects the [_Board Support Package (BSP)_](#board-support-packages) + - Example type selects the example project to be copied as the template for the new project. + - Adapter type selects the debug adapter to use. + + ![Figure 33](res/Fig33.jpg) + +6. Select **Finish** to create the new project. + +#### Importing Examples + +1. [Launch](#running-eclipse) Eclipse. + +2. Use **File -> Import** to open the import wizard. + +3. Select **General -> Existing Projects into Workspace** and hit **Next**. + + ![Figure 23](res/Fig23.jpg) + +4. **Browse** to the [`Examples`](Examples) folder in the MSDK installation for your target microcontroller and select the example projects to import into the workspace. + + ![Figure 24](res/Fig24.jpg) + +5. Ensure that **Copy projects into workspace** is selected. This will copy the projects out of the MSDK, and leave the originals unmodified. + +6. Select **Finish** to import the project(s). + +7. The projects should now show up in the Project Explorer. + + ![Figure 25](res/Fig25.jpg) + +#### How to Set the BSP (Eclipse) + +[Imported](#importing-examples) Eclipse projects files are configured for the **EVKIT**-type _BSP_ by default. To set the BSP: + +1. Open (right click) the **project properties** and navigate to **C/C++ Build -> Environment**. +2. Set the **`BOARD`** _[Build Configuration Variable](#build-configuration-variables-reference-table)_ to match the target evaluation platform. + + See [Board Support Packages](#board-support-packages) for a table of possible values. + + ![Figure 26](res/Fig26.jpg) + +3. **clean** and rebuild the project. + +#### Building a Project + +1. Ensure that the Eclipse is set to the **C/C++ perspective** (top right). + +2. Select the correct project in the **Launch Configuration** dropdown. + +3. Use the **Build** hammer button (top left) to build the project. + + ![Figure 27](res/Fig27.jpg) + +#### Flashing and Debugging + +1. Connect a debug adapter between the host PC and the evaluation platform. For more detailed instructions on this hardware setup refer to the evaluation platforms Datasheet and Quick-Start Guide. + +2. Ensure the correct project in the **Launch Configuration** dropdown is selected in **Debug** mode. + +3. Use the **Debug** button (top left) to flash the program binary and connect the debugger. + + ![Figure 28](res/Fig28.jpg) + +4. The Eclipse view will switch to debug mode, and the debugger will break on entry into main. + + ![Figure 29](res/Fig29.jpg) + +5. **Resume** the program (**`F8`**) using the top control bar and exercise the debugger. + + ![Figure 30](res/Fig30.jpg) + +6. **Terminate** the debugger (**`CTRL+F2`**) when finished. + +--- + +### Command-Line Development + +#### Setup (Command-Line) + +##### Windows + +On Windows, the MinGW shortcut should be used to launch a MSYS2/MinGW terminal. Alternatively, the `Tools/MSYS2/msys.bat` file can be launched directly. + +![Figure 22](res/Fig22.jpg) + +##### Linux/MacOS + +1. On Linux and MacOS, copy the following contents into your shell's terminal profile/startup script. Depending on your system and shell this could be `~/.profile`, `~/.zprofile`, `~/.bashrc`, `~/.zshrc`, etc. + + # Set MAXIM_PATH to point to the MSDK + export MAXIM_PATH=#changeme! + + # Add Arm Embedded GCC to path (v10.3) + export ARM_GCC_ROOT=$MAXIM_PATH/Tools/GNUTools/10.3 + export PATH=$ARM_GCC_ROOT/bin:$PATH + + # Add xPack RISC-V GCC to path (v10.2) + export XPACK_GCC_ROOT=$MAXIM_PATH/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2 + export PATH=$XPACK_GCC_ROOT/bin:$PATH + + # Add OpenOCD to path + export OPENOCD_ROOT=$MAXIM_PATH/Tools/OpenOCD + export PATH=$OPENOCD_ROOT:$PATH + +2. Change `export MAXIM_PATH=#changeme!` to the installation location of the MSDK. This will make the toolchain accessible from the command-line by adding it to your *system's path*. + + # Set MAXIM_PATH environment variable + export MAXIM_PATH=$HOME/MaximSDK + +##### Verification + +The following commands can be used to verify that the toolchain is accessible. They should display version numbers successfully. + +- `arm-none-eabi-gcc -v` +- `arm-none-eabi-gdb -v` +- `make -v` +- `openocd -v` + +#### How to Set the BSP (Command-Line) + +- Set the **`BOARD`** _[Build Configuration Variable](#build-configuration-variables-reference-table)_ in **project.mk** + + :::makefile + # This file can be used to set build configuration + # variables. These variables are defined in a file called + # "Makefile" that is located next to this one. + + # For instructions on how to use this system, see + # https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration + + # ********************************************************** + + # Add your config here! + + BOARD=FTHR_RevA # Set the BSP + +- Alternatively, set **`BOARD`** on the command-line when building (ie. `make -r -j BOARD=FTHR_RevA`) + +#### Building on the Command-Line + +1. `cd` into the project folder. + +2. Run `make` + + - **Parallel Build** (fastest build, but console message formatting may be mangled): + + make -r -j + + - **Serial Build** + + make -r + +3. Take note of the output filename and location, which by default is the lowercase name of the _Target microcontroller_ and created in the `build` folder. + +#### Cleaning on the Command-Line + +1. `cd` into the project folder. +2. Run `make clean` + - **Project clean**: `make clean` deletes the project `build` folder and all of its contents. + - **Library clean**: `make distclean` can be used to clean out _all_ build products, including the project `build` folder and all [peripheral driver](#peripheral-driver-api) libraries. + +#### Flashing on the Command-Line + +1. [Build](#building-on-the-command-line) the project. + +2. Connect a debug adapter between the host PC and the evaluation platform. For more detailed instructions on this hardware setup refer to the evaluation platforms Datasheet and Quick-Start Guide. + +3. Flash the program using `openocd`. + + - **Flash and exit:** Use this command if you just want to flash the program _but **not debug**_. OpenOCD will **flash** the program and **exit** on completion. + + openocd -s $MAXIM_PATH/Tools/OpenOCD/scripts -f interface/cmsis-dap.cfg -f target/max78002.cfg -c "program build/max78002.elf verify exit" + + - `-f target/max78002.cfg` sets the OpenOCD config file for the _Target microcontroller_. Supported options can be found in the [Tools/OpenOCD/scripts/target](Tools/OpenOCD/scripts/target) folder. **Change this to match the target microcontroller**. + - `-c "program build/max78002.elf verify exit"` flashes the program binary. Change `build/max78002.elf` to match the correct filename. + + Expected output: + + :::bash + Open On-Chip Debugger 0.11.0+dev-g4cdaa275b (2022-03-02-09:57) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + DEPRECATED! use 'adapter driver' not 'interface' + Info : CMSIS-DAP: SWD supported + Info : CMSIS-DAP: Atomic commands supported + Info : CMSIS-DAP: Test domain timer supported + Info : CMSIS-DAP: FW Version = 0256 + Info : CMSIS-DAP: Serial# = 044417016af50c6500000000000000000000000097969906 + Info : CMSIS-DAP: Interface Initialised (SWD) + Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1 + Info : CMSIS-DAP: Interface ready + Info : clock speed 2000 kHz + Info : SWD DPIDR 0x2ba01477 + Info : max32xxx.cpu: Cortex-M4 r0p1 processor detected + Info : max32xxx.cpu: target has 6 breakpoints, 4 watchpoints + Info : starting gdb server for max32xxx.cpu on 3333 + Info : Listening on port 3333 for gdb connections + Info : SWD DPIDR 0x2ba01477 + target halted due to debug-request, current mode: Thread + xPSR: 0x81000000 pc: 0x0000fff4 msp: 0x20003ff0 + ** Programming Started ** + ** Programming Finished ** + ** Verify Started ** + ** Verified OK ** + shutdown command invoked + + - **Flash and hold:** Use this if you want to also **debug** the program. OpenOCD will **flash** the program, **reset** the MAX78002, **halt** program execution, and **wait** for a GDB debugger client connection. + + openocd -s $MAXIM_PATH/Tools/OpenOCD/scripts -f interface/cmsis-dap.cfg -f target/max78002.cfg -c "program build/max78002.elf verify; init; reset halt" + + - `-f target/max78002.cfg` sets the OpenOCD config file for the _Target microcontroller_. Supported options can be found in the [Tools/OpenOCD/scripts/target](Tools/OpenOCD/scripts/target) folder. **Change this to match the target microcontroller**. + - `-c "program build/max78002.elf verify exit"` flashes the program binary. Change **`build/max78002.elf`** to match the correct filename. + + Expected output: + + :::bash + Open On-Chip Debugger 0.11.0+dev-g4cdaa275b (2022-03-02-09:57) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + DEPRECATED! use 'adapter driver' not 'interface' + Info : CMSIS-DAP: SWD supported + Info : CMSIS-DAP: Atomic commands supported + Info : CMSIS-DAP: Test domain timer supported + Info : CMSIS-DAP: FW Version = 0256 + Info : CMSIS-DAP: Serial# = 044417016af50c6500000000000000000000000097969906 + Info : CMSIS-DAP: Interface Initialised (SWD) + Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1 + Info : CMSIS-DAP: Interface ready + Info : clock speed 2000 kHz + Info : SWD DPIDR 0x2ba01477 + Info : max32xxx.cpu: Cortex-M4 r0p1 processor detected + Info : max32xxx.cpu: target has 6 breakpoints, 4 watchpoints + Info : starting gdb server for max32xxx.cpu on 3333 + Info : Listening on port 3333 for gdb connections + Info : SWD DPIDR 0x2ba01477 + target halted due to debug-request, current mode: Thread + xPSR: 0x81000000 pc: 0x0000fff4 msp: 0x20003ff0 + ** Programming Started ** + ** Programming Finished ** + ** Verify Started ** + ** Verified OK ** + Info : Listening on port 6666 for tcl connections + Info : Listening on port 4444 for telnet connections + # Note: OpenOCD is now waiting for a GDB client connection + +#### Debugging on the Command-Line + +1. [Flash](#flashing-on-the-command-line) the program using the **Flash and Hold** command. + +2. Launch an **_new_ separate terminal**. On Windows, use the MinGW shortcut or `Tools/MSYS2/msys.bat` file to launch the MSYS2 terminal. + +3. `cd` into the location of the copied example project. + +4. Run the following command to launch a **GDB *client***. + + arm-none-eabi-gdb --se=build/max78002.elf + + - `--se` sets the symbol and executable file to the compiled program file. **Change this to match the build output filename.** + + Expected output: + + :::bash + GNU gdb (GNU Arm Embedded Toolchain 10.3-2021.10) 10.2.90.20210621-git + Copyright (C) 2021 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "--host=i686-w64-mingw32 --target=arm-none-eabi". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + . + Find the GDB manual and other documentation resources online at: + . + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from build/max78002.elf... + (gdb) + +5. Connect the GDB Client to the OpenOCD server with the following command. + + target extended-remote localhost:3333 + + Expected output: + + :::bash + Remote debugging using localhost:3333 + 0x0000fff4 in ?? () # Note: ?? may be present at this stage, which is OK. + +6. Reset the target microcontroller. + + monitor reset halt + + Expected output: + + :::bash + SWD DPIDR 0x2ba01477 + target halted due to debug-request, current mode: Thread + xPSR: 0x81000000 pc: 0x0000fff4 msp: 0x20003ff0 + +7. Set a breakpoint on main. + + b main + + Expected output: + + :::bash + Breakpoint 1 at 0x10000224: file main.c, line 62. + Note: automatically using hardware breakpoints for read-only addresses. + +8. Continue the debugger. + + continue + + Expected output (for the Hello World example): + + :::bash + Continuing. + + Breakpoint 1, main () at main.c:62 + 62 printf("Hello World!\n"); + +9. (Optional) Continue exercising the debugger. + + Run `help` for GDB help, or see [Common GDB Commands](#common-gdb-commands). + +10. Quit GDB. + + quit + + Expected output: + + :::bash + A debugging session is active. + + Inferior 1 [Remote target] will be detached. + + Quit anyway? (y or n) [answered Y; input not from terminal] + Detaching from program: C:\Users\User\codespace\Hello_World\build\max78002.elf, Remote target + [Inferior 1 (Remote target) detached] + +11. Quit OpenOCD. In the terminal window running the OpenOCD _server_, press `CTRL + C` to issue the shutdown command. + +#### Common GDB Commands + +| **Command** | **Short Command** | **Description** | +| ------------------------------- | ----------------- | ------------------------------------------------------------ | +| `monitor halt` | | Halt the microcontroller. | +| `monitor reset halt` | | Reset the microcontroller and immediately halt. | +| `monitor max32xxx mass_erase 0` | | Mass erase the flash. | +| `file ` | | Set the program file to `` | +| `load` | | Flash the current program file | +| `continue` | `c` | Continue execution. | +| `break ` | `b ` | Set a breakpoint. `` can be a function name, file:line\_number, or address. | +| `print ` | `p` | Print the value of a variable. Variable must be in current scope. | +| `backtrace` | `bt` | Print contents of the stack frame. | +| `step` | `s` | Execute the next instruction. | +| `next` | `n` | Execute the next line of code. | +| `finish` | `f` | Continue to the end of the current function. | +| `info reg` | | Print the values of the ARM registers. | +| `help` | | Print descriptions for available commands | +| `help ` | | Print description for given command. | +| `quit` | `q` | Quit the GDB client | + +## Build System + +As discussed in [Key Concepts](#key-concepts), an MSDK project is primarily made up of two distinct systems: The **_Build System_** and the _**Project Management System**_. [Getting Started](#getting-started) demonstrates the basic usage and configuration of these systems, while this section offers a detailed reference into the build system's **CLI** and additional documentation on advanced options and use-cases. + +### Build System Overview + +The **Build System** manages the compilation of source code into program binaries and offers a **Command-Line Interface (CLI)** for setting **Build Configuration Variables**. + +The Build System is managed by two files found in a project's root directory, one called **Makefile** and one called **project.mk**. These files are used alongside the [GNU Make](https://www.gnu.org/software/make/) program (which is a part of the MSDK toolchain) to locate and build a project's source code. + +* **Makefile** is the "core" file, and should not be edited directly. Instead, it exposes the **CLI** that can be accessed in the _project.mk_ file, on the command-line, in your system's environment, or via your IDE. It also comes with a default configuration that is suitable for most projects. +* **project.mk** offers a convenient and stable access point for advanced build configuration, and this is the file that should be edited if necessary. + +When the command... + + make + +... is run from inside of a project folder, the program `make` will resolve any project-specific settings and then build the project's source code. + +### Default Build Behavior + +By default, when `make` is run the build system will **auto-search** the **root** project directory for _source code_ (**`*.c`**) and _header files_ (**`*.h`**) to compile into a program binary. The _optional_ **include** and **src** directories are also searched if they exist. + + :::bash + Root Project Directory + ├─ project.mk + ├─ Makefile + ├─ *.h + ├─ *.c + ├─include # <-- Optional + └─ *.h + ├─src # <-- Optional + └─ *.c + +Additionally, a project's build system will come pre-configured for a specific _Target Microcontroller_ and its primary _BSP_. + +The default configuration is suitable for most use-cases, but a system of _Build Configuration Variables_ are available if additional configuration is needed for a project. + +### Build Configuration Variables + +A **Build Configuration Variable** is a [Makefile variable](https://www.gnu.org/software/make/manual/make.html#Using-Variables), and therefore follows the same rules. However, they have been streamlined to be made much easier to use, so most of the [official GNU Make documentation](https://www.gnu.org/software/make/manual/make.html) is only needed for extremely advanced use-cases. + +#### How to Set a Build Configuration Variable + +To set a **standard** configuration variable, **use the `=` syntax**... + + VARIABLE=VALUE + +The **`=`** operater is used for _most_ configuration variables with a few exceptions (documented in the [reference table](#build-configuration-variables-reference-table)) when a variable should contain a **_list_ of values**. In such cases, **use `+=` the syntax** to _add_ values to the list. + + VARIABLE+=VALUE1 + VARIABLE+=VALUE2 + +#### Where to Set a Build Configuration Variable + +For most variables, you should set them in the **project.mk** file (exceptions are documented in the [reference table](#build-configuration-variables-reference-table) and IDE-specific sections). + +For example, to enable hardware floating-point acceleration for a project, the **`MFLOAT_ABI`** configuration variable can be used with a value of **`hard`**. The contents of **project.mk** might then look as follows: + +(_Inside project.mk_) + + :::Make + # This file can be used to set build configuration + # variables. These variables are defined in a file called + # "Makefile" that is located next to this one. + + # For instructions on how to use this system, see + # https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration + + # ********************************************************** + + MFLOAT_ABI=hard # Enable hardware floating point acceleration + +It should also be noted that configuration variables can be set on the **command-line** as well. For example... + + make MFLOAT_ABI=hard + +... will have the same effect. + +Additionally, **environment variables** can be used. For example (on linux)... + + export MFLOAT_ABI=hard + +... will set the hardware floating point acceleration as the default for all projects with an environment variable. + +However, there is a _precedence hierarchy_ that should be taken into consideration. + +#### Precedence Hierarchy + +The precedence hierarchy for the value of a configuration variable is: + +- **IDE/command-line > project.mk > environment variable > default value** + +...meaning if a value is set in an IDE _and_ project.mk, the IDE's value will take precedence. However, the ["override" directive](https://www.gnu.org/software/make/manual/make.html#Override-Directive) can be used in project.mk to give it max precedence. + +#### Build Configuration Variables Reference Table + +| Configuration Variable | Description | Details | +| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | +| | | | +| `TARGET` | Set the _Target Microcontroller_ | **If you are using an IDE, set this variable in the IDE's settings instead of project.mk** | +| `BOARD` | Set the _Board Support Package (BSP)_ | **If you are using an IDE, set this variable in the IDE's settings instead of project.mk.** See [Board Support Packages](#board-support-packages) for more details. When you change this option, it's usually a good idea to fully clean your project, then re-build. | +| | | | +| `MAXIM_PATH` | (Optional) Specify the location of the MSDK | This optional variable can be used to change where the Makefile looks for the MSDK installation. By default, the build system will attempt to locate the MSDK with a relative path. If a project is moved _outside_ of the SDK this variable must be set to the absolute path of the MSDK installation. | +| `CAMERA` | (Optional) Set the Camera drivers to use | This option is only useful for the MAX78000 and MAX78002, and sets the camera drivers to use for the project. Permitted values are `HM01B0`, `HM0360_MONO`, `HM0360_COLOR`, `OV5642`, `OV7692` (default), or `PAG7920`. Camera drivers can be found in the [`Libraries/MiscDrivers/Camera`](Libraries/MiscDrivers/Camera) folder. Depending on the selected camera, a compiler definition may be added to the build. See the `board.mk` file for the active BSP for more details. | +| | | | +| `VPATH` | Where to search for source (.c) files | **Use the `+=` operator with this variable**. This controls where the Makefile will look for **source code** files. If `AUTOSEARCH` is enabled (which it is by default) this controls which paths will be searched. If `AUTOSEARCH` is disabled, this tells the Makefile where to look for the files specified by `SRCS`. | +| `IPATH` | Where to search for header (.h) files | **Use the `+=` operator with this variable**. This controls where the Makefile will look for **header** files. _Unlike_ the `VPATH` option, this is not related to `AUTOSEARCH`. Individual header files are _not_ ever manually added into the build. Instead, you only need to specify the _location_ of your header files. | +| `AUTOSEARCH` | Automatically search for source (.c) files | Enable or disable the automatic detection of .c files on `VPATH` (enabled by default). Set to `0` to disable, or `1` to enable. If auto-search is disabled, source files must be manually added to `SRCS`. | +| `SRCS` | List of source (.c) files to add to the build | **Use the `+=` operator with this variable**. All of the files in this list will be added to the build. If `AUTOSEARCH` is enabled, this is most useful for adding the full absolute path to a singular source file to selectively add to the build. If `AUTOSEARCH` is disabled, _all_ of the source files for the project must be added to `SRCS`, and they must also all be located on an entry in `VPATH`. Otherwise, a full path relative to the Makefile must be used. | +| `PROJECT` | Set the output filename | This controls the output filename of the build. File extensions should _not_ be included in the filename. **For VS Code, you should use the [project_name](#project_name) advanced config option instead of project.mk.** | +| | | | +| `MXC_OPTIMIZE_CFLAGS` | Set the optimization level | See [Optimize Options](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html) for more details. Normal builds will default to `-Og`, which is good for debugging, while release builds will default to `-O2`. | +| `PROJ_CFLAGS` | Add a compiler flag to the build | **Use the `+=` operator with this variable**. Compiler flags can be added with this option, including compiler definitions. For each value, the same syntax should be used as if the compiler flag was passed in via the command-line. These can include standard [GCC options](https://gcc.gnu.org/onlinedocs/gcc-10.4.0/gcc/Option-Summary.html#Option-Summary) and/or [ARM-specific](https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html) options. | +| `PROJ_AFLAGS` | Add an assembler flag to the build | **Use the `+=` operator with this variable**. Assembler flags can be added with this option. | +| `MFLOAT_ABI` | Set the floating point acceleration level | Sets the floating-point acceleration level. Permitted values are `hard`, `soft`, `softfp` (default). To enable full hardware acceleration instructions use `hard`, but keep in mind that _all_ libraries your source code uses must also be compiled with `hard`. If there is any conflict, you'll get a linker error. For more details, see `-mfloat-abi` under [ARM Options](https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html). | +| | | | +| `LINKERFILE` | Set the linkerfile to use | Set the linkerfile with this option. The file should exists in `Libraries/CMSIS/Device/Maxim/TARGET/Source/GCC` in the MSDK, or it should be placed inside the root directory of the project. | +| `PROJ_LDFLAGS` | Add a linker flag to the build | **Use the `+=` operator with this variable**. Flags can be passed to the linker with this option. See [GCC Options for Linking](https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html#Link-Options) | +| | | | +| `LIB_BOARD` | Include the BSP library (enabled by default) | Inclusion of the Board-Support Package (BSP) library, which is enabled by default, can be toggled with this variable. Set to `0` to disable, or `1` to enable. | +| `LIB_PERIPHDRIVERS` | Include the peripheral driver library (enabled by default) | The peripheral driver library can be toggled with this option. If disabled, you'll lose access to the higher-level driver functions but still have access to the register-level files. Set to `0` to disable, or `1` to enable. | +| `LIB_CMSIS_DSP` | Include the CMSIS-DSP library | The [CMSIS-DSP library](https://www.keil.com/pack/doc/CMSIS/DSP/html/index.html) can be enabled with this option. Set to `0` to disable, or `1` to enable. | +| `LIB_CORDIO` | Include the Cordio library | The Cordio BLE library can be included with this option. This is only applicable towards microcontrollers with an integrated BLE controller. | +| `LIB_FCL` | Include the Free Cryptographic Library (FCL) | This option toggles the Free Cryptographic Library (FCL), which is a collection of software-implemented common cryptographic functions can be included with this option. Set to `0` to disable, or `1` to enable. | +| `LIB_FREERTOS` | Include the FreeRTOS library | The [FreeRTOS](https://freertos.org/) library can be enabled with this option, which is an open-source Real-Time Operating System (RTOS). Set to `0` to disable, or `1` to enable. | +| `LIB_LC3` | Include the LC3 codec library | This option enables the inclusion of the Low Complexity Communication Codec (LC3), which is an efficient low latency audio codec. Set to `0` to disable, or `1` to enable. | +| `LIB_LITTLEFS` | Include the littleFS library | This option toggles the ["Little File System"](https://github.com/littlefs-project/littlefs) library - a small filesystem library designed for microcontrollers. Set to `0` to disable, or `1` to enable. | +| `LIB_LWIP` | Include the lwIP library | | +| `LIB_MAXUSB` | Include the MaxUSB library | This option toggles the inclusion of the MAXUSB library, which facilitates the use of the native USB peripherals on some microcontrollers. Set to `0` to disable, or `1` to enable. | +| `LIB_SDHC` | Include the SDHC library | This options toggles the Secure Digital High Capacity (SDHC) library, which can be used to interface with SD cards. Additionally, it enables the [FatFS](http://elm-chan.org/fsw/ff/00index_e.html) library, which implements a generic FAT filesystem. | +| | | | +| `SBT` | Toggle SBT integration | Toggles integration with the [Secure Boot Tools (SBTs)](https://www.analog.com/en/design-center/evaluation-hardware-and-software/software/software-download.html?swpart=SFW0015360C). These are a suite of applications designed for use with microcontrollers that have secure bootloaders. When this is enabled, some additional rules become available such as `make sla` and `make scpa`. Set to `0` to disable or `1` to enable. | +| `MAXIM_SBT_DIR` | Where to find the SBTs | This option can be used to manually specify the location of the SBTs. Usually, this is not necessary. By default, the `Tools/SBT` directory of the MaximSDK will be searched. If the [SBT installer](https://www.analog.com/en/design-center/evaluation-hardware-and-software/software/software-download.html?swpart=SFW0015360C) is used, it will set the `MAXIM_SBT_DIR` environment variable to point to itself automatically. | +| `TARGET_SEC` | Secure part number to use | Some secure microcontrollers have multiple secure variants, and this option can be used to specify the variant to use with the SBTs. Defaults are intelligently selected, and can be found in `$(MAXIM_SBT_DIR)/SBT-config.mk` | +| `SCP_PACKETS` | Where to build the scp_packets folder | Defaults to `build/scp_packets` | +| `TEST_KEY` | Which test key to sign applications with | Defaults to `$(MAXIM_SBT_DIR)/devices/$(TARGET_SEC)/keys/maximtestcrk.key`, which is the Maxim test key that can be used for development. | + +## Peripheral Driver API + +### Overview + +A microcontroller is made up of a Central Processing Unit (CPU) that is surrounded by additional _peripheral_ hardware blocks such as timers, memory controllers, UART controllers, ADCs, RTCs, audio interfaces, and many more. The **Peripheral Driver API** is an important core library in the MSDK that allows the CPU to utilize the microcontroller's hardware blocks over a higher-level **_Application Programming Interface (API)_**. + +![Figure 38](res/Fig38.jpg) + +A detailed API reference can be found in the [Documentation](Documentation) folder of the MSDK installation for each microcontroller. This documentation is auto-generated with DoxyGen from the API's source code, and is organized into _modules_ matching each of the available hardware peripherals. The MSDK will contain at _minimum_ one example per module demonstrating its usage. + +### Organization + +The Peripheral Driver API's source code is organized as follows: + +- **Header files _(.h)_** can be found in the [`Libraries/PeriphDrivers/Include`](Libraries/PeriphDrivers/Include) folder. + - These files contain function _declarations_ for the API, describing the function prototypes and their associated documentation. +- **Source files _(.c)_** can be found in the [`Libraries/PeriphDrivers/Source`](Libraries/PeriphDrivers/Source) folder. + - These file contain the function _definitions_ for the API - the _implementations_ of the functions declared by the header files. + +The _**implementation**_ files are further organized based on _**die type**_ and **_hardware revision_**. This is worthy to note when browsing or debugging through the drivers. + +- The **_die type_** files follow the **`_MEXX`** or **`_AIXX`** naming convention + - These file's responsibility is to manage microcontroller-specific implementation details that may interact with other peripheral APIs _before_ ultimately calling the revision-specific files. +- The **_hardware** revision_ files follow the **`_revX`** naming convention. + - These files contain the _pure_ driver implementation for a peripheral block, and typically interact with the hardware almost entirely at the register level. + +### API Reference Manuals + +A full Peripheral Driver API reference manual is available for each microcontroller below. + +- [MAX32520 API](Libraries/PeriphDrivers/Documentation/MAX32520/index.html) + +- [MAX32650 API](Libraries/PeriphDrivers/Documentation/MAX32650/index.html) + +- [MAX32655 API](Libraries/PeriphDrivers/Documentation/MAX32655/index.html) + +- [MAX32660 API](Libraries/PeriphDrivers/Documentation/MAX32660/index.html) + +- [MAX32665-MAX32668 API](Libraries/PeriphDrivers/Documentation/MAX32665/index.html) + +- [MAX32670 API](Libraries/PeriphDrivers/Documentation/MAX32670/index.html) + +- [MAX32672 API](Libraries/PeriphDrivers/Documentation/MAX32672/index.html) + +- [MAX32675 API](Libraries/PeriphDrivers/Documentation/MAX32675/index.html) + +- [MAX32680 API](Libraries/PeriphDrivers/Documentation/MAX32680/index.html) + +- [MAX78000 API](Libraries/PeriphDrivers/Documentation/MAX78000/index.html) + +- [MAX78002 API](Libraries/PeriphDrivers/Documentation/MAX78002/index.html) + +## Libraries + +The MSDK contains a large number of **libraries**, both third-party and in-house. These libraries are an extension to the "core" SDK resources and contain drivers for miscellaneous _**external**_ components such as TFT displays, cameras, accelerometers, audio codecs, and other devices. The MSDK also contains libraries for more advanced _**internal**_ hardware peripherals that provide an _additional_ higher-level abstraction layer above the [Peripheral Driver API](#peripheral-driver-api) such as USB, the SDHC interface, and the Cordio BLE stack. + +These libraries may also offer their _own_ Build Configuration Variables in addition to those already available in the [Build System](#build-system). These additional build options are enabled alongside the library itself via a convenient *toggle switch* (See the **"Libraries"** section of the _[Build Configuration Variables](#build-configuration-variables-reference-table)_). + +Source code is located in the [Libraries](Libraries) folder of the SDK and managed with the `Libraries/libs.mk` file, which comes pre-included in each example project. + +### CMSIS-DSP + +The CMSIS-DSP library provides a suite of common **Digital Signal Processing _(DSP)_** functions that take advantage of hardware accelerated _Floating Point Unit (FPU)_ available on microcontrollers with Arm Cortex-M cores. This library is distributed in the MSDK as a pre-compiled static library file and the MSDK maintains a port of the official code examples in the **ARM-DSP** [Examples](Examples) folder for each microcontroller. + +Please refer to the [CMSIS-DSP official documentation](https://www.keil.com/pack/doc/CMSIS/DSP/html/index.html) for more detailed documentation on the library functions and usage. + +#### CMSIS-DSP Supported Parts + +- All microcontrollers with a Cortex M4 core are supported. + +--- + +### Cordio Bluetooth Low Energy + +The Cordio Bluetooth Low Energy (BLE) library provides a full BLE stack for microcontrollers with an integrated BLE controller. + +#### Cordio Supported Parts + +- MAX32655 +- MAX32665 +- MAX32680 +- MAX32690 + +--- + +### MAXUSB + +The MAXUSB library provides a higher-level interface for utilizing the built-in USB controller hardware available on some microcontrollers. This allows the microcontroller to enumerate as a USB device without the need for an external USB controller IC. + +#### MAXUSB Supported Parts + +- MAX32570 +- MAX32650 +- MAX32655 & MAX32656 +- MAX32665-MAX32668 +- MAX32690 +- MAX78002 + +--- + +### Miscellaneous Drivers + +The [`Libraries/MiscDrivers`](Libraries/MiscDrivers) folder of the MSDK contains drivers for miscellaneous external components such as TFT displays, cameras, audio codecs, PMICs, pushbuttons, etc. These resources are usually closely tied with the [Board Support Packages](#board-support-packages). + +--- + +### SDHC + +The **Secure Digital High Capacity *(SDHC)*** library offers a higher-level interface built on top of the SDHC [Peripheral Driver API](#peripheral-driver-api) that includes a [FatFS File System](http://elm-chan.org/fsw/ff/00index_e.html) implementation for managing files on SD cards. + +#### SDHC Supported Parts + +- MAX32650 +- MAX32570 +- MAX32665-MAX32668 +- MAX78002 diff --git a/Documentation/build.py b/Documentation/build.py new file mode 100644 index 00000000000..7f8aed37161 --- /dev/null +++ b/Documentation/build.py @@ -0,0 +1,31 @@ +from pathlib import Path +import shutil +from subprocess import run +from mkdocs.commands.build import build +from mkdocs.config import load_config + +# Locate some directories relative to this file +here = Path(__file__).parent +repo = here.parent +periph_docs_dir = repo / "Libraries" / "PeriphDrivers" / "Documentation" + +# Run Doxygen builds +for f in periph_docs_dir.glob("*_Doxyfile"): + run(f"doxygen {f.name}", cwd=f.parent) + micro = f.name.split("_")[0].upper() # max32xxx_Doxyfile -> MAX32XXX + dest = here / "Libraries" / "PeriphDrivers" / "Documentation" / micro + # ^ Recreate directory structure so built links work + shutil.copytree(periph_docs_dir / micro, dest, dirs_exist_ok=True) + +# Pre-populate markdown files +for f in repo.glob("*.md"): + shutil.copy(f, here) + +# Pre-populate resources folder +shutil.copytree(repo / "res", here / "res", dirs_exist_ok=True) + +# Run mkdocs build +# A subprocess is used because the Mkdocs Python API does not print any logging info +print("Building docs (this could take a few minutes)...") +run("mkdocs build") # Build with CLI +# build(load_config()) # Build with Python API \ No newline at end of file diff --git a/Documentation/index.md b/Documentation/index.md new file mode 100644 index 00000000000..af9bea4b710 --- /dev/null +++ b/Documentation/index.md @@ -0,0 +1,12 @@ +# Analog Devices MSDK Documentation + +Welcome to the MSDK Documentation. + +The Maxim Microcontrollers SDK (MSDK), now a part of [Analog Devices](https://www.analog.com/en/index.html), contains the necessary software and tools to develop firmware for the [MAX32xxx and MAX78xxx Microcontrollers](https://www.analog.com/en/parametricsearch/10984). + +To **get started** see the [**User Guide**](USERGUIDE.md). + +For **development resources**: + +* [Github](https://github.com/Analog-Devices-MSDK/msdk) +* [Contributing](CONTRIBUTING.md) diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt new file mode 100644 index 00000000000..a0a99f1b975 --- /dev/null +++ b/Documentation/requirements.txt @@ -0,0 +1 @@ +mkdocs >= 1.4.2 \ No newline at end of file diff --git a/Documentation/res/Fig1.jpg b/Documentation/res/Fig1.jpg new file mode 100644 index 00000000000..a4f117e8607 Binary files /dev/null and b/Documentation/res/Fig1.jpg differ diff --git a/Documentation/res/Fig10.jpg b/Documentation/res/Fig10.jpg new file mode 100644 index 00000000000..40ac40d6687 Binary files /dev/null and b/Documentation/res/Fig10.jpg differ diff --git a/Documentation/res/Fig11.jpg b/Documentation/res/Fig11.jpg new file mode 100644 index 00000000000..6fed7ad1dec Binary files /dev/null and b/Documentation/res/Fig11.jpg differ diff --git a/Documentation/res/Fig16.jpg b/Documentation/res/Fig16.jpg new file mode 100644 index 00000000000..8b5a2f176fb Binary files /dev/null and b/Documentation/res/Fig16.jpg differ diff --git a/Documentation/res/Fig17.jpg b/Documentation/res/Fig17.jpg new file mode 100644 index 00000000000..3dce5594e41 Binary files /dev/null and b/Documentation/res/Fig17.jpg differ diff --git a/Documentation/res/Fig18.jpg b/Documentation/res/Fig18.jpg new file mode 100644 index 00000000000..ccc12ac574c Binary files /dev/null and b/Documentation/res/Fig18.jpg differ diff --git a/Documentation/res/Fig19.jpg b/Documentation/res/Fig19.jpg new file mode 100644 index 00000000000..39094e06519 Binary files /dev/null and b/Documentation/res/Fig19.jpg differ diff --git a/Documentation/res/Fig2.jpg b/Documentation/res/Fig2.jpg new file mode 100644 index 00000000000..9afd22f125a Binary files /dev/null and b/Documentation/res/Fig2.jpg differ diff --git a/Documentation/res/Fig20.jpg b/Documentation/res/Fig20.jpg new file mode 100644 index 00000000000..991c4159721 Binary files /dev/null and b/Documentation/res/Fig20.jpg differ diff --git a/Documentation/res/Fig21.jpg b/Documentation/res/Fig21.jpg new file mode 100644 index 00000000000..dadf0726e04 Binary files /dev/null and b/Documentation/res/Fig21.jpg differ diff --git a/Documentation/res/Fig22.jpg b/Documentation/res/Fig22.jpg new file mode 100644 index 00000000000..2fe5153ddb2 Binary files /dev/null and b/Documentation/res/Fig22.jpg differ diff --git a/Documentation/res/Fig23.jpg b/Documentation/res/Fig23.jpg new file mode 100644 index 00000000000..965a0e37936 Binary files /dev/null and b/Documentation/res/Fig23.jpg differ diff --git a/Documentation/res/Fig24.jpg b/Documentation/res/Fig24.jpg new file mode 100644 index 00000000000..e13086e38ce Binary files /dev/null and b/Documentation/res/Fig24.jpg differ diff --git a/Documentation/res/Fig25.jpg b/Documentation/res/Fig25.jpg new file mode 100644 index 00000000000..9beb6806af8 Binary files /dev/null and b/Documentation/res/Fig25.jpg differ diff --git a/Documentation/res/Fig26.jpg b/Documentation/res/Fig26.jpg new file mode 100644 index 00000000000..cb4a3e3bf18 Binary files /dev/null and b/Documentation/res/Fig26.jpg differ diff --git a/Documentation/res/Fig27.jpg b/Documentation/res/Fig27.jpg new file mode 100644 index 00000000000..2cd171d1940 Binary files /dev/null and b/Documentation/res/Fig27.jpg differ diff --git a/Documentation/res/Fig28.jpg b/Documentation/res/Fig28.jpg new file mode 100644 index 00000000000..ecdf5b28123 Binary files /dev/null and b/Documentation/res/Fig28.jpg differ diff --git a/Documentation/res/Fig29.jpg b/Documentation/res/Fig29.jpg new file mode 100644 index 00000000000..ad7639c6604 Binary files /dev/null and b/Documentation/res/Fig29.jpg differ diff --git a/Documentation/res/Fig3.jpg b/Documentation/res/Fig3.jpg new file mode 100644 index 00000000000..7ad368c0623 Binary files /dev/null and b/Documentation/res/Fig3.jpg differ diff --git a/Documentation/res/Fig30.jpg b/Documentation/res/Fig30.jpg new file mode 100644 index 00000000000..67803ba2868 Binary files /dev/null and b/Documentation/res/Fig30.jpg differ diff --git a/Documentation/res/Fig31.jpg b/Documentation/res/Fig31.jpg new file mode 100644 index 00000000000..6522c19593f Binary files /dev/null and b/Documentation/res/Fig31.jpg differ diff --git a/Documentation/res/Fig32.jpg b/Documentation/res/Fig32.jpg new file mode 100644 index 00000000000..b61b0febee4 Binary files /dev/null and b/Documentation/res/Fig32.jpg differ diff --git a/Documentation/res/Fig33.jpg b/Documentation/res/Fig33.jpg new file mode 100644 index 00000000000..1a0d52a3686 Binary files /dev/null and b/Documentation/res/Fig33.jpg differ diff --git a/Documentation/res/Fig34.jpg b/Documentation/res/Fig34.jpg new file mode 100644 index 00000000000..b5ff0a37f84 Binary files /dev/null and b/Documentation/res/Fig34.jpg differ diff --git a/Documentation/res/Fig35.jpg b/Documentation/res/Fig35.jpg new file mode 100644 index 00000000000..1c8b7097a01 Binary files /dev/null and b/Documentation/res/Fig35.jpg differ diff --git a/Documentation/res/Fig36.jpg b/Documentation/res/Fig36.jpg new file mode 100644 index 00000000000..cfe3aa963c5 Binary files /dev/null and b/Documentation/res/Fig36.jpg differ diff --git a/Documentation/res/Fig37.jpg b/Documentation/res/Fig37.jpg new file mode 100644 index 00000000000..ab87a15e0be Binary files /dev/null and b/Documentation/res/Fig37.jpg differ diff --git a/Documentation/res/Fig38.jpg b/Documentation/res/Fig38.jpg new file mode 100644 index 00000000000..1e9a1ad8667 Binary files /dev/null and b/Documentation/res/Fig38.jpg differ diff --git a/Documentation/res/Fig39.jpg b/Documentation/res/Fig39.jpg new file mode 100644 index 00000000000..08d56008c57 Binary files /dev/null and b/Documentation/res/Fig39.jpg differ diff --git a/Documentation/res/Fig4.jpg b/Documentation/res/Fig4.jpg new file mode 100644 index 00000000000..33ca4a9d9c3 Binary files /dev/null and b/Documentation/res/Fig4.jpg differ diff --git a/Documentation/res/Fig5.jpg b/Documentation/res/Fig5.jpg new file mode 100644 index 00000000000..07e1dccb148 Binary files /dev/null and b/Documentation/res/Fig5.jpg differ diff --git a/Documentation/res/Fig6.jpg b/Documentation/res/Fig6.jpg new file mode 100644 index 00000000000..84b7792f814 Binary files /dev/null and b/Documentation/res/Fig6.jpg differ diff --git a/Documentation/res/Fig7.jpg b/Documentation/res/Fig7.jpg new file mode 100644 index 00000000000..f0feec86af0 Binary files /dev/null and b/Documentation/res/Fig7.jpg differ diff --git a/Documentation/res/Fig8.jpg b/Documentation/res/Fig8.jpg new file mode 100644 index 00000000000..245025d120a Binary files /dev/null and b/Documentation/res/Fig8.jpg differ diff --git a/Documentation/res/Fig9.jpg b/Documentation/res/Fig9.jpg new file mode 100644 index 00000000000..b8ef429bb58 Binary files /dev/null and b/Documentation/res/Fig9.jpg differ diff --git a/Documentation/res/eclipse_start.jpg b/Documentation/res/eclipse_start.jpg new file mode 100644 index 00000000000..6ba782d8d22 Binary files /dev/null and b/Documentation/res/eclipse_start.jpg differ diff --git a/Documentation/res/symlinks-windows.jpg b/Documentation/res/symlinks-windows.jpg new file mode 100644 index 00000000000..a3caf105877 Binary files /dev/null and b/Documentation/res/symlinks-windows.jpg differ diff --git a/README.md b/README.md index eacebfc4865..cf16c22dd97 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,86 @@ # Analog Devices MSDK -## License Agreement - -**© Copyright (C) 2022 Maxim Integrated Products, Inc., All rights Reserved.** - -This software is protected by copyright laws of the United States and -of foreign countries. This material may also be protected by patent laws -and technology transfer regulations of the United States and of foreign -countries. This software is furnished under a license agreement and/or a -nondisclosure agreement and may only be used or reproduced in accordance -with the terms of those agreements. Dissemination of this information to -any party or parties not specified in the license agreement and/or -nondisclosure agreement is expressly prohibited. - -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Software. - -**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES -OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE.** - -Except as contained in this notice, the name of **Maxim Integrated Products, Inc.** -shall not be used except as stated in the **Maxim Integrated Products, Inc. Branding Policy.** - -The mere transfer of this software does not imply any licenses -of trade secrets, proprietary technology, copyrights, patents, -trademarks, maskwork rights, or any other form of intellectual -property whatsoever. **Maxim Integrated Products, Inc.** retains all -ownership rights. +## Introduction -[Final Copyright](https://www.maximintegrated.com/en/aboutus/legal/copyrights/default-copyright.html "Final Copyright") +The Maxim Microcontrollers SDK (MSDK), now a part of [Analog Devices](https://www.analog.com/en/index.html), contains the necessary software and tools to develop firmware for the [MAX32xxx and MAX78xxx Microcontrollers](https://www.analog.com/en/parametricsearch/10984). This includes register files, peripheral drivers, system startup files, documentation, various utilities, third-party libraries, IDE support files, and a toolchain. -[Final Software License Agreement](https://www.maximintegrated.com/en/aboutus/legal/sla/no-distribute.html "Final SLA") +**This repository** contains the latest ***source code*** of the MSDK and is used for *development*. It does _not_ contain the MSDK _toolchain_, which is a separate collection of programs used to build, program, and debug the contents of this repo on hardware. -## Introduction +## Installation -The Maxim Microcontrollers SDK (MSDK), now a part of Analog Devices, contains tools and resources to develop firmware for the [MAX-series of microcontrollers](https://www.maximintegrated.com/en/products/microcontrollers.html). This includes register files, peripheral drivers, system startup files, documentation, various utilities, third-party libraries, IDE support files, and a toolchain. +The full MSDK is available via an Automatic Installer, and installation instructions can be found in the [MSDK User Guide](Documentation/USERGUIDE.md). -The following development environments are supported: +Users who would like to use the latest beeding-edge _development_ resources can follow [Developing from the Repo](#developing-from-the-repo) below, but this should only be done **_after_** installing the full MSDK above. -* Command-line development -* Eclipse -* Visual Studio Code -* IAR -* Keil +## Contributing -This repository contains the latest source code of the MSDK and is used for development. It does _not_ contain the MSDK _toolchain_, which is a separate collection of programs used to build, program, and debug the contents of this repo on hardware. +Contributions to the MSDK are welcome. See [CONTRIBUTING.md](Documentation/CONTRIBUTING.md) for guidelines. -The full MSDK is available via an [Automatic Installer](#automatic-installer), which pulls from the latest release tag of this repo and packages it alongside the toolchain. +## Developing from the Repo -Users who would like to retrieve the bleeding-edge development copies of the MSDK resources can pull them from this repository. See [Developing from the Repo](#developing-from-the-repo). +This section assumes some familiarity with the MSDK and the standard setup procedure for its supported development environments. First-time users should work from a standard MSDK installation instead. -## Installation +### Cloning -### Automatic Installer +This repo can be cloned using [Git](https://git-scm.com/) to obtain the latest development copies of the MSDK source code. -The MSDK is available via an automatic installer for the platforms below. The automatic installer will retrieve the latest _release_ version of this repository and the latest toolchain for your OS. +1. Download and install [Git](https://git-scm.com/downloads). -* [Windows 10](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0010820A) +2. Add an SSH key to your Github account. See the [Github Docs on SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for instructions. -* [Ubuntu Linux](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018720A) +3. Open a terminal on your system. - * This file must be made executable before it can be run. Use the command `chmod +x MaximMicrosSDK_linux.run`. Alternatively, set “Allow executing as program” in the Ubuntu GUI. +4. `cd` into a directory ***without any spaces in its filepath***. The repo will be cloned inside of this folder. -* [MacOS](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018610A) +5. Clone the repository using the `git clone` command. - * Some additional steps are required to complete the automatic installation on MacOS. See the [Completing the Installation on MacOS](#completing-the-installation-on-macos) below. + * **SSH clone (recommended)** -### Cloning the Github Repo + ```bash + git clone --recurse git@github.com:Analog-Devices-MSDK/msdk.git + ``` -This repo can be cloned to obtain the latest development copies of the MSDK source code. + * **HTTPS Clone** -1. First, you'll need to set up an SSH key for your Github account. See the [Github Docs on SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) for instructions. + ```bash + git clone --recurse https://github.com/Analog-Devices-MSDK/msdk.git + ``` -2. Once you've set up an SSH key for your account, you can clone this repository with the command: + Expected output: - ```shell - git clone --recurse git@github.com:Analog-Devices-MSDK/msdk.git - ``` + ```shell + Cloning into 'msdk'... + remote: Enumerating objects: 65643, done. + remote: Counting objects: 100% (8622/8622), done. + remote: Compressing objects: 100% (4175/4175), done. + remote: Total 65643 (delta 4472), reused 8166 (delta 4215), pack-reused 57021 + Receiving objects: 100% (65643/65643), 231.23 MiB | 15.51 MiB/s, done. + Resolving deltas: 100% (48045/48045), done. + Updating files: 100% (20873/20873), done. + Submodule 'Libraries/Cordio' (git@github.com:Analog-Devices-MSDK/Libraries-cordio.git) registered for path 'Libraries/Cordio' + Cloning into '/home/jakecarter/repos/test/msdk/Libraries/Cordio'... + remote: Enumerating objects: 2905, done. + remote: Counting objects: 100% (228/228), done. + remote: Compressing objects: 100% (153/153), done. + remote: Total 2905 (delta 81), reused 193 (delta 70), pack-reused 2677 + Receiving objects: 100% (2905/2905), 10.10 MiB | 14.53 MiB/s, done. + Resolving deltas: 100% (1209/1209), done. + Submodule path 'Libraries/Cordio': checked out '91cef69d49e5db8b32602b089007ab1aafe26900' + ``` -The source code in the repo can now be copied elsewhere, but if you'd like to set it up for "in-place" development you'll also need to perform a few manual steps to link the toolchain. See [Developing from the Repo](#developing-from-the-repo). +### Toolchain Setup -### Developing from the Repo +This repository contains the MSDK's *source code* only. In order to develop on it directly the toolchain must be made available at the same file-paths as the full MSDK installation. The easiest way to do this is to retrieve the toolchain with the automatic installer and then create symbolic links. This section walks through the process. -The Github repo contains source code only. In order to develop on it directly the toolchain must be made available at the same file-paths as the full MSDK installation. The easiest way to do this is to retrieve the toolchain with the automatic installer and then create symbolic links. This section walks through the process. +1. Install the MSDK via the [Automatic Installer](Documentation/USERGUIDE.md#installation) for your OS if you haven't already. -1. Install the toolchain via the [Automatic Installer](#automatic-installer) for your OS if you haven't already. - - At minimum, install the components: + At ***minimum***, install the following components: * GNU RISC-V Embedded GCC * GNU Tools for ARM Embedded Processors * Open On-Chip Debugger * MSYS2 (if you're on Windows 10) - If you've already installed the MSDK, run the `MaintenanceTool` program to ensure these components are selected and updated to the latest version. - -2. Clone the Github repository to an accessible location without any spaces in its filepath. See [Cloning the Github Repo](#cloning-the-github-repo). +2. [Clone](#cloning) the Github repository to an accessible location *without any spaces in its filepath*. 3. Create symbolic directory links to link the toolchain at the expected locations. @@ -131,17 +112,22 @@ The Github repo contains source code only. In order to develop on it directly t ```cmd C:\Users\Username\repos\msdk>mklink /D Tools\GNUTools C:\MaximSDK\Tools\GNUTools symbolic link created for Tools\GNUTools <<===>> C:\MaximSDK\Tools\GNUTools - + C:\Users\Username\repos\msdk>mklink /D Tools\OpenOCD C:\MaximSDK\Tools\OpenOCD symbolic link created for Tools\OpenOCD <<===>> C:\MaximSDK\Tools\OpenOCD - + C:\Users\Username\repos\msdk>mklink /D Tools\MSYS2 C:\MaximSDK\Tools\MSYS2 symbolic link created for Tools\MSYS2 <<===>> C:\MaximSDK\Tools\MSYS2 - + C:\Users\Username\repos\msdk>mklink /D Tools\xPack C:\MaximSDK\Tools\xPack symbolic link created for Tools\xPack <<===>> C:\MaximSDK\Tools\xPack - ``` + + The [Tools](Tools) directory of the MSDK repo should now contain valid symbolic links to the full installation's toolchain. + + ![Symbolic links (windows)](res/symlinks-windows.jpg) + + 4. Proceed to On **Linux/MacOS**: * Open a terminal @@ -184,77 +170,28 @@ The Github repo contains source code only. In order to develop on it directly t 4. The MSDK now contains a virtual copy of the toolchain at the correct locations. Some additional setup may be required to use it depending on your chosen development environment. See [Setup](#setup) below. -### Completing the Installation on MacOS - -On MacOS, some additional missing packages must be manually installed via [Homebrew](https://brew.sh/). - -**For non-M1 platforms:** - -1. Follow the instructions on the [Homebrew home page](https://brew.sh/) to install Homebrew on your system. - -2. Then, open a terminal and run the command... - - ```shell - brew install libusb-compat libftdi hidapi libusb - ``` - -**For M1 platforms**: - -The MSDK's OpenOCD binaries ship pre-compiled for Intel Silicon (i386). As a result, you should use a [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) terminal on M1 platforms to install the _i386 version_ of Homebrew and retrieve OpenOCD's dependencies with it. This ensures OpenOCD gets the packages with the architecture it needs. From there, Rosetta will handle the rest and allow running the binaries on the M1 platform's arm64 architecture. - -The i386 version of Homebrew can be installed in parallel with the arm64 version, and typically installs into a separate filesystem. - -1. Open a terminal and update Rosetta. - - ```shell - softwareupdate --install-rosetta --agree-to-license - ``` - -2. Close the terminal. - -3. Run a new terminal in Rosetta: - - 1. Go to Finder > Applications and find your Terminal - - 2. Right-Click Terminal and Duplicate it. Rename it to "Terminal i386". - - 3. Rich-Click "Terminal i386" > Get Info > Enable "Open using Rosetta" - - 4. Launch the new "Terminal i386" and type `arch` to verify that it says `i386` now. - -4. From your Rosetta terminal follow the instructions on the [Homebrew home page](https://brew.sh/) to install Homebrew on your system. - -5. Verify the correct version of Homebrew is running from your Rosetta terminal using the `which brew` command. This should return a path beginning with `/usr/local`. - - **Note:** On systems with multiple or pre-existing Homebrew installations, the arm64 version of Homebrew may still take precendence over the newly installed x86_64 version. If `which brew` contains `/opt/homebrew` instead, you may need to edit your terminal profile's startup script. Alternatively, you can run the correct Homebrew binary directly. `/usr/local/homebrew/bin/brew ...` - -6. Run the command... - - ```shell - brew install libusb-compat libftdi hidapi libusb - ``` - - (or, if you need to use the absolute path) - - ```shell - /usr/local/homebrew/bin/brew install libusb-compat libftdi hidapi libusb - ``` +### Environment Setup (Visual Studio Code) -## Setup +To use Visual Studio Code with the _development repository_ simply set `MAXIM_PATH` to the cloned location of the _development repo_ instead of the full *release MSDK* location in your user settings.json file and reload VS Code. If you have not previously configured VS Code, see See [Setup (VS Code)](USERGUIDE.md#setup-vs-code) in the User Guide. -The setup guides below demonstrate how to configure supported development environments for use with this repository. It assumes a successful [installation](#installation). +The *release* `MAXIM_PATH` can be commented out for later to easily switch back. For example: -### Visual Studio Code - -All example projects in the MSDK come pre-configured with [Visual Studio Code](https://code.visualstudio.com/) project folders that are managed by the [VSCode-Maxim](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop) repository. They can be found in the `.vscode` sub-folder of each example, and include local copies of the VSCode-Maxim documentation. - -The setup procedure is exactly the same as a standard VSCode-Maxim installation (instructions [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#installation)), except on step 9 `"MAXIM_PATH"` can be set to the location of this repository instead of the release version of the MSDK. - -See [Usage](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#usage) from the VSCode-Maxim readme for more details on using the projects once setup is complete. +```json +{ + // There may be other settings up here... + + // "MAXIM_PATH":"C:/MaximSDK", // Work from the release MSDK + "MAXIM_PATH":"C:/Users/Username/repos/msdk", // Work from the development MSDK + "update.mode": "manual", + "extensions.autoUpdate": false, + + // There may be other settings down here... +} +``` -### Eclipse +### Environment Setup (Eclipse) -Eclipse itself should be launched with the `Tools/Eclipse/cdt/eclipse(.bat/.sh)` script, which will set `MAXIM_PATH` and a few other environment variables for use with the _release_ version of the MSDK by default. Therefore, there are two options for using Eclipse with the MSDK development repository: +Eclipse itself should be launched with the `Tools/Eclipse/cdt/eclipse(.bat/.sh)` script, which will set `MAXIM_PATH` and a few other environment variables for use with the _release_ version of the MSDK by default. Therefore, there are two options for using Eclipse with the MSDK *development* repository: #### Option 1 - Project Settings @@ -300,19 +237,17 @@ The project is now configured for use with the MSDK development repo, and subseq set MAXIM_PATH=C:\Users\Username\repos\msdk ``` -**Note:** This will configure _all_ Eclipse sessions to load resources from the development repo. - -### Command-line Setup +​ **Note:** This will configure _all_ Eclipse sessions to load resources from the development repo. -This section assumes some familiarity with basic terminal concepts such as your system's Path and environment variables. Since there are such wide variety of terminal applications and Operating Systems, these instructions are intentionally left somewhat generic. +### Environment Setup (Command-Line) -However, an example `.bashrc` file is provided below that can be referenced for most Unix systems. Simply copy and paste the entries below into your shell's startup script and edit `MAXIM_PATH` to the installed location of this repository. +Pointing the `MAXIM_PATH` environment variable to the cloned location of the repository and restarting the shell is sufficient to configure the command-line to use the development resources. The shell startup script added in [Setup (Command-Line)](USERGUIDE.md#setup-command-line) can be modified as follows: ```bash -# ~/.bashrc - -# Set MAXIM_PATH environment variable -export MAXIM_PATH=#changeme! +# Set MAXIM_PATH to point to the MSDK (release) +# export MAXIM_PATH=$HOME/MaximSDK +# Set MAXIM_PATH to point to the MSDK (development) +export MAXIM_PATH=$HOME/repos/msdk # Add Arm Embedded GCC to path (v10.3) export ARM_GCC_ROOT=$MAXIM_PATH/Tools/GNUTools/10.3 @@ -327,110 +262,39 @@ export OPENOCD_ROOT=$MAXIM_PATH/Tools/OpenOCD export PATH=$OPENOCD_ROOT:$PATH ``` -More generic instructions can be found below. These instructions will use Unix syntax unless a step is targeted specifically at Windows. - -1. Create a new environment variable on your system called `MAXIM_PATH`. Set its value to the installed location of this repository. - -2. Add the following entries to your system's path: - - * `$MAXIM_PATH/Tools/GNUTools/10.3/bin` - * `$MAXIM_PATH/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2/bin` - * `$MAXIM_PATH/Tools/OpenOCD` - -3. (Windows only) Add the following entry to your system's path: - * `%MAXIM_PATH%/Tools/MSYS2/usr/bin` - -4. Restart your shell, and verify the tools are accessible with the following commands: - - 1. Arm Embedded GCC: - - ```shell - $ arm-none-eabi-gcc -v - - Using built-in specs. - COLLECT_GCC=arm-none-eabi-gcc - - # ... Lots of other info will be printed here... - - Supported LTO compression algorithms: zlib - gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10) - ``` - - 2. xPack RISC-V GCC: - - ```shell - $ riscv-none-embed-gcc -v - - Using built-in specs. - COLLECT_GCC=riscv-none-embed-gcc - - # ... Lots of other info will be printed here... - - Supported LTO compression algorithms: zlib - gcc version 10.2.0 (xPack GNU RISC-V Embedded GCC x86_64) - ``` - - 3. OpenOCD - - ```shell - $ openocd -v - - Open On-Chip Debugger 0.11.0+dev-g56a818e4c (2022-07-19-19:00) - Licensed under GNU GPL v2 - For bug reports, read - http://openocd.org/doc/doxygen/bugs.html - ``` - - **Note:** The automatic installer should have installed OpenOCD dependencies. Should any missing package errors get thrown on this command they can be resolved by installing the missing packages manually. - - **On linux:** - - ```shell - sudo apt-get install libusb-1.0 libusb-0.1 libhidapi-libusb0 libhidapi-hidraw0 - ``` - - **On MacOS with [Homebrew](https://brew.sh/)** - - ```shell - brew install libusb-compat libftdi hidapi libusb - ``` - - 4. GNU Make - - ```shell - $ make -v - - GNU Make 4.3 - Built for x86_64-pc-linux-gnu - Copyright (C) 1988-2020 Free Software Foundation, Inc. - License GPLv3+: GNU GPL version 3 or later - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - ``` - - Make should also have been installed by the automatic installer. If Make is not available, install it with your package manager. - - **On linux:** +## License Agreement - ```shell - sudo apt-get install make - ``` +**© Copyright (C) 2022 Maxim Integrated Products, Inc., All rights Reserved.** - **On MacOS with [Homebrew](https://brew.sh/)** +This software is protected by copyright laws of the United States and +of foreign countries. This material may also be protected by patent laws +and technology transfer regulations of the United States and of foreign +countries. This software is furnished under a license agreement and/or a +nondisclosure agreement and may only be used or reproduced in accordance +with the terms of those agreements. Dissemination of this information to +any party or parties not specified in the license agreement and/or +nondisclosure agreement is expressly prohibited. - ```shell - brew install make - ``` +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. -## Usage Quick-Start +**THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES +OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE.** -Following a successful [installation](#installation) and [setup](#setup), additional documentation on usage can be found below: +Except as contained in this notice, the name of **Maxim Integrated Products, Inc.** +shall not be used except as stated in the **Maxim Integrated Products, Inc. Branding Policy.** -* [Visual Studio Code](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#usage) -* [Eclipse](https://www.maximintegrated.com/en/design/technical-documents/userguides-and-manuals/6/6245.html) -* [IAR](https://www.youtube.com/playlist?list=PLQ4i891m2efIwwd4ScApoPv7RaYLwhAjF) -* [Keil](https://www.youtube.com/watch?v=d_O2tu5CMbQ) +The mere transfer of this software does not imply any licenses +of trade secrets, proprietary technology, copyrights, patents, +trademarks, maskwork rights, or any other form of intellectual +property whatsoever. **Maxim Integrated Products, Inc.** retains all +ownership rights. -## Contributing +[Final Copyright](https://www.maximintegrated.com/en/aboutus/legal/copyrights/default-copyright.html "Final Copyright") -Contributions to the MSDK are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +[Final Software License Agreement](https://www.maximintegrated.com/en/aboutus/legal/sla/no-distribute.html "Final SLA") diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000000..945b84f7ea9 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,17 @@ +site_name: Analog Devices MSDK Documentation +site_author: Analog Devices +copyright: 'Copyright (C) Maxim Integrated Products, Inc., All rights Reserved.' +repo_url: https://github.com/Analog-Devices-MSDK/msdk +edit_uri: null +docs_dir: 'Documentation' +site_dir: 'docs' +nav: + - Home: 'index.md' + - User Guide: 'USERGUIDE.md' + - Contributing: 'CONTRIBUTING.md' + - License: 'LICENSE.md' +theme: + name: readthedocs +markdown_extensions: + codehilite: + use_pygments: False \ No newline at end of file