Troubleshooting Guide for PSoC® 3/PSoC 4/ PSoC 5LP Bootloader Designs - KBA210593

Version: **



This guide discusses troubleshooting steps for common issues that can occur in your bootloader designs based on PSoC 3/ PSoC 4/ PSoC 5LP devices. If you are new to bootloaders in PSoC 3/ PSoC 4/ PSoC 5LP, get started with AN73854 - PSoC® 3, PSoC 4, and PSoC 5LP Introduction to Bootloaders.


A typical bootloader design based on PSoC 3/ PSoC 4/ PSoC 5LP looks similar to Figure 1 or Figure 2:


Figure 1: Bootloading from a Host Controller


Bootloading from a MacPC.PNG


Figure 2: Bootloading from a Mac/PC


The flow chart in Figure 3 shows the procedure to troubleshoot simple bootloader issues. The scope of this flow chart is limited to the designs using PSoC Creator Bootloader/Bootloadable Component and /or PSoC Creator Bootloader Host.




Figure 3: Flow Chart for Bootloader Troubleshooting




  1. The bootloader project is consuming more flash, which is restricting the maximum allowable size of the bootloadable project. In addition, Memory Overflow errors are reported during build. How can the bootloader project flash consumption be reduced?  
    • Disable the commands that are not used in the set of Optional Commands in the Bootloader Component (see Figure 4) if the bootloader host does not use these. This would help in reducing the bootloader flash size. However, note that the following commands are required by the PSoC Creator Bootloader Host tool:      
      • Get flash size
      • Send data
      • Get row checksum

        Figure 4: Bootloader Optional Commands

    • Ensure that Device Configuration Mode under the System tab in the .cydwr file is set to Compressed as shown in Figure 5.

      Figure 5: Device Configuration Mode

  2. UART bootloading fails while trying to bootload large .cyacd files. How can this situation be avoided?
      This could be mainly because of the implementation with the custom bootloader host.  
    • Try reducing the UART baud rate. Issues are very rarely observed for baud rates up to 57600 bps.
    • Ensure that the host baud rate matches with that of the UART bootloader.
    • Follow the guidelines in AN68272 as a starting point on how to implement the host in custom bootloader host applications.
  3. In an application that needs to enter the bootloader on every reset and needs to wait for a certain duration, the target device doesn’t appear or appears only for a short duration and then disappears in the bootloader host tool. How do I fix this?
      Check the Wait for command time option in the Bootloader Component as shown in Figure 6 and specify the wait time.

    Figure 6: Wait for Command in Bootloader

  4. Errors are reported while building the Fixed Stack Shared Memory OTA Bootloadable example projects even after pointing to the correct hex file of the Bootloader Component. Why is it so?
      The example projects are designed in such a way that the linker script files are generated by running the application mk.bat file, which is provided along with the projects. Ensure that you make the necessary edits as listed in the PSoC Creator example project documentation (mainly adding the correct names of the bootloader and bootloadable project in the mk.bat file) and run the mk.bat file.
  5. Why doesn’t the bootloadable application start on subsequent resets?
      This is because of the code getting stuck in bootloader due to a bootloadable checksum failure. The bootloadable project’s checksum value, which is stored in the metadata section of the bootloadable section, will not be modified when the flash content of the bootloadable project is modified. Therefore, the checksum fails the next time PSoC gets through a reset.
      There are two scenarios that could cause the checksum failure.  
    • Using APIs that change the value of flash variables that are part.
    • When using the Emulated EEPROM Component in the bootloadable project.
          To work around this, select the Fast Application Verification option in the bootloadable project as shown in Figure 7. When this parameter is enabled, the bootloader calculates the flash checksum only once when the new bootloadable code (application code) is downloaded. Then, one nonvolatile flag is set to indicate that the checksum matches and the bootloader does not compute the checksum on further resets. The drawback is that it compromises the security and the validity of a new application.

      Figure 7: Bootloadable Fast Application Validation

          Another workaround is to use the new option available with the latest Bootloadable Component – Checksum exclude section (bytes) as shown in Figure 8. When this option is enabled, a section with the name “cy_checksum_exclude” is added in the cm3gcc.ld linker script file of the bootloadable project with the size equal to the value set in the Component. Now, you can point the flash variables or the Emulated EEPROM data to this section using the method explained in AN89610.
          Bootloadable Checksum Exclude Section_0.png 

      Figure 8: Bootloadable Checksum Exclude Section

  6. Why doesn’t the bootloaded application start even if bootloading was successful when a custom bootloader (not the Cypress-provided Bootloader Component) is used?
      This can happen if the flash is not written with the correct data given in the .cyacd file. In that case, do the following:  
    • Read back the whole flash using PSoC Programmer. Check if the bootloadable section of flash has the same data bytes as in the .cyacd file.
    • If a few bytes in certain rows of the flash contain wrong data, check the Flash Write APIs in bootloader and verify whether the API parameters are set correctly.
    • If the Flash Write APIs are correct, the stale data in cache could be corrupting the flash during SPC writes. Use the CyFlushCache () API immediately after CyWriteRow () in bootloader or disable instruction cache under Systems in the cydwr file of the bootloader project to avoid flash corruption.
  7. Communication failure while bootloading.
      If the host-target communication fails while bootloading, capture a log of the packet transactions in the channel during bootloading using a protocol analyzer. The status/error codes in the response packets from the bootloader indicate the reason for failure. Refer to the ‘Error codes’ section of Bootloader Component datasheet for various error codes.


Bootloader and Bootloadable
AN73854 - PSoC® 3, PSoC 4, and PSoC 5LP Introduction to Bootloaders
AN84401 PSoC 3 and PSoC 5LP SPI Bootloader
AN60317 - PSoC® 3 and PSoC 5LP I2C Bootloader
AN73503 - USB HID Bootloader for PSoC 3 and PSoC 5LP
AN86526 - PSoC® 4 I2C Bootloader