From 0484ad0a8f55654884b1bf856f987da953eeed8b Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 25 Apr 2022 15:35:22 -0500 Subject: [PATCH 1/7] Add terminal profile option to template --- MaximSDK/Template/.vscode/templatesettings.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/MaximSDK/Template/.vscode/templatesettings.json b/MaximSDK/Template/.vscode/templatesettings.json index 8fe3c23..a2fee89 100644 --- a/MaximSDK/Template/.vscode/templatesettings.json +++ b/MaximSDK/Template/.vscode/templatesettings.json @@ -3,6 +3,8 @@ "Path":"${config:OCD_path};${config:ARM_GCC_path}/bin;${config:xPack_GCC_path}/bin;${config:Make_path};${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" }, + "terminal.integrated.defaultProfile.windows": "Command Prompt", + "terminal.integrated.env.linux": { "PATH":"${config:OCD_path}:${config:ARM_GCC_path}/bin:${config:xPack_GCC_path}/bin:${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" From ce261427b68fbff0b6ffc8e7c64baeee475e9020 Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Wed, 27 Apr 2022 18:11:22 -0500 Subject: [PATCH 2/7] Update test script with new toolchain paths --- .gitignore | 3 +++ maintain.py | 8 +++++--- 2 files changed, 8 insertions(+), 3 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6ad18a8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +build +buildlogs* +__pycache__ \ No newline at end of file diff --git a/maintain.py b/maintain.py index 2976f4d..c32e9b2 100644 --- a/maintain.py +++ b/maintain.py @@ -155,13 +155,14 @@ def release(version): # Tests cleaning and compiling example projects for target platforms. If no targets, boards, projects, etc. are specified then it will auto-detect def test(maxim_path, targets=None, boards=None, projects=None): + maxim_path = Path(maxim_path).resolve().as_posix() env = os.environ.copy() # Simulate the VS Code terminal by appending to the Path if curplatform == 'Linux': - env["PATH"] = f"{maxim_path}/Tools/OpenOCD:{maxim_path}/Tools/GNUTools/gcc-arm-none-eabi-9.2.1/bin:{maxim_path}/Tools/xPacks/riscv-none-embed-gcc/8.3.0-1.1/bin:" + env["PATH"] # Linux + env["PATH"] = f"{maxim_path}/Tools/GNUTools/10.3/bin:{maxim_path}/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2/bin:" + env["PATH"] elif curplatform == 'Windows': - env["PATH"] = f"{maxim_path}/Tools/MinGW/msys/1.0/bin;{maxim_path}/Tools/OpenOCD;{maxim_path}/Tools/GNUTools/bin;{maxim_path}/Tools/xPack/riscv-none-embed-gcc/bin;" + env["PATH"] # Windows + env["PATH"] = f"{maxim_path}/Tools/GNUTools/10.3/bin;{maxim_path}/Tools/xPack/riscv-none-embed-gcc/10.2.0-1.2/bin;" + env["PATH"] LOG_DIR = os.getcwd() @@ -173,6 +174,7 @@ def test(maxim_path, targets=None, boards=None, projects=None): # Log system info log(timestamp(), logfile) log(f"[PLATFORM] {platform.platform()}", logfile) + log(f"[MAXIM_PATH] {maxim_path}", logfile) # Get list of target micros if none is specified if targets is None: @@ -270,7 +272,7 @@ def test(maxim_path, targets=None, boards=None, projects=None): else: log(f"{timestamp()}[{board}] --- [BUILD]\t[SUCCESS] {round(duration, 4)}s", logfile) # Test clean (make clean) - clean_cmd = f"make clean TARGET={target} MAXIM_PATH={maxim_path} BOARD={board} MAKE=make" + clean_cmd = f"make distclean TARGET={target} MAXIM_PATH={maxim_path} BOARD={board} MAKE=make" res = ps(clean_cmd, env=env) # Run clean command # Error check clean command From 78aab8df89743bbb14da63238159f5739a68aa9a Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 16 May 2022 13:24:08 -0500 Subject: [PATCH 3/7] Fix typo in RISC-V debugger profile --- MaximSDK/Inject/.vscode/launch.json | 9 +++++---- MaximSDK/New_Project/.vscode/launch.json | 9 +++++---- MaximSDK/Template/.vscode/launch.json | 9 +++++---- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/MaximSDK/Inject/.vscode/launch.json b/MaximSDK/Inject/.vscode/launch.json index 272c0a2..9c45b1d 100755 --- a/MaximSDK/Inject/.vscode/launch.json +++ b/MaximSDK/Inject/.vscode/launch.json @@ -55,21 +55,21 @@ "request": "launch", "program": "${workspaceFolder}/buildrv/${config:program_file}", "args": [], - "stopAtEntry": true, + "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "linux": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/openocd", }, "windows": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb.exe", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb.exe", "debugServerPath": "${config:OCD_path}/openocd.exe", }, "osx": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/bin/openocd", }, "logging": { @@ -95,6 +95,7 @@ { "text":"exec-file build/${config:program_file}", "ignoreFailures": false }, { "text":"symbol-file buildrv/${config:symbol_file}", "ignoreFailures": false }, { "text":"target remote localhost:3334" }, + { "text":"b main" }, { "text": "set $pc=Reset_Handler","ignoreFailures": false } ] } diff --git a/MaximSDK/New_Project/.vscode/launch.json b/MaximSDK/New_Project/.vscode/launch.json index 272c0a2..9c45b1d 100755 --- a/MaximSDK/New_Project/.vscode/launch.json +++ b/MaximSDK/New_Project/.vscode/launch.json @@ -55,21 +55,21 @@ "request": "launch", "program": "${workspaceFolder}/buildrv/${config:program_file}", "args": [], - "stopAtEntry": true, + "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "linux": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/openocd", }, "windows": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb.exe", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb.exe", "debugServerPath": "${config:OCD_path}/openocd.exe", }, "osx": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/bin/openocd", }, "logging": { @@ -95,6 +95,7 @@ { "text":"exec-file build/${config:program_file}", "ignoreFailures": false }, { "text":"symbol-file buildrv/${config:symbol_file}", "ignoreFailures": false }, { "text":"target remote localhost:3334" }, + { "text":"b main" }, { "text": "set $pc=Reset_Handler","ignoreFailures": false } ] } diff --git a/MaximSDK/Template/.vscode/launch.json b/MaximSDK/Template/.vscode/launch.json index 272c0a2..9c45b1d 100755 --- a/MaximSDK/Template/.vscode/launch.json +++ b/MaximSDK/Template/.vscode/launch.json @@ -55,21 +55,21 @@ "request": "launch", "program": "${workspaceFolder}/buildrv/${config:program_file}", "args": [], - "stopAtEntry": true, + "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "linux": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/openocd", }, "windows": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb.exe", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb.exe", "debugServerPath": "${config:OCD_path}/openocd.exe", }, "osx": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/bin/openocd", }, "logging": { @@ -95,6 +95,7 @@ { "text":"exec-file build/${config:program_file}", "ignoreFailures": false }, { "text":"symbol-file buildrv/${config:symbol_file}", "ignoreFailures": false }, { "text":"target remote localhost:3334" }, + { "text":"b main" }, { "text": "set $pc=Reset_Handler","ignoreFailures": false } ] } From bbac04661d7c0df5fdb6fa5c57073411fe5d9840 Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 16 May 2022 13:29:29 -0500 Subject: [PATCH 4/7] Update debugger documentation --- readme.md | 81 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 66 insertions(+), 15 deletions(-) diff --git a/readme.md b/readme.md index c3e1895..22f1558 100644 --- a/readme.md +++ b/readme.md @@ -48,21 +48,25 @@ The project folders in this repo have the following dependencies: ![Open Settings JSON Command](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/open_settings_json.jpg) -10. Add the following entries _inside_ of the curly braces {}... +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 { - ... - "MAXIM_PATH":"", //Change this to the installation location of the MaximSDK from step 1. - "update.mode": "manual", // Disable auto updates of VS Code (Optional but strongly recommended) - "extensions.autoUpdate": false, // Disable auto updates of extensions (Optional but strongly recommended) - ... + // There may be other settings up here... + + "MAXIM_PATH":"C:/MaximSDK", + "update.mode": "manual", + "extensions.autoUpdate": false, + + // and/or other settings down here... } ``` -11. Save your changes to the file with `CTRL + S`. VS Code will prompt for a restart. Restart for the changes to take effect. +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 example projects come pre-populated with .vscode project folders, and the "Tools/VSCode-Maxim" folder of the SDK contains documentation and new project templates. See [Usage](#usage) below for more details on using the projects. +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 @@ -138,17 +142,25 @@ The usage guidelines below are specific to Maxim's Makefiles. The [GNU Make Man Debugging is enabled by Visual Studio Code's integrated debugger. Launch configurations are provided by the `.vscode/launch.json` file. -**Flashing does not happen automatically when launching the debugger.** Run the "Flash" [build task](#build-tasks) for your program before debugging. +* 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. Ensure that a debugger is attached to the target microcontroller on the correct port. (Refer to the datasheet of your evaluation board for instructions on connecting a 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 (CTRL+SHIFT+B). **Flashing does not happen automatically when launching the 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. +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) @@ -158,17 +170,56 @@ Debugging is enabled by Visual Studio Code's integrated debugger. Launch config #### Using the Debugger -The main interface for the debugger is the debugger control bar. +* 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 +`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) -For full usage details, please refer to the [official VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging). Documentation related to launch configurations can be ignored, as that's what's provided by this project. +#### 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 From 8e16b8e01ed867822942c974267dd8e9302e00d9 Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 16 May 2022 13:29:45 -0500 Subject: [PATCH 5/7] Sync installer package on release --- maintain.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/maintain.py b/maintain.py index 2976f4d..4f5bd95 100644 --- a/maintain.py +++ b/maintain.py @@ -93,6 +93,7 @@ def sync(): 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/") def release(version): sync() @@ -150,6 +151,9 @@ def release(version): with open(installscript_path, "w") as js: js.writelines(lines) + # Update dat afolder in installer package + shutil.copytree(r_dir, Path("installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/"), dirs_exist_ok=True) + # Update release date print("Done!") From 6e92e3e5da150ee4c6427eb814cf874763a4d7b1 Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 16 May 2022 13:30:08 -0500 Subject: [PATCH 6/7] Update installer package for v1.4.2 --- .../VSCode-Maxim/Inject/.vscode/launch.json | 9 +- .../VSCode-Maxim/Inject/.vscode/settings.json | 2 + .../VSCode-Maxim/Inject/.vscode/tasks.json | 2 +- .../New_Project/.vscode/launch.json | 9 +- .../New_Project/.vscode/settings.json | 2 + .../New_Project/.vscode/tasks.json | 2 +- .../data/Tools/VSCode-Maxim/readme.md | 343 +++++++++++------- .../meta/installscript.js | 9 +- .../meta/package.xml | 4 +- 9 files changed, 243 insertions(+), 139 deletions(-) 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 272c0a2..9c45b1d 100644 --- 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 @@ -55,21 +55,21 @@ "request": "launch", "program": "${workspaceFolder}/buildrv/${config:program_file}", "args": [], - "stopAtEntry": true, + "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "linux": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/openocd", }, "windows": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb.exe", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb.exe", "debugServerPath": "${config:OCD_path}/openocd.exe", }, "osx": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/bin/openocd", }, "logging": { @@ -95,6 +95,7 @@ { "text":"exec-file build/${config:program_file}", "ignoreFailures": false }, { "text":"symbol-file buildrv/${config:symbol_file}", "ignoreFailures": false }, { "text":"target remote localhost:3334" }, + { "text":"b main" }, { "text": "set $pc=Reset_Handler","ignoreFailures": false } ] } diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/settings.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/settings.json index 963695a..754de69 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/settings.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/Inject/.vscode/settings.json @@ -3,6 +3,8 @@ "Path":"${config:OCD_path};${config:ARM_GCC_path}/bin;${config:xPack_GCC_path}/bin;${config:Make_path};${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" }, + "terminal.integrated.defaultProfile.windows": "Command Prompt", + "terminal.integrated.env.linux": { "PATH":"${config:OCD_path}:${config:ARM_GCC_path}/bin:${config:xPack_GCC_path}/bin:${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" 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 3df3673..5eef671 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 @@ -27,7 +27,7 @@ "type": "shell", "command": "arm-none-eabi-gdb", "args": [ - "--ex=\"cd ${workspaceFolder}\"", + "--cd=\"${workspaceFolder}\"", "--se=\"build/${config:program_file}\"", "--symbols=build/${config:symbol_file}", "-x=\"${workspaceFolder}/.vscode/flash.gdb\"", 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 272c0a2..9c45b1d 100644 --- 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 @@ -55,21 +55,21 @@ "request": "launch", "program": "${workspaceFolder}/buildrv/${config:program_file}", "args": [], - "stopAtEntry": true, + "stopAtEntry": false, "cwd": "${workspaceFolder}", "environment": [], "externalConsole": false, "MIMode": "gdb", "linux": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/openocd", }, "windows": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb.exe", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb.exe", "debugServerPath": "${config:OCD_path}/openocd.exe", }, "osx": { - "miDebuggerPath": "${config:ARM_GCC_path}/bin/arm-none-eabi-gdb", + "miDebuggerPath": "${config:xPack_GCC_path}/bin/riscv-none-embed-gdb", "debugServerPath": "${config:OCD_path}/bin/openocd", }, "logging": { @@ -95,6 +95,7 @@ { "text":"exec-file build/${config:program_file}", "ignoreFailures": false }, { "text":"symbol-file buildrv/${config:symbol_file}", "ignoreFailures": false }, { "text":"target remote localhost:3334" }, + { "text":"b main" }, { "text": "set $pc=Reset_Handler","ignoreFailures": false } ] } diff --git a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/settings.json b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/settings.json index 963695a..754de69 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/settings.json +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/New_Project/.vscode/settings.json @@ -3,6 +3,8 @@ "Path":"${config:OCD_path};${config:ARM_GCC_path}/bin;${config:xPack_GCC_path}/bin;${config:Make_path};${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" }, + "terminal.integrated.defaultProfile.windows": "Command Prompt", + "terminal.integrated.env.linux": { "PATH":"${config:OCD_path}:${config:ARM_GCC_path}/bin:${config:xPack_GCC_path}/bin:${env:PATH}", "MAXIM_PATH":"${config:MAXIM_PATH}" 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 3df3673..5eef671 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 @@ -27,7 +27,7 @@ "type": "shell", "command": "arm-none-eabi-gdb", "args": [ - "--ex=\"cd ${workspaceFolder}\"", + "--cd=\"${workspaceFolder}\"", "--se=\"build/${config:program_file}\"", "--symbols=build/${config:symbol_file}", "-x=\"${workspaceFolder}/.vscode/flash.gdb\"", 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 index 5d2e66b..22f1558 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/readme.md +++ b/installer/com.maximintegrated.dist.vscodemaxim/data/Tools/VSCode-Maxim/readme.md @@ -1,22 +1,28 @@ # VSCode-Maxim -https://github.com/MaximIntegratedTechSupport/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 +## 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 +## 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 +## 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) @@ -42,29 +48,34 @@ The project folders in this repo have the following dependencies: ![Open Settings JSON Command](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/open_settings_json.jpg) -10. Add the following entries _inside_ of the curly braces {}... +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 { - ... - "MAXIM_PATH":"", //Change this to the installation location of the MaximSDK from step 1. - "update.mode": "manual", // Disable auto updates of VS Code (Optional but strongly recommended) - "extensions.autoUpdate": false, // Disable auto updates of extensions (Optional but strongly recommended) - ... + // There may be other settings up here... + + "MAXIM_PATH":"C:/MaximSDK", + "update.mode": "manual", + "extensions.autoUpdate": false, + + // and/or other settings down here... } ``` -11. Save your changes to the file with `CTRL + S`. VS Code will prompt for a restart. Restart for the changes to take effect. +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 example projects come pre-populated with .vscode project folders, and the "Tools/VSCode-Maxim" folder of the SDK contains documentation and new project templates. See [Usage](#usage) below for more details on using the projects. +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 -# Usage -## Introduction 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 +### 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) @@ -77,63 +88,79 @@ Opening an existing project is as simple as `File -> Open Folder...`. A project Note: You may need to enable viewing of hidden items in your file explorer to see the .vscode sub-folder. -## Build Tasks +### 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. + * 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. - + * 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. + * 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. + * 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 -## 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 +#### 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 + * 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 +#### 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. + * 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 -### 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 + Debugging is enabled by Visual Studio Code's integrated debugger. Launch configurations are provided by the `.vscode/launch.json` file. -**Flashing does not happen automatically when launching the debugger.** Run the "Flash" [build task](#build-tasks) for your program before debugging. +* 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) -### Launching the Debugger -1. Ensure that a debugger is attached to the target microcontroller on the correct port. (Refer to the datasheet of your evaluation board for instructions on connecting a debugger) +#### Debugger Limitations -2. Flash the program to the microcontroller with the "Flash" Build Task (CTRL+SHIFT+B). **Flashing does not happen automatically when launching the debugger.** +In general, Maxim's microcontrollers have the following debugger limitations at the hardware level: -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. +* 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) @@ -141,21 +168,63 @@ Debugging is enabled by Visual Studio Code's integrated debugger. Launch config ![Debugger Break on Main](https://raw.githubusercontent.com/MaximIntegratedTechSupport/VSCode-Maxim/main/img/debugger_breakmain.JPG) -### Using the Debugger -The main interface for the debugger is the debugger control bar. +#### 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 +`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) -For full usage details, please refer to the [official VS Code debugger documentation](https://code.visualstudio.com/docs/editor/debugging). Documentation related to launch configurations can be ignored, as that's what's provided by this project. +#### 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 -# 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.** @@ -167,112 +236,120 @@ The default project configuration should work for most use cases as long as `"ta 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 + +### 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"` - + * 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 + * 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 + ![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). + * 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. - * Don't touch unless you know what you're doing :) + * 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}"` + * 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"` + * 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}"` + * 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"` + * 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"` + * 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"` + * 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"` + * 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"` + * 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"` + * 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"` + * 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}"` + * 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}"` + * 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"` + * Where to find Make binaries (only used on Windows) + * Default value: `"${config:MAXIM_PATH}/Tools/MSYS2/usr/bin"` + +### Setting Search Paths for Intellisense -## 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 +## 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 | @@ -290,8 +367,10 @@ The MaximSDK's peripheral driver filenames are written using die types instead o | AI85 | MAX78000 | | AI87 | MAX78002 | -# Project Creation +## 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. @@ -309,15 +388,18 @@ The release package for this project (Located at Tools/VSCode-Maxim in the Maxim 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 : - C:\Users\Jake.Carter\workspace\MyNewProject - +-- \.vscode - +-- Makefile + ```shell + C:\Users\Jake.Carter\workspace\MyNewProject + +-- \.vscode + +-- Makefile + ``` 3. Open the project in VS Code (`File -> Open Folder...`) @@ -327,13 +409,15 @@ If you want to start from scratch, take this option. 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 +## 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 : +### 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+`). @@ -345,21 +429,22 @@ Opening a VSCode-Maxim project with `File > Open Folder` should make Maxim's too * `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 +### 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/issue_includeerrors.jpg) + ![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/issue_compilerpath.jpg) + ![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. @@ -367,32 +452,40 @@ If you see the issues below ensure that you have set "MAXIM_PATH" in your _globa This can be resolved by double checking that the [Installation](#installation) procedure has been followed exactly. -You can check the MAXIM_PATH on the terminal with the following commands... +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 location of the MaximSDK location. +... which should print the exact location of the MaximSDK installation. + +### Strange Debugger Behavior -## 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 +## 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 diff --git a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js index 10226f0..5973292 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js +++ b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js @@ -1,6 +1,6 @@ function Component() { - + installer.installationStarted.connect(this, Component.prototype.installationStarted); } Component.prototype.createOperations = function() @@ -21,9 +21,14 @@ Component.prototype.createOperations = function() } } +Component.prototype.installationStarted = function() +{ + console.log("Test installation started!"); +} + Component.prototype.installationFinished = function() { - var tag = "v1.4.1"; + var tag = "v1.4.2"; 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 8392ce6..36129e6 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-04-25 + 2022-05-16 net.sourceforge.openocd, net.launchpad.gcc.arm.embedded, net.launchpad.gcc.riscv.embedded, com.maximintegrated.libraries.periphdrivers - 1.4.1 + 1.4.2 1 \ No newline at end of file From 240296573b3dad1ed0a4ed6243664cecf26ebb93 Mon Sep 17 00:00:00 2001 From: Jake Carter Date: Mon, 16 May 2022 13:40:51 -0500 Subject: [PATCH 7/7] Remove unecessary test code in installscripts.js --- .../meta/installscript.js | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js index 5973292..8fd3678 100644 --- a/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js +++ b/installer/com.maximintegrated.dist.vscodemaxim/meta/installscript.js @@ -1,6 +1,6 @@ function Component() { - installer.installationStarted.connect(this, Component.prototype.installationStarted); + } Component.prototype.createOperations = function() @@ -21,11 +21,6 @@ Component.prototype.createOperations = function() } } -Component.prototype.installationStarted = function() -{ - console.log("Test installation started!"); -} - Component.prototype.installationFinished = function() { var tag = "v1.4.2";