diff --git a/.gitignore b/.gitignore index a803a46..6fb66cf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ build buildlogs* __pycache__ -MaximSDK/Template/.vscode/readme.md \ No newline at end of file +MaximSDK/Template/.vscode/README.md diff --git a/MaximSDK/Inject/.vscode/c_cpp_properties.json b/MaximSDK/Inject/.vscode/c_cpp_properties.json index bd9d5ef..dfbed47 100644 --- a/MaximSDK/Inject/.vscode/c_cpp_properties.json +++ b/MaximSDK/Inject/.vscode/c_cpp_properties.json @@ -11,7 +11,7 @@ "intelliSenseMode": "gcc-arm", "compilerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gcc.exe", "browse": { - "path": [ + "path": [ "${default}" ] } diff --git a/MaximSDK/Inject/.vscode/launch.json b/MaximSDK/Inject/.vscode/launch.json index 9c45b1d..fb021b9 100755 --- a/MaximSDK/Inject/.vscode/launch.json +++ b/MaximSDK/Inject/.vscode/launch.json @@ -46,6 +46,7 @@ { "text":"symbol-file build/${config:symbol_file}" }, { "text":"target remote localhost:3333" }, { "text":"monitor reset halt" }, + { "text":"set $pc=Reset_Handler"}, { "text":"b main" } ] }, diff --git a/MaximSDK/Inject/.vscode/tasks.json b/MaximSDK/Inject/.vscode/tasks.json index 3951f35..81917f6 100644 --- a/MaximSDK/Inject/.vscode/tasks.json +++ b/MaximSDK/Inject/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "build", "type": "shell", - "command": "make -r -j 8 all TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", + "command": "make -r -j 8 TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", "group": "build", "problemMatcher": [] }, diff --git a/MaximSDK/Inject/Makefile b/MaximSDK/Inject/Makefile index aa6f3e8..f16fc0e 100644 --- a/MaximSDK/Inject/Makefile +++ b/MaximSDK/Inject/Makefile @@ -1,5 +1,5 @@ # /******************************************************************************* -# * Copyright (C) 2021 Maxim Integrated Products, Inc., All Rights Reserved. +# * Copyright (C) 2022 Maxim Integrated Products, Inc., All Rights Reserved. # * # * Permission is hereby granted, free of charge, to any person obtaining a # * copy of this software and associated documentation files (the "Software"), @@ -29,91 +29,360 @@ # * property whatsoever. Maxim Integrated Products, Inc. retains all # * ownership rights. # ******************************************************************************* +# */ - ############################################################################### -# Main configuration -# Below are the most commonly needed configuration options for this Makefile. -# You shouldn't need to touch anything else unless advanced configuration is required. +# ** Readme! ** +# Don't edit this file! This is the core Makefile for a MaximSDK +# project. The available configuration options can be overridden +# in "project.mk", on the command-line, or with system environment +# variables. -# Source files to compile for this project (add path to VPATH below) -SRCS += main.c +# See https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration +# for more detailed instructions on how to use this system. -# Where to find source files for this project -VPATH += ./src +# The detailed instructions mentioned above are easier to read than +# this file, but the comments found in this file also outline the +# available configuration variables. This file is organized into +# sub-sections, some of which expose config variables. -# Where to find header files for this project -IPATH += ./src -# Set compiler flags -PROJ_CFLAGS+=-Wall # Enable warnings -PROJ_CFLAGS+=-DMXC_ASSERT_ENABLE # Enable assertion checking for development +# ******************************************************************************* +# Set the target microcontroller and board to compile for. -# Set compiler optimization level -MXC_OPTIMIZE_CFLAGS=-Og +# Every TARGET microcontroller has some Board Support Packages (BSPs) that are +# available for it under the MaximSDK/Libraries/Boards/TARGET folder. The BSP +# that gets selected is MaximSDK/Libraries/Boards/TARGET/BOARD. - ############################################################################### +# Configuration Variables: +# - TARGET : Override the default target microcontroller. Ex: TARGET=MAX78000 +# - BOARD : Override the default BSP (case sensitive). Ex: BOARD=EvKit_V1, BOARD=FTHR_RevA -# Set the MAKE variable. This eliminates issues with some setups -MAKE=make ifeq "$(TARGET)" "" -$(error target must be specified! Set the TARGET variable.) +# Default target microcontroller +TARGET := MAX78000 +TARGET_UC := MAX78000 +TARGET_LC := max78000 +else +# "TARGET" has been overridden in the environment or on the command-line. +# We need to calculate an upper and lowercase version of the part number, +# because paths on Linux and MacOS are case-sensitive. +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) endif -# Default board used. This is overridden in settings.json -ifeq "$(BOARD)" "" -$(error board must be specified! Set the BOARD variable.) -endif +# Default board. +BOARD ?= EvKit_V1 + +# ******************************************************************************* +# Locate the MaximSDK + +# This Makefile needs to know where to find the MaximSDK, and the MAXIM_PATH variable +# should point to the root directory of the MaximSDK installation. Setting this manually +# is usually only required if you're working on the command-line. + +# If MAXIM_PATH is not specified, we assume the project still lives inside of the MaximSDK +# and move up from this project's original location. + +# Configuration Variables: +# - MAXIM_PATH : Tell this Makefile where to find the MaximSDK. Ex: MAXIM_PATH=C:/MaximSDK + -# Set output filename -ifeq "$(PROJECT)" "" -PROJECT=$(TARGET) +ifneq "$(MAXIM_PATH)" "" +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) +# Locate some other useful paths... +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS endif -# Create Target name variables -TARGET_UC:=$(shell echo $(TARGET) | tr a-z A-Z) -TARGET_LC:=$(shell echo $(TARGET) | tr A-Z a-z) +# ******************************************************************************* +# Include project Makefile. We do this after formulating TARGET, BOARD, and MAXIM_PATH +# in case project.mk needs to reference those values. However, we also include +# this as early as possible in the Makefile so that it can append to or override +# the variables below. -# Select 'GCC' or 'IAR' compiler -COMPILER=GCC -# This is the path to the CMSIS root directory +include ./project.mk +$(info Loaded project.mk) + +# ******************************************************************************* +# Final path sanitization and re-calculation. No options here. + ifeq "$(MAXIM_PATH)" "" -LIBS_DIR=../../../Libraries +# MAXIM_PATH is still not defined... +DEPTH := ../../../ +MAXIM_PATH := $(abspath $(DEPTH)) +$(warning Warning: MAXIM_PATH is not set! Set MAXIM_PATH in your environment or in project.mk to clear this warning.) +$(warning Warning: Attempting to use $(MAXIM_PATH) calculated from relative path) else -LIBS_DIR=/$(subst \,/,$(subst :,,$(MAXIM_PATH))/Libraries) +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) endif -#LIBS_DIR = ./Libraries -CMSIS_ROOT=$(LIBS_DIR)/CMSIS +# Final recalculation of LIBS_DIR/CMSIS_ROOT +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS + +# One final UC/LC check in case user set TARGET in project.mk +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) -#Use this for other library make files so they are all based off the same as root as the project +export TARGET +export TARGET_UC +export TARGET_LC export CMSIS_ROOT +# TODO: Remove dependency on exports for these variables. + +# ******************************************************************************* +# Set up search paths, and auto-detect all source code on those paths. + +# The following paths are searched by default, where "./" is the project directory. +# ./ +# |- *.h +# |- *.c +# |-include (optional) +# |- *.h +# |-src (optional) +# |- *.c + +# Configuration Variables: +# - VPATH : Tell this Makefile to search additional locations for source (.c) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - IPATH : Tell this Makefile to search additional locations for header (.h) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - SRCS : Tell this Makefile to explicitly add a source (.c) file to the build. +# This is really only useful if you want to add a source file that isn't +# on any VPATH, in which case you can add the full path to the file here. +# You should use the "+=" operator with this option. +# Ex: SRCS += your/specific/source/file.c +# - AUTOSEARCH : Set whether this Makefile should automatically detect .c files on +# VPATH and add them to the build. This is enabled by default. Set +# to 0 to disable. If autosearch is disabled, source files must be +# manually added to SRCS. +# Ex: AUTOSEARCH = 0 + + +# Where to find source files for this project. +VPATH += . +VPATH += src +VPATH := $(VPATH) + +# Where to find header files for this project +IPATH += . +IPATH += include +IPATH := $(IPATH) + +AUTOSEARCH ?= 1 +ifeq ($(AUTOSEARCH), 1) +# Auto-detect all C source files on VPATH +SRCS += $(wildcard $(addsuffix /*.c, $(VPATH))) +endif + +# Collapse SRCS before passing them on to the next stage +SRCS := $(SRCS) + +# ******************************************************************************* +# Set the output filename + +# Configuration Variables: +# - PROJECT : Override the default output filename. Ex: PROJECT=MyProject + + +# The default value creates a file named after the target micro. Ex: MAX78000.elf +PROJECT ?= $(TARGET_LC) + +# ******************************************************************************* +# Compiler options + +# Configuration Variables: +# - MXC_OPTIMIZE_CFLAGS : Override the default compiler optimization level. +# Ex: MXC_OPTIMIZE_CFLAGS = -O2 +# - PROJ_CFLAGS : Add additional compiler flags to the build. +# You should use the "+=" operator with this option. +# Ex: PROJ_CFLAGS += -Wextra +# - MFLOAT_ABI : Set the floating point acceleration level. +# The only options are "hard", "soft", or "softfp". +# Ex: MFLOAT_ABI = hard +# - LINKERFILE : Override the default linkerfile. +# Ex: LINKERFILE = customlinkerfile.ld + + +# Select 'GCC' or 'IAR' compiler +ifeq "$(COMPILER)" "" +COMPILER := GCC +endif + +# Set default compiler optimization levels +ifeq "$(MAKECMDGOALS)" "release" +# Default optimization level for "release" builds (make release) +MXC_OPTIMIZE_CFLAGS ?= -O2 +DEBUG = 0 +endif + +ifeq ($(DEBUG),1) +# Default optimization level for debug builds (make DEBUG=1 ...) +# gcc.mk checks for this flag to add some additional debug +# info to the build, and should be used when you really need to +# debug. +MXC_OPTIMIZE_CFLAGS := -Og +endif + +# Fallback default optimizes for debugging as recommended +# by GNU for code-edit-debug cycles +# https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options +MXC_OPTIMIZE_CFLAGS ?= -Og + +# Set compiler flags +PROJ_CFLAGS += -Wall # Enable warnings +PROJ_CFLAGS += -DMXC_ASSERT_ENABLE + +# Set hardware floating point acceleration. +# Options are: +# - hard +# - soft +# - softfp (default if MFLOAT_ABI is not set) +MFLOAT_ABI ?= softfp +# MFLOAT_ABI must be exported to other Makefiles, who check this too +export MFLOAT_ABI + +# Set the default linkerfile. Since the core Makefiles later add the location of Maxim's +# linkerfiles to VPATH, and the local project directory has also been added to VPATH, Make +# will search both locations for the specified linkerfile if it can't find it by its path alone. +# The result is that overriding LINKERFILE with the filename of one of Maxim's alternate linkerfiles +# (ex: LINKERFILE=max78000_arm.ld) will work just the same as LINKERFILE=mycustom.ld +# even if mycustom.ld lives locally to this project. + +ifeq "$(RISCV_CORE)" "" +# Default linkerfile is only specified for standard Arm-core projects. +# Otherwise, gcc_riscv.mk sets the appropriate riscv linkerfile. +LINKER = $(TARGET_LC).ld +LINKERFILE ?= $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +endif + +# This path contains system-level intialization files for the target micro. Add to the build. VPATH += $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source -# Point this variable to a linker file to override the default file -LINKER=$(TARGET_LC).ld -LINKERFILE=$(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +# ******************************************************************************* +# Secure Boot Tools (SBT) + +# This section integrates the Secure Boot Tools. It's intended for use with +# microcontrollers that have a secure bootloader. + +# Enabling SBT integration will add some special rules, such as "make sla", "make scpa", etc. + +# Configuration variables: +# SBT : Toggle SBT integration. Set to 1 to enable, or 0 +# to disable +# MAXIM_SBT_DIR : Specify the location of the SBT tool binaries. This defaults to +# Tools/SBT in the MaximSDK. The standalone SBT installer will override +# this via an environment variable. +# TARGET_SEC : Specify the part number to be passed into the SBT. This should match +# the secure variant part #. The default value will depend on TARGET. +# For example, TARGET=MAX32650 will result in TARGET_SEC=MAX32651, and +# the default selection happens in Tools/SBT/SBT-config. +# However, if there are multiple secure part #s for the target +# microcontroller this variable may need to be changed. + +SBT ?= 0 +ifeq ($(SBT), 1) +MAXIM_SBT_DIR ?= $(MAXIM_PATH)/Tools/SBT +MAXIM_SBT_DIR := $(subst \,/,$(MAXIM_SBT_DIR)) +# ^ Must sanitize path for \ on Windows, since this may come from an environment +# variable. + +export MAXIM_SBT_DIR # SBTs must have this environment variable defined to work + +# SBT-config.mk and SBT-rules.mk are included further down this Makefile. + +endif # SBT + +# ******************************************************************************* +# Default goal selection. This section allows you to override the default goal +# that will run if no targets are specified on the command-line. +# (ie. just running 'make' instead of 'make all') + +# Configuration variables: +# .DEFAULT_GOAL : Set the default goal if no targets were specified on the +# command-line +# ** "override" must be used with this variable. ** +# Ex: "override .DEFAULT_GOAL = mygoal" + +ifeq "$(.DEFAULT_GOAL)" "" +ifeq ($(SBT),1) +override .DEFAULT_GOAL := sla +else +override .DEFAULT_GOAL := all +endif +endif + +# Developer note: 'override' is used above for legacy Makefile compatibility. +# gcc.mk/gcc_riscv.mk need to hard-set 'all' internally, so this new system +# uses 'override' to come in over the top without breaking old projects. + +# It's also necessary to explicitly set MAKECMDGOALS... +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + +# ******************************************************************************* +# Include SBT config. We need to do this here because it needs to know +# the current MAKECMDGOAL. +ifeq ($(SBT),1) +include $(MAXIM_PATH)/Tools/SBT/SBT-config.mk +endif + +# ******************************************************************************* +# Libraries -################################################################################ -# Include external library makefiles here +# This section offers "toggle switches" to include or exclude the libraries that +# are available in the MaximSDK. Set a configuration variable to 1 to include the +# library in the build, or 0 to exclude. -# Include the BSP -BOARD_DIR=$(LIBS_DIR)/Boards/$(TARGET_UC)/$(BOARD) -include $(BOARD_DIR)/board.mk +# Each library may also have its own library specific configuration variables. See +# Libraries/libs.mk for more details. -# Include the peripheral driver -PERIPH_DRIVER_DIR=$(LIBS_DIR)/PeriphDrivers -include $(PERIPH_DRIVER_DIR)/periphdriver.mk -export PERIPH_DRIVER_DIR +# Configuration variables: +# - LIB_BOARD : Include the Board-Support Package (BSP) library. (Enabled by default) +# - LIB_PERIPHDRIVERS : Include the peripheral driver library. (Enabled by default) +# - LIB_CMSIS_DSP : Include the CMSIS-DSP library. +# - LIB_CORDIO : Include the Cordio BLE library +# - LIB_FCL : Include the Free Cryptographic Library (FCL) +# - LIB_FREERTOS : Include the FreeRTOS and FreeRTOS-Plus-CLI libraries +# - LIB_LC3 : Include the Low Complexity Communication Codec (LC3) library +# - LIB_LITTLEFS : Include the "little file system" (littleFS) library +# - LIB_LWIP : Include the lwIP library +# - LIB_MAXUSB : Include the MAXUSB library +# - LIB_SDHC : Include the SDHC library + +include $(LIBS_DIR)/libs.mk + + +# ******************************************************************************* +# Rules -################################################################################ # Include the rules for building for this target. All other makefiles should be # included before this one. include $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/$(COMPILER)/$(TARGET_LC).mk +# Include the rules that integrate the SBTs. SBTs are a special case that must be +# include after the core gcc rules to extend them. +ifeq ($(SBT), 1) +include $(MAXIM_PATH)/Tools/SBT/SBT-rules.mk +endif + + +# Get .DEFAULT_GOAL working. +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + + all: # Extend the functionality of the "all" recipe here + arm-none-eabi-size --format=berkeley $(BUILD_DIR)/$(PROJECT).elf libclean: $(MAKE) -f ${PERIPH_DRIVER_DIR}/periphdriver.mk clean.periph diff --git a/MaximSDK/Inject/project.mk b/MaximSDK/Inject/project.mk new file mode 100644 index 0000000..250f70c --- /dev/null +++ b/MaximSDK/Inject/project.mk @@ -0,0 +1,13 @@ +# 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! + + + diff --git a/MaximSDK/New_Project/.vscode/c_cpp_properties.json b/MaximSDK/New_Project/.vscode/c_cpp_properties.json index bd9d5ef..dfbed47 100644 --- a/MaximSDK/New_Project/.vscode/c_cpp_properties.json +++ b/MaximSDK/New_Project/.vscode/c_cpp_properties.json @@ -11,7 +11,7 @@ "intelliSenseMode": "gcc-arm", "compilerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gcc.exe", "browse": { - "path": [ + "path": [ "${default}" ] } diff --git a/MaximSDK/New_Project/.vscode/launch.json b/MaximSDK/New_Project/.vscode/launch.json index 9c45b1d..fb021b9 100755 --- a/MaximSDK/New_Project/.vscode/launch.json +++ b/MaximSDK/New_Project/.vscode/launch.json @@ -46,6 +46,7 @@ { "text":"symbol-file build/${config:symbol_file}" }, { "text":"target remote localhost:3333" }, { "text":"monitor reset halt" }, + { "text":"set $pc=Reset_Handler"}, { "text":"b main" } ] }, diff --git a/MaximSDK/New_Project/.vscode/tasks.json b/MaximSDK/New_Project/.vscode/tasks.json index 3951f35..81917f6 100644 --- a/MaximSDK/New_Project/.vscode/tasks.json +++ b/MaximSDK/New_Project/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "build", "type": "shell", - "command": "make -r -j 8 all TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", + "command": "make -r -j 8 TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", "group": "build", "problemMatcher": [] }, diff --git a/MaximSDK/New_Project/Makefile b/MaximSDK/New_Project/Makefile index aa6f3e8..f16fc0e 100644 --- a/MaximSDK/New_Project/Makefile +++ b/MaximSDK/New_Project/Makefile @@ -1,5 +1,5 @@ # /******************************************************************************* -# * Copyright (C) 2021 Maxim Integrated Products, Inc., All Rights Reserved. +# * Copyright (C) 2022 Maxim Integrated Products, Inc., All Rights Reserved. # * # * Permission is hereby granted, free of charge, to any person obtaining a # * copy of this software and associated documentation files (the "Software"), @@ -29,91 +29,360 @@ # * property whatsoever. Maxim Integrated Products, Inc. retains all # * ownership rights. # ******************************************************************************* +# */ - ############################################################################### -# Main configuration -# Below are the most commonly needed configuration options for this Makefile. -# You shouldn't need to touch anything else unless advanced configuration is required. +# ** Readme! ** +# Don't edit this file! This is the core Makefile for a MaximSDK +# project. The available configuration options can be overridden +# in "project.mk", on the command-line, or with system environment +# variables. -# Source files to compile for this project (add path to VPATH below) -SRCS += main.c +# See https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration +# for more detailed instructions on how to use this system. -# Where to find source files for this project -VPATH += ./src +# The detailed instructions mentioned above are easier to read than +# this file, but the comments found in this file also outline the +# available configuration variables. This file is organized into +# sub-sections, some of which expose config variables. -# Where to find header files for this project -IPATH += ./src -# Set compiler flags -PROJ_CFLAGS+=-Wall # Enable warnings -PROJ_CFLAGS+=-DMXC_ASSERT_ENABLE # Enable assertion checking for development +# ******************************************************************************* +# Set the target microcontroller and board to compile for. -# Set compiler optimization level -MXC_OPTIMIZE_CFLAGS=-Og +# Every TARGET microcontroller has some Board Support Packages (BSPs) that are +# available for it under the MaximSDK/Libraries/Boards/TARGET folder. The BSP +# that gets selected is MaximSDK/Libraries/Boards/TARGET/BOARD. - ############################################################################### +# Configuration Variables: +# - TARGET : Override the default target microcontroller. Ex: TARGET=MAX78000 +# - BOARD : Override the default BSP (case sensitive). Ex: BOARD=EvKit_V1, BOARD=FTHR_RevA -# Set the MAKE variable. This eliminates issues with some setups -MAKE=make ifeq "$(TARGET)" "" -$(error target must be specified! Set the TARGET variable.) +# Default target microcontroller +TARGET := MAX78000 +TARGET_UC := MAX78000 +TARGET_LC := max78000 +else +# "TARGET" has been overridden in the environment or on the command-line. +# We need to calculate an upper and lowercase version of the part number, +# because paths on Linux and MacOS are case-sensitive. +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) endif -# Default board used. This is overridden in settings.json -ifeq "$(BOARD)" "" -$(error board must be specified! Set the BOARD variable.) -endif +# Default board. +BOARD ?= EvKit_V1 + +# ******************************************************************************* +# Locate the MaximSDK + +# This Makefile needs to know where to find the MaximSDK, and the MAXIM_PATH variable +# should point to the root directory of the MaximSDK installation. Setting this manually +# is usually only required if you're working on the command-line. + +# If MAXIM_PATH is not specified, we assume the project still lives inside of the MaximSDK +# and move up from this project's original location. + +# Configuration Variables: +# - MAXIM_PATH : Tell this Makefile where to find the MaximSDK. Ex: MAXIM_PATH=C:/MaximSDK + -# Set output filename -ifeq "$(PROJECT)" "" -PROJECT=$(TARGET) +ifneq "$(MAXIM_PATH)" "" +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) +# Locate some other useful paths... +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS endif -# Create Target name variables -TARGET_UC:=$(shell echo $(TARGET) | tr a-z A-Z) -TARGET_LC:=$(shell echo $(TARGET) | tr A-Z a-z) +# ******************************************************************************* +# Include project Makefile. We do this after formulating TARGET, BOARD, and MAXIM_PATH +# in case project.mk needs to reference those values. However, we also include +# this as early as possible in the Makefile so that it can append to or override +# the variables below. -# Select 'GCC' or 'IAR' compiler -COMPILER=GCC -# This is the path to the CMSIS root directory +include ./project.mk +$(info Loaded project.mk) + +# ******************************************************************************* +# Final path sanitization and re-calculation. No options here. + ifeq "$(MAXIM_PATH)" "" -LIBS_DIR=../../../Libraries +# MAXIM_PATH is still not defined... +DEPTH := ../../../ +MAXIM_PATH := $(abspath $(DEPTH)) +$(warning Warning: MAXIM_PATH is not set! Set MAXIM_PATH in your environment or in project.mk to clear this warning.) +$(warning Warning: Attempting to use $(MAXIM_PATH) calculated from relative path) else -LIBS_DIR=/$(subst \,/,$(subst :,,$(MAXIM_PATH))/Libraries) +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) endif -#LIBS_DIR = ./Libraries -CMSIS_ROOT=$(LIBS_DIR)/CMSIS +# Final recalculation of LIBS_DIR/CMSIS_ROOT +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS + +# One final UC/LC check in case user set TARGET in project.mk +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) -#Use this for other library make files so they are all based off the same as root as the project +export TARGET +export TARGET_UC +export TARGET_LC export CMSIS_ROOT +# TODO: Remove dependency on exports for these variables. + +# ******************************************************************************* +# Set up search paths, and auto-detect all source code on those paths. + +# The following paths are searched by default, where "./" is the project directory. +# ./ +# |- *.h +# |- *.c +# |-include (optional) +# |- *.h +# |-src (optional) +# |- *.c + +# Configuration Variables: +# - VPATH : Tell this Makefile to search additional locations for source (.c) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - IPATH : Tell this Makefile to search additional locations for header (.h) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - SRCS : Tell this Makefile to explicitly add a source (.c) file to the build. +# This is really only useful if you want to add a source file that isn't +# on any VPATH, in which case you can add the full path to the file here. +# You should use the "+=" operator with this option. +# Ex: SRCS += your/specific/source/file.c +# - AUTOSEARCH : Set whether this Makefile should automatically detect .c files on +# VPATH and add them to the build. This is enabled by default. Set +# to 0 to disable. If autosearch is disabled, source files must be +# manually added to SRCS. +# Ex: AUTOSEARCH = 0 + + +# Where to find source files for this project. +VPATH += . +VPATH += src +VPATH := $(VPATH) + +# Where to find header files for this project +IPATH += . +IPATH += include +IPATH := $(IPATH) + +AUTOSEARCH ?= 1 +ifeq ($(AUTOSEARCH), 1) +# Auto-detect all C source files on VPATH +SRCS += $(wildcard $(addsuffix /*.c, $(VPATH))) +endif + +# Collapse SRCS before passing them on to the next stage +SRCS := $(SRCS) + +# ******************************************************************************* +# Set the output filename + +# Configuration Variables: +# - PROJECT : Override the default output filename. Ex: PROJECT=MyProject + + +# The default value creates a file named after the target micro. Ex: MAX78000.elf +PROJECT ?= $(TARGET_LC) + +# ******************************************************************************* +# Compiler options + +# Configuration Variables: +# - MXC_OPTIMIZE_CFLAGS : Override the default compiler optimization level. +# Ex: MXC_OPTIMIZE_CFLAGS = -O2 +# - PROJ_CFLAGS : Add additional compiler flags to the build. +# You should use the "+=" operator with this option. +# Ex: PROJ_CFLAGS += -Wextra +# - MFLOAT_ABI : Set the floating point acceleration level. +# The only options are "hard", "soft", or "softfp". +# Ex: MFLOAT_ABI = hard +# - LINKERFILE : Override the default linkerfile. +# Ex: LINKERFILE = customlinkerfile.ld + + +# Select 'GCC' or 'IAR' compiler +ifeq "$(COMPILER)" "" +COMPILER := GCC +endif + +# Set default compiler optimization levels +ifeq "$(MAKECMDGOALS)" "release" +# Default optimization level for "release" builds (make release) +MXC_OPTIMIZE_CFLAGS ?= -O2 +DEBUG = 0 +endif + +ifeq ($(DEBUG),1) +# Default optimization level for debug builds (make DEBUG=1 ...) +# gcc.mk checks for this flag to add some additional debug +# info to the build, and should be used when you really need to +# debug. +MXC_OPTIMIZE_CFLAGS := -Og +endif + +# Fallback default optimizes for debugging as recommended +# by GNU for code-edit-debug cycles +# https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options +MXC_OPTIMIZE_CFLAGS ?= -Og + +# Set compiler flags +PROJ_CFLAGS += -Wall # Enable warnings +PROJ_CFLAGS += -DMXC_ASSERT_ENABLE + +# Set hardware floating point acceleration. +# Options are: +# - hard +# - soft +# - softfp (default if MFLOAT_ABI is not set) +MFLOAT_ABI ?= softfp +# MFLOAT_ABI must be exported to other Makefiles, who check this too +export MFLOAT_ABI + +# Set the default linkerfile. Since the core Makefiles later add the location of Maxim's +# linkerfiles to VPATH, and the local project directory has also been added to VPATH, Make +# will search both locations for the specified linkerfile if it can't find it by its path alone. +# The result is that overriding LINKERFILE with the filename of one of Maxim's alternate linkerfiles +# (ex: LINKERFILE=max78000_arm.ld) will work just the same as LINKERFILE=mycustom.ld +# even if mycustom.ld lives locally to this project. + +ifeq "$(RISCV_CORE)" "" +# Default linkerfile is only specified for standard Arm-core projects. +# Otherwise, gcc_riscv.mk sets the appropriate riscv linkerfile. +LINKER = $(TARGET_LC).ld +LINKERFILE ?= $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +endif + +# This path contains system-level intialization files for the target micro. Add to the build. VPATH += $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source -# Point this variable to a linker file to override the default file -LINKER=$(TARGET_LC).ld -LINKERFILE=$(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +# ******************************************************************************* +# Secure Boot Tools (SBT) + +# This section integrates the Secure Boot Tools. It's intended for use with +# microcontrollers that have a secure bootloader. + +# Enabling SBT integration will add some special rules, such as "make sla", "make scpa", etc. + +# Configuration variables: +# SBT : Toggle SBT integration. Set to 1 to enable, or 0 +# to disable +# MAXIM_SBT_DIR : Specify the location of the SBT tool binaries. This defaults to +# Tools/SBT in the MaximSDK. The standalone SBT installer will override +# this via an environment variable. +# TARGET_SEC : Specify the part number to be passed into the SBT. This should match +# the secure variant part #. The default value will depend on TARGET. +# For example, TARGET=MAX32650 will result in TARGET_SEC=MAX32651, and +# the default selection happens in Tools/SBT/SBT-config. +# However, if there are multiple secure part #s for the target +# microcontroller this variable may need to be changed. + +SBT ?= 0 +ifeq ($(SBT), 1) +MAXIM_SBT_DIR ?= $(MAXIM_PATH)/Tools/SBT +MAXIM_SBT_DIR := $(subst \,/,$(MAXIM_SBT_DIR)) +# ^ Must sanitize path for \ on Windows, since this may come from an environment +# variable. + +export MAXIM_SBT_DIR # SBTs must have this environment variable defined to work + +# SBT-config.mk and SBT-rules.mk are included further down this Makefile. + +endif # SBT + +# ******************************************************************************* +# Default goal selection. This section allows you to override the default goal +# that will run if no targets are specified on the command-line. +# (ie. just running 'make' instead of 'make all') + +# Configuration variables: +# .DEFAULT_GOAL : Set the default goal if no targets were specified on the +# command-line +# ** "override" must be used with this variable. ** +# Ex: "override .DEFAULT_GOAL = mygoal" + +ifeq "$(.DEFAULT_GOAL)" "" +ifeq ($(SBT),1) +override .DEFAULT_GOAL := sla +else +override .DEFAULT_GOAL := all +endif +endif + +# Developer note: 'override' is used above for legacy Makefile compatibility. +# gcc.mk/gcc_riscv.mk need to hard-set 'all' internally, so this new system +# uses 'override' to come in over the top without breaking old projects. + +# It's also necessary to explicitly set MAKECMDGOALS... +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + +# ******************************************************************************* +# Include SBT config. We need to do this here because it needs to know +# the current MAKECMDGOAL. +ifeq ($(SBT),1) +include $(MAXIM_PATH)/Tools/SBT/SBT-config.mk +endif + +# ******************************************************************************* +# Libraries -################################################################################ -# Include external library makefiles here +# This section offers "toggle switches" to include or exclude the libraries that +# are available in the MaximSDK. Set a configuration variable to 1 to include the +# library in the build, or 0 to exclude. -# Include the BSP -BOARD_DIR=$(LIBS_DIR)/Boards/$(TARGET_UC)/$(BOARD) -include $(BOARD_DIR)/board.mk +# Each library may also have its own library specific configuration variables. See +# Libraries/libs.mk for more details. -# Include the peripheral driver -PERIPH_DRIVER_DIR=$(LIBS_DIR)/PeriphDrivers -include $(PERIPH_DRIVER_DIR)/periphdriver.mk -export PERIPH_DRIVER_DIR +# Configuration variables: +# - LIB_BOARD : Include the Board-Support Package (BSP) library. (Enabled by default) +# - LIB_PERIPHDRIVERS : Include the peripheral driver library. (Enabled by default) +# - LIB_CMSIS_DSP : Include the CMSIS-DSP library. +# - LIB_CORDIO : Include the Cordio BLE library +# - LIB_FCL : Include the Free Cryptographic Library (FCL) +# - LIB_FREERTOS : Include the FreeRTOS and FreeRTOS-Plus-CLI libraries +# - LIB_LC3 : Include the Low Complexity Communication Codec (LC3) library +# - LIB_LITTLEFS : Include the "little file system" (littleFS) library +# - LIB_LWIP : Include the lwIP library +# - LIB_MAXUSB : Include the MAXUSB library +# - LIB_SDHC : Include the SDHC library + +include $(LIBS_DIR)/libs.mk + + +# ******************************************************************************* +# Rules -################################################################################ # Include the rules for building for this target. All other makefiles should be # included before this one. include $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/$(COMPILER)/$(TARGET_LC).mk +# Include the rules that integrate the SBTs. SBTs are a special case that must be +# include after the core gcc rules to extend them. +ifeq ($(SBT), 1) +include $(MAXIM_PATH)/Tools/SBT/SBT-rules.mk +endif + + +# Get .DEFAULT_GOAL working. +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + + all: # Extend the functionality of the "all" recipe here + arm-none-eabi-size --format=berkeley $(BUILD_DIR)/$(PROJECT).elf libclean: $(MAKE) -f ${PERIPH_DRIVER_DIR}/periphdriver.mk clean.periph diff --git a/MaximSDK/New_Project/project.mk b/MaximSDK/New_Project/project.mk new file mode 100644 index 0000000..250f70c --- /dev/null +++ b/MaximSDK/New_Project/project.mk @@ -0,0 +1,13 @@ +# 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! + + + diff --git a/MaximSDK/Template/.vscode/c_cpp_properties.json b/MaximSDK/Template/.vscode/c_cpp_properties.json index bd9d5ef..dfbed47 100644 --- a/MaximSDK/Template/.vscode/c_cpp_properties.json +++ b/MaximSDK/Template/.vscode/c_cpp_properties.json @@ -11,7 +11,7 @@ "intelliSenseMode": "gcc-arm", "compilerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gcc.exe", "browse": { - "path": [ + "path": [ "${default}" ] } diff --git a/MaximSDK/Template/.vscode/launch.json b/MaximSDK/Template/.vscode/launch.json index 9c45b1d..fb021b9 100755 --- a/MaximSDK/Template/.vscode/launch.json +++ b/MaximSDK/Template/.vscode/launch.json @@ -46,6 +46,7 @@ { "text":"symbol-file build/${config:symbol_file}" }, { "text":"target remote localhost:3333" }, { "text":"monitor reset halt" }, + { "text":"set $pc=Reset_Handler"}, { "text":"b main" } ] }, diff --git a/MaximSDK/Template/.vscode/tasks.json b/MaximSDK/Template/.vscode/tasks.json index 3951f35..81917f6 100644 --- a/MaximSDK/Template/.vscode/tasks.json +++ b/MaximSDK/Template/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "build", "type": "shell", - "command": "make -r -j 8 all TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", + "command": "make -r -j 8 TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", "group": "build", "problemMatcher": [] }, diff --git a/README.md b/README.md new file mode 100644 index 0000000..b6456f1 --- /dev/null +++ b/README.md @@ -0,0 +1,547 @@ +# VSCode-Maxim + +_(If you're viewing this document from within Visual Studio Code you can press `CTRL+SHIFT+V` to open a Markdown preview window.)_ + +## Quick Links + +* [VSCode-Maxim Github](https://github.com/Analog-Devices-MSDK/VSCode-Maxim) +* [Wiki](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki) + * If it's not in the readme, check the wiki. + * If it's not in the wiki, open a ticket! + +## Introduction + +VSCode-Maxim is a set of [Visual Studio Code](https://code.visualstudio.com/) project configurations and utilities for enabling embedded development for [Analog Device's MSDK](https://github.com/Analog-Devices-MSDK/msdk) and the [MAX-series](https://www.maximintegrated.com/en/products/microcontrollers.html) microcontrollers. + +The following features are supported: + +* Code editing with intellisense down to the register level +* Code compilation with the ability to easily re-target a project for different microcontrollers and boards +* Flashing programs +* GUI and command-line debugging + +## Dependencies + +* [Visual Studio Code](https://code.visualstudio.com/) +* [C/C++ VSCode Extension](https://github.com/microsoft/vscode-cpptools) +* [Maxim Micros SDK](https://www.maximintegrated.com/content/maximintegrated/en/design/software-description.html/swpart=SFW0010820A) + +## Installation + +The steps below are also available in video form in "Understanding Artificial Intelligence Episode 8.5 - Visual Studio Code" [here](https://www.maximintegrated.com/en/products/microcontrollers/artificial-intelligence.html/tab4/vd_1_2eaktism#.YyDxHaE8U_Y.mailto). + +1. Download & install the Maxim Microcontrollers SDK for your OS from the links below. + * [Windows](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0010820A) + * [Linux (Ubuntu)](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018720A) + * [MacOS](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018610A) + +2. Run the installer executable, and ensure that "Visual Studio Code Support" is enabled for your installation. + + ![Selected Components](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/installer_components.JPG) + +3. Finish the MaximSDK installation, taking note of where the MaximSDK was installed. + +4. Download & install Visual Studio Code for your OS [here](https://code.visualstudio.com/Download). + +5. Launch Visual Studio Code. + +6. Install the Microsoft [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + +7. Use `CTRL + SHIFT + P` (or `COMMAND + SHIFT + P` on MacOS) to open the developer prompt. + +8. Type "open settings json" and select the "Preferences: Open Settings (JSON)" option (_not_ the "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) + +9. 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... + } + ``` + +10. Save your changes to the file with `CTRL + S` and restart VS Code. + +11. That's it! You're ready to start using Visual Studio Code to develop with Maxim's Microcontrollers. The MaximSDK examples come pre-populated with .vscode project folders, and the `Tools/VSCode-Maxim` folder of the SDK contains documentation and templates. See [Usage](#usage) below for more details. + +## Usage + +This section covers basic usage of the VSCode-Maxim project files. For documentation on Visual Studio Code itself, please refer to the official docs [here](https://code.visualstudio.com/Docs). + +### Opening 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. + +A project that is configured for VS Code will have, at minimum, a .vscode sub-folder and a Makefile in its directory _(Note: You may need to enable viewing of hidden items in your file explorer to see the .vscode sub-folder)_. + +Ex: + +![Example Directory Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/opening_projects_2.jpg) + +### Where to Find Projects + +The [Examples](https://github.com/Analog-Devices-MSDK/msdk/tree/main/Examples) in the MSDK come with with pre-configured .vscode project folders. These projects can be opened "out of the box", but it's good practice to copy example folders _outside_ of the MSDK so that the original copies are kept as clean references. The examples can be freely moved to any location _without a space in its path_. + +Additionally, empty project templates and a drag-and-drop folder for "injecting" a VSCode-Maxim project can be found under `Tools/VSCode-Maxim` in the MaximSDK installation. + +### Build Tasks + +Once a project is opened 4 available build tasks will become available via `Terminal > Run Build task...` or the shortcut `Ctrl+Shift+B`. These tasks are configured by the `.vscode/task.json` file. + +![Build Tasks Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/buildtasks.JPG) + +#### Build + +* Compiles the code with a `make all` command. +* Additional options are passed into Make on the command-line based on the project's settings.json file. +* The `./build` directory will be created and will contain the output binary, as well as all intermediary object files. + +#### Clean + +* Cleans the build output, removing the `./build` directory and all of its contents. + +#### Clean-Periph + +* This task is the same as 'clean', but it also removes the build output for Maxim's peripheral drivers. +* Use this if you would like to recompile the peripheral drivers from source on the next build. + +#### Flash + +* Launching this task automatically runs the `Build` task first. Then, it flashes the output binary to the microcontroller. +* It uses the GDB `load` and `compare-sections` commands, and handles launching an OpenOCD internally via a pipe connection. +* The flashed program will be halted until the microcontroller is reset, power cycled, or a debugger is connected. +* A debugger must be connected correctly to use this task. Refer to the datasheet of your microcontroller's evaluation board for instructions. + +#### Flash & Run + +* This is the same as the `Flash` task, but it also will launch execution of the program once flashing is complete. + +#### Erase Flash + +* Completely erases all of the application code in the flash memory bank. +* Once complete, the target microcontroller will be effectively "blank". +* This can be useful for recovering from Low-Power (LP) lockouts, bad firmware, etc. + +### Debugging + +![Debug Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger.JPG) + +Debugging is enabled by Visual Studio Code's integrated debugger. Launch configurations can be found in the `.vscode/launch.json` file. + +* Note: **Flashing does not happen automatically when launching the debugger.** Run the "Flash" [build task](#build-tasks) for your program _before_ debugging. + +#### Debugger Limitations + +In general, Maxim's microcontrollers have the following debugger limitations at the hardware level: + +* The debugger can not be connected _while_ the device is in reset. + +* The device can not be debugged while the device is in Sleep, Low Power Mode, Micro Power Mode, Standby, Backup, or Shutdown mode. These modes shut down the SWD clock. + +* These limitations can sometimes make the device difficult or impossible to connect to if firmware has locked out the debugger. In such cases, the ["Erase Flash"](#erase-flash) task can be used to recover the part. + +#### Launching the Debugger + +1. Attach your debugger to the SWD port on the target microcontroller. (Refer to the datasheet of your evaluation board for instructions on connecting a debugger) + +2. Flash the program to the microcontroller with the "Flash" [Build Task](#build-tasks). **Flashing does not happen automatically when launching the debugger.** + +3. Launch the debugger with `Run > Start Debugging`, with the shortcut `F5`, or via the `Run and Debug` window (Ctrl + Shift + D) and the green "launch" arrow. + + ![Debug Tab](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_window.JPG) + +4. The debugger will launch a GDB client & OpenOCD server, reset the microcontroller, and should break on entry into `main`. + + ![Debugger Break on Main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_breakmain.JPG) + +#### Using the Debugger + +* For full usage details, please refer to the [official VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging). + +The main interface for the debugger is the debugger control bar: + +![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 can be set by clicking in the space next to the line number in a source code file. A red dot indicates a line to break on. Breakpoints can be removed by clicking on them again. Ex: + +![Breakpoint](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/breakpoint.JPG) + +## Project Configuration + +### Project Settings + +`.vscode/settings.json` is the main project configuration file. Values set here are parsed into the other .json config files. + +**When a change is made to this file, VS Code should be reloaded with CTRL+SHIFT+P -> Reload Window (or alternatively restarted completely) to force a re-parse.** + +![Reload Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/reload_window.JPG) + +The default project configuration should work for most use cases as long as `"target"` and `"board"` are set correctly. + +Any field from `settings.json` can be referenced from any other config file (including itself) with `"${config:[fieldname]}"` + +The following configuration options are available: + +### Basic Config Options + +#### `"target"` + +* This sets the target microcontroller for the project. +* It sets the `TARGET` [Build Configuration](#build-configuration) variable. +* Supported values: + * `"MAX32520"` + * `"MAX32570"` + * `"MAX32650"` + * `"MAX32655"` + * `"MAX32660"` + * `"MAX32662"` + * `"MAX32665"` (for MAX32665-MAX32668) + * `"MAX32670"` + * `"MAX32672"` + * `"MAX32675"` + * `"MAX32680"` + * `"MAX32690"` + * `"MAX78000"` + * `"MAX78002"` + +#### `"board"` + +* This sets the target board for the project (ie. Evaluation Kit, Feather board, etc.) +* Supported values: + * ... can be found in the `Libraries/Boards` folder of the MaximSDK + * For example, the supported options for the MAX78000 are `"EvKit_V1"`, `"FTHR_RevA"`, and `"MAXREFDES178"`. + + ![MAX78000 Boards](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/78000_boards.JPG) + +### Advanced Config Options + +#### `"MAXIM_PATH"` + +* This option must point to the root installation directory of the MaximSDK. +* It should be placed in the _global_ user settings.json file during first-time VSCode-Maxim setup. See [Installation](#installation). + +#### `"terminal.integrated.env.[platform]:Path"` + +* This prepends the location of toolchain binaries to the system `Path` used by VSCode's integrated terminal. +* The Path is not sanitized by default, which means that the terminal inherits the system path. +* Don't touch unless you know what you're doing :) + +#### `"project_name"` + +* Sets the name of project. This is used in other config options such as `program_file`. +* Default value: `"${workspaceFolderBasename}"` + +#### `"program_file"` + +* Sets the name of the file to flash and debug. This is provided in case it's needed, but for most use cases should be left at its default. +* File extension must be included. +* Default value: `"${config:project_name}.elf"` + +#### `"symbol_file"` + +* Sets the name of the file that GDB will load debug symbols from. +* File extension must be included. +* Default value: `"${config:program_file}"` + +#### `"M4_OCD_interface_file"` + +* Sets the OpenOCD interface file to use to connect to the Arm M4 core. This should match the debugger being used for the M4 core. +* The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"cmsis-dap.cfg"` + +#### `"M4_OCD_target_file"` + +* Sets the OpenOCD target file to use for the Arm M4 core. This should match the target microcontroller. +* `.cfg` file extension must be included. +* The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. +* Default value: `"${config:target}.cfg"` + +#### `"RV_OCD_interface_file"` + +* Sets the OpenOCD interface file to use to connect to the RISC-V core. This should match the debugger being used for the RISC-V core. +* The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"ftdi/olimex-arm-usb-ocd-h.cfg"` + +#### `"RV_OCD_target_file"` + +* Sets the OpenOCD target file to use for the RISC-V core. +* The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"${config:target}_riscv.cfg"` + +#### `"v_Arm_GCC"` + +* Sets the version of the Arm Embedded GCC to use, including toolchain binaries and the standard library version. +* This gets parsed into `ARM_GCC_path`. +* Default value: `"10.3"` + +#### `"v_xPack_GCC"` + +* Sets the version of the xPack RISC-V GCC to use. +* This gets parsed into `xPack_GCC_path`. +* Default value: `"10.2.0-1.2"` + +#### `"OCD_path"` + +* Where to find the OpenOCD. +* Default value: `"${config:MAXIM_PATH}/Tools/OpenOCD"` + +#### `"ARM_GCC_path"` + +* Where to find the Arm Embedded GCC Toolchain. +* Default value: `"${config:MAXIM_PATH}/Tools/GNUTools/${config:v_Arm_GCC}"` + +#### `"xPack_GCC_path"` + +* Where to find the RISC-V GCC Toolchain. +* Default value: `"${config:MAXIM_PATH}/Tools/xPack/riscv-none-embed-gcc/${config:v_xPack_GCC}"` + +#### `"Make_path"` + +* Where to find Make binaries (only used on Windows) +* Default value: `"${config:MAXIM_PATH}/Tools/MSYS2/usr/bin"` + +#### `"C_Cpp.default.includePath"` + +* Which paths to search to find header (.h) files. +* Does not recursively search by default. To recursively search, use `/**`. + +#### `"C_Cpp.default.browse.path"` + +* Which paths to search to find source (.c) files. +* Does not recursively search by default. To recursively search, use `/**`. + +#### `"C_Cpp.default.defines"` + +* Sets the compiler definitions to use for the intellisense engine. +* Most definitions should be defined in header files, but if a definition is missing it can be entered here to get the intellisense engine to recognize it. + +### Setting Search Paths for Intellisense + +VS Code's intellisense engine must be told where to find the header files for your source code. By default, Maxim's perpiheral drivers, the C standard libraries, and all of the sub-directories of the workspace will be searched for header files to use with Intellisense. If VS Code throws an error on an `#include` statement (and the file exists), then a search path is most likely missing. + +To add additional search paths : + +1. Open the `.vscode/settings.json` file. + +2. Add the include path(s) to the `C_Cpp.default.includePath` list. The paths set here should contain header files, and will be searched by the Intellisense engine and when using "Go to Declaration" in the editor. + +3. Add the path(s) to any relevant implementation files to the `C_Cpp.default.browse.path` list. This list contains the paths that will be searched when using "Go to Definition". + +## Build Configuration + +A project's build system is managed by two files found in the project's root directory. These files are used alongside the [GNU Make](https://www.gnu.org/software/make/) program (which is a part of the MaximSDK toolchain) to locate and build a project's source code for the correct microcontroller. + +* `Makefile` +* `project.mk` + +![Files are located in the root directory](img/projectmk.JPG) + +When the command... + +```shell +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 `=` operater 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 MaximSDK. 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 MaximSDK | `MAXIM_PATH=/path/to/MSDK` | This optional variable can be used to change where the Makefile looks for the MaximSDK. By default, the Makefile will attempt to locate the MaximSDK with a relative path moving "up" from its original location. This option is most useful when a project is moved _outside_ of the SDK 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 MaximSDK. 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 MaximSDK, 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.maximintegrated.com/en/design/technical-documents/userguides-and-manuals/7/7637.html). 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 MaximSDK will be searched. If the [SBT installer](https://www.maximintegrated.com/en/design/software-description.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 Maxim test key that can be used for development. + +## Project Creation + +### Option 1. Copying a Pre-Made Project + +Copying a pre-made example project is a great way to get rolling quickly, and is currently the recommended method for creating new projects. + +The release package for this project (Located at Tools/VSCode-Maxim in the MaximSDK) contains a `New_Project` folder designed for such purposes. Additionally, any of the VS Code-enabled Example projects can be copied from the SDK. + +1. Copy the existing project folder to an accessible location. This will be the location of your new project. + +2. (Optional) Rename the folder. For example, I might rename the folder to `MyProject`. + +3. Open the project in VS Code (`File -> Open Folder...`) + +4. Set your target microcontroller and board correctly. See [Basic Config Options](#basic-config-options) + +5. `CTRL+SHIFT+P -> Reload Window` to re-parse the project settings. + +6. That's it! The existing project is ready to build, debug, and modify. + +### Option 2 - Creating a Project from Scratch + +If you want to start from scratch, 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`. + +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 : + + ```shell + C:\Users\Jake.Carter\workspace\MyNewProject + +-- \.vscode + +-- Makefile + ``` + +3. Open the project in VS Code (`File -> Open Folder...`) + +4. Set your target microcontroller correctly. See [Basic Config Options](#basic-config-options). + +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. + +## Issue Tracker + +Bug reports, feature requests, and contributions are welcome via the [issues](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/issues) tracker on Github. + +New issues should contain _at minimum_ the following information: + +* Visual Studio Code version #s (see `Help -> About`) +* C/C++ Extension version # +* Target microcontroller and evaluation platform +* The projects `.vscode` folder and `Makefile` (where applicable). Standard compression formats such as `.zip`, `.rar`, `.tar.gz`, etc. are all acceptable. diff --git a/__init__.py b/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/generate.py b/generate.py index 57c3e62..e018d2f 100644 --- a/generate.py +++ b/generate.py @@ -32,18 +32,31 @@ *******************************************************************************/ """ -import os +import sys, os import shutil import stat -from utils import * +# from utils import * +from . import utils from pathlib import Path +from .maintain import sync # Get location of this file. # Need to use this so that template look-ups are decoupled from the caller's working directory -here = Path(__file__).parent +if getattr(sys, 'frozen', False): + # https://pyinstaller.org/en/stable/runtime-information.html#run-time-information + # Use sys.executable if app is bundled by pyinstaller + here = Path(sys.executable).parent + _defaults = here.joinpath("VSCode/MaximSDK/Inject/.vscode/settings.json") + template_dir = here.joinpath("VSCode/MaximSDK/Template").resolve() +else: + here = Path(__file__).parent + _defaults = here.joinpath("MaximSDK/Inject/.vscode/settings.json") + template_dir = here.joinpath("MaximSDK/Template").resolve() # Load default values for template from master "inject" folder so that we don't have to maintain multiple copies of the settings -defaults = parse_json(here.joinpath("MaximSDK/Inject/.vscode/settings.json")) +defaults = utils.parse_json(_defaults) + +synced=False whitelist = [ "MAX32650", @@ -61,10 +74,12 @@ ] def create_project( - out_path: str, + out_root: str, + out_stem: str, target: str, board: str, overwrite = False, + backup = False, program_file: str = defaults["PROGRAM_FILE"], symbol_file: str = defaults["SYMBOL_FILE"], m4_ocd_interface_file: str = defaults["M4_OCD_INTERFACE_FILE"], @@ -85,10 +100,12 @@ def create_project( Generates Visual Studio Code project files from the VSCode-Maxim project. """ - out_path = Path(out_path) + global synced + if not synced: + sync() + synced = True - template_dir = here.joinpath("MaximSDK/Template").resolve() - # Where to find the VS Code template directory relative to this script + out_path = Path(out_root).joinpath(out_stem) template_prefix = "template" # Filenames beginning with this will have substitution @@ -168,7 +185,7 @@ def create_project( write = True if out_file.exists(): - if not overwrite or compare_content(content, out_file): + if not overwrite or utils.compare_content(content, out_file): write = False if write: @@ -187,14 +204,16 @@ def create_project( write = True if out_file.exists(): - if not overwrite or (hash_file(in_file) == hash_file(out_file)): + if not overwrite or (utils.hash_file(in_file) == utils.hash_file(out_file)): write = False if write: + if backup and out_file.exists(): + shutil.copy(out_file, out_path.joinpath(f"{out_file.name}.backup")) shutil.copy(in_file, out_path) os.chmod(out_file, stat.S_IRWXU | stat.S_IRGRP | stat.S_IWGRP | stat.S_IROTH) if out_file not in updated: updated.append(out_file) # print(f"Wrote {os.path.basename(file)}") # Uncomment to debug - return (len(updated) > 0) \ No newline at end of file + return (len(updated) > 0) diff --git a/img/J-Link/browse-manually.JPG b/img/J-Link/browse-manually.JPG new file mode 100644 index 0000000..d0c0f78 Binary files /dev/null and b/img/J-Link/browse-manually.JPG differ diff --git a/img/J-Link/debug.JPG b/img/J-Link/debug.JPG new file mode 100644 index 0000000..a59b1c9 Binary files /dev/null and b/img/J-Link/debug.JPG differ diff --git a/img/J-Link/flash-jlink.JPG b/img/J-Link/flash-jlink.JPG new file mode 100644 index 0000000..d13cd45 Binary files /dev/null and b/img/J-Link/flash-jlink.JPG differ diff --git a/img/J-Link/flash.JPG b/img/J-Link/flash.JPG new file mode 100644 index 0000000..306ab3a Binary files /dev/null and b/img/J-Link/flash.JPG differ diff --git a/img/J-Link/jlink-debug.JPG b/img/J-Link/jlink-debug.JPG new file mode 100644 index 0000000..83b2c19 Binary files /dev/null and b/img/J-Link/jlink-debug.JPG differ diff --git a/img/J-Link/jlink-path.JPG b/img/J-Link/jlink-path.JPG new file mode 100644 index 0000000..386811e Binary files /dev/null and b/img/J-Link/jlink-path.JPG differ diff --git a/img/J-Link/jlinkcfg.JPG b/img/J-Link/jlinkcfg.JPG new file mode 100644 index 0000000..4f65d70 Binary files /dev/null and b/img/J-Link/jlinkcfg.JPG differ diff --git a/img/J-Link/m4_ocd_interface_file.JPG b/img/J-Link/m4_ocd_interface_file.JPG new file mode 100644 index 0000000..294a20d Binary files /dev/null and b/img/J-Link/m4_ocd_interface_file.JPG differ diff --git a/img/J-Link/open-settings.JPG b/img/J-Link/open-settings.JPG new file mode 100644 index 0000000..408cdd3 Binary files /dev/null and b/img/J-Link/open-settings.JPG differ diff --git a/img/J-Link/segger-driver.JPG b/img/J-Link/segger-driver.JPG new file mode 100644 index 0000000..9d3ac92 Binary files /dev/null and b/img/J-Link/segger-driver.JPG differ diff --git a/img/J-Link/zadig-listall.JPG b/img/J-Link/zadig-listall.JPG new file mode 100644 index 0000000..b23ad65 Binary files /dev/null and b/img/J-Link/zadig-listall.JPG differ diff --git a/img/J-Link/zadig-success.JPG b/img/J-Link/zadig-success.JPG new file mode 100644 index 0000000..f7f4568 Binary files /dev/null and b/img/J-Link/zadig-success.JPG differ diff --git a/img/J-Link/zadig.JPG b/img/J-Link/zadig.JPG new file mode 100644 index 0000000..d7d873d Binary files /dev/null and b/img/J-Link/zadig.JPG differ diff --git a/img/buildtasks.JPG b/img/buildtasks.JPG index d760616..98e6ffd 100644 Binary files a/img/buildtasks.JPG and b/img/buildtasks.JPG differ diff --git a/img/inject_gpio.JPG b/img/inject_gpio.JPG index 6a62cf2..6a47bf7 100644 Binary files a/img/inject_gpio.JPG and b/img/inject_gpio.JPG differ diff --git a/img/inject_gpio_finished.JPG b/img/inject_gpio_finished.JPG index 2cd01d4..143985f 100644 Binary files a/img/inject_gpio_finished.JPG and b/img/inject_gpio_finished.JPG differ diff --git a/img/projectmk.JPG b/img/projectmk.JPG new file mode 100644 index 0000000..1f4e6eb Binary files /dev/null and b/img/projectmk.JPG differ diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/c_cpp_properties.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/c_cpp_properties.json index bd9d5ef..dfbed47 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/c_cpp_properties.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/c_cpp_properties.json @@ -11,7 +11,7 @@ "intelliSenseMode": "gcc-arm", "compilerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gcc.exe", "browse": { - "path": [ + "path": [ "${default}" ] } diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/launch.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/launch.json index 9c45b1d..fb021b9 100755 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/launch.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/launch.json @@ -46,6 +46,7 @@ { "text":"symbol-file build/${config:symbol_file}" }, { "text":"target remote localhost:3333" }, { "text":"monitor reset halt" }, + { "text":"set $pc=Reset_Handler"}, { "text":"b main" } ] }, diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/tasks.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/tasks.json index 3951f35..81917f6 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/tasks.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "build", "type": "shell", - "command": "make -r -j 8 all TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", + "command": "make -r -j 8 TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", "group": "build", "problemMatcher": [] }, diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/Makefile b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/Makefile index aa6f3e8..f16fc0e 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/Makefile +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/Makefile @@ -1,5 +1,5 @@ # /******************************************************************************* -# * Copyright (C) 2021 Maxim Integrated Products, Inc., All Rights Reserved. +# * Copyright (C) 2022 Maxim Integrated Products, Inc., All Rights Reserved. # * # * Permission is hereby granted, free of charge, to any person obtaining a # * copy of this software and associated documentation files (the "Software"), @@ -29,91 +29,360 @@ # * property whatsoever. Maxim Integrated Products, Inc. retains all # * ownership rights. # ******************************************************************************* +# */ - ############################################################################### -# Main configuration -# Below are the most commonly needed configuration options for this Makefile. -# You shouldn't need to touch anything else unless advanced configuration is required. +# ** Readme! ** +# Don't edit this file! This is the core Makefile for a MaximSDK +# project. The available configuration options can be overridden +# in "project.mk", on the command-line, or with system environment +# variables. -# Source files to compile for this project (add path to VPATH below) -SRCS += main.c +# See https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration +# for more detailed instructions on how to use this system. -# Where to find source files for this project -VPATH += ./src +# The detailed instructions mentioned above are easier to read than +# this file, but the comments found in this file also outline the +# available configuration variables. This file is organized into +# sub-sections, some of which expose config variables. -# Where to find header files for this project -IPATH += ./src -# Set compiler flags -PROJ_CFLAGS+=-Wall # Enable warnings -PROJ_CFLAGS+=-DMXC_ASSERT_ENABLE # Enable assertion checking for development +# ******************************************************************************* +# Set the target microcontroller and board to compile for. -# Set compiler optimization level -MXC_OPTIMIZE_CFLAGS=-Og +# Every TARGET microcontroller has some Board Support Packages (BSPs) that are +# available for it under the MaximSDK/Libraries/Boards/TARGET folder. The BSP +# that gets selected is MaximSDK/Libraries/Boards/TARGET/BOARD. - ############################################################################### +# Configuration Variables: +# - TARGET : Override the default target microcontroller. Ex: TARGET=MAX78000 +# - BOARD : Override the default BSP (case sensitive). Ex: BOARD=EvKit_V1, BOARD=FTHR_RevA -# Set the MAKE variable. This eliminates issues with some setups -MAKE=make ifeq "$(TARGET)" "" -$(error target must be specified! Set the TARGET variable.) +# Default target microcontroller +TARGET := MAX78000 +TARGET_UC := MAX78000 +TARGET_LC := max78000 +else +# "TARGET" has been overridden in the environment or on the command-line. +# We need to calculate an upper and lowercase version of the part number, +# because paths on Linux and MacOS are case-sensitive. +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) endif -# Default board used. This is overridden in settings.json -ifeq "$(BOARD)" "" -$(error board must be specified! Set the BOARD variable.) -endif +# Default board. +BOARD ?= EvKit_V1 + +# ******************************************************************************* +# Locate the MaximSDK + +# This Makefile needs to know where to find the MaximSDK, and the MAXIM_PATH variable +# should point to the root directory of the MaximSDK installation. Setting this manually +# is usually only required if you're working on the command-line. + +# If MAXIM_PATH is not specified, we assume the project still lives inside of the MaximSDK +# and move up from this project's original location. + +# Configuration Variables: +# - MAXIM_PATH : Tell this Makefile where to find the MaximSDK. Ex: MAXIM_PATH=C:/MaximSDK + -# Set output filename -ifeq "$(PROJECT)" "" -PROJECT=$(TARGET) +ifneq "$(MAXIM_PATH)" "" +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) +# Locate some other useful paths... +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS endif -# Create Target name variables -TARGET_UC:=$(shell echo $(TARGET) | tr a-z A-Z) -TARGET_LC:=$(shell echo $(TARGET) | tr A-Z a-z) +# ******************************************************************************* +# Include project Makefile. We do this after formulating TARGET, BOARD, and MAXIM_PATH +# in case project.mk needs to reference those values. However, we also include +# this as early as possible in the Makefile so that it can append to or override +# the variables below. -# Select 'GCC' or 'IAR' compiler -COMPILER=GCC -# This is the path to the CMSIS root directory +include ./project.mk +$(info Loaded project.mk) + +# ******************************************************************************* +# Final path sanitization and re-calculation. No options here. + ifeq "$(MAXIM_PATH)" "" -LIBS_DIR=../../../Libraries +# MAXIM_PATH is still not defined... +DEPTH := ../../../ +MAXIM_PATH := $(abspath $(DEPTH)) +$(warning Warning: MAXIM_PATH is not set! Set MAXIM_PATH in your environment or in project.mk to clear this warning.) +$(warning Warning: Attempting to use $(MAXIM_PATH) calculated from relative path) else -LIBS_DIR=/$(subst \,/,$(subst :,,$(MAXIM_PATH))/Libraries) +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) endif -#LIBS_DIR = ./Libraries -CMSIS_ROOT=$(LIBS_DIR)/CMSIS +# Final recalculation of LIBS_DIR/CMSIS_ROOT +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS + +# One final UC/LC check in case user set TARGET in project.mk +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) -#Use this for other library make files so they are all based off the same as root as the project +export TARGET +export TARGET_UC +export TARGET_LC export CMSIS_ROOT +# TODO: Remove dependency on exports for these variables. + +# ******************************************************************************* +# Set up search paths, and auto-detect all source code on those paths. + +# The following paths are searched by default, where "./" is the project directory. +# ./ +# |- *.h +# |- *.c +# |-include (optional) +# |- *.h +# |-src (optional) +# |- *.c + +# Configuration Variables: +# - VPATH : Tell this Makefile to search additional locations for source (.c) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - IPATH : Tell this Makefile to search additional locations for header (.h) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - SRCS : Tell this Makefile to explicitly add a source (.c) file to the build. +# This is really only useful if you want to add a source file that isn't +# on any VPATH, in which case you can add the full path to the file here. +# You should use the "+=" operator with this option. +# Ex: SRCS += your/specific/source/file.c +# - AUTOSEARCH : Set whether this Makefile should automatically detect .c files on +# VPATH and add them to the build. This is enabled by default. Set +# to 0 to disable. If autosearch is disabled, source files must be +# manually added to SRCS. +# Ex: AUTOSEARCH = 0 + + +# Where to find source files for this project. +VPATH += . +VPATH += src +VPATH := $(VPATH) + +# Where to find header files for this project +IPATH += . +IPATH += include +IPATH := $(IPATH) + +AUTOSEARCH ?= 1 +ifeq ($(AUTOSEARCH), 1) +# Auto-detect all C source files on VPATH +SRCS += $(wildcard $(addsuffix /*.c, $(VPATH))) +endif + +# Collapse SRCS before passing them on to the next stage +SRCS := $(SRCS) + +# ******************************************************************************* +# Set the output filename + +# Configuration Variables: +# - PROJECT : Override the default output filename. Ex: PROJECT=MyProject + + +# The default value creates a file named after the target micro. Ex: MAX78000.elf +PROJECT ?= $(TARGET_LC) + +# ******************************************************************************* +# Compiler options + +# Configuration Variables: +# - MXC_OPTIMIZE_CFLAGS : Override the default compiler optimization level. +# Ex: MXC_OPTIMIZE_CFLAGS = -O2 +# - PROJ_CFLAGS : Add additional compiler flags to the build. +# You should use the "+=" operator with this option. +# Ex: PROJ_CFLAGS += -Wextra +# - MFLOAT_ABI : Set the floating point acceleration level. +# The only options are "hard", "soft", or "softfp". +# Ex: MFLOAT_ABI = hard +# - LINKERFILE : Override the default linkerfile. +# Ex: LINKERFILE = customlinkerfile.ld + + +# Select 'GCC' or 'IAR' compiler +ifeq "$(COMPILER)" "" +COMPILER := GCC +endif + +# Set default compiler optimization levels +ifeq "$(MAKECMDGOALS)" "release" +# Default optimization level for "release" builds (make release) +MXC_OPTIMIZE_CFLAGS ?= -O2 +DEBUG = 0 +endif + +ifeq ($(DEBUG),1) +# Default optimization level for debug builds (make DEBUG=1 ...) +# gcc.mk checks for this flag to add some additional debug +# info to the build, and should be used when you really need to +# debug. +MXC_OPTIMIZE_CFLAGS := -Og +endif + +# Fallback default optimizes for debugging as recommended +# by GNU for code-edit-debug cycles +# https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options +MXC_OPTIMIZE_CFLAGS ?= -Og + +# Set compiler flags +PROJ_CFLAGS += -Wall # Enable warnings +PROJ_CFLAGS += -DMXC_ASSERT_ENABLE + +# Set hardware floating point acceleration. +# Options are: +# - hard +# - soft +# - softfp (default if MFLOAT_ABI is not set) +MFLOAT_ABI ?= softfp +# MFLOAT_ABI must be exported to other Makefiles, who check this too +export MFLOAT_ABI + +# Set the default linkerfile. Since the core Makefiles later add the location of Maxim's +# linkerfiles to VPATH, and the local project directory has also been added to VPATH, Make +# will search both locations for the specified linkerfile if it can't find it by its path alone. +# The result is that overriding LINKERFILE with the filename of one of Maxim's alternate linkerfiles +# (ex: LINKERFILE=max78000_arm.ld) will work just the same as LINKERFILE=mycustom.ld +# even if mycustom.ld lives locally to this project. + +ifeq "$(RISCV_CORE)" "" +# Default linkerfile is only specified for standard Arm-core projects. +# Otherwise, gcc_riscv.mk sets the appropriate riscv linkerfile. +LINKER = $(TARGET_LC).ld +LINKERFILE ?= $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +endif + +# This path contains system-level intialization files for the target micro. Add to the build. VPATH += $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source -# Point this variable to a linker file to override the default file -LINKER=$(TARGET_LC).ld -LINKERFILE=$(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +# ******************************************************************************* +# Secure Boot Tools (SBT) + +# This section integrates the Secure Boot Tools. It's intended for use with +# microcontrollers that have a secure bootloader. + +# Enabling SBT integration will add some special rules, such as "make sla", "make scpa", etc. + +# Configuration variables: +# SBT : Toggle SBT integration. Set to 1 to enable, or 0 +# to disable +# MAXIM_SBT_DIR : Specify the location of the SBT tool binaries. This defaults to +# Tools/SBT in the MaximSDK. The standalone SBT installer will override +# this via an environment variable. +# TARGET_SEC : Specify the part number to be passed into the SBT. This should match +# the secure variant part #. The default value will depend on TARGET. +# For example, TARGET=MAX32650 will result in TARGET_SEC=MAX32651, and +# the default selection happens in Tools/SBT/SBT-config. +# However, if there are multiple secure part #s for the target +# microcontroller this variable may need to be changed. + +SBT ?= 0 +ifeq ($(SBT), 1) +MAXIM_SBT_DIR ?= $(MAXIM_PATH)/Tools/SBT +MAXIM_SBT_DIR := $(subst \,/,$(MAXIM_SBT_DIR)) +# ^ Must sanitize path for \ on Windows, since this may come from an environment +# variable. + +export MAXIM_SBT_DIR # SBTs must have this environment variable defined to work + +# SBT-config.mk and SBT-rules.mk are included further down this Makefile. + +endif # SBT + +# ******************************************************************************* +# Default goal selection. This section allows you to override the default goal +# that will run if no targets are specified on the command-line. +# (ie. just running 'make' instead of 'make all') + +# Configuration variables: +# .DEFAULT_GOAL : Set the default goal if no targets were specified on the +# command-line +# ** "override" must be used with this variable. ** +# Ex: "override .DEFAULT_GOAL = mygoal" + +ifeq "$(.DEFAULT_GOAL)" "" +ifeq ($(SBT),1) +override .DEFAULT_GOAL := sla +else +override .DEFAULT_GOAL := all +endif +endif + +# Developer note: 'override' is used above for legacy Makefile compatibility. +# gcc.mk/gcc_riscv.mk need to hard-set 'all' internally, so this new system +# uses 'override' to come in over the top without breaking old projects. + +# It's also necessary to explicitly set MAKECMDGOALS... +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + +# ******************************************************************************* +# Include SBT config. We need to do this here because it needs to know +# the current MAKECMDGOAL. +ifeq ($(SBT),1) +include $(MAXIM_PATH)/Tools/SBT/SBT-config.mk +endif + +# ******************************************************************************* +# Libraries -################################################################################ -# Include external library makefiles here +# This section offers "toggle switches" to include or exclude the libraries that +# are available in the MaximSDK. Set a configuration variable to 1 to include the +# library in the build, or 0 to exclude. -# Include the BSP -BOARD_DIR=$(LIBS_DIR)/Boards/$(TARGET_UC)/$(BOARD) -include $(BOARD_DIR)/board.mk +# Each library may also have its own library specific configuration variables. See +# Libraries/libs.mk for more details. -# Include the peripheral driver -PERIPH_DRIVER_DIR=$(LIBS_DIR)/PeriphDrivers -include $(PERIPH_DRIVER_DIR)/periphdriver.mk -export PERIPH_DRIVER_DIR +# Configuration variables: +# - LIB_BOARD : Include the Board-Support Package (BSP) library. (Enabled by default) +# - LIB_PERIPHDRIVERS : Include the peripheral driver library. (Enabled by default) +# - LIB_CMSIS_DSP : Include the CMSIS-DSP library. +# - LIB_CORDIO : Include the Cordio BLE library +# - LIB_FCL : Include the Free Cryptographic Library (FCL) +# - LIB_FREERTOS : Include the FreeRTOS and FreeRTOS-Plus-CLI libraries +# - LIB_LC3 : Include the Low Complexity Communication Codec (LC3) library +# - LIB_LITTLEFS : Include the "little file system" (littleFS) library +# - LIB_LWIP : Include the lwIP library +# - LIB_MAXUSB : Include the MAXUSB library +# - LIB_SDHC : Include the SDHC library + +include $(LIBS_DIR)/libs.mk + + +# ******************************************************************************* +# Rules -################################################################################ # Include the rules for building for this target. All other makefiles should be # included before this one. include $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/$(COMPILER)/$(TARGET_LC).mk +# Include the rules that integrate the SBTs. SBTs are a special case that must be +# include after the core gcc rules to extend them. +ifeq ($(SBT), 1) +include $(MAXIM_PATH)/Tools/SBT/SBT-rules.mk +endif + + +# Get .DEFAULT_GOAL working. +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + + all: # Extend the functionality of the "all" recipe here + arm-none-eabi-size --format=berkeley $(BUILD_DIR)/$(PROJECT).elf libclean: $(MAKE) -f ${PERIPH_DRIVER_DIR}/periphdriver.mk clean.periph diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/project.mk b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/project.mk new file mode 100644 index 0000000..250f70c --- /dev/null +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/project.mk @@ -0,0 +1,13 @@ +# 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! + + + diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/c_cpp_properties.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/c_cpp_properties.json index bd9d5ef..dfbed47 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/c_cpp_properties.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/c_cpp_properties.json @@ -11,7 +11,7 @@ "intelliSenseMode": "gcc-arm", "compilerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gcc.exe", "browse": { - "path": [ + "path": [ "${default}" ] } diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/launch.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/launch.json index 9c45b1d..fb021b9 100755 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/launch.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/launch.json @@ -46,6 +46,7 @@ { "text":"symbol-file build/${config:symbol_file}" }, { "text":"target remote localhost:3333" }, { "text":"monitor reset halt" }, + { "text":"set $pc=Reset_Handler"}, { "text":"b main" } ] }, diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/tasks.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/tasks.json index 3951f35..81917f6 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/tasks.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/tasks.json @@ -4,7 +4,7 @@ { "label": "build", "type": "shell", - "command": "make -r -j 8 all TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", + "command": "make -r -j 8 TARGET=${config:target} BOARD=${config:board} MAXIM_PATH=${config:MAXIM_PATH} MAKE=make PROJECT=${config:project_name}", "group": "build", "problemMatcher": [] }, diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/Makefile b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/Makefile index aa6f3e8..f16fc0e 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/Makefile +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/Makefile @@ -1,5 +1,5 @@ # /******************************************************************************* -# * Copyright (C) 2021 Maxim Integrated Products, Inc., All Rights Reserved. +# * Copyright (C) 2022 Maxim Integrated Products, Inc., All Rights Reserved. # * # * Permission is hereby granted, free of charge, to any person obtaining a # * copy of this software and associated documentation files (the "Software"), @@ -29,91 +29,360 @@ # * property whatsoever. Maxim Integrated Products, Inc. retains all # * ownership rights. # ******************************************************************************* +# */ - ############################################################################### -# Main configuration -# Below are the most commonly needed configuration options for this Makefile. -# You shouldn't need to touch anything else unless advanced configuration is required. +# ** Readme! ** +# Don't edit this file! This is the core Makefile for a MaximSDK +# project. The available configuration options can be overridden +# in "project.mk", on the command-line, or with system environment +# variables. -# Source files to compile for this project (add path to VPATH below) -SRCS += main.c +# See https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration +# for more detailed instructions on how to use this system. -# Where to find source files for this project -VPATH += ./src +# The detailed instructions mentioned above are easier to read than +# this file, but the comments found in this file also outline the +# available configuration variables. This file is organized into +# sub-sections, some of which expose config variables. -# Where to find header files for this project -IPATH += ./src -# Set compiler flags -PROJ_CFLAGS+=-Wall # Enable warnings -PROJ_CFLAGS+=-DMXC_ASSERT_ENABLE # Enable assertion checking for development +# ******************************************************************************* +# Set the target microcontroller and board to compile for. -# Set compiler optimization level -MXC_OPTIMIZE_CFLAGS=-Og +# Every TARGET microcontroller has some Board Support Packages (BSPs) that are +# available for it under the MaximSDK/Libraries/Boards/TARGET folder. The BSP +# that gets selected is MaximSDK/Libraries/Boards/TARGET/BOARD. - ############################################################################### +# Configuration Variables: +# - TARGET : Override the default target microcontroller. Ex: TARGET=MAX78000 +# - BOARD : Override the default BSP (case sensitive). Ex: BOARD=EvKit_V1, BOARD=FTHR_RevA -# Set the MAKE variable. This eliminates issues with some setups -MAKE=make ifeq "$(TARGET)" "" -$(error target must be specified! Set the TARGET variable.) +# Default target microcontroller +TARGET := MAX78000 +TARGET_UC := MAX78000 +TARGET_LC := max78000 +else +# "TARGET" has been overridden in the environment or on the command-line. +# We need to calculate an upper and lowercase version of the part number, +# because paths on Linux and MacOS are case-sensitive. +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) endif -# Default board used. This is overridden in settings.json -ifeq "$(BOARD)" "" -$(error board must be specified! Set the BOARD variable.) -endif +# Default board. +BOARD ?= EvKit_V1 + +# ******************************************************************************* +# Locate the MaximSDK + +# This Makefile needs to know where to find the MaximSDK, and the MAXIM_PATH variable +# should point to the root directory of the MaximSDK installation. Setting this manually +# is usually only required if you're working on the command-line. + +# If MAXIM_PATH is not specified, we assume the project still lives inside of the MaximSDK +# and move up from this project's original location. + +# Configuration Variables: +# - MAXIM_PATH : Tell this Makefile where to find the MaximSDK. Ex: MAXIM_PATH=C:/MaximSDK + -# Set output filename -ifeq "$(PROJECT)" "" -PROJECT=$(TARGET) +ifneq "$(MAXIM_PATH)" "" +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) +# Locate some other useful paths... +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS endif -# Create Target name variables -TARGET_UC:=$(shell echo $(TARGET) | tr a-z A-Z) -TARGET_LC:=$(shell echo $(TARGET) | tr A-Z a-z) +# ******************************************************************************* +# Include project Makefile. We do this after formulating TARGET, BOARD, and MAXIM_PATH +# in case project.mk needs to reference those values. However, we also include +# this as early as possible in the Makefile so that it can append to or override +# the variables below. -# Select 'GCC' or 'IAR' compiler -COMPILER=GCC -# This is the path to the CMSIS root directory +include ./project.mk +$(info Loaded project.mk) + +# ******************************************************************************* +# Final path sanitization and re-calculation. No options here. + ifeq "$(MAXIM_PATH)" "" -LIBS_DIR=../../../Libraries +# MAXIM_PATH is still not defined... +DEPTH := ../../../ +MAXIM_PATH := $(abspath $(DEPTH)) +$(warning Warning: MAXIM_PATH is not set! Set MAXIM_PATH in your environment or in project.mk to clear this warning.) +$(warning Warning: Attempting to use $(MAXIM_PATH) calculated from relative path) else -LIBS_DIR=/$(subst \,/,$(subst :,,$(MAXIM_PATH))/Libraries) +# Sanitize MAXIM_PATH for backslashes +MAXIM_PATH := $(subst \,/,$(MAXIM_PATH)) endif -#LIBS_DIR = ./Libraries -CMSIS_ROOT=$(LIBS_DIR)/CMSIS +# Final recalculation of LIBS_DIR/CMSIS_ROOT +LIBS_DIR := $(abspath $(MAXIM_PATH)/Libraries) +CMSIS_ROOT := $(LIBS_DIR)/CMSIS + +# One final UC/LC check in case user set TARGET in project.mk +TARGET_UC := $(subst m,M,$(subst a,A,$(subst x,X,$(TARGET)))) +TARGET_LC := $(subst M,m,$(subst A,a,$(subst X,x,$(TARGET)))) -#Use this for other library make files so they are all based off the same as root as the project +export TARGET +export TARGET_UC +export TARGET_LC export CMSIS_ROOT +# TODO: Remove dependency on exports for these variables. + +# ******************************************************************************* +# Set up search paths, and auto-detect all source code on those paths. + +# The following paths are searched by default, where "./" is the project directory. +# ./ +# |- *.h +# |- *.c +# |-include (optional) +# |- *.h +# |-src (optional) +# |- *.c + +# Configuration Variables: +# - VPATH : Tell this Makefile to search additional locations for source (.c) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - IPATH : Tell this Makefile to search additional locations for header (.h) files. +# You should use the "+=" operator with this option. +# Ex: VPATH += your/new/path +# - SRCS : Tell this Makefile to explicitly add a source (.c) file to the build. +# This is really only useful if you want to add a source file that isn't +# on any VPATH, in which case you can add the full path to the file here. +# You should use the "+=" operator with this option. +# Ex: SRCS += your/specific/source/file.c +# - AUTOSEARCH : Set whether this Makefile should automatically detect .c files on +# VPATH and add them to the build. This is enabled by default. Set +# to 0 to disable. If autosearch is disabled, source files must be +# manually added to SRCS. +# Ex: AUTOSEARCH = 0 + + +# Where to find source files for this project. +VPATH += . +VPATH += src +VPATH := $(VPATH) + +# Where to find header files for this project +IPATH += . +IPATH += include +IPATH := $(IPATH) + +AUTOSEARCH ?= 1 +ifeq ($(AUTOSEARCH), 1) +# Auto-detect all C source files on VPATH +SRCS += $(wildcard $(addsuffix /*.c, $(VPATH))) +endif + +# Collapse SRCS before passing them on to the next stage +SRCS := $(SRCS) + +# ******************************************************************************* +# Set the output filename + +# Configuration Variables: +# - PROJECT : Override the default output filename. Ex: PROJECT=MyProject + + +# The default value creates a file named after the target micro. Ex: MAX78000.elf +PROJECT ?= $(TARGET_LC) + +# ******************************************************************************* +# Compiler options + +# Configuration Variables: +# - MXC_OPTIMIZE_CFLAGS : Override the default compiler optimization level. +# Ex: MXC_OPTIMIZE_CFLAGS = -O2 +# - PROJ_CFLAGS : Add additional compiler flags to the build. +# You should use the "+=" operator with this option. +# Ex: PROJ_CFLAGS += -Wextra +# - MFLOAT_ABI : Set the floating point acceleration level. +# The only options are "hard", "soft", or "softfp". +# Ex: MFLOAT_ABI = hard +# - LINKERFILE : Override the default linkerfile. +# Ex: LINKERFILE = customlinkerfile.ld + + +# Select 'GCC' or 'IAR' compiler +ifeq "$(COMPILER)" "" +COMPILER := GCC +endif + +# Set default compiler optimization levels +ifeq "$(MAKECMDGOALS)" "release" +# Default optimization level for "release" builds (make release) +MXC_OPTIMIZE_CFLAGS ?= -O2 +DEBUG = 0 +endif + +ifeq ($(DEBUG),1) +# Default optimization level for debug builds (make DEBUG=1 ...) +# gcc.mk checks for this flag to add some additional debug +# info to the build, and should be used when you really need to +# debug. +MXC_OPTIMIZE_CFLAGS := -Og +endif + +# Fallback default optimizes for debugging as recommended +# by GNU for code-edit-debug cycles +# https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#Optimize-Options +MXC_OPTIMIZE_CFLAGS ?= -Og + +# Set compiler flags +PROJ_CFLAGS += -Wall # Enable warnings +PROJ_CFLAGS += -DMXC_ASSERT_ENABLE + +# Set hardware floating point acceleration. +# Options are: +# - hard +# - soft +# - softfp (default if MFLOAT_ABI is not set) +MFLOAT_ABI ?= softfp +# MFLOAT_ABI must be exported to other Makefiles, who check this too +export MFLOAT_ABI + +# Set the default linkerfile. Since the core Makefiles later add the location of Maxim's +# linkerfiles to VPATH, and the local project directory has also been added to VPATH, Make +# will search both locations for the specified linkerfile if it can't find it by its path alone. +# The result is that overriding LINKERFILE with the filename of one of Maxim's alternate linkerfiles +# (ex: LINKERFILE=max78000_arm.ld) will work just the same as LINKERFILE=mycustom.ld +# even if mycustom.ld lives locally to this project. + +ifeq "$(RISCV_CORE)" "" +# Default linkerfile is only specified for standard Arm-core projects. +# Otherwise, gcc_riscv.mk sets the appropriate riscv linkerfile. +LINKER = $(TARGET_LC).ld +LINKERFILE ?= $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +endif + +# This path contains system-level intialization files for the target micro. Add to the build. VPATH += $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source -# Point this variable to a linker file to override the default file -LINKER=$(TARGET_LC).ld -LINKERFILE=$(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/GCC/$(LINKER) +# ******************************************************************************* +# Secure Boot Tools (SBT) + +# This section integrates the Secure Boot Tools. It's intended for use with +# microcontrollers that have a secure bootloader. + +# Enabling SBT integration will add some special rules, such as "make sla", "make scpa", etc. + +# Configuration variables: +# SBT : Toggle SBT integration. Set to 1 to enable, or 0 +# to disable +# MAXIM_SBT_DIR : Specify the location of the SBT tool binaries. This defaults to +# Tools/SBT in the MaximSDK. The standalone SBT installer will override +# this via an environment variable. +# TARGET_SEC : Specify the part number to be passed into the SBT. This should match +# the secure variant part #. The default value will depend on TARGET. +# For example, TARGET=MAX32650 will result in TARGET_SEC=MAX32651, and +# the default selection happens in Tools/SBT/SBT-config. +# However, if there are multiple secure part #s for the target +# microcontroller this variable may need to be changed. + +SBT ?= 0 +ifeq ($(SBT), 1) +MAXIM_SBT_DIR ?= $(MAXIM_PATH)/Tools/SBT +MAXIM_SBT_DIR := $(subst \,/,$(MAXIM_SBT_DIR)) +# ^ Must sanitize path for \ on Windows, since this may come from an environment +# variable. + +export MAXIM_SBT_DIR # SBTs must have this environment variable defined to work + +# SBT-config.mk and SBT-rules.mk are included further down this Makefile. + +endif # SBT + +# ******************************************************************************* +# Default goal selection. This section allows you to override the default goal +# that will run if no targets are specified on the command-line. +# (ie. just running 'make' instead of 'make all') + +# Configuration variables: +# .DEFAULT_GOAL : Set the default goal if no targets were specified on the +# command-line +# ** "override" must be used with this variable. ** +# Ex: "override .DEFAULT_GOAL = mygoal" + +ifeq "$(.DEFAULT_GOAL)" "" +ifeq ($(SBT),1) +override .DEFAULT_GOAL := sla +else +override .DEFAULT_GOAL := all +endif +endif + +# Developer note: 'override' is used above for legacy Makefile compatibility. +# gcc.mk/gcc_riscv.mk need to hard-set 'all' internally, so this new system +# uses 'override' to come in over the top without breaking old projects. + +# It's also necessary to explicitly set MAKECMDGOALS... +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + +# ******************************************************************************* +# Include SBT config. We need to do this here because it needs to know +# the current MAKECMDGOAL. +ifeq ($(SBT),1) +include $(MAXIM_PATH)/Tools/SBT/SBT-config.mk +endif + +# ******************************************************************************* +# Libraries -################################################################################ -# Include external library makefiles here +# This section offers "toggle switches" to include or exclude the libraries that +# are available in the MaximSDK. Set a configuration variable to 1 to include the +# library in the build, or 0 to exclude. -# Include the BSP -BOARD_DIR=$(LIBS_DIR)/Boards/$(TARGET_UC)/$(BOARD) -include $(BOARD_DIR)/board.mk +# Each library may also have its own library specific configuration variables. See +# Libraries/libs.mk for more details. -# Include the peripheral driver -PERIPH_DRIVER_DIR=$(LIBS_DIR)/PeriphDrivers -include $(PERIPH_DRIVER_DIR)/periphdriver.mk -export PERIPH_DRIVER_DIR +# Configuration variables: +# - LIB_BOARD : Include the Board-Support Package (BSP) library. (Enabled by default) +# - LIB_PERIPHDRIVERS : Include the peripheral driver library. (Enabled by default) +# - LIB_CMSIS_DSP : Include the CMSIS-DSP library. +# - LIB_CORDIO : Include the Cordio BLE library +# - LIB_FCL : Include the Free Cryptographic Library (FCL) +# - LIB_FREERTOS : Include the FreeRTOS and FreeRTOS-Plus-CLI libraries +# - LIB_LC3 : Include the Low Complexity Communication Codec (LC3) library +# - LIB_LITTLEFS : Include the "little file system" (littleFS) library +# - LIB_LWIP : Include the lwIP library +# - LIB_MAXUSB : Include the MAXUSB library +# - LIB_SDHC : Include the SDHC library + +include $(LIBS_DIR)/libs.mk + + +# ******************************************************************************* +# Rules -################################################################################ # Include the rules for building for this target. All other makefiles should be # included before this one. include $(CMSIS_ROOT)/Device/Maxim/$(TARGET_UC)/Source/$(COMPILER)/$(TARGET_LC).mk +# Include the rules that integrate the SBTs. SBTs are a special case that must be +# include after the core gcc rules to extend them. +ifeq ($(SBT), 1) +include $(MAXIM_PATH)/Tools/SBT/SBT-rules.mk +endif + + +# Get .DEFAULT_GOAL working. +ifeq "$(MAKECMDGOALS)" "" +MAKECMDGOALS:=$(.DEFAULT_GOAL) +endif + + all: # Extend the functionality of the "all" recipe here + arm-none-eabi-size --format=berkeley $(BUILD_DIR)/$(PROJECT).elf libclean: $(MAKE) -f ${PERIPH_DRIVER_DIR}/periphdriver.mk clean.periph diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/project.mk b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/project.mk new file mode 100644 index 0000000..250f70c --- /dev/null +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/project.mk @@ -0,0 +1,13 @@ +# 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! + + + diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/README.md b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/README.md new file mode 100644 index 0000000..b6456f1 --- /dev/null +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/README.md @@ -0,0 +1,547 @@ +# VSCode-Maxim + +_(If you're viewing this document from within Visual Studio Code you can press `CTRL+SHIFT+V` to open a Markdown preview window.)_ + +## Quick Links + +* [VSCode-Maxim Github](https://github.com/Analog-Devices-MSDK/VSCode-Maxim) +* [Wiki](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki) + * If it's not in the readme, check the wiki. + * If it's not in the wiki, open a ticket! + +## Introduction + +VSCode-Maxim is a set of [Visual Studio Code](https://code.visualstudio.com/) project configurations and utilities for enabling embedded development for [Analog Device's MSDK](https://github.com/Analog-Devices-MSDK/msdk) and the [MAX-series](https://www.maximintegrated.com/en/products/microcontrollers.html) microcontrollers. + +The following features are supported: + +* Code editing with intellisense down to the register level +* Code compilation with the ability to easily re-target a project for different microcontrollers and boards +* Flashing programs +* GUI and command-line debugging + +## Dependencies + +* [Visual Studio Code](https://code.visualstudio.com/) +* [C/C++ VSCode Extension](https://github.com/microsoft/vscode-cpptools) +* [Maxim Micros SDK](https://www.maximintegrated.com/content/maximintegrated/en/design/software-description.html/swpart=SFW0010820A) + +## Installation + +The steps below are also available in video form in "Understanding Artificial Intelligence Episode 8.5 - Visual Studio Code" [here](https://www.maximintegrated.com/en/products/microcontrollers/artificial-intelligence.html/tab4/vd_1_2eaktism#.YyDxHaE8U_Y.mailto). + +1. Download & install the Maxim Microcontrollers SDK for your OS from the links below. + * [Windows](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0010820A) + * [Linux (Ubuntu)](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018720A) + * [MacOS](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018610A) + +2. Run the installer executable, and ensure that "Visual Studio Code Support" is enabled for your installation. + + ![Selected Components](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/installer_components.JPG) + +3. Finish the MaximSDK installation, taking note of where the MaximSDK was installed. + +4. Download & install Visual Studio Code for your OS [here](https://code.visualstudio.com/Download). + +5. Launch Visual Studio Code. + +6. Install the Microsoft [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). + +7. Use `CTRL + SHIFT + P` (or `COMMAND + SHIFT + P` on MacOS) to open the developer prompt. + +8. Type "open settings json" and select the "Preferences: Open Settings (JSON)" option (_not_ the "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) + +9. 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... + } + ``` + +10. Save your changes to the file with `CTRL + S` and restart VS Code. + +11. That's it! You're ready to start using Visual Studio Code to develop with Maxim's Microcontrollers. The MaximSDK examples come pre-populated with .vscode project folders, and the `Tools/VSCode-Maxim` folder of the SDK contains documentation and templates. See [Usage](#usage) below for more details. + +## Usage + +This section covers basic usage of the VSCode-Maxim project files. For documentation on Visual Studio Code itself, please refer to the official docs [here](https://code.visualstudio.com/Docs). + +### Opening 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. + +A project that is configured for VS Code will have, at minimum, a .vscode sub-folder and a Makefile in its directory _(Note: You may need to enable viewing of hidden items in your file explorer to see the .vscode sub-folder)_. + +Ex: + +![Example Directory Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/opening_projects_2.jpg) + +### Where to Find Projects + +The [Examples](https://github.com/Analog-Devices-MSDK/msdk/tree/main/Examples) in the MSDK come with with pre-configured .vscode project folders. These projects can be opened "out of the box", but it's good practice to copy example folders _outside_ of the MSDK so that the original copies are kept as clean references. The examples can be freely moved to any location _without a space in its path_. + +Additionally, empty project templates and a drag-and-drop folder for "injecting" a VSCode-Maxim project can be found under `Tools/VSCode-Maxim` in the MaximSDK installation. + +### Build Tasks + +Once a project is opened 4 available build tasks will become available via `Terminal > Run Build task...` or the shortcut `Ctrl+Shift+B`. These tasks are configured by the `.vscode/task.json` file. + +![Build Tasks Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/buildtasks.JPG) + +#### Build + +* Compiles the code with a `make all` command. +* Additional options are passed into Make on the command-line based on the project's settings.json file. +* The `./build` directory will be created and will contain the output binary, as well as all intermediary object files. + +#### Clean + +* Cleans the build output, removing the `./build` directory and all of its contents. + +#### Clean-Periph + +* This task is the same as 'clean', but it also removes the build output for Maxim's peripheral drivers. +* Use this if you would like to recompile the peripheral drivers from source on the next build. + +#### Flash + +* Launching this task automatically runs the `Build` task first. Then, it flashes the output binary to the microcontroller. +* It uses the GDB `load` and `compare-sections` commands, and handles launching an OpenOCD internally via a pipe connection. +* The flashed program will be halted until the microcontroller is reset, power cycled, or a debugger is connected. +* A debugger must be connected correctly to use this task. Refer to the datasheet of your microcontroller's evaluation board for instructions. + +#### Flash & Run + +* This is the same as the `Flash` task, but it also will launch execution of the program once flashing is complete. + +#### Erase Flash + +* Completely erases all of the application code in the flash memory bank. +* Once complete, the target microcontroller will be effectively "blank". +* This can be useful for recovering from Low-Power (LP) lockouts, bad firmware, etc. + +### Debugging + +![Debug Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger.JPG) + +Debugging is enabled by Visual Studio Code's integrated debugger. Launch configurations can be found in the `.vscode/launch.json` file. + +* Note: **Flashing does not happen automatically when launching the debugger.** Run the "Flash" [build task](#build-tasks) for your program _before_ debugging. + +#### Debugger Limitations + +In general, Maxim's microcontrollers have the following debugger limitations at the hardware level: + +* The debugger can not be connected _while_ the device is in reset. + +* The device can not be debugged while the device is in Sleep, Low Power Mode, Micro Power Mode, Standby, Backup, or Shutdown mode. These modes shut down the SWD clock. + +* These limitations can sometimes make the device difficult or impossible to connect to if firmware has locked out the debugger. In such cases, the ["Erase Flash"](#erase-flash) task can be used to recover the part. + +#### Launching the Debugger + +1. Attach your debugger to the SWD port on the target microcontroller. (Refer to the datasheet of your evaluation board for instructions on connecting a debugger) + +2. Flash the program to the microcontroller with the "Flash" [Build Task](#build-tasks). **Flashing does not happen automatically when launching the debugger.** + +3. Launch the debugger with `Run > Start Debugging`, with the shortcut `F5`, or via the `Run and Debug` window (Ctrl + Shift + D) and the green "launch" arrow. + + ![Debug Tab](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_window.JPG) + +4. The debugger will launch a GDB client & OpenOCD server, reset the microcontroller, and should break on entry into `main`. + + ![Debugger Break on Main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_breakmain.JPG) + +#### Using the Debugger + +* For full usage details, please refer to the [official VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging). + +The main interface for the debugger is the debugger control bar: + +![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 can be set by clicking in the space next to the line number in a source code file. A red dot indicates a line to break on. Breakpoints can be removed by clicking on them again. Ex: + +![Breakpoint](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/breakpoint.JPG) + +## Project Configuration + +### Project Settings + +`.vscode/settings.json` is the main project configuration file. Values set here are parsed into the other .json config files. + +**When a change is made to this file, VS Code should be reloaded with CTRL+SHIFT+P -> Reload Window (or alternatively restarted completely) to force a re-parse.** + +![Reload Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/reload_window.JPG) + +The default project configuration should work for most use cases as long as `"target"` and `"board"` are set correctly. + +Any field from `settings.json` can be referenced from any other config file (including itself) with `"${config:[fieldname]}"` + +The following configuration options are available: + +### Basic Config Options + +#### `"target"` + +* This sets the target microcontroller for the project. +* It sets the `TARGET` [Build Configuration](#build-configuration) variable. +* Supported values: + * `"MAX32520"` + * `"MAX32570"` + * `"MAX32650"` + * `"MAX32655"` + * `"MAX32660"` + * `"MAX32662"` + * `"MAX32665"` (for MAX32665-MAX32668) + * `"MAX32670"` + * `"MAX32672"` + * `"MAX32675"` + * `"MAX32680"` + * `"MAX32690"` + * `"MAX78000"` + * `"MAX78002"` + +#### `"board"` + +* This sets the target board for the project (ie. Evaluation Kit, Feather board, etc.) +* Supported values: + * ... can be found in the `Libraries/Boards` folder of the MaximSDK + * For example, the supported options for the MAX78000 are `"EvKit_V1"`, `"FTHR_RevA"`, and `"MAXREFDES178"`. + + ![MAX78000 Boards](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/78000_boards.JPG) + +### Advanced Config Options + +#### `"MAXIM_PATH"` + +* This option must point to the root installation directory of the MaximSDK. +* It should be placed in the _global_ user settings.json file during first-time VSCode-Maxim setup. See [Installation](#installation). + +#### `"terminal.integrated.env.[platform]:Path"` + +* This prepends the location of toolchain binaries to the system `Path` used by VSCode's integrated terminal. +* The Path is not sanitized by default, which means that the terminal inherits the system path. +* Don't touch unless you know what you're doing :) + +#### `"project_name"` + +* Sets the name of project. This is used in other config options such as `program_file`. +* Default value: `"${workspaceFolderBasename}"` + +#### `"program_file"` + +* Sets the name of the file to flash and debug. This is provided in case it's needed, but for most use cases should be left at its default. +* File extension must be included. +* Default value: `"${config:project_name}.elf"` + +#### `"symbol_file"` + +* Sets the name of the file that GDB will load debug symbols from. +* File extension must be included. +* Default value: `"${config:program_file}"` + +#### `"M4_OCD_interface_file"` + +* Sets the OpenOCD interface file to use to connect to the Arm M4 core. This should match the debugger being used for the M4 core. +* The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"cmsis-dap.cfg"` + +#### `"M4_OCD_target_file"` + +* Sets the OpenOCD target file to use for the Arm M4 core. This should match the target microcontroller. +* `.cfg` file extension must be included. +* The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. +* Default value: `"${config:target}.cfg"` + +#### `"RV_OCD_interface_file"` + +* Sets the OpenOCD interface file to use to connect to the RISC-V core. This should match the debugger being used for the RISC-V core. +* The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"ftdi/olimex-arm-usb-ocd-h.cfg"` + +#### `"RV_OCD_target_file"` + +* Sets the OpenOCD target file to use for the RISC-V core. +* The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. +* `.cfg` file extension must be included. +* Default value: `"${config:target}_riscv.cfg"` + +#### `"v_Arm_GCC"` + +* Sets the version of the Arm Embedded GCC to use, including toolchain binaries and the standard library version. +* This gets parsed into `ARM_GCC_path`. +* Default value: `"10.3"` + +#### `"v_xPack_GCC"` + +* Sets the version of the xPack RISC-V GCC to use. +* This gets parsed into `xPack_GCC_path`. +* Default value: `"10.2.0-1.2"` + +#### `"OCD_path"` + +* Where to find the OpenOCD. +* Default value: `"${config:MAXIM_PATH}/Tools/OpenOCD"` + +#### `"ARM_GCC_path"` + +* Where to find the Arm Embedded GCC Toolchain. +* Default value: `"${config:MAXIM_PATH}/Tools/GNUTools/${config:v_Arm_GCC}"` + +#### `"xPack_GCC_path"` + +* Where to find the RISC-V GCC Toolchain. +* Default value: `"${config:MAXIM_PATH}/Tools/xPack/riscv-none-embed-gcc/${config:v_xPack_GCC}"` + +#### `"Make_path"` + +* Where to find Make binaries (only used on Windows) +* Default value: `"${config:MAXIM_PATH}/Tools/MSYS2/usr/bin"` + +#### `"C_Cpp.default.includePath"` + +* Which paths to search to find header (.h) files. +* Does not recursively search by default. To recursively search, use `/**`. + +#### `"C_Cpp.default.browse.path"` + +* Which paths to search to find source (.c) files. +* Does not recursively search by default. To recursively search, use `/**`. + +#### `"C_Cpp.default.defines"` + +* Sets the compiler definitions to use for the intellisense engine. +* Most definitions should be defined in header files, but if a definition is missing it can be entered here to get the intellisense engine to recognize it. + +### Setting Search Paths for Intellisense + +VS Code's intellisense engine must be told where to find the header files for your source code. By default, Maxim's perpiheral drivers, the C standard libraries, and all of the sub-directories of the workspace will be searched for header files to use with Intellisense. If VS Code throws an error on an `#include` statement (and the file exists), then a search path is most likely missing. + +To add additional search paths : + +1. Open the `.vscode/settings.json` file. + +2. Add the include path(s) to the `C_Cpp.default.includePath` list. The paths set here should contain header files, and will be searched by the Intellisense engine and when using "Go to Declaration" in the editor. + +3. Add the path(s) to any relevant implementation files to the `C_Cpp.default.browse.path` list. This list contains the paths that will be searched when using "Go to Definition". + +## Build Configuration + +A project's build system is managed by two files found in the project's root directory. These files are used alongside the [GNU Make](https://www.gnu.org/software/make/) program (which is a part of the MaximSDK toolchain) to locate and build a project's source code for the correct microcontroller. + +* `Makefile` +* `project.mk` + +![Files are located in the root directory](img/projectmk.JPG) + +When the command... + +```shell +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 `=` operater 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 MaximSDK. 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 MaximSDK | `MAXIM_PATH=/path/to/MSDK` | This optional variable can be used to change where the Makefile looks for the MaximSDK. By default, the Makefile will attempt to locate the MaximSDK with a relative path moving "up" from its original location. This option is most useful when a project is moved _outside_ of the SDK 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 MaximSDK. 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 MaximSDK, 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.maximintegrated.com/en/design/technical-documents/userguides-and-manuals/7/7637.html). 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 MaximSDK will be searched. If the [SBT installer](https://www.maximintegrated.com/en/design/software-description.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 Maxim test key that can be used for development. + +## Project Creation + +### Option 1. Copying a Pre-Made Project + +Copying a pre-made example project is a great way to get rolling quickly, and is currently the recommended method for creating new projects. + +The release package for this project (Located at Tools/VSCode-Maxim in the MaximSDK) contains a `New_Project` folder designed for such purposes. Additionally, any of the VS Code-enabled Example projects can be copied from the SDK. + +1. Copy the existing project folder to an accessible location. This will be the location of your new project. + +2. (Optional) Rename the folder. For example, I might rename the folder to `MyProject`. + +3. Open the project in VS Code (`File -> Open Folder...`) + +4. Set your target microcontroller and board correctly. See [Basic Config Options](#basic-config-options) + +5. `CTRL+SHIFT+P -> Reload Window` to re-parse the project settings. + +6. That's it! The existing project is ready to build, debug, and modify. + +### Option 2 - Creating a Project from Scratch + +If you want to start from scratch, 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`. + +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 : + + ```shell + C:\Users\Jake.Carter\workspace\MyNewProject + +-- \.vscode + +-- Makefile + ``` + +3. Open the project in VS Code (`File -> Open Folder...`) + +4. Set your target microcontroller correctly. See [Basic Config Options](#basic-config-options). + +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. + +## Issue Tracker + +Bug reports, feature requests, and contributions are welcome via the [issues](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/issues) tracker on Github. + +New issues should contain _at minimum_ the following information: + +* Visual Studio Code version #s (see `Help -> About`) +* C/C++ Extension version # +* Target microcontroller and evaluation platform +* The projects `.vscode` folder and `Makefile` (where applicable). Standard compression formats such as `.zip`, `.rar`, `.tar.gz`, etc. are all acceptable. diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/userguide.md b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/userguide.md index c828d6b..b6a5041 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/userguide.md +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/userguide.md @@ -1,6 +1,7 @@ # How to Use Visual Studio Code with Maxim's Microcontrollers SDK (Windows & Linux) ## Table of Contents + * [Introduction](#introduction) * [De-Mystifying the SDK Toolchain](#de-mystifying-the-sdk-toolchain) * [Integrating the Toolchain](#integrating-the-toolchain) @@ -8,15 +9,16 @@ * [Referencing Example Code](#referencing-example-code) * [Loading Example Projects](#loading-example-projects) * [Injecting into Existing Source Code](#injecting-into-existing-source-code) -* [Adding Source Code](#adding-source-code) * [Conclusion](#conclusion) ## Introduction + Integrated Development Environments (IDEs) targeted at embedded systems and microcontroller development can come with a lot of overhead. They have a tendency to be bulky, unwieldy programs that can take up a lot of hard drive space, and when something isn't configured properly they can be a pain to troubleshoot. No one likes digging into project settings for hours trying to get their include paths working, troubleshooting five different configuration options just to link a library, or tracking a bug back down to project config option. [Visual Studio Code](https://code.visualstudio.com/) is a lightweight, powerful, and customizable editor that can serve as a great free alternative to the more traditional micro IDEs like Eclipse, Code-Composer Studio, IAR, Keil uVision, etc. This app note outlines step-by-step how to get started with [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim), which is a collection of project configurations that integrate Maxim's Microcontrollers SDK into Visual Studio Code. ## De-Mystifying the SDK Toolchain + Maxim maintains a Software Development Kits (SDK) for microcontroller development called the "Maxim Micros SDK". The SDK contains a large number of components, such as register files, linker files, board-support packages (BSPs), peripheral drivers, example code, etc. This section will focus on one of the _core_ components of the SDK - the _toolchain_. Understanding the toolchain is important because this VSCode-Maxim project is essentially a "wrapper" around the toolchain. Let's take a look under the hood... @@ -24,13 +26,14 @@ Understanding the toolchain is important because this VSCode-Maxim project is es A [toolchain](https://en.wikipedia.org/wiki/Toolchain) is really just a collection of programs and typically includes compiler, linker, and debugger executables. It also may include utility programs and build systems to make using these lower-level programs more convenient. The main components of the SDK's Toolchain are: -* [Arm GNU Compiler Collection](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) (GCC) - located under `~\MaximSDK\Tools\GNUTools\bin` -* [Open On-Chip Debugger](http://openocd.org/) (OpenOCD) - located under `~\MaximSDK\Tools\OpenOCD` -* [GNU Make](https://www.gnu.org/software/make) - made available on Windows via MSYS2 and located under `~\MaximSDK\Tools\MinGW\msys\1.0\bin` + +* [Arm GNU Compiler Collection](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) (GCC) - located under `~/MaximSDK/Tools/GNUTools/10.3` +* [Open On-Chip Debugger](http://openocd.org/) (OpenOCD) - located under `~/MaximSDK/Tools/OpenOCD` +* [GNU Make](https://www.gnu.org/software/make) - made available on Windows via [MSYS2](https://www.msys2.org/) and located under `~/MaximSDK/Tools/MSYS2/usr/bin` GCC is used to compile source code but is rarely called directly. Instead, GCC is most frequently invoked in a list of directives collected into a _Makefile_. This list of directives is called a _recipe_. If you are new to Make, think of GCC as the hammer and Make as the builder who knows how to use it. You can tell Make to do a task (such as "make all" the source code) and Make will follow the instructions outlined in the Makefile's recipe to complete it. -The core Makefile for a target microcontroller can be found under `~\MaximSDK\Libraries\CMSIS\Device\Maxim\\Source\GCC` - see `gcc.mk`. This file tells Make exactly how to use GCC to compile code for that microcontroller. All projects can then have their own Makefile that builds off of this one by `include`-ing it. +Detailed documentation on the Makefile system can be found [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration). The important thing to note now is that every example project comes with a Makefile and project.mk file that manages GCC. They offer convenient configuration variables if needed and manage the source code for the project. Great - so source code is compiled into firmware binaries by Make using GCC. How is it flashed onto the microcontroller? That's where OpenOCD comes in. @@ -39,6 +42,7 @@ OpenOCD handles flashing firmware and opening a debugger _server_. It handles t In general, this is how things work at a low level. Integrated Development Environments (IDEs) such as Visual Studio Code have mechanisms for integrating toolchains so that these low-level steps can be abstracted away in a more convenient way. ## Integrating the Toolchain + Visual Studio Code provides the [Tasks](https://code.visualstudio.com/Docs/editor/tasks) interface for integrating external tools. To use the Maxim SDK toolchain via Tasks, the toolchain binaries must be made accessible from the command line. Additionally, the correct board and peripheral driver files for a target platform must be loaded for compilation and source code development. When those conditions are met, then Tasks can be created to conveniently implement the features that you would expect from an IDE: building, cleaning, flashing, etc. [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim) handles this for you and offers project files that are configured for Maxim's SDK and toolchain. @@ -48,11 +52,13 @@ Let's get started setting it up and walking through some common use-cases. The ## Getting Started with VSCode-Maxim ### 1 - Install Software Requirements -First, follow the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) for your OS from the readme if you haven't already. This include installing software requirements, setting the `MAXIM_PATH` environment variable, and downloading the latest release of VSCode-Maxim to an accessible location. -
+First, follow the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) for your OS from the readme if you haven't already. This include installing software requirements and setting the `MAXIM_PATH` environment variable. + +--- ### 2 - Release Package Overview + The VSCode-Maxim release package should contain the following contents. Note: Releases between OS's/versions may differ _slightly_ from the screenshot below, but this should match in general... ![Release Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/Release-contents.jpg) @@ -65,6 +71,7 @@ The VSCode-Maxim release package should contain the following contents. Note: R * `"userguide.md"` is this User Guide. ### 3 - Starter Project + In this section, we'll get hands on with the VSCode-Maxim starter project to see how it works. First, copy the "New_Project" folder from the VSCode-Maxim release package into an accessible location. You can also rename the folder if you'd like. For example, I've copied the folder to a `workspace` directory I created in my User folder below. I've also renamed the project to "MyProject". @@ -96,31 +103,34 @@ Now, VS Code should look something like this, where the template project has bee ![File opened](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_opened.jpg) -
+--- ### 4 - Verify Toolchain Access + At this point, the project is opened and ready to use and configure. Let's take a few steps on the integrated terminal to verify that things _are_ actually working correctly. First, launch a terminal with `Terminal > New Terminal`. ![New Terminal](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_terminal.jpg) -Next, we'll run through the commands in the ["Testing the Setup"](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/blob/main/readme.md#testing-the-setup) of the readme to see that the toolchain is accessible. This is critical for everything else to work. The project settings in the `.vscode` folder will add the locations of the toolchain to the terminal's `PATH`, which will allow them to be accessed directly. +Next, we'll run through the commands in the ["Testing the Setup"](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki/Troubleshooting#testing-the-setup) of the wiki to see that the toolchain is accessible. This is critical for everything else to work. The project settings in the `.vscode` folder will add the locations of the toolchain to the terminal's `PATH`, which will allow them to be accessed directly. For example, running `make -v` in the terminal should output a version # for Make, as shown below. ![Make Test](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/make_test.JPG) Run the other commands for OpenOCD, GCC, and GDB to verify that the integrated terminal has been configured correctly and the toolchain is in the right place. These should all run without error. + * `openocd -v` * `arm-none-eabi-gcc -v` * `arm-none-eabi-gdb -v` -If there _are_ any errors thrown by any of the commands above, first verify that you've followed the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) correctly. Problems are usually related to a missing or incorrect `MAXIM_PATH` environment variable and/or missing SDK components. Otherwise, see the [troubleshooting section](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/issues) of the readme. +If there _are_ any errors thrown by any of the commands above, first verify that you've followed the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) correctly. Problems are usually related to a missing or incorrect `MAXIM_PATH` environment variable and/or missing SDK components. Otherwise, see the [troubleshooting section](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki/Troubleshooting) of the wiki. -
+--- ### 4 - Set the Target Platform + With the tools verified as accessible from within VS Code, we can now start to configure the project for a specific microcontroller. In this case, we'll do some basic configuration of the project for the MAX32670EVKIT, but the same steps apply to any micro. @@ -131,10 +141,11 @@ Open `.vscode/settings.json`. This is the main configuration file, and you shou Set the `"target"` and `"board"` variables for your target platform. For example, for the MAX32670EVKIT I would set... + * `"target":"MAX32670"` * `"board":"EvKit_V1"` -The [Configuration](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#configuration) section of the readme will tell you the values that can be set here. In this case, we've changed the two most basic options: `"target"` and `"board"`. +The [Project Configuration](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#project-configuration) section of the readme will tell you the values that can be set here. In this case, we've changed the two most basic options: `"target"` and `"board"`. ![Basic Config Options](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/readme_basicconfig.jpg) @@ -148,16 +159,18 @@ Next, reload the VS Code window. A reload is necessary after changing any optio Now VS Code is ready to edit, build, and debug source code for the target platform. -
+--- ### 5 - Opening main.c + Open `main.c`, which can be found in the `src` folder. Here we can see the source code for a simple "Hello world" program. -![main.c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/main.JPG) +![main.c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/main.JPG) -
+--- ### 6 - Clean the Program + First, let's ensure that we're starting from a clean slate. Open the build tasks menu with `Ctrl+Shift+B` or `Terminal > Run Build Task...` and select the "clean-periph" option. This cleans out the build products from the current project as well as the peripheral drivers in the SDK. With everything cleaned out, the next step will build everything from scratch. ![Cleaning the program](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/clean-periph.jpg) @@ -166,9 +179,10 @@ Selecting the `clean-periph` build task will launch the task in the integrated t ![Clean-periph Complete](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/clean-periph_complete.jpg) -
+--- ### 7 - Build the Program + Next, we'll build the source code. Open the build tasks menu again with `Ctrl+Shift+B` or `Terminal > Run Build Task...` @@ -193,9 +207,10 @@ This is a good time to (once again) re-iterate an important point: _All configu For now, take note of the fact that the example project comes pre-configured for a single `main.c` source file, and looks for all `.c` and `.h` files inside of the `src` directory. -
+--- ### 8 - Flash and Debug the Program + Now that we've seen the program build successfully, let's flash it onto the microcontroller and debug it. First, ensure that your microcontroller is powered on and connected to your PC through your debug adapter. The specifics of this will vary based on the platform you're using, but documentation can be found in the datasheet. On a platform with an integrated debugger, such as the [MAX32670EVKIT](https://datasheets.maximintegrated.com/en/ds/MAX32670EVKIT.pdf), this is as simple as plugging it in with a micro-usb cable. On platforms where the debug adapter is not integrated, you'll need to connect your debug adapter to the right debugger port and power the platform separately. @@ -212,12 +227,14 @@ Once the debugger connects it will break the program execution on entry into the ![Breakpoint Hit](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/breakpoint_hit.JPG) -
+--- ### 9 (optional) - Open a Serial Port to the Micro + Before we continue the program execution, you can optionally open up a serial port to the microcontroller to see the "Hello world!" message and count printed. Default serial communication settings are: + * BAUD : 115200 * Data : 8-bit * Parity : none @@ -232,9 +249,10 @@ From there, steps will be program-specific to the serial terminal you're using. ![TeraTerm](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/TeraTerm.JPG) -
+--- ### 10 - Continue the Program + Press `F5` or hit the continue button in the debugger menu to continue the program past the breakpoint. ![Continue button](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/continue_button.JPG) @@ -245,16 +263,17 @@ You should see the LED on your microcontroller blinking. If you have a terminal Feel free to play around in the debugger here (setting different breakpoints, watch variables, stepping into and out of functions, etc.) to get familiar. When you're ready, you can hit the stop button to quit debugging. -
+--- ### 11 - Wrapping Up + Here, we've gotten started with a basic project configuration, the available build tasks, and have flashed/debugged the template Hello World program. The `New_Project` project template is designed as a good re-usable starting point, and you can freely copy this project around and re-configure it for different target platforms. You should now have a good basic understanding of how VS Code works and how Maxim's toolchain is integrated. The next sections cover more advanced subjects. -
+--- ## Referencing Example Code @@ -269,6 +288,7 @@ Opening the GPIO example reveals the following contents: ![GPIO Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_contents.JPG) There are a couple components inside the project: + * A `main.c` file with the example code * A project `Makefile` for building the example code * Eclipse configuration files and debugger profile (`.cproject`, `.project`, `GPIO.launch`) @@ -303,6 +323,7 @@ Using this method, you can quickly and easily reference example code for your ow Note: It's recommended to only use this method for _browsing/referencing_ example code. If you'd like to work with the example projects directly, it's recommended to copy them to an external location to keep the SDK's reference copy untouched. See the next section for more details. ## Loading Example Projects + Following the [installation procedure](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) from the VSCode-Maxim readme will populate the MaximSDK's example projects with `.vscode` project folders. As such, they're ready to use "out of the box" with `File -> Open Folder`. However, it's recommended to copy the example projects to a location _outside_ of the SDK before using them. Keeping a copy of the original examples intact and untouched is always a good idea in case you need to go back and reference them later. @@ -310,20 +331,23 @@ However, it's recommended to copy the example projects to a location _outside_ o By default, the example projects are configured for the "EVKIT" evaluation platform for each target microcontroller. See [Project Settings](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#project-settings) in the readme if you need to change this. ## Injecting into Existing Source Code + Using example code as a reference is great, but what if we want to inject the VS Code setup into an existing project that's not in the MaximSDK? That's where the `Inject` folder in the VSCode-Maxim release package comes in. In the example below, we'll use the GPIO example _without_ any pre-existing VS Code project settings. The same procedure applies to any existing source code. ### 1 - Locate the Existing Project + For the sake of this example, a working copy of the GPIO example has been copied over into a separate folder. The contents of this GPIO example are as follows: ![GPIO Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_contents.JPG) -
+--- ### 2 - Inject the VSCode-Maxim Files + Copy the _contents_ of the `Inject` folder from the VSCode-Maxim release package into the example project. ![GPIO Inject](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/inject_gpio.JPG) @@ -332,9 +356,10 @@ The contents of the project should now look something like this, with our `.vsco ![GPIO Injected](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/inject_gpio_finished.JPG) -
+--- ### 3 - Open the Project + The GPIO is now ready to be opened from within VS Code, and from here we'll follow a similar process as the one outlined in the "Getting Started" section of this User Guide. You'll open the project folder and configure `settings.json` for your target platform. However, since we're injecting into existing source code, we'll need to configure the Makefile as well. First things first... Launch VS Code. Open the project folder with `File > Open Folder...` and browse to the root directory of the project. @@ -345,57 +370,31 @@ VS Code should prompt for workspace trust. Select _Trust folder and enable all ![Workspace Trust Prompt](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/workspaceTrustPrompt.JPG) -
+--- ### 4 - Set the Target Platform & Reload + Open `settings.json` inside of the `.vscode` folder and configure the project settings for your target platform. See the [readme](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/blob/main/readme.md) if you are unsure what to set here. For example, settings for the MAX32670EVKIT would be... + * `"target":"MAX32670"` * `"board":"EvKit_V1"` -The rest of the settings should be suitable for most use-cases. The only other setting that might need a deeper look here is the `M4_OCD_interface_file`. The default `cmsis-dap.cfg` setting is suitable for use with a target platform that MAX32625PICO debugger. If your target platform has an integrated debugger (such as the MAX32670EVKIT), that's it. Additionally, most evaluation kits will usually come with an _external_ MAX32625PICO debugger, so this setting can be left at its default. In other cases, see [Advanced Config Options](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#advanced-config-options) in the readme. +The rest of the settings should be suitable for most use-cases. The only other setting that might need a deeper look here is the `M4_OCD_interface_file`. The default `cmsis-dap.cfg` setting is suitable for use with a target platform that MAX32625PICO debugger. If your target platform has an integrated debugger (such as the MAX32670EVKIT), that's it. Additionally, most evaluation kits will usually come with an _external_ MAX32625PICO debugger, so this setting can be left at its default. In other cases, see [Advanced Config Options](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#advanced-config-options) in the readme. ![Reload Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/settings.JPG) `CTRL+S` to save the changes to the file, and then reload the VS Code window with `CTRL + SHIFT + P` > `Developer: Reload Window`. This is necessary so that VS Code re-parses all file-paths for our new target platform. -
+--- ### 5 - Configure the Build System -With the project settings configured, everything should be working in the editor. The `main.c` file can be opened and Intellisense will work properly. -However, in order to actually build this project, we'll need to configure the build system to match the existing source code. This involves editing the core project `Makefile`. - -Open the `Makefile` in the editor. - -![Open Makefile](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_open_makefile.JPG) - -Here, we can see a "Main Configuration" section highlighting some common options that, collectively, handle the configuration needed for most projects. The first thing to check is that all the source files have been added to the `SRCS` variable. The GPIO project only has a single `main.c` file, and the Makefile comes pre-configured for a `main.c` file by default. So, we're good to go there. - -However, if we look at the `VPATH` and `IPATH` options we can see some modifications are required. `VPATH` controls where Make will look for the source files (.c) specified by the `SRCS` variable, and `IPATH` controls where it will look for header files (.h). The GPIO example has placed the `main.c` file right in the root directory of the project but the Makefile is only configured to look inside of a `src` folder by default. So we have two options: -1. Re-organize the existing source code to match the Makefile. - * Create a new folder inside of the project called `src` - * Drag `main.c` inside of that folder - - ![GPIO Reorganized](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_reorganized.JPG) - -or... - -2. Re-configure the Makefile to match the existing source code. - * Set `VPATH` and `IPATH` to `.` to search the root directory for source and header files. - - ![Makefile Edited](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_makefile_edited.JPG) - -
- -Take option 1 or 2. - -In this case, that's all the Makefile configuration that's needed for the project. See [Editing the Makefile](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#editing-the-makefile) in the readme for more details on other scenarios, such as adding additional source files, changing compiler flags, linking libraries, etc. +By default, the build system will look in the root directory of the project for source (.c) and header (.h) files. It will also search in the optional "src" (.c) and "include" (.h) directories. If the project follows a non-standard structure with additional folders and files, they will need to be added to the build using the `IPATH` and `VPATH` [Build Configuration](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) Variables. ### 6 - Clean & Build the GPIO Example -With the Makefile configured, we're ready to build the project. -As always, with a new project it's best to run a `clean-periph` first to ensure we're starting from scratch. +As always, with a new project it's best to run a `clean-periph` first to ensure we're starting from scratch. Then, run a `build` task to compile the GPIO example. Remember - build tasks can be accessed via `Terminal > Run Build Task...` or `Ctrl+Shift+B`. @@ -409,53 +408,22 @@ Monitor the terminal for any errors as the Makefile builds the periphal drivers ![GPIO Build Products](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_build_products.JPG) -
+--- + +### 6 - Wrapping Up -### 7 - Wrapping Up From here, the example is ready to be flashed to the target microcontroller, debugged, edited, and explored further. This same process can be applied to injecting the VS Code setup into any example project or existing source code. To summarize, you will... + 1. Copy the contents of the `Inject` folder into the root directory of the existing project (optionally renaming any existing Makefile for later reference). 2. Open the root directory of the project folder from within VS Code 3. Configure `settings.json` to match your target platform -4. Configure the Build system by editing the Makefile and/or re-organizing the source code. - -
+4. Configure the Build system with project.mk if needed. +5. Clean-periph and rebuild. -## Adding Source Code -In the example below, we'll walk through adding in additional source code files. This program will have a more advanced project structure with sub-folders. This example will assume you've worked through the basics of project configuration and setup, and already have the project open in VS Code. - -Adding and editing additional source code in the VS Code editor is straightforward. Files can be created from within VS Code or dragged and dropped into the project explorer. However, the `Makefile` must be configured to add additional source code files to the build. - -There are some general rules that can be followed for configuring the `Makefile`: -* Make sure the any implementation files added (.c) are added to the list of files to compile with the `SRCS` variable. -* Make sure the `Makefile` knows where to find these implementation files. You control where it looks with the `VPATH` variable. -* Header files (.h) don't need to be explicitly added to the build like source files (.c) do, but the `Makefile` needs to know where to look for them. You control where it looks with the `IPATH` variable. - -These rules cover basic scenarios. See [Editing the Makefile](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#editing-the-makefile) in the readme for a more thorough list. - -Let's say I add the following source code in its own folder called `mylibrary`, with a `hellolibrary` header (.h) and implementation (.c) file. - -![Hello Library h](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_h.JPG) - -![Hello Library c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_c.JPG) - -All this library does is contain a function called `myfunction` that prints a string to the console. Our main file can `#include` the header file and call `myfunction()`, which will print "Hello function!" to the console. - -![Hello Library main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_main.JPG) - -For this source code, we'll then modify the `Makefile` to add it to the build as follows: -* `SRCS += hellolibrary.c` to add the implementation file to the build -* `VPATH += ./src/mylibrary` so the `Makefile` knows where to find the implementation file -* `VPATH += ./src/mylibrary` so the `Makefile` knows where to find the header file. - -![Hello Library Makefile](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_makefile.JPG) - -Now, when we run the `Build` task we can see the hellolibrary.c file added to the build successfully and compiled. The program is ready to be flashed to the microcontroller and debugged, where it will print "Hello function!" once to the serial port before exiting. - -![MyProject Build](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_build.JPG) - -
+--- ## Conclusion + Visual Studio Code is a great free code editor that, with the help of [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim), can be used for embedded development with Maxim's Microcontroller toolchain. Having worked through this User Guide, you now hopefully have a good understanding of how Maxim's toolchain works, how it's integrated into VS Code, and how to leverage it to develop your own projects. diff --git a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js index 0fa69b6..b9df166 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js +++ b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js @@ -23,7 +23,7 @@ Component.prototype.createOperations = function() Component.prototype.installationFinished = function() { - var tag = "v1.4.3"; + var tag = "v1.5.0"; var tag_url = "https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/tree/" + tag; var release_url = "https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/releases/tag/" + tag; diff --git a/installer/com.maximintegrated.dist.vscodemaxim/meta/package.xml b/installer/com.maximintegrated.dist.vscodemaxim/meta/package.xml index afc42dc..e2e2318 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/meta/package.xml +++ b/installer/com.maximintegrated.dist.vscodemaxim/meta/package.xml @@ -1,9 +1,9 @@ Visual Studio Code Support Project files, templates, and documentation for integrating Visual Studio Code and the MaximSDK. Example projects come pre-populated with .vscode project folders, and this package contains information on how to use them. It installs to "Tools/VSCode-Maxim". - 2022-08-01 + 2022-11-21 net.sourceforge.openocd, net.launchpad.gcc.arm.embedded, net.launchpad.gcc.riscv.embedded, com.maximintegrated.libraries.periphdrivers - 1.4.3 + 1.5.0 1 \ No newline at end of file diff --git a/maintain.py b/maintain.py index c696bdd..5fdeadb 100644 --- a/maintain.py +++ b/maintain.py @@ -32,7 +32,7 @@ *******************************************************************************/ """ -import os +import os, sys from subprocess import run import platform import time @@ -41,6 +41,17 @@ from pathlib import Path from datetime import date +# Get location of this file. +# Need to use this so that template look-ups are decoupled from the caller's working directory +if getattr(sys, 'frozen', False): + # https://pyinstaller.org/en/stable/runtime-information.html#run-time-information + # Use sys.executable if app is bundled by pyinstaller + here = Path(sys.executable).parent + _vscode_dir = here.joinpath("VSCode") +else: + here = Path(__file__).parent + _vscode_dir = here + curplatform = platform.system() # Get OS def log(string, file): @@ -74,16 +85,20 @@ def run_cmd(*args, **kwargs): def sync(): # Inject .vscode folder into example projects - print("Copying from Inject folder into example project and template...") - for f in os.scandir("MaximSDK/Inject/.vscode"): - shutil.copy(f, "MaximSDK/New_Project/.vscode/") + inject_dir = _vscode_dir.joinpath("MaximSDK", "Inject", ".vscode") + new_proj_dir = _vscode_dir.joinpath("MaximSDK", "New_Project", ".vscode") + template_dir = _vscode_dir.joinpath("MaximSDK", "Template", ".vscode") + + # print("Syncing VSCode template...") + for f in os.scandir(inject_dir): + shutil.copy(f, new_proj_dir) # Copy files into template folder - shutil.copy("MaximSDK/Inject/.vscode/launch.json", "MaximSDK/Template/.vscode/") - shutil.copy("MaximSDK/Inject/.vscode/c_cpp_properties.json", "MaximSDK/Template/.vscode/") - shutil.copy("MaximSDK/Inject/.vscode/tasks.json", "MaximSDK/Template/.vscode/") - shutil.copy("MaximSDK/Inject/.vscode/flash.gdb", "MaximSDK/Template/.vscode/") - shutil.copy("readme.md", "MaximSDK/Template/.vscode/") + shutil.copy(inject_dir.joinpath("launch.json"), template_dir) + shutil.copy(inject_dir.joinpath("c_cpp_properties.json"), template_dir) + shutil.copy(inject_dir.joinpath("tasks.json"), template_dir) + shutil.copy(inject_dir.joinpath("flash.gdb"), template_dir) + shutil.copy(_vscode_dir.joinpath("README.md"), template_dir) def release(version): sync() @@ -102,7 +117,7 @@ def release(version): shutil.copytree(Path("MaximSDK/New_Project"), r_dir.joinpath("New_Project"), dirs_exist_ok=True) print("Copying markdown files") - shutil.copy("readme.md", r_dir) + shutil.copy("README.md", r_dir) shutil.copy("userguide.md", r_dir) shutil.copy("LICENSE.md", r_dir) @@ -243,7 +258,7 @@ def test(maxim_path, targets=None, boards=None, projects=None): success = True # Test build (make all) - build_cmd = f"make -r -j 8 all TARGET={target} MAXIM_PATH={maxim_path.as_posix()} BOARD={board} MAKE=make" + build_cmd = f"make -r -j 8 TARGET={target} MAXIM_PATH={maxim_path.as_posix()} BOARD={board} MAKE=make" res = run_cmd(build_cmd, env=env, cwd=project, shell=True, capture_output=True, encoding="utf-8") # Run build command # Error check build command diff --git a/readme.md b/readme.md deleted file mode 100644 index 4cce59b..0000000 --- a/readme.md +++ /dev/null @@ -1,492 +0,0 @@ -# VSCode-Maxim - -[VSCode-Maxim on Github](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim) - -If you are viewing this document from within Visual Studio Code, press `CTRL+SHIFT+V` to open a Markdown preview window. - -## Introduction - -This repository is dedicated to maintaining [Visual Studio Code](https://code.visualstudio.com/) project files that integrate with [Maxim Integrated's](https://www.maximintegrated.com/en/products/microcontrollers.html) Microcontroller SDK. The following features are enabled by the project files: - -* Code editing with intellisense and definition look-ups down to the register level -* Code compilation with the ability to easily re-target a project for different microcontrollers and boards -* Flashing program binaries -* GUI and command-line debugging - -## Dependencies - -The project folders in this repo have the following dependencies: - -* [Visual Studio Code](https://code.visualstudio.com/) -* [C/C++ VSCode Extension](https://github.com/microsoft/vscode-cpptools) -* [Maxim Micros SDK](https://www.maximintegrated.com/content/maximintegrated/en/design/software-description.html/swpart=SFW0010820A) - -## Installation - -1. Download & install the Maxim Microcontrollers SDK for your OS from the links below. - * [Windows](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0010820A) - * [Linux (Ubuntu)](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018720A) - * [MacOS](https://www.maximintegrated.com/en/design/software-description.html/swpart=SFW0018610A) - -2. Run the installer executable. - -3. During component selection, ensure that "Visual Studio Code Support" is selected. - - ![Selected Components](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/installer_components.JPG) - -4. Finish the MaximSDK installation, and proceed to step 5 below to set up Visual Studio Code. - -5. Download & install Visual Studio Code for your OS [here](https://code.visualstudio.com/Download). - -6. Launch Visual Studio Code. - -7. Install the Microsoft [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). - -8. Use `CTRL + SHIFT + P` (or `COMMAND + SHIFT + P` on MacOS) to open the developer prompt. - -9. Type "open settings json" and select the "Preferences: Open Settings (JSON)" option (_not_ the "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) - -10. Add the entries below into your user settings.json file. - - Note: **If you installed the MaximSDK to a non-default location change the value of `"MAXIM_PATH"`. Only use forward slashes `/` when setting `"MAXIM_PATH"`.** - - ```json - { - // There may be other settings up here... - - "MAXIM_PATH":"C:/MaximSDK", // Only use forward slahes '/' when setting this path! - "update.mode": "manual", - "extensions.autoUpdate": false, - - // and/or other settings down here... - } - ``` - -11. Save your changes to the file with `CTRL + S` and restart VS Code. - -12. That's it! You're ready to start using Visual Studio Code to develop with Maxim's Microcontrollers. The MaximSDK examples come pre-populated with .vscode project folders, and the `Tools/VSCode-Maxim` folder of the SDK contains documentation and templates. See [Usage](#usage) below for more details. - -## Usage - -This section covers basic usage of the VSCode-Maxim project files. For documentation on Visual Studio Code itself, please refer to the official docs [here](https://code.visualstudio.com/Docs). - -Prior experience with Visual Studio Code is not required to understand this section or use the project files, but some basic familiarity is helpful. For new users, this initial familiarity can be gained by working through the full [User Guide](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/blob/main/userguide.md). - -### Opening Projects - -Visual Studio Code is built around a "working directory" paradigm. VS Code's editor is always running from inside of 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) - -VS Code will look in the opened folder for a `.vscode` _sub_-folder to load project-specific settings from. - -Opening an existing project is as simple as `File -> Open Folder...`. A project that is configured for VS Code will have, at minimum, a .vscode sub-folder and a Makefile in its directory. Ex: - -![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. - -### Build Tasks - -Once a project is opened 4 available build tasks will become available via `Terminal > Run Build task...` or the shortcut `Ctrl+Shift+B`. These tasks are configured by the `.vscode/task.json` file. - -![Build Tasks Image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/buildtasks.JPG) - -* Build - * Compiles the code. - * The `./build` directory will be created and will contain the output binary, as well as all intermediary object files. - -* Clean - * This task cleans the build output, removing the `./build` directory and all of its contents. - -* Clean-Periph - * This task is the same as 'clean', but it also removes the build output for Maxim's peripheral drivers. - * Use this if you would like to recompile the peripheral drivers from source on the next build. - -* Flash - * This task runs the Build task, and then flashes the output binary to the microcontroller. - * A debugger must be connected to the correct debugger port on the target microcontroller. Refer to the datasheet of your microcontrollers evaluation board for instructions on connecting a debugger. - -### Editing the Makefile - -At the heart of every project is its `Makefile`. Build Tasks are essentially a wrapper around the Makefile. Adding source code files to the build, setting compiler flags, linking libraries, etc. must be done by directly editing this file. - -The usage guidelines below are specific to Maxim's Makefiles. The [GNU Make Manual](https://www.gnu.org/software/make/manual/html_node/index.html) is a good one to have on hand for documentation regarding Makefiles in general. - -#### Adding Source Code Files - -* VS Code's editor can create and add new files to a project, but they won't be added to the build automatically. The Makefile must be told which source code files to build, and where to find them. -* Add a source file to the build with `SRCS += yourfile.c` -* The Makefile looks for project source files in the `/src` directory by default. Add additional directories to search with `VPATH += yoursourcedirectory` -* The Makefile looks for project header files in the `/src` directory by default. Add additional directories to search with `IPATH += yourincludedirectory` - -#### Compiler Flags - -* Compiler flags can be added/changed via the `PROJ_CFLAGS` variable. -* Add a new flag to be passed to the compiler with `PROJ_CFLAGS += -yourflag`. Flags are passed in the order that they are added to the `PROJ_CFLAGS` variable. - -#### Linking Libraries - -* Additional libraries can be linked via the `PROJ_LIBS` variable. Add a new library to the build with `PROJ_LIBS += yourlibraryname`. - * Note : Do not include the 'lib' part of the library name, or the file extension. For example, to link `libarm_cortexM4lf_math.a` set `PROJ_LIBS += arm_cortexM4lf_math`. -* Tell the linker where to find the library with the '-L' linker flag. Set `PROJ_LDFLAGS += -Lpathtoyourlibrary`. For example, set `PROJ_LDFLAGS += -L./lib` to search a 'lib' directory inside of the project for libraries. - -#### Optimization Level - -* The optimization level that the compiler uses can be set by changing the `MXC_OPTIMIZE_CFLAGS` variable. -* See [GCC Optimization Options](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html) for more details on available optimization levels. For example, disable optimization with `MXC_OPTIMIZE_CFLAGS = -O0` - -### Debugging - -Debugging is enabled by Visual Studio Code's integrated debugger. Launch configurations are provided by the `.vscode/launch.json` file. - -* Note: **Flashing does not happen automatically when launching the debugger.** Run the "Flash" [build task](#build-tasks) for your program before debugging. - -![Debug Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger.JPG) - -#### Debugger Limitations - -In general, Maxim's microcontrollers have the following debugger limitations at the hardware level: - -* The debugger can not be connected _while_ the device is in reset. - -* The device can not be debugged while the device is in Sleep, Low Power Mode, Micro Power Mode, Standby, Backup, or Shutdown mode. These modes shut down the SWD clock. - -#### Launching the Debugger - -1. Attach your debugger to the SWD port on the target microcontroller. (Refer to the datasheet of your evaluation board for instructions on connecting a debugger) - -2. Flash the program to the microcontroller with the "Flash" [Build Task](#Build-Tasks). **Flashing does not happen automatically when launching the debugger.** - -3. Launch the debugger with `Run > Start Debugging`, with the shortcut `F5`, or via the `Run and Debug` window (Ctrl + Shift + D) and the green "launch" arrow. - - ![Debug Tab](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_window.JPG) - -4. The debugger will launch a GDB client & OpenOCD server, reset the microcontroller, and should break on entry into `main`. - - ![Debugger Break on Main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_breakmain.JPG) - -#### Using the Debugger - -* For full usage details, please refer to the [official VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging). - -The main interface for the debugger is the debugger control bar: - -![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 can be set by clicking in the space next to the line number in a source code file. A red dot indicates a line to break on. Breakpoints can be removed by clicking on them again. Ex: - -![Breakpoint](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/breakpoint.JPG) - -#### RISC-V 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. - -To debug a RISC-V project: - -1. Connect your Arm (SWD) and RISC-V (JTAG) debuggers. The RISC-V projects come pre-configured for 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/) adapter. - -2. Make sure your Olimex debugger drivers are installed correctly. Sometimes they need to be updated using the "zadig" tool. See [this](https://www.olimex.com/Products/ARM/JTAG/_resources/ARM-USB-OCD_and_OCD_H_manual.pdf) Olimex User Manual for more details. - -3. Run the "Flash" task. Ex: - - ![image](https://user-images.githubusercontent.com/38844790/168398354-2ac2961b-6d45-4f84-8805-0ab5339a4b98.png) - -4. 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) - -5. 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) - -6. Now, launch another debugger window with the GDB (RISC-V) profile. - - ![image](https://user-images.githubusercontent.com/38844790/168398707-b6771bf3-b6bf-47a2-b963-b0b9fc003ca4.png) - - ... which should hit the breakpoint on main. - - Notice the "Signal 0" exception below... This is a known issue caused by a reset hardware bug on the RISC-V core that can be safely ignored. The exception message is harmless, but annoying... It will present itself every time the debugger is paused. - - ![image](https://user-images.githubusercontent.com/38844790/168399130-95fe7539-fb46-4c06-a268-6b720403b539.png) - -7. From here, the debugger should be fully functional. Ex, stepping through loading CNN weights on the MAX78000 RISC-V core: - - ![image](https://user-images.githubusercontent.com/38844790/168399419-d0488a0e-2068-4cc7-9108-0a296fdc04b4.png) - -## Configuration - -### Project Settings - -`.vscode/settings.json` is the main project configuration file. Values set here are parsed into the other .json config files. - -**When a change is made to this file, VS Code should be reloaded with CTRL+SHIFT+P -> Reload Window (or alternatively restarted completely) to force a re-parse.** - -![Reload Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/reload_window.JPG) - -The default project configuration should work for most use cases as long as `"target"` and `"board"` are set correctly. - -Any field from `settings.json` can be referenced from any other config file (including itself) with `"${config:[fieldname]}"` - -The following configuration options are available: - -### Basic Config Options - -* `"target"` - * This sets the target microcontroller for the project. - * Supported values: - * `"MAX32520"` - * `"MAX32570"` - * `"MAX32650"` - * `"MAX32655"` - * `"MAX32660"` - * `"MAX32665"` (for MAX32665-MAX32668) - * `"MAX32670"` - * `"MAX32672"` - * `"MAX32675"` - * `"MAX78000"` - -* `"board"` - * This sets the target board for the project (ie. Evaluation Kit, Feather board, etc.) - * Supported values: - * ... can be found in the `Libraries/Boards` folder of the MaximSDK - * For example, the supported options for the MAX78000 are `"EvKit_V1"`, `"FTHR_RevA"`, and `"MAXREFDES178"`. - - ![MAX78000 Boards](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/78000_boards.JPG) - -### Advanced Config Options - -* `"MAXIM_PATH"` - * This option must point to the root installation directory of the MaximSDK. - * It should be placed in the _global_ user settings.json file during first-time VSCode-Maxim setup. See [Installation](#installation). - -* `"terminal.integrated.env.[platform]:Path"` - * This prepends the location of toolchain binaries to the system `Path` used by VSCode's integrated terminal. - * The Path is not sanitized by default, which means that the terminal inherits the system path. - * Don't touch unless you know what you're doing :) - -* `"project_name"` - * Sets the name of project. This is used in other config options such as `program_file`. - * Default value: `"${workspaceFolderBasename}"` - -* `"program_file"` - * Sets the name of the file to flash and debug. This is provided in case it's needed, but for most use cases should be left at its default. - * File extension must be included. - * Default value: `"${config:project_name}.elf"` - -* `"symbol_file"` - * Sets the name of the file that GDB will load debug symbols from. - * File extension must be included. - * Default value: `"${config:program_file}"` - -* `"M4_OCD_interface_file"` - * Sets the OpenOCD interface file to use to connect to the Arm M4 core. This should match the debugger being used for the M4 core. - * The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. - * `.cfg` file extension must be included. - * Default value: `"cmsis-dap.cfg"` - -* `"M4_OCD_target_file"` - * Sets the OpenOCD target file to use for the Arm M4 core. This should match the target microcontroller. - * `.cfg` file extension must be included. - * The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. - * Default value: `"${config:target}.cfg"` - -* `"RV_OCD_interface_file"` - * Sets the OpenOCD interface file to use to connect to the RISC-V core. This should match the debugger being used for the RISC-V core. - * The `MaximSDK/Tools/OpenOCD/scripts/interface` folder is searched for the file specified by this setting. - * `.cfg` file extension must be included. - * Default value: `"ftdi/olimex-arm-usb-ocd-h.cfg"` - -* `"RV_OCD_target_file"` - * Sets the OpenOCD target file to use for the RISC-V core. - * The `MaximSDK/Tools/OpenOCD/scripts/target` folder is searched for the file specified by this setting. - * `.cfg` file extension must be included. - * Default value: `"${config:target}_riscv.cfg"` - -* `"v_Arm_GCC"` - * Sets the version of the Arm Embedded GCC to use, including toolchain binaries and the standard library version. - * This gets parsed into `ARM_GCC_path`. - * Default value: `"10.3"` - -* `"v_xPack_GCC"` - * Sets the version of the xPack RISC-V GCC to use. - * This gets parsed into `xPack_GCC_path`. - * Default value: `"10.2.0-1.2"` - -* `"OCD_path"` - * Where to find the OpenOCD. - * Default value: `"${config:MAXIM_PATH}/Tools/OpenOCD"` - -* `"ARM_GCC_path"` - * Where to find the Arm Embedded GCC Toolchain. - * Default value: `"${config:MAXIM_PATH}/Tools/GNUTools/${config:v_Arm_GCC}"` - -* `"xPack_GCC_path"` - * Where to find the RISC-V GCC Toolchain. - * Default value: `"${config:MAXIM_PATH}/Tools/xPack/riscv-none-embed-gcc/${config:v_xPack_GCC}"` - -* `"Make_path"` - * Where to find Make binaries (only used on Windows) - * Default value: `"${config:MAXIM_PATH}/Tools/MSYS2/usr/bin"` - -### Setting Search Paths for Intellisense - -VS Code's intellisense engine must be told where to find the header files for your source code. By default, Maxim's perpiheral drivers, the C standard libraries, and all of the sub-directories of the workspace will be searched for header files to use with Intellisense. If VS Code throws an error on an `#include` statement (and the file exists), then a search path is most likely missing. - -To add additional search paths : - -1. Open the `.vscode/settings.json` file. - -2. Add the include path(s) to the `C_Cpp.default.includePath` list. The paths set here should contain header files, and will be searched by the Intellisense engine and when using "Go to Declaration" in the editor. - -3. Add the path(s) to any relevant implementation files to the `C_Cpp.default.browse.path` list. This list contains the paths that will be searched when using "Go to Definition". - -## Die Types to Part Numbers - -The MaximSDK's peripheral driver filenames are written using die types instead of external part numbers. This table shows which part numbers correspond to each die type, which is useful when browsing through source file definitions in Maxim's peripheral drivers. - -| Die Type | Part Number | -| -------- | ----------- | -| ES17 | MAX32520 | -| ME10 | MAX32650 | -| ME11 | MAX32660 | -| ME13 | MAX32570 | -| ME14 | MAX32665 | -| ME15 | MAX32670 | -| ME16 | MAX32675 | -| ME17 | MAX32655 | -| ME18 | MAX32690 | -| ME21 | MAX32672 | -| AI85 | MAX78000 | -| AI87 | MAX78002 | - -## Project Creation - -### Option 1. Copying a Pre-Made Project - -Copying a pre-made example project is a great way to get rolling quickly, and is currently the recommended method for creating new projects. - -The release package for this project (Located at Tools/VSCode-Maxim in the MaximSDK) contains a `New_Project` folder designed for such purposes. Additionally, any of the VS Code-enabled Example projects can be copied from the SDK. - -1. Copy the existing project folder to an accessible location. This will be the location of your new project. - -2. (Optional) Rename the folder. For example, I might rename the folder to `MyProject`. - -3. Open the project in VS Code (`File -> Open Folder...`) - -4. Set your target microcontroller and board correctly. See [Basic Config Options](#basic-config-options) - -5. `CTRL+SHIFT+P -> Reload Window` to re-parse the project settings. - -6. That's it! The existing project is ready to build, debug, and modify. - -### Option 2 - Creating a Project from Scratch - -If you want to start from scratch, 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`. - -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 : - - ```shell - C:\Users\Jake.Carter\workspace\MyNewProject - +-- \.vscode - +-- Makefile - ``` - -3. Open the project in VS Code (`File -> Open Folder...`) - -4. Set your target microcontroller correctly. See [Basic Config Options](#basic-config-options). - -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. However, you'll probably want to add some source code. See [Configuring the Makefile](#configuring-the-makefile). - -## Troubleshooting - -Before troubleshooting, ensure that you are using the project files from the latest VSCode-Maxim version, and that the version number of Visual Studio Code and the C/C++ extension match the release notes. Sometimes, issues are caused by VS Code auto-updates. - -Additionally, ensure that your MaximSDK is updated to the latest version. You can use the "MaintenanceTool" application in the root directory of the SDK installation. - -### Testing the Setup - -Opening a VSCode-Maxim project with `File > Open Folder` should make Maxim's toolchain accessible from the integrated terminal. To test that everything is working properly : - -1. Navigate to the open `TERMINAL` tab on the bottom of the VS Code application. If a terminal is not open, you can open a new terminal with `Terminal > New Terminal` or (Ctrl+Shift+`). - - ![Terminal image](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/Terminal.JPG) - -2. The following commands to retrieve version numbers should be able to be run successfully from within the terminal : - - * `make -v` - * `openocd -v` - * `arm-none-eabi-gcc -v` - * `arm-none-eabi-gdb -v` - - For example, the `make -v` command should similar to the following: - - ![Make -v example output](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/make_test.JPG) - -If the tools are not accessible from the terminal, then the system settings and/or project settings must be examined further. (Troubleshooting guide is in progress) - -### Common Issues Caused by a Bad MAXIM_PATH - -* Large 'Problem' count when opening VS Code - - ![Problems Screenshot](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/issue_includeerrors.jpg) - -* "Unable to resolve configuration with compilerPath..." - - ![Compiler Path Issue](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/issue_compilerpath.jpg) - -The issues above are usually caused by a missing or improperly set "MAXIM_PATH" global settings.json variable. - -If you see the issues below ensure that you have set "MAXIM_PATH" in your _global_ user settings.json file, and that this path matches the location of the MaximSDK installation on your system. - -This can be resolved by double checking that the [Installation](#installation) procedure has been followed exactly. - -You can check the MAXIM_PATH on the VS Code terminal with the following commands... - -(Windows cmd) - -```shell -echo %MAXIM_PATH% -``` - -(Windows powershell) - -```shell -echo $env:MAXIM_PATH -``` - -(Linux/MacOS) - -```shell -printenv | grep MAXIM_PATH -``` - -... which should print the exact location of the MaximSDK installation. - -### Strange Debugger Behavior - -If you debugger is behaving strangely (which might consist of skipping code, throwing hard faults, failing to find function definitions, etc.) ensure that the program you're debugging matches the latest build output of the project. These symptoms are usually caused by a mismatch between the build output file and the contents of the micro's flash. - -This issue is can usually be fixed by running the "Flash" build task. Remember - flashing does not happen automatically when launching the debugger. - -## Issue Tracker - -Bug reports, feature requests, and contributions are welcome via the [issues](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/issues) tracker on Github. - -New issues should contain _at minimum_ the following information: - -* Visual Studio Code version #s (see `Help -> About`) -* C/C++ Extension version # -* Target microcontroller and evaluation platform -* The projects `.vscode` folder and `Makefile` (where applicable). Standard compression formats such as `.zip`, `.rar`, `.tar.gz`, etc. are all acceptable. diff --git a/userguide.md b/userguide.md index c828d6b..b6a5041 100644 --- a/userguide.md +++ b/userguide.md @@ -1,6 +1,7 @@ # How to Use Visual Studio Code with Maxim's Microcontrollers SDK (Windows & Linux) ## Table of Contents + * [Introduction](#introduction) * [De-Mystifying the SDK Toolchain](#de-mystifying-the-sdk-toolchain) * [Integrating the Toolchain](#integrating-the-toolchain) @@ -8,15 +9,16 @@ * [Referencing Example Code](#referencing-example-code) * [Loading Example Projects](#loading-example-projects) * [Injecting into Existing Source Code](#injecting-into-existing-source-code) -* [Adding Source Code](#adding-source-code) * [Conclusion](#conclusion) ## Introduction + Integrated Development Environments (IDEs) targeted at embedded systems and microcontroller development can come with a lot of overhead. They have a tendency to be bulky, unwieldy programs that can take up a lot of hard drive space, and when something isn't configured properly they can be a pain to troubleshoot. No one likes digging into project settings for hours trying to get their include paths working, troubleshooting five different configuration options just to link a library, or tracking a bug back down to project config option. [Visual Studio Code](https://code.visualstudio.com/) is a lightweight, powerful, and customizable editor that can serve as a great free alternative to the more traditional micro IDEs like Eclipse, Code-Composer Studio, IAR, Keil uVision, etc. This app note outlines step-by-step how to get started with [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim), which is a collection of project configurations that integrate Maxim's Microcontrollers SDK into Visual Studio Code. ## De-Mystifying the SDK Toolchain + Maxim maintains a Software Development Kits (SDK) for microcontroller development called the "Maxim Micros SDK". The SDK contains a large number of components, such as register files, linker files, board-support packages (BSPs), peripheral drivers, example code, etc. This section will focus on one of the _core_ components of the SDK - the _toolchain_. Understanding the toolchain is important because this VSCode-Maxim project is essentially a "wrapper" around the toolchain. Let's take a look under the hood... @@ -24,13 +26,14 @@ Understanding the toolchain is important because this VSCode-Maxim project is es A [toolchain](https://en.wikipedia.org/wiki/Toolchain) is really just a collection of programs and typically includes compiler, linker, and debugger executables. It also may include utility programs and build systems to make using these lower-level programs more convenient. The main components of the SDK's Toolchain are: -* [Arm GNU Compiler Collection](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) (GCC) - located under `~\MaximSDK\Tools\GNUTools\bin` -* [Open On-Chip Debugger](http://openocd.org/) (OpenOCD) - located under `~\MaximSDK\Tools\OpenOCD` -* [GNU Make](https://www.gnu.org/software/make) - made available on Windows via MSYS2 and located under `~\MaximSDK\Tools\MinGW\msys\1.0\bin` + +* [Arm GNU Compiler Collection](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm) (GCC) - located under `~/MaximSDK/Tools/GNUTools/10.3` +* [Open On-Chip Debugger](http://openocd.org/) (OpenOCD) - located under `~/MaximSDK/Tools/OpenOCD` +* [GNU Make](https://www.gnu.org/software/make) - made available on Windows via [MSYS2](https://www.msys2.org/) and located under `~/MaximSDK/Tools/MSYS2/usr/bin` GCC is used to compile source code but is rarely called directly. Instead, GCC is most frequently invoked in a list of directives collected into a _Makefile_. This list of directives is called a _recipe_. If you are new to Make, think of GCC as the hammer and Make as the builder who knows how to use it. You can tell Make to do a task (such as "make all" the source code) and Make will follow the instructions outlined in the Makefile's recipe to complete it. -The core Makefile for a target microcontroller can be found under `~\MaximSDK\Libraries\CMSIS\Device\Maxim\\Source\GCC` - see `gcc.mk`. This file tells Make exactly how to use GCC to compile code for that microcontroller. All projects can then have their own Makefile that builds off of this one by `include`-ing it. +Detailed documentation on the Makefile system can be found [here](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration). The important thing to note now is that every example project comes with a Makefile and project.mk file that manages GCC. They offer convenient configuration variables if needed and manage the source code for the project. Great - so source code is compiled into firmware binaries by Make using GCC. How is it flashed onto the microcontroller? That's where OpenOCD comes in. @@ -39,6 +42,7 @@ OpenOCD handles flashing firmware and opening a debugger _server_. It handles t In general, this is how things work at a low level. Integrated Development Environments (IDEs) such as Visual Studio Code have mechanisms for integrating toolchains so that these low-level steps can be abstracted away in a more convenient way. ## Integrating the Toolchain + Visual Studio Code provides the [Tasks](https://code.visualstudio.com/Docs/editor/tasks) interface for integrating external tools. To use the Maxim SDK toolchain via Tasks, the toolchain binaries must be made accessible from the command line. Additionally, the correct board and peripheral driver files for a target platform must be loaded for compilation and source code development. When those conditions are met, then Tasks can be created to conveniently implement the features that you would expect from an IDE: building, cleaning, flashing, etc. [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim) handles this for you and offers project files that are configured for Maxim's SDK and toolchain. @@ -48,11 +52,13 @@ Let's get started setting it up and walking through some common use-cases. The ## Getting Started with VSCode-Maxim ### 1 - Install Software Requirements -First, follow the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) for your OS from the readme if you haven't already. This include installing software requirements, setting the `MAXIM_PATH` environment variable, and downloading the latest release of VSCode-Maxim to an accessible location. -
+First, follow the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) for your OS from the readme if you haven't already. This include installing software requirements and setting the `MAXIM_PATH` environment variable. + +--- ### 2 - Release Package Overview + The VSCode-Maxim release package should contain the following contents. Note: Releases between OS's/versions may differ _slightly_ from the screenshot below, but this should match in general... ![Release Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/Release-contents.jpg) @@ -65,6 +71,7 @@ The VSCode-Maxim release package should contain the following contents. Note: R * `"userguide.md"` is this User Guide. ### 3 - Starter Project + In this section, we'll get hands on with the VSCode-Maxim starter project to see how it works. First, copy the "New_Project" folder from the VSCode-Maxim release package into an accessible location. You can also rename the folder if you'd like. For example, I've copied the folder to a `workspace` directory I created in my User folder below. I've also renamed the project to "MyProject". @@ -96,31 +103,34 @@ Now, VS Code should look something like this, where the template project has bee ![File opened](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_opened.jpg) -
+--- ### 4 - Verify Toolchain Access + At this point, the project is opened and ready to use and configure. Let's take a few steps on the integrated terminal to verify that things _are_ actually working correctly. First, launch a terminal with `Terminal > New Terminal`. ![New Terminal](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_terminal.jpg) -Next, we'll run through the commands in the ["Testing the Setup"](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/blob/main/readme.md#testing-the-setup) of the readme to see that the toolchain is accessible. This is critical for everything else to work. The project settings in the `.vscode` folder will add the locations of the toolchain to the terminal's `PATH`, which will allow them to be accessed directly. +Next, we'll run through the commands in the ["Testing the Setup"](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki/Troubleshooting#testing-the-setup) of the wiki to see that the toolchain is accessible. This is critical for everything else to work. The project settings in the `.vscode` folder will add the locations of the toolchain to the terminal's `PATH`, which will allow them to be accessed directly. For example, running `make -v` in the terminal should output a version # for Make, as shown below. ![Make Test](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/make_test.JPG) Run the other commands for OpenOCD, GCC, and GDB to verify that the integrated terminal has been configured correctly and the toolchain is in the right place. These should all run without error. + * `openocd -v` * `arm-none-eabi-gcc -v` * `arm-none-eabi-gdb -v` -If there _are_ any errors thrown by any of the commands above, first verify that you've followed the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) correctly. Problems are usually related to a missing or incorrect `MAXIM_PATH` environment variable and/or missing SDK components. Otherwise, see the [troubleshooting section](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/issues) of the readme. +If there _are_ any errors thrown by any of the commands above, first verify that you've followed the [installation instructions](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) correctly. Problems are usually related to a missing or incorrect `MAXIM_PATH` environment variable and/or missing SDK components. Otherwise, see the [troubleshooting section](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/wiki/Troubleshooting) of the wiki. -
+--- ### 4 - Set the Target Platform + With the tools verified as accessible from within VS Code, we can now start to configure the project for a specific microcontroller. In this case, we'll do some basic configuration of the project for the MAX32670EVKIT, but the same steps apply to any micro. @@ -131,10 +141,11 @@ Open `.vscode/settings.json`. This is the main configuration file, and you shou Set the `"target"` and `"board"` variables for your target platform. For example, for the MAX32670EVKIT I would set... + * `"target":"MAX32670"` * `"board":"EvKit_V1"` -The [Configuration](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#configuration) section of the readme will tell you the values that can be set here. In this case, we've changed the two most basic options: `"target"` and `"board"`. +The [Project Configuration](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#project-configuration) section of the readme will tell you the values that can be set here. In this case, we've changed the two most basic options: `"target"` and `"board"`. ![Basic Config Options](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/readme_basicconfig.jpg) @@ -148,16 +159,18 @@ Next, reload the VS Code window. A reload is necessary after changing any optio Now VS Code is ready to edit, build, and debug source code for the target platform. -
+--- ### 5 - Opening main.c + Open `main.c`, which can be found in the `src` folder. Here we can see the source code for a simple "Hello world" program. -![main.c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/main.JPG) +![main.c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/main.JPG) -
+--- ### 6 - Clean the Program + First, let's ensure that we're starting from a clean slate. Open the build tasks menu with `Ctrl+Shift+B` or `Terminal > Run Build Task...` and select the "clean-periph" option. This cleans out the build products from the current project as well as the peripheral drivers in the SDK. With everything cleaned out, the next step will build everything from scratch. ![Cleaning the program](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/clean-periph.jpg) @@ -166,9 +179,10 @@ Selecting the `clean-periph` build task will launch the task in the integrated t ![Clean-periph Complete](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/clean-periph_complete.jpg) -
+--- ### 7 - Build the Program + Next, we'll build the source code. Open the build tasks menu again with `Ctrl+Shift+B` or `Terminal > Run Build Task...` @@ -193,9 +207,10 @@ This is a good time to (once again) re-iterate an important point: _All configu For now, take note of the fact that the example project comes pre-configured for a single `main.c` source file, and looks for all `.c` and `.h` files inside of the `src` directory. -
+--- ### 8 - Flash and Debug the Program + Now that we've seen the program build successfully, let's flash it onto the microcontroller and debug it. First, ensure that your microcontroller is powered on and connected to your PC through your debug adapter. The specifics of this will vary based on the platform you're using, but documentation can be found in the datasheet. On a platform with an integrated debugger, such as the [MAX32670EVKIT](https://datasheets.maximintegrated.com/en/ds/MAX32670EVKIT.pdf), this is as simple as plugging it in with a micro-usb cable. On platforms where the debug adapter is not integrated, you'll need to connect your debug adapter to the right debugger port and power the platform separately. @@ -212,12 +227,14 @@ Once the debugger connects it will break the program execution on entry into the ![Breakpoint Hit](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/breakpoint_hit.JPG) -
+--- ### 9 (optional) - Open a Serial Port to the Micro + Before we continue the program execution, you can optionally open up a serial port to the microcontroller to see the "Hello world!" message and count printed. Default serial communication settings are: + * BAUD : 115200 * Data : 8-bit * Parity : none @@ -232,9 +249,10 @@ From there, steps will be program-specific to the serial terminal you're using. ![TeraTerm](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/TeraTerm.JPG) -
+--- ### 10 - Continue the Program + Press `F5` or hit the continue button in the debugger menu to continue the program past the breakpoint. ![Continue button](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/continue_button.JPG) @@ -245,16 +263,17 @@ You should see the LED on your microcontroller blinking. If you have a terminal Feel free to play around in the debugger here (setting different breakpoints, watch variables, stepping into and out of functions, etc.) to get familiar. When you're ready, you can hit the stop button to quit debugging. -
+--- ### 11 - Wrapping Up + Here, we've gotten started with a basic project configuration, the available build tasks, and have flashed/debugged the template Hello World program. The `New_Project` project template is designed as a good re-usable starting point, and you can freely copy this project around and re-configure it for different target platforms. You should now have a good basic understanding of how VS Code works and how Maxim's toolchain is integrated. The next sections cover more advanced subjects. -
+--- ## Referencing Example Code @@ -269,6 +288,7 @@ Opening the GPIO example reveals the following contents: ![GPIO Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_contents.JPG) There are a couple components inside the project: + * A `main.c` file with the example code * A project `Makefile` for building the example code * Eclipse configuration files and debugger profile (`.cproject`, `.project`, `GPIO.launch`) @@ -303,6 +323,7 @@ Using this method, you can quickly and easily reference example code for your ow Note: It's recommended to only use this method for _browsing/referencing_ example code. If you'd like to work with the example projects directly, it's recommended to copy them to an external location to keep the SDK's reference copy untouched. See the next section for more details. ## Loading Example Projects + Following the [installation procedure](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#installation) from the VSCode-Maxim readme will populate the MaximSDK's example projects with `.vscode` project folders. As such, they're ready to use "out of the box" with `File -> Open Folder`. However, it's recommended to copy the example projects to a location _outside_ of the SDK before using them. Keeping a copy of the original examples intact and untouched is always a good idea in case you need to go back and reference them later. @@ -310,20 +331,23 @@ However, it's recommended to copy the example projects to a location _outside_ o By default, the example projects are configured for the "EVKIT" evaluation platform for each target microcontroller. See [Project Settings](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#project-settings) in the readme if you need to change this. ## Injecting into Existing Source Code + Using example code as a reference is great, but what if we want to inject the VS Code setup into an existing project that's not in the MaximSDK? That's where the `Inject` folder in the VSCode-Maxim release package comes in. In the example below, we'll use the GPIO example _without_ any pre-existing VS Code project settings. The same procedure applies to any existing source code. ### 1 - Locate the Existing Project + For the sake of this example, a working copy of the GPIO example has been copied over into a separate folder. The contents of this GPIO example are as follows: ![GPIO Contents](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_contents.JPG) -
+--- ### 2 - Inject the VSCode-Maxim Files + Copy the _contents_ of the `Inject` folder from the VSCode-Maxim release package into the example project. ![GPIO Inject](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/inject_gpio.JPG) @@ -332,9 +356,10 @@ The contents of the project should now look something like this, with our `.vsco ![GPIO Injected](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/inject_gpio_finished.JPG) -
+--- ### 3 - Open the Project + The GPIO is now ready to be opened from within VS Code, and from here we'll follow a similar process as the one outlined in the "Getting Started" section of this User Guide. You'll open the project folder and configure `settings.json` for your target platform. However, since we're injecting into existing source code, we'll need to configure the Makefile as well. First things first... Launch VS Code. Open the project folder with `File > Open Folder...` and browse to the root directory of the project. @@ -345,57 +370,31 @@ VS Code should prompt for workspace trust. Select _Trust folder and enable all ![Workspace Trust Prompt](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/workspaceTrustPrompt.JPG) -
+--- ### 4 - Set the Target Platform & Reload + Open `settings.json` inside of the `.vscode` folder and configure the project settings for your target platform. See the [readme](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim/blob/main/readme.md) if you are unsure what to set here. For example, settings for the MAX32670EVKIT would be... + * `"target":"MAX32670"` * `"board":"EvKit_V1"` -The rest of the settings should be suitable for most use-cases. The only other setting that might need a deeper look here is the `M4_OCD_interface_file`. The default `cmsis-dap.cfg` setting is suitable for use with a target platform that MAX32625PICO debugger. If your target platform has an integrated debugger (such as the MAX32670EVKIT), that's it. Additionally, most evaluation kits will usually come with an _external_ MAX32625PICO debugger, so this setting can be left at its default. In other cases, see [Advanced Config Options](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#advanced-config-options) in the readme. +The rest of the settings should be suitable for most use-cases. The only other setting that might need a deeper look here is the `M4_OCD_interface_file`. The default `cmsis-dap.cfg` setting is suitable for use with a target platform that MAX32625PICO debugger. If your target platform has an integrated debugger (such as the MAX32670EVKIT), that's it. Additionally, most evaluation kits will usually come with an _external_ MAX32625PICO debugger, so this setting can be left at its default. In other cases, see [Advanced Config Options](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#advanced-config-options) in the readme. ![Reload Window](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/settings.JPG) `CTRL+S` to save the changes to the file, and then reload the VS Code window with `CTRL + SHIFT + P` > `Developer: Reload Window`. This is necessary so that VS Code re-parses all file-paths for our new target platform. -
+--- ### 5 - Configure the Build System -With the project settings configured, everything should be working in the editor. The `main.c` file can be opened and Intellisense will work properly. -However, in order to actually build this project, we'll need to configure the build system to match the existing source code. This involves editing the core project `Makefile`. - -Open the `Makefile` in the editor. - -![Open Makefile](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_open_makefile.JPG) - -Here, we can see a "Main Configuration" section highlighting some common options that, collectively, handle the configuration needed for most projects. The first thing to check is that all the source files have been added to the `SRCS` variable. The GPIO project only has a single `main.c` file, and the Makefile comes pre-configured for a `main.c` file by default. So, we're good to go there. - -However, if we look at the `VPATH` and `IPATH` options we can see some modifications are required. `VPATH` controls where Make will look for the source files (.c) specified by the `SRCS` variable, and `IPATH` controls where it will look for header files (.h). The GPIO example has placed the `main.c` file right in the root directory of the project but the Makefile is only configured to look inside of a `src` folder by default. So we have two options: -1. Re-organize the existing source code to match the Makefile. - * Create a new folder inside of the project called `src` - * Drag `main.c` inside of that folder - - ![GPIO Reorganized](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_reorganized.JPG) - -or... - -2. Re-configure the Makefile to match the existing source code. - * Set `VPATH` and `IPATH` to `.` to search the root directory for source and header files. - - ![Makefile Edited](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_makefile_edited.JPG) - -
- -Take option 1 or 2. - -In this case, that's all the Makefile configuration that's needed for the project. See [Editing the Makefile](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#editing-the-makefile) in the readme for more details on other scenarios, such as adding additional source files, changing compiler flags, linking libraries, etc. +By default, the build system will look in the root directory of the project for source (.c) and header (.h) files. It will also search in the optional "src" (.c) and "include" (.h) directories. If the project follows a non-standard structure with additional folders and files, they will need to be added to the build using the `IPATH` and `VPATH` [Build Configuration](https://github.com/Analog-Devices-MSDK/VSCode-Maxim/tree/develop#build-configuration) Variables. ### 6 - Clean & Build the GPIO Example -With the Makefile configured, we're ready to build the project. -As always, with a new project it's best to run a `clean-periph` first to ensure we're starting from scratch. +As always, with a new project it's best to run a `clean-periph` first to ensure we're starting from scratch. Then, run a `build` task to compile the GPIO example. Remember - build tasks can be accessed via `Terminal > Run Build Task...` or `Ctrl+Shift+B`. @@ -409,53 +408,22 @@ Monitor the terminal for any errors as the Makefile builds the periphal drivers ![GPIO Build Products](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/gpio_build_products.JPG) -
+--- + +### 6 - Wrapping Up -### 7 - Wrapping Up From here, the example is ready to be flashed to the target microcontroller, debugged, edited, and explored further. This same process can be applied to injecting the VS Code setup into any example project or existing source code. To summarize, you will... + 1. Copy the contents of the `Inject` folder into the root directory of the existing project (optionally renaming any existing Makefile for later reference). 2. Open the root directory of the project folder from within VS Code 3. Configure `settings.json` to match your target platform -4. Configure the Build system by editing the Makefile and/or re-organizing the source code. - -
+4. Configure the Build system with project.mk if needed. +5. Clean-periph and rebuild. -## Adding Source Code -In the example below, we'll walk through adding in additional source code files. This program will have a more advanced project structure with sub-folders. This example will assume you've worked through the basics of project configuration and setup, and already have the project open in VS Code. - -Adding and editing additional source code in the VS Code editor is straightforward. Files can be created from within VS Code or dragged and dropped into the project explorer. However, the `Makefile` must be configured to add additional source code files to the build. - -There are some general rules that can be followed for configuring the `Makefile`: -* Make sure the any implementation files added (.c) are added to the list of files to compile with the `SRCS` variable. -* Make sure the `Makefile` knows where to find these implementation files. You control where it looks with the `VPATH` variable. -* Header files (.h) don't need to be explicitly added to the build like source files (.c) do, but the `Makefile` needs to know where to look for them. You control where it looks with the `IPATH` variable. - -These rules cover basic scenarios. See [Editing the Makefile](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim#editing-the-makefile) in the readme for a more thorough list. - -Let's say I add the following source code in its own folder called `mylibrary`, with a `hellolibrary` header (.h) and implementation (.c) file. - -![Hello Library h](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_h.JPG) - -![Hello Library c](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_c.JPG) - -All this library does is contain a function called `myfunction` that prints a string to the console. Our main file can `#include` the header file and call `myfunction()`, which will print "Hello function!" to the console. - -![Hello Library main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_main.JPG) - -For this source code, we'll then modify the `Makefile` to add it to the build as follows: -* `SRCS += hellolibrary.c` to add the implementation file to the build -* `VPATH += ./src/mylibrary` so the `Makefile` knows where to find the implementation file -* `VPATH += ./src/mylibrary` so the `Makefile` knows where to find the header file. - -![Hello Library Makefile](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_hellolibrary_makefile.JPG) - -Now, when we run the `Build` task we can see the hellolibrary.c file added to the build successfully and compiled. The program is ready to be flashed to the microcontroller and debugged, where it will print "Hello function!" once to the serial port before exiting. - -![MyProject Build](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/myproject_build.JPG) - -
+--- ## Conclusion + Visual Studio Code is a great free code editor that, with the help of [VSCode-Maxim](https://github.com/MaximIntegratedTechSupport/VSCode-Maxim), can be used for embedded development with Maxim's Microcontroller toolchain. Having worked through this User Guide, you now hopefully have a good understanding of how Maxim's toolchain works, how it's integrated into VS Code, and how to leverage it to develop your own projects. diff --git a/utils.py b/utils.py index dca96e9..b917c1b 100644 --- a/utils.py +++ b/utils.py @@ -33,7 +33,6 @@ """ from collections.abc import MutableMapping -from string import Template import json from pathlib import Path import hashlib @@ -62,9 +61,6 @@ def __iter__(self): def __len__(self): return len(self.d) -class MSDKTemplate(Template): - delimiter = "##__" - def parse_json(filename): """ Parse values from a json file into a template-friendly (all-caps keys) dictionary