1.5.5 Bootloader Core Commands

The core of the bootloader resides in the file

mcc_generated_files\boot\boot_process.c 

. The core code in this file is continually called by the user code to poll the communication driver for a command. When the communication driver has received all the data for a command, the bootloader will copy the entire command from the communication driver over to its own working area. It will then parse, validate and execute the command if it's valid. The core code will then return the pass/fail information for the command along with any requested data to the communication adapter which will then forward it to the communication device.

WriteFlash()

Upon reception of the WriteFlash command from the PC Host, the bootloader will take the address and data from the command and it will write the data to flash. Prior to writing, the address of the write command is checked to verify that it will not overwrite the Boot Loader or any reserved space and that it's within the flash address range. If the address is invalid or the programming fails for any reason, the command is terminated and an error response is sent back to the PC Host. No verification of the data is performed.

EraseFlash()

Upon reception of the EraseFlash command from the PC Host, the bootloader will erase the range of flash indicated in the command one page at a time. The address of each page is checked to make sure that it will not overwrite the Boot Loader or any reserved space and that it's within the flash address range and that the address is aligned to a page boundary. If any of these checks fail during the execution of this command, the command is terminated and an error response is sent back to the PC Host.

ReadVersion()

Offset	Description
0,1	Bootloader version
2,3	Max Packet Size - Maximum size of the packet sent between host/device. Includes header, data and any status bits
4,5	Unused
6,7	Device ID
8,9	Unused
10,11	Minimum Erase Size Minimum erase in bytes. Usually the PIC24 Page Size. Actual size depends on the PIC24 device.
12,13	Minimum Write Size Minimum write size in bytes. Usually 4,8 or larger depending on internal flash controller. This is the minimum size of data that can be written at one time. If the device only supports row writes, then this value will be larger. The host must also make sure that any request to write data is aligned on this boundary and is modulus this size. The device firmware does check for this and will not write if the data is not properly aligned and has the correct length.
14,15,16,17	Unused
18,19,20,21	User Reserved Area Start Address User Reserved Area Start Address (Pic24 Address) - Start address of user area protected from over writing by bootloader. To leave un-used set both User Reserved Area fields to 0.
22,23,24,25	User Reserved Area End Address User Reserved Area End Address (Pic24 Address)- End address of user area protected from over writing by bootloader. To leave un-used set both User Reserved Area fields to 0.

GetMemoryAddressRange()

Upon reception of the GetMemoryAddressRange command from the PC Host, the bootloader will return the start and end address of the execution image to the host. The two addresses are returned to the PC host.

bool SelfVerify()

Upon reception of the SelfVerify command, the bootloader will verify the integrity of the download image in flash using the verification method chosen for this bootloader. Upon finishing the verification process, it will return a pass or fail depending on the outcome of the verification process. This command is usually called by the bootloader host to verify the integrity of the newly downloaded code in the download partition specified when the bootloader was configured.

ReadFlash()

Upon Reception of the ReadFlash command from the PC Host, the bootloader will read the number of bytes requested from flash and send the data back to the PC application. The address of the requested data is checked to be within the application area. Reading any address outside of this window is not allowed and an error will be returned.

CalcCheckSum()

Upon reception of the CalcChecksum command from the PC Host, the bootloader will calculate a checksum of the requested address and return the checksum to the PC application. The address of the requested data is checked to be within the application area. Reading any address outside of this window is not allowed and an error will be returned.

ResetDevice()

Upon reception of the ResetDevice command from the PC Host, the bootloader will execute a software reset of the executed device.

ReadFlash()

This command returns the number of bytes requested from flash and sends the data back to the PC application. The address of the requested data is checked to be within the application area. Reading any address outside of this window is not allowed and an error will be returned.

bool BOOT_ImageCopy(enum BOOT_IMAGE destinationImage, enum BOOT_IMAGE sourceImage)

The BOOT_ImageCopy command copies one image to another using the image number of the source and destination. Prior to the actual copy, once the image numbers are validated, the destination memory area is first erased. This function frees the user from having to know the address and size of each image as well as from having to write their own routines calling the flash erase, read and write commands. Upon finishing a pass/fail status will be returned. This command is only available on bootloaders with multiple images enabled.

uint32_t BOOT_ImageAddressGet(enum BOOT_IMAGE image, uint32_t addressInExecutableImage)

The BOOT_ImageAddressGet() command returns the physical address of a location within a specific image on the device. It's often useful to read a specific memory location within a section of code. However, since there could be multiple images on a device, the target image number must also be taken into account. The two parameters are the image number as well as the desired local address. This command is only available on bootloaders with multiple images enabled.