Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Jake-Carter
Jake-Carter committed Mar 27, 2023
1 parent 5ae0059 commit ce72454
Showing 1 changed file with 11 additions and 139 deletions.
150 changes: 11 additions & 139 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -363,138 +363,7 @@ make

... is run, the program `make` will load settings from these two files. Then, it will use them to build the project's source code. VSCode-Maxim is a "wrapper" around this Makefile system.

The file named `Makefile` is the "core" file for the project. It should not be edited directly. Instead, it offers a number of configuration variables that can be overridden 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.

### Default Build Behavior

By default, the build system will auto-search the root project directory source code (`*.c`) and header files (`*.h`). The optional "include" and "src" directories are also searched if they exist.

```shell
Root Project Directory
├─ project.mk
├─ Makefile
├─ *.h
├─ *.c
├─include # <-- Optional
└─ *.h
├─src # <-- Optional
└─ *.c
```

Additionally, the "core" `Makefile` will come pre-configured for a specific target microcontroller and Board Support Package (BSP). The default BSP will match the main EVKIT for the device. In VSCode-Maxim, the two [Basic Config Options](#basic-config-options) can be used to easily override the target microcontroller and BSP. These options are passed to `make` on the command-line when the ["Build" task](#build-tasks) is run.

For more advanced build configuration, configuration variables should be used.

### How to Set a Configuration Variable

A 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 is only needed for advanced use-cases.

To set a configuration variable, use the syntax...

```Makefile
VARIABLE=VALUE
```

The `=` operator is used for _most_ configuration variables with a few exceptions (that are clearly documented) when a variable should contain a _list_ of values. In such cases, use the syntax...

```Makefile
VARIABLE+=VALUE1
VARIABLE+=VALUE2
```

... to _add_ values to the list.

In most cases, you should do this from inside of **project.mk**.

For example, if I wanted to enable hardware floating-point acceleration for my project, I would use the `MFLOAT_ABI` configuration variable to set its value to `hard`. The contents of **project.mk** might then look as follows:

(_Inside 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

#BOARD=FTHR_RevA
# ^ For example, you can uncomment this line to make the
# project build for the "FTHR_RevA" board.

# **********************************************************

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...
```shell
make MFLOAT_ABI=hard
```

... will have the same effect.

Additionally, **environment variables** can be used. For example (on linux)...

```shell
export TARGET=MAX78000
```

... will set all projects to build for the MAX78000.

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 on the command-line _and_ project.mk, the command-line 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.

### Configuration Variables Table

The following configuration variables are available.

| Variable | Description | Example | Details |
|--- | --- | --- | ---|
**Target**
| `TARGET` | Set the target microcontroller | `TARGET=MAX78000` |
| `BOARD` | Set the Board Support Package (BSP) | `BOARD=FTHR_RevA` | Every microcontroller has a number of BSPs available for it that can be found in the `Libraries/Boards/TARGET` folder of the MSDK. When you change this option, it's usually a good idea to fully clean your project, then re-build.
**SDK**
| `MAXIM_PATH` | (Optional) Specify the location of the MSDK | `MAXIM_PATH=/path/to/MSDK` | This optional variable can be used to change where the Makefile looks for the MSDK. By default, the Makefile will attempt to locate the MSDK with a relative path moving "up" from its original location. This option is most useful when a project is moved _outside_ of the MSDK and you're developing on the command-line, since VS Code and Eclipse will set this via an environment variable. It's also useful for re-targeting a project to point to the development repository.
| `CAMERA` | (Optional) Set the Camera drivers to use | `CAMERA=HM0360_MONO` | 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` folder of the MSDK. Depending on the selected camera, a compiler definition may be added to the build. See the `board.mk` Makefile in the active BSP for more details.
**Source Code**
| `VPATH` | Where to search for source (.c) files | `VPATH+=your/source/path` | **Use the `+=` operator with this option**. 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 | `IPATH+=your/include/path` | **Use the `+=` operator with this option**. 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 | `AUTOSEARCH=0` | Enable or disable the automatic detection of .c files on `VPATH` (enabled by default). Set to `0` to disable, or `1` to enable. If autosearch is disabled, source files must be manually added to `SRCS`.
| `SRCS` | List of source (.c) files to add to the build | `SRCS+=./my/other/source.c` | **Use the `+=` operator with this option**. 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 | `PROJECT=MyProject` | This controls the output filename of the build. File extensions should _not_ be set here since the output file format may vary depending on the build recipe. For VSCode-Maxim, you should use the [project_name](#project_name) advanced config option instead, which sets `PROJECT` on the command-line [Build Tasks](#build-tasks).
**Compiler**
| `MXC_OPTIMIZE_CFLAGS` | Set the optimization level | `MXC_OPTIMIZE_CFLAGS=-O2` | 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 | `PROJ_CFLAGS+=-Wextra`, `PROJ_CFLAGS+=-DMYDEFINE` | 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.
| `MFLOAT_ABI` | Set the floating point acceleration level | `MFLOAT_ABI=hard` | 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).
**Linker**
| `LINKERFILE` | Set the linkerfile to use | `LINKERFILE=newlinker.ld` | You can use a different 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.
**Libraries**
| `LIB_BOARD` | Include the BSP library (enabled by default) | `LIB_BOARD=0` | Inclusion of the Board-Support Package (BSP) library, which is enabled by default, can be toggled with this variable. This library contains important startup code specific to a microcontroller's evaluation platform, such as serial port initialization, power sequencing, external peripheral initalization, etc. Set to `0` to disable, or `1` to enable.
| `LIB_PERIPHDRIVERS` | Include the peripheral driver library (enabled by default) | `LIB_PERIPHDRIVERS=0` | 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 | `LIB_CMSIS_DSP=1` | 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 | `LIB_CORDIO=1` | 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) | `LIB_FCL=1` | 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 | `LIB_FREERTOS=1` | 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 | `LIB_LC3=1` | 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 | `LIB_LITTLEFS=1` | 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_LWIP=1` | |
| `LIB_MAXUSB` | Include the MaxUSB library | `LIB_MAXUSB=1` | 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 | `LIB_SDHC=1` | 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.
**Secure Boot Tools (SBT)**
| `SBT` | Toggle SBT integration | `SBT=1` | 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 | `MAXIM_SBT_DIR=C:/MaximSBT` | 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 MSDK will be searched. If the [SBT installer](hhttps://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 | `TARGET_SEC=MAX32651` | 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 test key that can be used for development.
**See the [MSDK User Guide](https://analog-devices-msdk.github.io/msdk/USERGUIDE/#build-system) for full documentation on how to configure the build system.**

## Project Creation

Expand All @@ -516,18 +385,19 @@ The release package for this project (Located at Tools/VSCode-Maxim in the Analo

6. That's it! The existing project is ready to build, debug, and modify.

### Option 2 - Creating a Project from Scratch
### Option 2 - Injecting

If you want to start from scratch, take this option.
VSCode-Maxim releases provide the `Inject` folder for "injecting" into an existing folder. If you want to start from scratch or use the project files with existing source code, take this option.

1. Create your project folder. For example, I might create a new project in a workspace folder with the path: `C:\Users\Jake.Carter\workspace\MyNewProject`.
1. Create your project folder if necessary. For example, I might create a new project in a workspace folder with the path: `C:\Users\Jake.Carter\workspace\MyNewProject`.

2. Copy the **contents** of the `Inject` folder into the project folder created in step 2. This includes a `.vscode` folder and a `Makefile`. In the example above, the contents of the 'MyProject' folder would be the following :
2. Copy the **contents** of the `Inject` folder into the project folder from step 1. The contents to copy include a `.vscode` folder, a `Makefile`, and a `project.mk` file. For this example, the contents of the 'MyProject' folder would be the following:

```shell
C:\Users\Jake.Carter\workspace\MyNewProject
+-- \.vscode
+-- Makefile
|- .vscode
|- Makefile
|- project.mk
```

3. Open the project in VS Code (`File -> Open Folder...`)
Expand All @@ -536,7 +406,9 @@ If you want to start from scratch, take this option.

5. `CTRL+SHIFT+P -> Reload Window` to re-parse the project settings.

6. Fundamentally, that's it. Your new empty project can now be opened with `File > Open Folder` from within VS Code.
6. Configure the [build system](https://analog-devices-msdk.github.io/msdk/USERGUIDE/#build-system) for use with any pre-existing source code.

7. That's it! Your new empty project can now be opened with `File > Open Folder` from within VS Code.
## Issue Tracker
Expand Down

0 comments on commit ce72454

Please sign in to comment.