contrib/loaders/flash/cc26xx/flashloader.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2
   3 /******************************************************************************
   4 *
   5 * Copyright (C) 2017-2018 Texas Instruments Incorporated - http://www.ti.com/
   6 *
   7 ******************************************************************************/
   8
   9 #ifndef OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H
  10 #define OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H
  11
  12 #include <stdint.h>
  13 #include <stdbool.h>
  14 #include <string.h>
  15 #include "flash.h"
  16
  17 /* Number of elements in an array */
  18 #define NELEMS(a) (sizeof(a) / sizeof(a[0]))
  19
  20 struct __attribute__((__packed__)) flash_params {
  21         uint32_t dest;     /* Destination address in flash */
  22         uint32_t len;      /* Number of bytes */
  23         uint32_t cmd;      /* Command */
  24         uint32_t full;     /* Handshake signal. Is buffer ready? */
  25         uint32_t buf_addr; /* Address of data buffer. */
  26 };
  27
  28 typedef enum {
  29         CMD_NO_ACTION = 0,                     /* No action, default value */
  30         CMD_ERASE_ALL = 1,                     /* Erase all unprotected sectors */
  31         CMD_PROGRAM = 2,                       /* Program data */
  32         CMD_ERASE_AND_PROGRAM = 3,             /* Erase and program data */
  33         CMD_ERASE_AND_PROGRAM_WITH_RETAIN = 4, /* Erase and program, but retain */
  34                                                                                    /* sector data outside given range */
  35         CMD_ERASE_SECTORS = 5                  /* Erase unprotected sectors */
  36 } flash_commands_t;
  37
  38 typedef enum {
  39         BUFFER_EMPTY = 0x0,      /* No data in buffer, flags last task complete */
  40         BUFFER_FULL = 0xFFFFFFFF /* Buffer has data, flags next task to start */
  41 } flash_handshake_t;
  42
  43 #define STATUS_FLASHLOADER_STATUS_M 0x0000FFFF
  44 #define STATUS_FLASHLOADER_STATUS_S 0
  45 #define STATUS_ROM_CODE_M           0x00FF0000
  46 #define STATUS_ROM_CODE_S           16
  47 #define STATUS_EXT_INFO_M           0xFF000000
  48 #define STATUS_EXT_INFO_S           24
  49
  50 typedef enum {
  51         STATUS_OK = 0,
  52         STATUS_FAILED_ERASE_ALL = 0x101,
  53         STATUS_FAILED_SECTOR_ERASE = 0x102,
  54         STATUS_FAILED_PROGRAM = 0x103,
  55         STATUS_FAILED_INVALID_ARGUMENTS = 0x104,
  56         STATUS_FAILED_UNKNOWN_COMMAND = 0x105,
  57 } flash_status_t;
  58
  59 /* The buffer size used by the flashloader. The size of 1 flash sector. */
  60 #define BUFFER_LEN FLASH_ERASE_SIZE
  61
  62 /*
  63 * This function initializes the flashloader. The application must
  64 * allocate memory for the two data buffers and the flash_params structures.
  65 *
  66 * params Pointer an flash_params array with 2 elements.
  67 * buf1   Pointer to data buffer 1
  68 * buf2   Pointer to data buffer 2
  69 *
  70 * Returns STATUS_OK
  71 *
  72 */
  73 extern uint32_t flashloader_init(struct flash_params *params, uint8_t *buf1,
  74         uint8_t *buf2);
  75
  76 /*
  77 * Erase and program the necessary sectors. Data outside the given
  78 * range will be deleted.
  79 *
  80 * src        Pointer to buffer containing the data.
  81 * address    Start address in device flash
  82 * byte_count The number of bytes to program
  83 *
  84 * Returns STATUS_OK on success. For status on failure:
  85 * See flashloader_program() and flashloader_erase_sectors().
  86 *
  87 */
  88 extern uint32_t flashloader_erase_and_program(uint8_t *src, uint32_t address,
  89         uint32_t byte_count);
  90
  91 /*
  92 * Erase and program the device sectors. Data outside the given
  93 * data range will be kept unchanged.
  94 *
  95 * src        Pointer to buffer containing the data.
  96 * address    Start address in device flash
  97 * byte_count The number of bytes to program
  98 *
  99 * Returns STATUS_OK on success. For status on failure:
 100 * See flashloader_program() and flashloader_erase_sectors().
 101 *
 102 */
 103 extern uint32_t flashloader_program_with_retain(uint8_t *src, uint32_t address,
 104         uint32_t byte_count);
 105
 106 /*
 107 * Erases all flash sectors (that are not write-protected).
 108 *
 109 * Returns STATUS_OK on success.
 110 *
 111 */
 112 extern uint32_t flashloader_erase_all(void);
 113
 114 /*
 115 * Erases the flash sectors affected by the given range.
 116 *
 117 * This function only erases sectors that are not already erased.
 118 *
 119 * start_addr The first address in the range.
 120 * byte_count The number of bytes in the range.
 121 *
 122 * Returns STATUS_OK on success. Returns a combined status on failure:
 123 * [31:24] The sector that failed.
 124 * [23:16] ROM function status code. 0 means success.
 125 * [16: 0] STATUS_FAILED_SECTOR_ERASE
 126 *
 127 */
 128 extern uint32_t flashloader_erase_sectors(uint32_t start_addr,
 129         uint32_t byte_count);
 130
 131 /*
 132 * Program the given range.
 133 *
 134 * This function does not erase anything, it assumes the sectors are ready to
 135 * be programmed.
 136 *
 137 * src        Pointer to buffer containing the data.
 138 * address    Start address in device flash
 139 * byte_count The number of bytes to program
 140 *
 141 * Returns STATUS_OK on success. Returns a combined status value on failure:
 142 * [31:16] ROM function status code. 0 means success.
 143 * [15:0 ] STATUS_FAILED_PROGRAM
 144 *
 145 */
 146 extern uint32_t flashloader_program(uint8_t *src, uint32_t address,
 147         uint32_t byte_count);
 148
 149 /*
 150 * Convert the input address into a sector number.
 151 *
 152 * address The address.
 153 *
 154 * Returns the flash sector which the address resides in. The first sector
 155 * is sector 0.
 156 *
 157 */
 158 static inline uint32_t flashloader_address_to_sector(uint32_t address)
 159         { return (address / FLASH_ERASE_SIZE); };
 160
 161 #endif /* #ifndef OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H */