contrib/loaders/flash/cc26xx/flashloader.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2017-2018 Texas Instruments Incorporated - http://www.ti.com/
   4 *
   5 * Redistribution and use in source and binary forms, with or without
   6 * modification, are permitted provided that the following conditions
   7 * are met:
   8 *
   9 *  Redistributions of source code must retain the above copyright
  10 *  notice, this list of conditions and the following disclaimer.
  11 *
  12 *  Redistributions in binary form must reproduce the above copyright
  13 *  notice, this list of conditions and the following disclaimer in the
  14 *  documentation and/or other materials provided with the
  15 *  distribution.
  16 *
  17 *  Neither the name of Texas Instruments Incorporated nor the names of
  18 *  its contributors may be used to endorse or promote products derived
  19 *  from this software without specific prior written permission.
  20 *
  21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 *
  33 ******************************************************************************/
  34
  35 #ifndef OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H
  36 #define OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H
  37
  38 #include <stdint.h>
  39 #include <stdbool.h>
  40 #include <string.h>
  41 #include "flash.h"
  42
  43 /* Number of elements in an array */
  44 #define NELEMS(a) (sizeof(a) / sizeof(a[0]))
  45
  46 struct __attribute__((__packed__)) flash_params {
  47         uint32_t dest;     /* Destination address in flash */
  48         uint32_t len;      /* Number of bytes */
  49         uint32_t cmd;      /* Command */
  50         uint32_t full;     /* Handshake signal. Is buffer ready? */
  51         uint32_t buf_addr; /* Address of data buffer. */
  52 };
  53
  54 typedef enum {
  55         CMD_NO_ACTION = 0,                     /* No action, default value */
  56         CMD_ERASE_ALL = 1,                     /* Erase all unprotected sectors */
  57         CMD_PROGRAM = 2,                       /* Program data */
  58         CMD_ERASE_AND_PROGRAM = 3,             /* Erase and program data */
  59         CMD_ERASE_AND_PROGRAM_WITH_RETAIN = 4, /* Erase and program, but retain */
  60                                                                                    /* sector data outside given range */
  61         CMD_ERASE_SECTORS = 5                  /* Erase unprotected sectors */
  62 } flash_commands_t;
  63
  64 typedef enum {
  65         BUFFER_EMPTY = 0x0,      /* No data in buffer, flags last task complete */
  66         BUFFER_FULL = 0xFFFFFFFF /* Buffer has data, flags next task to start */
  67 } flash_handshake_t;
  68
  69 #define STATUS_FLASHLOADER_STATUS_M 0x0000FFFF
  70 #define STATUS_FLASHLOADER_STATUS_S 0
  71 #define STATUS_ROM_CODE_M           0x00FF0000
  72 #define STATUS_ROM_CODE_S           16
  73 #define STATUS_EXT_INFO_M           0xFF000000
  74 #define STATUS_EXT_INFO_S           24
  75
  76 typedef enum {
  77         STATUS_OK = 0,
  78         STATUS_FAILED_ERASE_ALL = 0x101,
  79         STATUS_FAILED_SECTOR_ERASE = 0x102,
  80         STATUS_FAILED_PROGRAM = 0x103,
  81         STATUS_FAILED_INVALID_ARGUMENTS = 0x104,
  82         STATUS_FAILED_UNKNOWN_COMMAND = 0x105,
  83 } flash_status_t;
  84
  85 /* The buffer size used by the flashloader. The size of 1 flash sector. */
  86 #define BUFFER_LEN FLASH_ERASE_SIZE
  87
  88 /*
  89 * This function initializes the flashloader. The application must
  90 * allocate memory for the two data buffers and the flash_params structures.
  91 *
  92 * params Pointer an flash_params array with 2 elements.
  93 * buf1   Pointer to data buffer 1
  94 * buf2   Pointer to data buffer 2
  95 *
  96 * Returns STATUS_OK
  97 *
  98 */
  99 extern uint32_t flashloader_init(struct flash_params *params, uint8_t *buf1,
 100         uint8_t *buf2);
 101
 102 /*
 103 * Erase and program the necessary sectors. Data outside the given
 104 * range will be deleted.
 105 *
 106 * src        Pointer to buffer containing the data.
 107 * address    Start address in device flash
 108 * byte_count The number of bytes to program
 109 *
 110 * Returns STATUS_OK on success. For status on failure:
 111 * See flashloader_program() and flashloader_erase_sectors().
 112 *
 113 */
 114 extern uint32_t flashloader_erase_and_program(uint8_t *src, uint32_t address,
 115         uint32_t byte_count);
 116
 117 /*
 118 * Erase and program the device sectors. Data outside the given
 119 * data range will be kept unchanged.
 120 *
 121 * src        Pointer to buffer containing the data.
 122 * address    Start address in device flash
 123 * byte_count The number of bytes to program
 124 *
 125 * Returns STATUS_OK on success. For status on failure:
 126 * See flashloader_program() and flashloader_erase_sectors().
 127 *
 128 */
 129 extern uint32_t flashloader_program_with_retain(uint8_t *src, uint32_t address,
 130         uint32_t byte_count);
 131
 132 /*
 133 * Erases all flash sectors (that are not write-protected).
 134 *
 135 * Returns STATUS_OK on success.
 136 *
 137 */
 138 extern uint32_t flashloader_erase_all(void);
 139
 140 /*
 141 * Erases the flash sectors affected by the given range.
 142 *
 143 * This function only erases sectors that are not already erased.
 144 *
 145 * start_addr The first address in the range.
 146 * byte_count The number of bytes in the range.
 147 *
 148 * Returns STATUS_OK on success. Returns a combined status on failure:
 149 * [31:24] The sector that failed.
 150 * [23:16] ROM function status code. 0 means success.
 151 * [16: 0] STATUS_FAILED_SECTOR_ERASE
 152 *
 153 */
 154 extern uint32_t flashloader_erase_sectors(uint32_t start_addr,
 155         uint32_t byte_count);
 156
 157 /*
 158 * Program the given range.
 159 *
 160 * This function does not erase anything, it assumes the sectors are ready to
 161 * be programmed.
 162 *
 163 * src        Pointer to buffer containing the data.
 164 * address    Start address in device flash
 165 * byte_count The number of bytes to program
 166 *
 167 * Returns STATUS_OK on success. Returns a combined status value on failure:
 168 * [31:16] ROM function status code. 0 means success.
 169 * [15:0 ] STATUS_FAILED_PROGRAM
 170 *
 171 */
 172 extern uint32_t flashloader_program(uint8_t *src, uint32_t address,
 173         uint32_t byte_count);
 174
 175 /*
 176 * Convert the input address into a sector number.
 177 *
 178 * address The address.
 179 *
 180 * Returns the flash sector which the address resides in. The first sector
 181 * is sector 0.
 182 *
 183 */
 184 static inline uint32_t flashloader_address_to_sector(uint32_t address)
 185         { return (address / FLASH_ERASE_SIZE); };
 186
 187 #endif /* #ifndef OPENOCD_LOADERS_FLASH_CC26XX_FLASHLOADER_H */