DFUSec programming API

Document created by jorge_plascencia Employee on Apr 26, 2016Last modified by jorge_plascencia Employee on Apr 27, 2016
Version 3Show Document
  • View in full screen mode

A simple programming API is available that allows custom development of programming algorithms for different memory types such as NOR or NAND FLASH or EEPROM based memory. By mixing programming algorithms and different program images as different steps with the DFUSec tool, a single programming sequence could program all non-volatile memories and memory regions in a single DFUSec programming cycle via USB! This section explains the process of creating a new programming algorithm.

Programming algorithm creation process

A programming algorithm is an executable program that runs on the target hardware and is download via DFUSec to the board using the LPC18xx/43xx's DFU boot capability. Each programming algorithm has unqiue code for handling the memory it will program.

To create a new programming algorithm requires the following steps:

  • Download the DFUSec programming API examples (here). This provides the DFU streaming code that calls the programming API, several reference drivers (emulated IRAM, internal FLASH, SPI FLASH), and several projects to build an executable programming algorithm image. The examples require the LPC18xx CMSIS library attahced below. Although the example builds inside the LPC18xx CMSIS source tree, the generated binaries should executed on the LPC43xx device (as it's using the M3 instruction set) with common peripherals.
  • Write a new driver for the new memory type with the supported API functions
  • Compile the driver with the DFU streaming code to get a programming algorithm executable in binary form
  • Using the DFUSec RAW/HDR mode tab, generate a binary with a header attached to it

Programming API functions

The dfusec_programming_api.h header file contains the function prototypes and shared data structures that must be developed for the DFU streamer code driver. The driver requires one global function that initializes the non-volatile memory interface and device and prepares the data structure that defines the non-volatile's devices memory regions and callback functions. The structure provides five additional functions (via indirect calls) that handle region erase, full erase, program, verify, and address check.Not all of these functions are required to do something.

Programming API - algo_flash_init() function

The first function that needs to be provided is the algo_flash_init() function. This function is called by the DFU streamer to initialize the non-volatile memory device, return the pointer and size of the DFU streaming buffer, and return the FLASH configuration structure and callbacks.The function has the following prototype:/* Initializes device programming capability */
DFUPROG_REGION_T *algo_flash_init(void **buffer, int32_t *buffer_size); style="color:rgb(100, 100, 100);font-family:Arial, sans-serif;font-size:12px"

  • The buffer size must be a multiple of 64 bytes (DFU max packet size)
typedef struct {
    int32_t num_regions; /* Number of program regions on the device */
    /* Buffer should be 32-bit aligned */
    void *buffer;
    /* This must be a minimum of 64 bytes or DFU max packet size and must
       be a factor (1x, 2x, 3x, etc.) of max packets size */
    uint32_t buffer_size;
    const PROGALGOS_T *pprogalgos;
    const DFUPROG_REGZONE_T *pregions; /* Address and region size array */
/* Function pointer types and function array */
typedef int32_t (* progalgo_flash_erase_region) (uint32_t, uint32_t);
typedef int32_t (* progalgo_flash_erase_all) (void);
typedef int32_t (* progalgo_flash_write) (uint32_t, uint32_t);
typedef int32_t (* progalgo_flash_verify) (uint32_t, uint32_t, uint32_t);
typedef int32_t (* progalgo_verify_range) (uint32_t, uint32_t);
typedef struct {
    progalgo_flash_erase_region erase_region;
    progalgo_flash_erase_all    erase_all;
    progalgo_flash_write        write;
    progalgo_flash_verify       verify;
    progalgo_verify_range       vrange;

Shared DFU streamer programming info structure

/* Programming info received from DFUSec for a specific step */
#define DFUPROG_VALIDVAL 0xDB001843
typedef struct {
    int32_t stepnum;         /* Step number, 0 - 9 */
    uint32_t imagesize;      /* Size of image in bytes */
    uint32_t address;        /* Address to start programming of image or start of erase */
    int32_t regionsize;      /* Size of region to erase for 'eraseregion' */
    int32_t eraseregion;     /* Erase region flag, will erase region if !0 */
    int32_t erasefulldevice; /* Erase full device if !0 */
    int32_t parameter;       /* Optional parameter value */
    uint32_t validatetag;    /* Must be value of DFUPROG_VALIDVAL */
extern DFUSEC_PROGINFO_T dfusec_proginfo;

Building the programming algorithm

The currently available pre-configured projects for building the programming algorithms are only available for the Keil uVision4 toolchain. To build the project with your driver, open one of the pre-configured projects and replace the file under the DFUSec_programming_algorithm group with the new driver. Click build to compile and link the image. The final result of the build cycle will be a binary image with a .bin extension.



Adding UART log output support to the programming algorithm

LPC18xx/43xx DFUSec programming API tool
Build date: Jul 19 2012:15:03:24
Initializing USB interface
Initializing DFU
Connecting USB
stepnum         = 0
imagesize       = 4724
address         = 10080000
regionsize      = 00004000
eraseregion     = 0
erasefulldevice = 0
validatetag     = db001843
Program cycle complete

Appending a header to the programming algorithm binary

The final step in preparing the programming algorithm for use with the DFUSec tool is to append a boot header to the binary file generated in the previous step. The DFUSec tool cannot boot the binary directly and requires this header.

To generate the header, run the DFUSec tool and click on the HDR/RAW modes tab. For the binary box, select the .bin file to create the header for.

Then click the "Generate binary file with header" button to generate a new file. A new file will be created in the same directory as the .bin file with the .hdr extension.

This .hdr file is you programming algorithm file that should be used with the Algo box in the Program mode tab with DFUSec.