Version: *A
Context: In ModusToolbox™ 3.0, dual-CPU applications are reorganized to contain the project folders under the application folder unlike in ModusToolbox™ 2.4 where the project folders were separate without any top-level application folder. An illustration of a basic dual-CPU application structure in ModusToolbox™ 3.0 is shown below:
Figure 1 Multi-project application structure
The ModusToolbox™ 3.0 build system recognizes this structure using the Makefiles and automatically merges the hex files of the projects as part of the post-build process to create a combined hex file.
Figure 2 Build process for merging hex files
Additionally, based on the IDE that you are using, OpenOCD configuration files for programming and debugging are generated.
Figure 3 OpenOCD configurations in Eclipse IDEProblem: Although the auto-merging of hex files and generation of OpenOCD configuration files works as expected for most applications, it affects applications that have the following characteristics:
- Require multiple projects targeting a single CPU (for example, more than one project targeting the CM0+ or CM4 core)
- Do not require all project hex files to be merged (for example, when the bootloader must be programmed separately from the user application)
- Require hex files to be merged in a certain way and order (for example, the CM0+ and CM4 application bundle can be created in different ways: by merging the hex files directly, by signing the hex files individually and merging them, or by merging the hex files first and then signing them)
- Require different OpenOCD configurations to work correctly (for example, OpenOCD configurations for programming the bootloader and user application separately)
As an example, the mtb-example-psoc6-security code example has the following application structure:
The ModusToolbox™ 3.0 build system automatically merges the hex files of all the projects as explained earlier. Although this may be desirable in some cases, the code example requires a separate hex file for the bootloader project and a combined hex file for the user projects. The OpenOCD configurations generated would thus be incorrect because there is no top-level combined hex file to point to.
Figure 4 Program application configuration error
Solution: As explained in the problem statement, there are several issues that need to be resolved based on your application structure and requirement. The solutions for each of the requirements are described as follows.
- Prevent hex files from being merged automatically
The build system uses the MERGE make variable internally to merge all the project hex files. To prevent the hex files from being merged automatically, add this variable to the top-level application Makefile with no value as shown below:
MERGE=
The side effect of adding this variable is that the “Program Application” OpenOCD configuration file points to the app_combined.hex file which doesn’t exist. See 3.2 Deleting an OpenOCD configuration to delete this file.
- Merge hex files of specific projects
Use the MERGE make variable to specify the projects that need to be merged. Add this variable to the top-level application Makefile with a space-separated list of projects in the following manner:
MERGE=proj_cm0p proj_cm4
Note : The project names provided must be exactly the same as the APPNAME value specified in the project-level Makefiles. The hex files are merged in the same order as the projects specified. A hex file named “app_combined.hex” will be generated in the application build folder.
- Fix the OpenOCD configurations generated in Eclipse
In Eclipse IDE for ModusToolbox™, the following OpenOCD configurations are generated:
For each project:
- Debug – Starts a debug connection
- Attach – Attaches to the running target
For the application:
- Program Application – Programs the combined hex file (app_combined.hex) present in the application build folder
- Debug MultiCore – A launch group that launches a debug session per core on all cores
Based on the application requirement, create new OpenOCD configurations or modify the existing ones. The following sections show how you can create, modify, or delete existing configurations in Eclipse IDE for ModusToolbox™.
3.1 Creating an OpenOCD configuration to program a specific project hex file
The mtb-example-psoc6-security code example is used to demonstrate this step.
In this code example, the bootloader must be programmed separately. Note that there is no program configuration available for the project. Do the following to add an OpenOCD configuration for programming a specific project hex file:
- Select Run > Run Configurations to view the configuration files.
- Right-click the configuration named <Application>.<Project> Debug (KitProg3_MiniProg4) of the project that you want to program, and select Duplicate.
For example, to program the bootloader project (proj_btldr_cm0p), select the mtb-example-psoc6-security.proj_btldr_cm0p Debug (KitProg3_MiniProg4) configuration and select Duplicate.
Figure 5 Creating a duplicate OpenOCD configuration
- Add a new name for the configuration in the Name field.
Figure 6 Naming the configuration file
- Do the following on the Startup tab:
a) Select Use file under Load Executable and choose the appropriate project hex file using the File System button.
b) In the Run/Restart Commands section, remove all the existing commands and add quit in the text box. Clear the options Set breakpoint at and Continue as shown below:
Figure 7 Startup configuration options
- On the Common tab, select Run under Display in favorites menu option.
Figure 8 Common configuration options
- Click Apply for the changes to take effect. This configuration will be available in the Quick Panel under Launches when the corresponding project (bootloader project in this case) is focused in the Project Explorer window.
Figure 9 Bootloader project configurations
- Click this configuration to program the project-specific hex file.
3.2 Deleting an OpenOCD configuration
For applications that do not require merging the hex files, there will not be a app_combined.hex file generated; therefore, the “Program Application” configuration file is invalid. You need to either modify the configuration to point to a different hex file or remove it altogether.
Do the following to delete the configuration file:
- Select Run > Run Configurations.
- Right-click the configuration file and click Delete.
Figure 10 Deleting an OpenOCD configuration
3.3 Modifying the multi-core application debug configuration
To launch a debug session on all cores, use a launch group with the debug configuration of all the projects. Do the following:
- Select Run > Debug Configurations to view the launch group as shown below:
Figure 11 Launch group options
The security code example contains three projects, two of them targeting CM0+ and one targeting CM4. Because the CM0+ and CM4 user projects are combined, you need a multi-core debug session on these two projects. However, the default launch group chooses the CM0+ bootloader project and the CM4 user project, which is not correct.
- Click Edit and select the CM0+ user project “Debug” configuration as shown below:
Figure 12 Modifying the launch group
- Click Apply for the changes to take effect.
Note that this requirement is specific to the security code example. Make appropriate modifications or additions necessary to your Launch Group based on your application requirement.
Note: Make sure that the debug configurations of all the projects point to the correct hex file and not app_combined.hex.
- Fix the project views in VS Code workspace
When a multi-project application is created in VS Code using Project Creator and opened in VS Code, it only groups two of the projects and shows other projects under the application folder as shown below:
Figure 13 VS Code workspace
As you can see, the “proj_cm0p” project is not grouped together similar to the other projects. To fix this, click the code-workspace file. It is a JSON file that tells VS Code how to display the projects. Modify the file as follows:
- Find the project that has been missed in the folders field.
Figure 14 VS Code workspace JSON file
- Add the path to the project by copying one of the array values and modifying them as follows:
Figure 15 Modifying the project folders- Edit the settings field to add another element to the array for the project that was missed.
Figure 16 Modifying the settings
- Refresh the workspace for changes to take effect.
Figure 17 Workspace view with the changes- Fix the OpenOCD configurations generated in VS Code
In VS Code, the top-level application folder and the project folders each contain a .vscode folder that has the launch.json file with the following OpenOCD configurations:
For each project:
- Launch – Starts a debug connection
- Attach – Attaches to running target
For the application:
- Program Application – Program the combined hex file (app_combined.hex) present in the application build folder
- Erase Application – Performs an erase operation on the device
- Debug MultiCore – A launch group that launches a debug session per core on all the cores.
Based on the application requirement, create new OpenOCD configurations or modify existing ones. The following sections show how you can create, modify or delete existing configurations in Eclipse.
5.1 Creating an OpenOCD configuration to program a specific project hex file
- Navigate to the project folder that you want to program and open the .vscode folder.
- Open the launch.json file. All the configurations are present under “configurations” field in the JSON file as shown below:
Figure 18 Contents of launch.json file- Do the following to add the “Program” configuration:
a) Copy the values inside the curly brackets ({}) of the configuration with the name “Launch … (KitProg3_MiniProg4)” and paste it as another element in the configurations array.
b) Change the name field to “Program … (KitProg3_MiniProg4)”.
Figure 19 Modifying the name Change the overrideLaunchCommands field to point to the project hex file instead of app_combined.hex in the command that starts with “monitor program …”.
Figure 20 Modifying the executable
d) Edit the postStartSessionCommands field to remove the existing commands and add quit as shown below:
Figure 21 Modifying the configuration options
E) Remove the following fields:
- overrideRestartCommands
- postRestartSessionCommands
- svdFile
- breakAfterReset
- runToEntryPoint
F)Save your changes.
5.2 Deleting an OpenOCD configuration in VS Code
To delete any OpenOCD configuration, edit the launch.json file and remove the configuration defined inside the “configurations” array.
5.3 Modifying an OpenOCD configuration in VS Code
To modify any OpenOCD configuration, edit the launch.json file and edit the fields defined inside the configurations array.
For example, the “launch” configuration used for debugging points to the app_combined.hex file by default. In multi-project applications like the security code example, because the app_combined.hex doesn’t exist, you need to modify the “launch” configuration to use the proj_btldr_cm0p.hex file instead as shown below:
Figure 22 Modifying the debug configuration
Similarly, the “Multi-Core Debug” configuration is also incorrect because it picks up any of the two projects randomly out of the many. For example, the security code example contains three projects, two of them targeting CM0+ and one targeting CM4. Because the CM0+ and CM4 user projects are combined, you need a multi-core debug session on these two projects. However, the default launch group chooses the CM0+ bootloader project and the CM4 user project, which is not correct.
To fix this, select the launch.json file at the application-level .vscode folder and edit it to point to the correct executable. In this case, it should be the CM0+ user project (proj_cm0p) executable.
Figure 23 Modifying the multi-core debug configuration