******************************************************************** USER GUIDE FOR INTEGRATING CC5X/CC8E AND MPLAB X, STEP BY STEP *** This description covers MPLAB X integration using the dedicated plugin developed by Patrick Hayes. CC5X and CC8E can be used a tool in MPLAB X to build single-module projects. Multi-module projects is also possible by using MPASM and MPLINK. CC5X/CC8E or MPLINK generates the required HEX and COF files for debugging and production Build. * Thanks to Patrick Hayes for creating this plugin! CONTENTS: * INITIAL SETUP: PREPARING THE INTEGRATION * THE MIT LICENSE FOR THE PLUGIN * NORMAL USAGE: DEFINING A MPLAB X PROJECT * SINGLE-MODULE MODE: THE COMPILER GENERATES HEX AND COF FILES * SINGLE-MODULE DEBUGGING AND BREAKPOINTS * MAKING MPLAB X UNDERSTAND THE COMPILER DEFINITIONS * DISPLAYING VARIABLE CONTENTS DURING DEBUGGING * SETTING THE DEVICE CONFIGURATION BITS * SPECIAL NOTES * MULTI-MODULE MODE: MPLINK GENERATES HEX AND COF FILES * MULTI-MODULE DEBUGGING AND BREAKPOINTS * PLUG-IN SOURCE CODE ******************************************************************** INITIAL SETUP: PREPARING THE INTEGRATION * install the compiler if not already installed. Required: * CC5X latest version, minimum 3.5D * CC8E latest version, minimum 1.4D For older compiler versions it is possible to perform a Production Build and load the HEX file, but ONLY when using the generic Microchip plugin (mplabx-p.txt). The dedicated plugin described here does not support old compiler versions. * install MPLAX X IDE if not already installed. The latest version is normally recommended, also if not listed here. MPLAB X version 6.10 debugging does not work, normal build ok MPLAB X version 3.35 - 6.05 ok MPLAB X version 2.35 - 3.26 ok http://www.microchip.com/mplab/mplab-x-ide * start MPLAB X * the dedicated plugin is preregistered in MPLAB X. Select menu item Tools->Plugins, chose card "Available Plugins" or "Installed". Look for "CC5X Toolchain" and/or "CC8E Toolchain". If the plugin(s) are not Active they will need to be activated first. Select one or both plugins and click on the Activate button and follow the instructions. If the plugin(s) are not installed they will need to be installed first. Select one or both plugins and click on the Install button and follow the instructions. The MIT License has to be accepted. Terminate and restart MPLAB X. ******************************************************************** THE MIT LICENSE FOR THE PLUGIN Copyright (c) 2017 Patrick Hayes Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ******************************************************************** NORMAL USAGE: DEFINING A MPLAB X PROJECT * start MPLAB X. Click on menu item "File->New Project..." or use the equivalent button or command. A "New Project" window pops up. Follow the sequential steps. Use for example: 1. Choose Project: "Microchip Embedded" + "Standalone Project". Click Next. 2. Select device: "Mid-range 8-bit MCUs" or "Advanced 8 bit MCUs" and select the actual device. Click Next. 3. Select Header: None (Alternably your own selection). Click Next. 4. Select Tool: Simulator (Alternably your own selection). Click Next. 5. Select Plugin Board: None (Alternably your own selection). 6. Select Compiler: Select "CC5X compiler" or "CC8E Compiler. These are for the dedicated plugin. If the generic plugin also is configured for CC5X/ CC8E then it will appear as "Custom CC5X" or "Custom CC8E". The custom compiler plugin has another description. Click Next when the name assosiated with the dedicated plugin has been selected. IMPORTANT NOTE: The dedicated plugin is ONLY visible when selecting a device supported by the plugin. The plugin and the compiler are independent of each other and there could be differences in what devices are supported. 7. Select Project Name and Folder: Enter a Project name and decide Project Location. A folder with name "MyProject.X" will be created at the " Project Location". Click Finish. NOTE: It is possible to locate the MPLAB X project folder in the folder used for the project source files. Alternatively the source files can be stored in the MPLAB X project folder or anywhere else. The MPLAB X project folder will contain the Build files (HEX, COF, ASM, VAR, O, etc.). ******************************************************************** SINGLE-MODULE MODE: THE COMPILER GENERATES HEX AND COF FILES * Right-Click on the "Source Files" under the project name in the Projects window. Select an existing source file or create a new one. * Select the first symbol at top on the left side of the "Dashboard" tab field. Then the "Project Properties" window pops up. The "Project Properties" window can alternatively be selected by a right-click on the project name in the Projects window. Select the last item "Properties" in the large pop-up menu. Select item "CC5X Compiler" or "CC8E Compiler" and enter desired compiler options. * Perform a Production Build by selecting menu item "Run->Build Main Project" Look for messages "BUILD SUCCESSFUL" and "Loading completed". Syntax errors must be corrected. Point-and-click on error and warning messages is possible when using option -FM as stated above. Note that the make job is generic and may print information in the output window that does not look applicable. The locateion of the generated files can be found by inspecting the MPLAB X Output window. * Perform Debug Build by selecting menu item "Debug->Debug Main Project" Look for messages "BUILD SUCCESSFUL" and "Loading completed". The simulator/debugger may start immediate after the Debug Build. Ensure setting of proper breakpoints. ******************************************************************** SINGLE-MODULE DEBUGGING AND BREAKPOINTS When using single-module compiler mode the source code is often split into many C files which are included in the main C file. PROBLEM: MPLAB X may not recognise BREAKPOINTS in an included C file unless this file is listed in the "Source Files" of the project. SOLUTION: It is strongly recommended to list ALL C files belonging to the project as "Source Files". IMPORTANT: In order to prevent MPLAB X from compiling all files listed as "Source Files" separately it is required to exclude these files in the "Project Properties" window (select the first symbol at top on the left side of the "Dashboard" tab field OR right-click on the project name and select "Properties"). Click on Category "File Inclusion/Exclusion". Then move all C files that are included in the main C file to the "Excluded Files:" window. Click on the OK button when finished. ******************************************************************** MAKING MPLAB X UNDERSTAND THE COMPILER DEFINITIONS MPLAB X has an advanced editor that recognises defined symbols and try to provide useful help. CC5X and CC8E has many specific definitions that MPLAB X does not understand. It is recommended to copy the following definition into the main project source file. The MPLAB X editor will then recognize the specific compiler definitions. Note that the definitions are ONLY for the MPLAB X EDITOR and will not influence on debugging. The definitions will enable displaying simplified variable values. However, the variable watch window may provide more correct and comprehensive variable types. // FOR CC5X: #if !defined __CC5X__ // These definitions are for the MPLAB X GUI only (not compiled) #include "C:\Program Files (x86)\bknd\cc5x\defmpx16.h" // MPLAB X will read chip specific symbols from the device header file: #include "C:\Program Files (x86)\bknd\cc5x\16F1938.h" #endif // FOR CC8E: #if !defined __CC8E__ // These definitions are for the MPLAB X GUI only (not compiled) #include "C:\Program Files (x86)\bknd\cc8e\defmpx18.h" // MPLAB X will read chip specific symbols from the device header file: #include "C:\Program Files (x86)\bknd\cc8e\18F4680.h" #endif ******************************************************************** DISPLAYING VARIABLE CONTENTS DURING DEBUGGING MPLAB X will be able to display surprisingly many compiler data types. Some data types will only be displayed correctly in the Watch window. Variable type bit : displayed as a bitfield struct (item "value"). 8 bit signed/unsigned integer : OK 16 bit signed/unsigned integer : OK 24 bit signed/unsigned integer : OK 32 bit signed/unsigned integer : OK 24 bit (Microchip) float : NOT possible to display correctly 32 bit (Microchip) float : OK 8 - 32 bit fixed point : Initially displayed as an integer, but the correct format can be displayed in a Watch window by right-clicking on the variable name and selecting "Display Value Columns As->Fractional Integer" and chosing the right decimal point using the slide bar. 8 bit pointers : limited support, only the pointer itself can be displayed. 16 bit pointers : OK ******************************************************************** SETTING THE DEVICE CONFIGURATION BITS The compiler supports both direct and symbolic setting of the device configuration (see config.txt). The config symbols are defined in the device header file. * ALTERNATIVE 1: Use the -VG or -Vg compiler command line option to write all available symbolic config settings to the end of the generated *.VAR file. Then copy these definitions to a C source file and enable the desired settings. -VG: list default config settings and alternatives -Vg: list config setting alternatives * ALTERNATIVE 2: The available symbols for a specific device should be identical to the symbols generated by MPLAB X for the XC8 and C18 compilers. MPLAB X can be used to generate the required config setting for the project. ===> The settings generated by MPLAB X can be copied and pasted into the source code for compilation. Procedure when the XC8 (or C18) compiler is installed: 1. Start MPLAB X and make sure your project is set as the main project. 2. Right-click on the project name in the Projects window. Select last item Properties and change "Compiler Toolchain" to XC8 (or C18) temporarily. 3. Select menu Window->PIC Memory Views->Configuration Bits 4. Change each available item according to your selections for the project. 5. Click "Generate Source Code to Output" and copy the generated settings (except the #include statement) to your C source code. 6. Right-click on the project name in the Projects window. Select last item Properties and change language toolsuite back to CC5X/CC8E. This procedure can be repeated when configuration bits have to be changed. ******************************************************************** SPECIAL NOTES CC5X: * The MPLAB X editor does not recognize the pageX identifiers. - workaround 1: use the definitions stated in section "MAKING MPLAB X UNDERSTAND THE COMPILER DEFINITIONS" - workaround 2: use pageX modifiers on prototype function definitions only - workaround 3: use #pragma codepage or #pragma location CC8E: * It is required to disable the Extended instruction set. Otherwise program execution and Debug Build may fail. The solution is to use #pragma config to DISABLE the Extended instruction set (XINST = OFF). ******************************************************************** MULTI-MODULE MODE: MPLINK GENERATES HEX AND COF FILES IMPORTANT NOTE: Microchip has terminated support for MPLINK. MPLAB X 5.35 is the last version that includes mpasmx/mplink. However, devices supported by mplink can be used with newer MPLAB X versions if a copy of the mpasmx package (including mplink) is stored on the computer. It is possible to let the compiler or assembler generate object modules that are linked by MPLINK to build the final HEX and COF files. Note that this often requires more space for local variables because the compiler is not able to find the best overlapping layout. The code size may also increase compared to single-module projects. ==> NOTE: It is NOT possible to mix ASM and C modules. All modules have to be compiled using CC5X or CC8E. It is possible to use inline ASM code within the C modules according to the restrictions defined by the User's Manual of the compiler. * First open the "Project Properties" window by selecting the first symbol at top on the left side of the "Dashboard" tab field OR by a right-click on the project name and select "Properties"). 1. Select item "CC5X toolchain" or "CC8E toolchain" and UNCHECK item "Single module mode" 2. Then item "Location of MPlink" becomes visible. Normally only the MPLAB X version part of the path need to be modified. This must be corrected according to the current MPLAB X version. It should look something like: C:\Program Files (x86)\Microchip\MPLABX\v4.01\mpasmx\mplink.exe 3. File "reloc.inc" need to be copied from the compiler folder to the project folder and similarly modified to suit the location of mpasmx. Normally only the one line need to be modified: -x"C:\Program Files (x86)\Microchip\MPLABX\v4.01\mpasmx\mpasmx.exe" 4. Select item "CC5X Compiler" or "CC8E Compiler" and enter your desired compiler options. Select OK and the project is ready to compile for production and debug. * Right-Click on the "Source Files" under the project name in the Projects window. Select an existing source file or create a new one. * Perform a Production Build by selecting menu item "Run->Build Main Project" Look for messages "BUILD SUCCESSFUL" and "Loading completed". Correct syntax errors. Point-and-click on error and warning messages is possible. Note that the make job is generic and may print information in output window the that are not applicable for the current Build. * Perform Debug Build by selecting menu item "Debug->Debug Main Project" Look for messages "BUILD SUCCESSFUL" and "Loading completed". The simulator/debugger may start immediate after the Debug Build. Ensure setting of proper breakpoints. ******************************************************************** MULTI-MODULE DEBUGGING AND BREAKPOINTS In multi-module mode the compiler generates ASM files. It is NOT possible to set breakpoints in the C files. Instead the ASM files generated by the compiler must be used for debugging. PROBLEM: MPLAB X may not recognise BREAKPOINTS in a generated ASM file unless this file is listed in the "Source Files" of the project. SOLUTION: It is strongly recommended to list ALL generated ASM files belonging to the project as "Source Files". The generated ASM files are found in: .X\build\default\debug\_ext\1472 IMPORTANT: In order to prevent MPLAB X from compiling all files listed as "Source Files" separately it is required to exclude these files in the "Project Properties" window (select the first symbol at top on the left side of the " Dashboard" tab field OR right-click on the project name and select "Properties"). Click on Category "File Inclusion/Exclusion". Then move all generated ASM files to the "Excluded Files:" window. Click on the OK button when finished. ******************************************************************** PLUG-IN SOURCE CODE https://github.com/mc6pac/toolchainCC5X https://github.com/mc6pac/toolchainCC8E Tools: NetBeans IDE 8.1 (8.2) Java SDK 1.8.xxx, or the latest version MPLABX SDK 3.40 from microchip – found on their developer site: http://www.opensource4pic.org/content/content/mplab-x-sdk-mplab-x-ide