Release Notes for Microchip Easy Bootloader Library v2.11
Microchip Technology Inc.
August 2018
Table of Contents
1. What is Microchip Easy Bootloader Library?
4. What is New, Changed, and Migration
Microchip Easy Bootloader Library (EZBL) is a collection of Microchip firmware APIs, example projects and PC-side build tools to address the needs of modern in-the-field flash reprogramming of 16-bit PIC24 MCU, dsPIC33 DSC and 32-bit PIC32MM targets while minimizing development and maintenance effort. The software library helps create modern, richly-featured bootloaders and compatible applications that can reuse bootloader communications, timing, flash read/erase/write and other APIs. EZBL is distributed with full source code, but uses a mix of pre-compiled/archived object code, PC binaries, build-time linker script generation, and editable source files in order to minimize the amount of effort needed to create a stable bootloader using existing UART, I2C, or USB Host MSD ("thumb drive") communications libraries or a custom interface.
Besides being a Bootloader, EZBL offers BIOS-like services. Precision timing, task scheduling and communications software FIFO buffering are initialized for Bootloader use, but they will (optionally) continue to run in the background as the Application executes. The Application can call any public Bootloader API and make use of the versatile library of EZBL functions to avoid having to reimplement or port code over when implementing a first product or implementing a derivative product targeting a new/lower cost or bigger/more powerful target processor.
To obtain the latest version of EZBL, use the download link on the Microchip web site at www.microchip.com/ezbl. EZBL is distributed as a .zip package containing all needed source code, binaries, documentation, and reference projects without using an installer. Simply unzip the package to a desired folder on your computer (that does not contain spaces in the parent path) and either open the reference MPLAB® X IDE projects or documentation in the ezbl-vx.xx.zip: ezbl-vx.xx\help folder.
A preferred method to update to newer versions of EZBL is to unpack the .zip into a new target folder and use a file/directory comparison tool to merge the updated files into your existing EZBL based projects. Note that if a historical EZBL bootloader project has been deployed in your product to the field, it is generally not advised to try and update portions related to EZBL. The Bootloader will not self-update Bootloader flash when uploading a new Application image, so any changes to EZBL internals or protocols break backwards compatibility. Be sure and always maintain a backup before starting an update (especially if you have deployed the previous version) and read the below Migration section to see what components in this release may be compatible with previous EZBL versions.
The PC-side build components (ezbl_tools.jar) require the Microchip MPLAB® X IDE or IPE be installed, a suitable Microchip XC16 or XC32 compiler tool-chain and a compatible Java Runtime Environment (JRE). As MPLAB X IDE/IPE are built with Java, any system that already has the MPLAB X IDE and XC16/XC32 compiler(s) installed should be able to execute the EZBL build components without the need to install a separate JRE.
For PC-side communications with a bootloader (via ezbl_comm.exe), a Microsoft Windows x86/x64 based platform is required, or alternatively, the C source code for this utility must be compiled and linked for the target operating system. It is not necessary to have MPLAB X IDE/IPE installed in order to transmit a firmware update to a Bootloader.
EZBL can be uninstalled by simply deleting the folder that you unpackaged the .zip into.
Read "help\EZBL Hands-on Bootloading Exercises.pdf", Exercise 1 and 2 (pages 3-7).
In most abbreviated form:
To make a typical UART bootloader, open the ex_boot_uart MPLAB X project (ex_boot_uart_pic32mm for PIC32MM targets), select your target processor in the project properties, then compile and program the project via an ICSP programming tool.
To test the bootloader, open the ex_app_led_blink (or ex_app_led_blink_pic32mm as applicable) MPLAB X project, select the "uart" Build Configuration, again select your target processor in the project properties, edit the ezbl_app.mk file (in Important Files) to set your PC's COM port ("-com=COMx" option to ezbl_tools.jar --communicator ezbl_post_build: recipe) and then build the project. Successful bootloading will be indicated by an LED blinking at 1 Hz with upload status printed to the MPLAB build Output window.
For more information and getting started steps for other types of bootloaders, see "help\EZBL Library Documentation.pdf"
ex_boot_usb_msd/exp16_pic32mm0256gpm064_pim.x USB Host MSD project for the PIC32MM0256GPM064 Family of devices. This is a memory-type bootloader implementation targetting USB thumb drives and other mass storage media. Functionality and behavior is equivalent to the existing, 16-bit ex_boot_usb_msd projects. However, ex_app_led_blink_pic32mm set to the 'usb_msd' Build Configuration is the proper test Application, not ex_app_led_blink.
To evaluate:
[16-bit only] Fixed ezbl_tools.jar null pointer exception when building a normal/single partition Bootloader project lacking a .const section. I.e. the project lacked any global or static object declarations with the const type qualifier, did not reference any string literals and did not call any library APIs declaring constants internally. The exception would have been thrown at the final build step for affected Bootloader projects, after linking was complete and .merge.gld/.merge.S files were being generated. This bug was a regression in EZBL v2.10 and did not occur with EZBL v2.04.
[16-bit only] Fixed Bootloader read back verification failure, EZBL_ERROR_HARD_VERIFY_ERROR (0xFFE8), being reported when all of the following conditions existed:
In the EZBL v2.10 distribution, USB Host MSD Bootloader projects targetting devices with 128KB or less of flash, such as the pic24f_analog_starter_kit.X project could readily meet these conditions and exhibit this error. The address of the verification failure occured at FICD or other Configuration word containing a reserved Config bit related to the hardware debugger. This bug was a regression in EZBL v2.10 and did not occur with EZBL v2.04.
[16-bit only] Suppressed unlikely Bootloader read back verification failure in reserved address range, EZBL_ERROR_SOFT_VERIFY_ERROR (0xFFE7), on a few devices, using certain versions of MPLAB X IDE/IPE to program the initial Bootloader .hex file, and certain ICSP hardware program tools. This error message would have been possible only on devices with Config words implemented on the last page of flash, when the Bootloader project contained code or PSV constants on the last page as well and when the device flash implements a 48-bit double word as the smallest programmable block size. The error would occur with 100% repeatable behavior (i.e. if you don't currently see this error message when trying to use your Bootloader, then you will never be affected by this issue and can ignore this change). The cause of this reserved space verification error is garbage/unknown data physically programmed to flash during ICSP programming of "don't care" memory addresses sharing the second half of a 48-bit flash double word as a defined Configuration word. These addresses cannot be used for project code/constants and are not connected to any hardware functions, so dummy data stored in them does not affect run-time device behaviors. However, previous versions of EZBL attempted to verify all '1's data in them. EZBL v2.11 will now detect when the Bootloader image and target device meet all pre-conditions to trigger the error and mask affected don't-care regions off in the __EZBL_TOOLS_COMPUTED_NO_VERIFY_RANGES linker macro.
[16-bit only] EZBL_SetAppReservedHole() macro in EZBL v2.10 may not have honored space reservations made against the last page of flash on devices with Configuration words also implemented on the last page of flash. ezbl_tools.jar will now correctly maintain the last page of flash as unoccupied when flagged by the macro and generating .merge.S/.merge.gld files for the Application project.
[16-bit only] ex_boot_usb_msd/pic24f_analog_starter_kit.x project only: swapped D1 and D2 LED assignment back to the way it was in EZBL v2.04. EZBL v2.10 called EZBL_DefineLEDMap() in system.c with D1 as the LSbit and D2 as the MSbit. By EZBL's bitmasking convention for LEDs and buttons, LSbits should correspond to the right-most hardware function while MSbits represent buttons or LEDs to the left of the LSbit. The MPLAB Starter Kit for PIC24F Intelligent.Integrated.Analog board confusingly has D1 silkscreened on the left and D2 on the right.
[32-bit only] Fixed typo in ezbl.h: EZBL_ForwardIRQToBoot() macro was incorrectly defined as "EZBL_ForwarIRQtToBoot()"
[32-bit only] Corrected ButtonRead()/ButtonPeek() ezbl_lib32mm.a function to return the same bit polarity as implemented in ezbl_lib.a for 16-bit devices. In EZBL v2.10, a '1' represented a unpushed state and '0' was the pushed state. This corrects the meaning of the ButtonsPushed and ButtonsReleased bit masks.
[32-bit only] Fixed EZBL_general_exception_context.S capture of CP0 Cause register. In EZBL v2.10, the EZBL_TrapHandler() function would decode and print incorrect data for the exception from the cause parameter.
[32-bit only] Fixed Application projects overlaying global and static variables on top of Bootloader allocated heap RAM (when present). This caused both the Bootloader's heap and Application global/static variables to be subject to corruption after launching the Application and calling Bootloader APIs referencing heap objects. As an example, the MLA USB Host stack for PIC32MM0256GPM064 family targets uses heap RAM for endpoint data after a USB device is plugged in. In EZBL v2.11, the Bootloader's _min_heap_size is exported as a reserved RAM region in the [boot_project].merge.S file so Application variables will not get overlayed on the dynamically allocated USB memory.
[32-bit only] Fixed Application project inheriting various compiler built-in code instanced in the Bootloader project which is inappropriate for reuse in the Application. Examples include the CRT startup data initialization code and malloc/calloc/realloc APIs, which include references to linker-generated flash data initialization tables and pointers to the project's heap.
Inheriting startup code caused global and static variables in the Bootloader project to get reinitialized or zeroed upon launching the Application project. Simultaneously, global and static variables located in the Application project were not getting initialized at start up.
malloc()/calloc()/realloc()/free() called from Application projects will now execute with respect to their own heap memory, reserved using the _min_heap_size xc32-ld linker option set in the Application project properties. If the Application wishes to specifically allocate/free memory against the Bootloader's heap, it can now do so by calling EZBL_BOOT_malloc()/EZBL_BOOT_calloc()/EZBL_BOOT_realloc()/EZBL_BOOT_free(), assuming the Bootloader project contains a corresponding malloc()/calloc()/realloc()/free() symbol or function in it.
[32-bit only] Corrected __KSEG0_DATA_MEM_LENGTH definition in ezbl_boot.ld for PIC32MM0016GPL036, PIC32MM0016GPL028, and PIC32MM0016GPL020 devices. This error would have prevented the ex_boot_uart_pic32mm project from correctly executing on these three targets due to stack pointer allocation to an unimplemented RAM address.
EZBL_NoExportSYM() and EZBL_NoExportSection() macros added to ezbl.h. These macros may be called in normal or single partition Bootloader projects and will prevent the named symbol(s) or symbols contained in named section(s) from being exported. This will prevent Application projects from seeing or otherwise being able to link against the specified functions, global variables, global const objects or other named symbols contained in the Bootloader project.
EZBL_InstallFILEIO2Flash() has been ported to ezbl_lib32mm.a. Use the corresponding ezbl_lib32mm\functions\EZBL_InstallFILEIO2Flash.c source file as a starting point for developing other memory-type Bootloaders for PIC32MM products, or use it as is in the library archive via the new ex_boot_usb_msd/exp16_pic32mm0256gpm064_pim.x project.
Idle() added to ezbl_lib32mm.a. With XC16, Idle() is a macro in the device header file which ultimatly maps to a PWRSAV #1 CPU instruction. The microMIPS32 ISA does not have an equivalent instruction, so XC32 targets require an external Idle() implementation.
These projects provide generally equivalent EZBL support for the PIC32MM0064GPL036 Family and PIC32MM0256GPM064 Family products using the XC32 toolchain. However, only UART based bootloader and application example projects are available.
Not all ezbl_lib.a functionality present in the 16-bit PIC24 and dsPIC projects in EZBL have been duplicated in the PIC32MM version. Most notably, the NOW_CreateTask() API has not been implemented. Consequently, bootloader functionality is implemented by polling the EZBL_BootloaderTask() API in the main() while(1) loop. The bootloader project must call this function periodically, while the application project can optionally call this function if it wishes to permit background monitoring for external firmware update requests/offers.
General interrupt handling and bootloader code sharing behaves similarly across 16-bit EZBL and 32-bit EZBL implementations. Every hardware exception vector is mapped by default to application projects and additionally/optionally mapped to bootloader project ISRs on a per-vector, run-time chosen basis. All global/non-static functions and variables in the bootloader project can be directly linked to and called or referenced in application projects (identically to the 16-bit EZBL implementation).
On the PC, the same ezbl_tools.jar and ezbl_comm.exe executables are used for build-time bootloader generation and to transferm firmware images in an identical manner to 16-bit EZBL implementations. The resulting bootloader outputs of bootloader_project_name.merge.S and bootloader_project_name.merge.gld are also generated for PIC32MM targets, however, the linker script instead receives a '.ld' file extension instead of '.gld'. The file extension is different to conform with existing MPLAB and XC32 conventions.
During application firmware update, the same '.bl2' file format is used and the communications protocol is 100% unchanged relative to EZBL v2.04.
XC32 targets outside the PIC32MM product line are not supported by EZBL
Fixed prior incompatibility with EZBL v2.04 and MPLAB X IDE versions >= v4.10. EZBL v2.10 is compatible with MPLAB X IDE v3.xx, v4.xx and v5.00 (latest available at time of release). ezbl_tools.jar now contains a trimmed device characteristics database compiled into the executable, removing the historical dependency on device information being available from the IDE.
Fixed prior application linker script generation logic in ezbl_tools.jar so that simplified bootloader projects requiring less than 1 total erase page quantiy of flash will still link with follow on application projects. In EZBL v2.04, such a (bootloader test shell) project compiled as an EZBL bootloader would generate a link-time build error while building any application project after adding the .merge.S/.merge.gld files.
Corrected EZBL_ReadPackedFlash() API bug whenever dataCount specified a 0 byte read operation. In EZBL v2.04 this case would have corrupted the TBLPAG contents and written at least one byte to the dest memory in RAM. The new implementation performs about 4.2% or 8.3% faster (device dependent).
EZBL_FIFOSetBaud() will no longer cause a "_U2MODE undefined" linker error when called on devices which have only one UART peripheral.
Various "relocation truncated to fit" linker errors no longer potentially occur against _NOW_TaskDispatcher and symbols kept via the EZBL_KeepSYM() macro whenever the bootloader project contains code at both high and low memory addresses, separated by at least 0x010000 program space addresses (assuming the project has been built with the Large Code model).
UART4 can now be used. Previously, the U4RXIF interrupt flag was being treated as existing at IFS5<7>, when it is actually located at IFS5<8> on applicable devices.
EZBL_WriteROMObj() can now correctly write object arrays to flash. In EZBL v2.04, this macro would incorrectly treat arrays as having exactly 2 bytes in them, regardless of the actual array base type or element count.
EZBL_ForwardInt(), EZBL_ForwardIntToApp(), EZBL_ForwardIntToBoot(), EZBL_ForwardAllInt(), EZBL_ForwardAllIntToApp() and EZBL_ForwardAllIntToBoot() macros added to eliminate the need to directly manipulate the bits in EZBL_ForwardBootloaderISR. These APIs also provide a more trivial migration between 16-bit PIC24/dsPIC33 and 32-bit PIC32MM projects as the PIC32MM microMIPS instruction set cannot multiplex between ISR functions efficiently using RAM bitfields. The essentially equivalent ezbl_lib32mm.a APIs of EZBL_ForwardIRQ(), EZBL_ForwardIRQToApp(), EZBL_ForwardIRQToBoot(), EZBL_ForwardAllIRQ(), EZBL_ForwardAllIRQToApp() and EZBL_ForwardAllIRQToBoot() facilitate ISR multiplexing by writing to shared global RAM function pointers instead of testing a bitfield and using static branch instructions.
EZBL_RdIntFlag(), EZBL_WrIntFlag(), EZBL_ClrIntFlag(), EZBL_SetIntFlag(), EZBL_InvIntFlag(), EZBL_RdIntEn(), EZBL_WrIntEn(), EZBL_ClrIntEn(), EZBL_SetIntEn(), EZBL_InvIntEn(), EZBL_RdIntPri() and EZBL_WrIntPri() added. These provide a means to run-time manipulate IECx, IFSx and IPCy bitfields by IRQ number without needing to statically specify which registers and bit positions are applicable during build time.
EZBL_fprintf() and EZBL_vfprintf() added. Additionally, the EZBL_printf.s APIs (that don't target a string buffer) will now always send output writes through the _write() callback function instead of conditionally calling EZBL_FIFOWrite() in order to support more arbitrary file handles and communications mediums.
EZBL_ERROR_CUSTOM_MESSAGE -28 (0xFFE4) can now be used as a bootloader communications response code in bootloader projects. The ezbl_comm.exe utility will now keep the communications port open after seeing this termination error until the next null character is received or an idle timeout occurs. This permits bootloaders to display a customized, null terminated user message string in response to their attempt to update the application firmware. Example code (default: commented-out) using this new mechanism can be found in the ex_app_led_blink project, main.c's EZBL_BootloadRequest() callback function.
.bl2 file format and UART/I2C communications protocols remain unchanged (excluding the optional EZBL_ERROR_CUSTOM_MESSAGE termination code that EZBL v2.10 bootloaders may now use).
NOW_GetIntEn() has been renamed to NOW_RdIntEn() to match the naming convention of the new EZBL_RdIntEn() and related generic interrupt control functions.
EZBL_WaitForNVMOpComplete() will now set the NVMADRH/NVMADRL or transparent program address latch to the unimplemented program address of 0xFFFFFE (or 0xFFFFFC on devices implementing flash double words) before return. This can help prevent the possibility of ever triggering an unintended, destructive flash erase or write operation if electrical or environmental conditions are violated, causing unpredictable CPU code execution (for example, due to rapid VDD oscillation from battery contact/switch bounce leading to execution at excess frequency near the BOR point). On PIC32MM devices, NVMADDR is set to the unimplemented 0x55555555 address instead.
The __EZBL_TOOLS_COMPUTED_NO_PROGRAM_RANGES table generated in the ezbl_integration\ezbl_build_standalone.gld linker script in Bootloader projects now includes the first 0xC addresses in the Application's flash space. These addresses correspond to the packed EZBL_appBootloadState structure in flash, which EZBL_WriteROM() can no longer program. This change is significant if you've implemented your own bootloading algorithms using the EZBL_WriteROM() primitive (for example: to make a memory-type bootloader, instead of the existing EZBL_Install2Flash(), EZBL_Install2IP(), or EZBL_InstallFILEIO2Flash() library implementations). To program the EZBL_appBootloadState record to flash, you'll now need to call EZBL_WriteROMEx(), passing 0xDEAD for the extraNoProgRanges parameter. Doing so will override all Bootloader address checking/self-preservation protection, so this function should only be used to program special locations like EZBL_appBootloadState, not general programming operations.
ezbl_comm PC host communications application has been rewritten to directly handle transfer of .bl2 files to UART and I2C bootloaders as a much simpler single threaded process. The project now uses C stdlib file operations (wherever possible) to open/read/write to communications ports, read the .bl2 image file and perform flow control. This code can now be used as reference or potentially be compiled directly for Linux, Mac OS, or embedded SOC platforms. Alternative platforms have not been tested in this release, although execution success was observed when compiled using Cygwin64 + gcc.
The new implementation can be directly used from the command line or other process without needing a Java JRE or the ezbl_tools.jar executable. The ezbl_tools.jar --communicator interface can still be used, but ezbl_tools.jar now acts as a simple wrapper that will launch ezbl_comm.exe, passing the .bl2 file path/communications parameters as command line arguments. Named pipes and multi-stage buffering has been removed, modestly improving communications throughput.
As the communications protocol has not changed, this newer ezbl_comm.exe executable may be used to transfer application .bl2 updates to older EZBL v2.04 based bootloaders. If doing this, be sure to invoke ezbl_comm.exe directly and not use the v2.04 ezbl_tools.jar interface.
Added ezbl_lib.a support for UART5, UART6, and I2C3 peripheral instances on applicable devices. To use any of these peripherals, configure necessary I/O pins/PPS settings and call UART_Reset() and/or I2C_Reset() macros with the first parameter set to the peripheral number.
Added hardware initialization code to control LEDs and buttons in ex_boot_usb_msd USB Host MSD Bootloader projects. These were historically absent, as per the EZBL v2.04 release notes.
Added "usb_msd_fileio_demo/fileio_demo.c" to the ex_app_led_blink example application when using the 'usb_msd' build configuration. The code example demonstrates full application reuse of the USB interrupt, USB Host MSD stack and FILEIO library APIs compiled into the bootloader project without duplicating the flash overhead of the host stack or FILEIO code in the application project. Several FILEIO API symbols are tagged using the EZBL_KeeySYM() macro in ex_boot_usb_msd bootloader projects now to best support the needs of application projects, even though the saved functions are not required by the bootloader.
Added automated support to execute a 3rd linking pass if the bootloader self-awareness table data generated in pass 1 linking resulted in an overall bootloader project that became bigger or smaller by one erase page sized block after pass 2 linking. Historically, this corner case would trigger a build abort error requesting manual rebuild of the bootloader project.
Background processing in EZBL_Install2Flash() and EZBL_Install2IP() will now suppress reading from the communications RX FIFO contents (following activation by receipt of the bootloader wake-up string in the RX ISR) until at least 48 RX bytes are available. This decreases the chance that a false wake up would consume data intended for application code rather than the bootloader in the rare case the 64-bit wake up string appeared in application's data stream.
EZBL_Install2Flash() and EZBL_Install2IP() will now block for up to 1.25ms at bootload termination in order to improve the odds of the termination status code being transmitted by the communications hardware in the event the processor needs to reset as a result of the bootloading operations. Being so short, this delay will likely contribute no noticable performance impact, but improves status reporting robustness when the firmware update request occurs while executing an existing application and not the bootloader.
Extensive changes affecting all components. This version of EZBL shares the same structure, build processes, and general behaviors as EZBL v1.xx bootloaders, but is substantially revised with several device/compiler compatibility issues resolved, bugs fixed, features added, behaviors updated, and capabilities increased. Numerous new 'ezbl_lib.a' APIs and inline macros added to 'ezbl.h'.
New .bl2 "Blob version 2" file format implemented containing bootloader product identification meta-data and application version information. EZBL v2.xx bootloaders will now automatically reject/ignore invalid firmware images before erasing an existing application from flash. Invalid firmware images include ones compiled for different target processors, different product hardware releases, and/or alternate parties’ products that are unrelated to your company but happen to also be implementing an EZBL bootloader. This data is stored as BOOTID_HASH in 'ezbl_boot.mk' files and APPID_VER_[MAJOR/MINOR/BUILD] in 'ezbl_app.mk' files. This .bl2 file format replaces the historical .blob file format and is documented in the "help\EZBL BL2 File Format Specification.pdf" file.
New communications protocol implemented for UART and I2C bootloading. Historically, a few handshake and command characters had to be transmitted to a bootloader before sending a .blob firmware image file. With EZBL v2.xx, the .bl2 firmware image contains all needed information to synchronize/wake-up the bootloader, confirm bootloader applicability and begin the firmware update. The new protocol involves directly sending a .bl2 file to a bootloader. See the "help\EZBL Communications Protocol.pdf" file for detailed protocol information.
ezbl_lib16.a/ezbl_lib16ep.a combined into a single ezbl_lib.a file for all 16-bit targets.
New example projects:
ex_app_live_update_smps_v1, ex_app_live_update_smps_v2 and ex_app_live_update_smps_v3 - SMPS Dual Partition, Live Update projects designed for the MPLAB Starter Kit for Digital Power ("Digital Power Starter Kit" based on dsPIC33EP64GS502).
ex_boot_app_blink_dual_partition - General Bootloader and Application combined example project for Dual Partition capable devices (ex: PIC24FJ1024GB610/GA610, PIC24FJ256GB412/GA412, dsPIC33EP128GS808 families and the dsPIC33EP64GS50x devices). This project implements UART bootloading that only erases/programs the Inactive Partition for ping-pong, non-blocking full replacement of the entire flash image (inclusive of the application and bootloader logic).
ex_boot_usb_msd_v2016_11_07 - USB Host Mass Storage Device ("USB thumb drive") bootloader based on the v2016_11_07 release of the Microchip Libraries for Applications (MLA) USB msd_simple_demo project. At reset, this bootloader searches for a "FIRMWARE.BL2" file in the root folder of a FAT16/FAT32 formatted USB media, and if different from the existing application in flash, will automatically result in application reprogramming. The ex_app_led_blink project has a new "usb_msd" Build Configuration added to build an application demo for testing the USB MSD bootloader.
ex_app_non_ezbl_base - LED blinking application project that contains no association to other EZBL components or a bootloader. This project is used for learning exercises documented in "help\EZBL Hands-on Bootloading Exercises.pdf".
ex_boot_i2c slave bootloader project can now be natively tested using the Explorer 16/32 development board or an external MCP2221A USB to I2C bridge device. The ex_app_led_blink project should be used with the "i2c" Build Configuration selected.
ex_boot_uart_icsp_prog and ex_boot_uart_icsp_prog_to_go projects temporarily removed, pending protocol migration changes. If ICSP based programming is desired, EZBL v1.01b code and MPLAB X IDE v4.00 or earlier should be used for this purpose.
Fixed incompatibilities with newer MPLAB X IDE and XC16 compiler versions. EZBL v1.01 fails to build Bootloader projects with MPLAB X IDE v4.01+. It also would not work with PIC24F devices with EDS (i.e. DSRPAG/DSWPAG PSV access instead of PSVPAG) while compiling with XC16 v1.30+.
Substantially more documentation added/updated. The "help\EZBL Library Documentation.pdf" file contains updates and additions all throughout.
Fixed a bug in ezbl_tools.jar which caused EZBL_FORWARD_MASK_xxx interrupt forwarding flag symbol values to have a 0x100 or 0x200 value offset on them when read back in both the bootloader and application projects. As a result EZBL v1.00 was limited to at most 8 or 9 implemented ISRs in your bootloader project before run-time interrupt forwarding failure would occur. To migrate to this version from v1.00, you must, at minimum, copy the ezbl_tools.jar and all .gld linker scripts from the v1.01 distribution into your bootloader and application projects.
Corrected PIC24FJ1024GB610 family hardware initializer file (hardware_initializer\pic24fj1024gb610_explorer_16.c) PLL and system clock configuration. Previously, the defined FOSCSEL Configuration Word was set to output 48MHz from the PLL and overclock the device. The PLL is now configured for FRC x4 operation for correct 16 MIPS clocking. The PIC24FJ1024GB610 family of targets should now work correctly.
As this is a v1.00 release, there are no new, changed, or migration notes. EZBL is an entirely new software product which is not based on or compatible with AN1094, AN1157, CE417, or any other bootloader that supports PIC24 and dsPIC33 targets.
If you previously used a pre-release copy of EZBL or “Boot HU” (this library’s original name used internally during development), be sure and fully evaluate this EZBL release before committing to transition to it. Although much code will be interchangeable between the pre-releases, certain features may have been removed or redefined.
EZBL supports all PIC32MM devices and essentially all PIC24 and dsPIC33 devices across all product classes. Some exceptions are applicable.
4.2 Targets with Known Issues
Known devices that EZBL v2.11 will have problems or limited usability on:
|
Product Group |
Part Numbers |
Problem |
||
|
PIC24F devices with K-Flash: |
PIC24F04KA200 |
PIC24F04KL100 |
PIC24F08KM101 |
- 4KB and 8KB devices do not have enough
Flash space to be practical for an EZBL bootloader |
PIC24F04KA201 |
PIC24F04KL101 |
PIC24F08KM102 |
||
PIC24F08KA101 |
PIC24F08KL200 |
PIC24F08KM202 |
||
PIC24F08KA102 |
PIC24F08KL201 |
PIC24F08KM204 |
||
PIC24F16KA101 |
PIC24F08KL301 |
PIC24F16KM102 |
||
PIC24F16KA102 |
PIC24F08KL302 |
PIC24F16KM104 |
||
PIC24F16KA301 |
PIC24F08KL401 |
PIC24F16KM202 |
||
PIC24F16KA302 |
PIC24F08KL402 |
PIC24F16KM204 |
||
PIC24F16KA304 |
PIC24F16KL401 |
|
||
PIC24F32KA301 |
PIC24F16KL402 |
|
||
PIC24F32KA302 |
|
|
||
PIC24F32KA304 |
|
|
||
|
PIC24HJXXXGPX06/X08/X10, |
PIC24HJ64GP206 |
dsPIC33FJ64GP206 |
dsPIC33FJ64MC506 |
- Bootloading & ICSP: Errata #32. Module: Device ID
Register workaround not implemented in EZBL. Programming may appear to work,
but due to the chance of the destructive errata event taking place, these
devices must not be used with EZBL. |
PIC24HJ64GP210 |
dsPIC33FJ64GP306 |
dsPIC33FJ64MC508 |
||
PIC24HJ64GP506 |
dsPIC33FJ64GP310 |
dsPIC33FJ64MC510 |
||
PIC24HJ64GP510 |
dsPIC33FJ64GP706 |
dsPIC33FJ64MC706 |
||
PIC24HJ128GP206 |
dsPIC33FJ64GP708 |
dsPIC33FJ64MC710 |
||
PIC24HJ128GP210 |
dsPIC33FJ64GP710 |
dsPIC33FJ128MC506 |
||
PIC24HJ128GP306 |
dsPIC33FJ128GP206 |
dsPIC33FJ128MC510 |
||
PIC24HJ128GP310 |
dsPIC33FJ128GP306 |
dsPIC33FJ128MC706 |
||
PIC24HJ128GP506 |
dsPIC33FJ128GP310 |
dsPIC33FJ128MC708 |
||
PIC24HJ128GP510 |
dsPIC33FJ128GP706 |
dsPIC33FJ128MC710 |
||
PIC24HJ256GP206 |
dsPIC33FJ128GP708 |
dsPIC33FJ256MC510 |
||
PIC24HJ256GP210 |
dsPIC33FJ128GP710 |
dsPIC33FJ256MC710 |
||
PIC24HJ256GP610 |
dsPIC33FJ256GP506 |
|
||
|
dsPIC33FJ256GP510 |
|
||
|
dsPIC33FJ256GP710 |
|
||
4.3 Tested Targets
EZBL v2.11 has been tested with and has out-of-box example hardware initialization code for:
Testing was performed using:
4.4 Other Targets
All other production PIC32MM, PIC24 and dsPIC33 targets not named above are expected to be compatible with EZBL, but may not have been explicitly tested. To create and test a viable bootloader for such devices, two project changes are generally required:
Write appropriate hardware initialization code to set the device’s Configuration words, define the CPU frequency, configure PPS (if present) to gain access to U2TX and U2RX pin functionality and configure one or more GPIO port pins to observe LED blinking. While configuring U2TX, U2RX, and your GPIO pins, any analog functionality that may share the desired pins should be disabled.
Select the target processor in the bootloader (ex_boot_uart/ex_boot_uart_pic32mm) and application (ex_app_led_blink/ex_app_led_blink_pic32mm) project properties.
Note that the default hardware initializer files for the tested PIMs have pre-processor macros that select the same hardware initialization code for devices that are very similar, such as a device in the same device family and differing only by a reduced flash memory and/or RAM size. In such cases, if your hardware communications interface mirrors the Explorer 16/32 + tested PIM or dedicated development board, the bootloader may work without code changes. Simply recompiling the projects with the correct target device selected may be sufficient.
EZBL v2.11 implements a device information database containing the latest information available for all PIC24/dsPIC33 and PIC32MM products available at the time of release and presently matching those also supported by MPLAB X IDE v5.00. Building a bootloader project for any future silicon products will require a newer version of EZBL. Application projects and .bl2 file transfer does not reference or have any dependency on this database.
Microchip provides online support via our web site at http://www.microchip.com. This web site is used as a means to make files and information easily available to customers. The web site contains the following information:
Users of Microchip products can receive assistance through several channels:
Customers should contact their distributor, representative or FAE for support. Local sales offices are also available to help customers. A listing of sales offices and locations is available on our website.
Technical support is available through the web site at: http://support.microchip.com
The Microchip name and logo, the Microchip logo, MPLAB, and PIC are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries.