contrib/loaders/flash/cc26xx/flash.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2016-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_FLASH_H
  36 #define OPENOCD_LOADERS_FLASH_CC26XX_FLASH_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #endif
  42
  43 #include <stdint.h>
  44 #include <stdbool.h>
  45 #include "hw_regs.h"
  46
  47 /* Location of flash in memory map */
  48 #define FLASHMEM_BASE 0
  49
  50 /* Defines to access flash API calls in ROM */
  51 #define ROM_API_TABLE       ((uint32_t *) 0x10000180)
  52 #define ROM_VERSION         (ROM_API_TABLE[0])
  53 #define ROM_API_FLASH_TABLE ((uint32_t *) (ROM_API_TABLE[10]))
  54
  55 #if defined(DEVICE_CC26X2)
  56
  57 /* Agama (CC26x2) specific definitions */
  58
  59 #define FLASH_ERASE_SIZE       8192
  60 /* Agama (and Agama 1M) has a maximum of 132 flash sectors (1056KB / 8KB) */
  61 #define FLASH_MAX_SECTOR_COUNT 132
  62 #define FLASH_SECTOR_BASE_M    0xFFFFE000
  63
  64 /* Bootloader Configuration */
  65 #define CCFG_O_BL_CONFIG 0x00001FD8
  66
  67 #elif defined(DEVICE_CC26X0)
  68
  69 /* Chameleon (CC26x0) specific definitions */
  70
  71 #define FLASH_ERASE_SIZE       4096
  72 /* Chameleon has a maximum of 32 flash sectors (128KB / 4KB) */
  73 #define FLASH_MAX_SECTOR_COUNT 32
  74 #define FLASH_SECTOR_BASE_M    0xFFFFF000
  75
  76 /* Bootloader Configuration */
  77 #define CCFG_O_BL_CONFIG 0x00000FD8
  78
  79 #else
  80 #error No DEVICE defined.
  81 #endif
  82
  83 /******************************************************************************
  84 *
  85 * Values that can be returned from the API functions
  86 *
  87 ******************************************************************************/
  88 #define FAPI_STATUS_SUCCESS   0x00000000 /* Function completed successfully */
  89 #define FAPI_STATUS_FSM_BUSY  0x00000001 /* FSM is Busy */
  90 #define FAPI_STATUS_FSM_READY 0x00000002 /* FSM is Ready */
  91 #define FAPI_STATUS_INCORRECT_DATABUFFER_LENGTH \
  92                                                           0x00000003 /* Incorrect parameter value */
  93 #define FAPI_STATUS_FSM_ERROR 0x00000004 /* Operation failed */
  94
  95 /******************************************************************************
  96 *
  97 * Define used by the flash programming and erase functions
  98 *
  99 ******************************************************************************/
 100 #define ADDR_OFFSET (0x1F800000 - FLASHMEM_BASE)
 101
 102 /******************************************************************************
 103 *
 104 * Define used for access to factory configuration area.
 105 *
 106 ******************************************************************************/
 107 #define FCFG1_OFFSET 0x1000
 108
 109 /******************************************************************************
 110 *
 111 * Define for the clock frequencey input to the flash module in number of MHz
 112 *
 113 ******************************************************************************/
 114 #define FLASH_MODULE_CLK_FREQ 48
 115
 116 /******************************************************************************
 117 *
 118 * Defined values for Flash State Machine commands
 119 *
 120 ******************************************************************************/
 121 typedef enum {
 122         FAPI_PROGRAM_DATA    = 0x0002, /* Program data. */
 123         FAPI_ERASE_SECTOR    = 0x0006, /* Erase sector. */
 124         FAPI_ERASE_BANK      = 0x0008, /* Erase bank. */
 125         FAPI_VALIDATE_SECTOR = 0x000E, /* Validate sector. */
 126         FAPI_CLEAR_STATUS    = 0x0010, /* Clear status. */
 127         FAPI_PROGRAM_RESUME  = 0x0014, /* Program resume. */
 128         FAPI_ERASE_RESUME    = 0x0016, /* Erase resume. */
 129         FAPI_CLEAR_MORE      = 0x0018, /* Clear more. */
 130         FAPI_PROGRAM_SECTOR  = 0x0020, /* Program sector. */
 131         FAPI_ERASE_OTP       = 0x0030  /* Erase OTP. */
 132 } flash_state_command_t;
 133
 134 /******************************************************************************
 135 *
 136 * Defines for values written to the FLASH_O_FSM_WR_ENA register
 137 *
 138 ******************************************************************************/
 139 #define FSM_REG_WRT_ENABLE  5
 140 #define FSM_REG_WRT_DISABLE 2
 141
 142 /******************************************************************************
 143 *
 144 * Defines for the bank power mode field the FLASH_O_FBFALLBACK register
 145 *
 146 ******************************************************************************/
 147 #define FBFALLBACK_SLEEP      0
 148 #define FBFALLBACK_DEEP_STDBY 1
 149 #define FBFALLBACK_ACTIVE     3
 150
 151 /******************************************************************************
 152 *
 153 * Defines for the bank grace period and pump grace period
 154 *
 155 ******************************************************************************/
 156 #define FLASH_BAGP 0x14
 157 #define FLASH_PAGP 0x14
 158
 159 /******************************************************************************
 160 *
 161 * Defines for the FW flag bits in the FLASH_O_FWFLAG register
 162 *
 163 ******************************************************************************/
 164 #define FW_WRT_TRIMMED 0x00000001
 165
 166 /******************************************************************************
 167 *
 168 * Defines used by the flash programming functions
 169 *
 170 ******************************************************************************/
 171 typedef volatile uint8_t fwp_write_byte;
 172 #define FWPWRITE_BYTE_ADDRESS \
 173         ((fwp_write_byte *)((FLASH_BASE + FLASH_O_FWPWRITE0)))
 174
 175 /******************************************************************************
 176 *
 177 * Define for FSM command execution
 178 *
 179 ******************************************************************************/
 180 #define FLASH_CMD_EXEC 0x15
 181
 182 /******************************************************************************
 183 *
 184 * Get size of a flash sector in number of bytes.
 185 *
 186 * This function will return the size of a flash sector in number of bytes.
 187 *
 188 * Returns size of a flash sector in number of bytes.
 189 *
 190 ******************************************************************************/
 191 static inline uint32_t flash_sector_size_get(void)
 192 {
 193         uint32_t sector_size_in_kbyte;
 194
 195         sector_size_in_kbyte = (HWREG(FLASH_BASE + FLASH_O_FCFG_B0_SSIZE0) &
 196                 FLASH_FCFG_B0_SSIZE0_B0_SECT_SIZE_M) >>
 197                 FLASH_FCFG_B0_SSIZE0_B0_SECT_SIZE_S;
 198
 199         /* Return flash sector size in number of bytes. */
 200         return sector_size_in_kbyte * 1024;
 201 }
 202
 203 /******************************************************************************
 204 *
 205 * Get the size of the flash.
 206 *
 207 * This function returns the size of the flash main bank in number of bytes.
 208 *
 209 * Returns the flash size in number of bytes.
 210 *
 211 ******************************************************************************/
 212 static inline uint32_t flash_size_get(void)
 213 {
 214         uint32_t num_of_sectors;
 215
 216         /* Get number of flash sectors */
 217         num_of_sectors = (HWREG(FLASH_BASE + FLASH_O_FLASH_SIZE) &
 218                                                 FLASH_FLASH_SIZE_SECTORS_M) >>
 219                                                 FLASH_FLASH_SIZE_SECTORS_S;
 220
 221         /* Return flash size in number of bytes */
 222         return num_of_sectors * flash_sector_size_get();
 223 }
 224
 225 /******************************************************************************
 226 *
 227 * Checks if the Flash state machine has detected an error.
 228 *
 229 * This function returns the status of the Flash State Machine indicating if
 230 * an error is detected or not. Primary use is to check if an Erase or
 231 * Program operation has failed.
 232 *
 233 * Please note that code can not execute in flash while any part of the flash
 234 * is being programmed or erased. This function must be called from ROM or
 235 * SRAM while any part of the flash is being programmed or erased.
 236 *
 237 * Returns status of Flash state machine:
 238 * FAPI_STATUS_FSM_ERROR
 239 * FAPI_STATUS_SUCCESS
 240 *
 241 ******************************************************************************/
 242 static inline uint32_t flash_check_fsm_for_error(void)
 243 {
 244         if (HWREG(FLASH_BASE + FLASH_O_FMSTAT) & FLASH_FMSTAT_CSTAT)
 245                 return FAPI_STATUS_FSM_ERROR;
 246         else
 247                 return FAPI_STATUS_SUCCESS;
 248 }
 249
 250 /******************************************************************************
 251 *
 252 * Checks if the Flash state machine is ready.
 253 *
 254 * This function returns the status of the Flash State Machine indicating if
 255 * it is ready to accept a new command or not. Primary use is to check if an
 256 * Erase or Program operation has finished.
 257 *
 258 * Please note that code can not execute in flash while any part of the flash
 259 * is being programmed or erased. This function must be called from ROM or
 260 * SRAM while any part of the flash is being programmed or erased.
 261 *
 262 * Returns readiness status of Flash state machine:
 263 * FAPI_STATUS_FSM_READY
 264 * FAPI_STATUS_FSM_BUSY
 265 *
 266 ******************************************************************************/
 267 static inline uint32_t flash_check_fsm_for_ready(void)
 268 {
 269         if (HWREG(FLASH_BASE + FLASH_O_STAT) & FLASH_STAT_BUSY)
 270                 return FAPI_STATUS_FSM_BUSY;
 271         else
 272                 return FAPI_STATUS_FSM_READY;
 273 }
 274
 275 /******************************************************************************
 276 *
 277 * Erase a flash sector.
 278 *
 279 * This function will erase the specified flash sector. The function will
 280 * not return until the flash sector has been erased or an error condition
 281 * occurred. If flash top sector is erased the function will program the
 282 * the device security data bytes with default values. The device security
 283 * data located in the customer configuration area of the flash top sector,
 284 * must have valid values at all times. These values affect the configuration
 285 * of the device during boot.
 286 *
 287 * Please note that code can not execute in flash while any part of the flash
 288 * is being programmed or erased. This function must only be executed from ROM
 289 * or SRAM.
 290 *
 291 * sector_address is the starting address in flash of the sector to be
 292 * erased.
 293 *
 294 * Returns the status of the sector erase:
 295 * FAPI_STATUS_SUCCESS                     : Success.
 296 * FAPI_STATUS_INCORRECT_DATABUFFER_LENGTH : Invalid argument.
 297 * FAPI_STATUS_FSM_ERROR                   : Programming error was encountered.
 298 *
 299 ******************************************************************************/
 300 extern uint32_t flash_sector_erase(uint32_t sector_address);
 301
 302 /******************************************************************************
 303 *
 304 * Erase all unprotected sectors in the flash main bank.
 305 *
 306 * This function will erase all unprotected flash sectors. The function will
 307 * not return until the flash sectors has been erased or an error condition
 308 * occurred. Since the flash top sector is erased the function will program the
 309 * the device security data bytes with default values. The device security
 310 * data located in the customer configuration area of the flash top sector,
 311 * must have valid values at all times. These values affect the configuration
 312 * of the device during boot. The execution time of the operation increases if
 313 * erase precondition is forced. This will cause the flash module to first
 314 * program all 1 bits in the bank to 0 before the actual erase is started.
 315 *
 316 * force_precondition controls if erase precondition should be forced.
 317 *
 318 * Returns the status of the sector erase:
 319 * FAPI_STATUS_SUCCESS   : Success
 320 * FAPI_STATUS_FSM_ERROR : Erase error was encountered.
 321 *
 322 ******************************************************************************/
 323 extern uint32_t flash_bank_erase(bool force_precondition);
 324
 325 /******************************************************************************
 326 *
 327 * Programs unprotected main bank flash sectors.
 328 *
 329 * This function will program a sequence of bytes into the on-chip flash.
 330 * Programming each location consists of the result of an AND operation
 331 * of the new data and the existing data; in other words bits that contain
 332 * 1 can remain 1 or be changed to 0, but bits that are 0 cannot be changed
 333 * to 1.  Therefore, a byte can be programmed multiple times as long as these
 334 * rules are followed; if a program operation attempts to change a 0 bit to
 335 * a 1 bit, that bit will not have its value changed.
 336 *
 337 * This function will not return until the data has been programmed or an
 338 * programming error has occurred.
 339 *
 340 * Please note that code can not execute in flash while any part of the flash
 341 * is being programmed or erased. This function must only be executed from ROM
 342 * or SRAM.
 343 *
 344 * The data_buffer pointer cannot point to flash.
 345 *
 346 * data_buffer is a pointer to the data to be programmed.
 347 * address is the starting address in flash to be programmed.
 348 * count is the number of bytes to be programmed.
 349 *
 350 * Returns status of the flash programming:
 351 * FAPI_STATUS_SUCCESS                     : Success.
 352 * FAPI_STATUS_INCORRECT_DATABUFFER_LENGTH : Too many bytes were requested.
 353 * FAPI_STATUS_FSM_ERROR                   : Programming error was encountered.
 354 *
 355 ******************************************************************************/
 356 extern uint32_t flash_program(uint8_t *data_buffer, uint32_t address,
 357         uint32_t count);
 358
 359 /******************************************************************************
 360 *
 361 * Disables all sectors for erase and programming on the active bank.
 362 *
 363 * This function disables all sectors for erase and programming on the active
 364 * bank and enables the Idle Reading Power reduction mode if no low power
 365 * mode is configured. Furthermore, an additional level of protection from
 366 * erase is enabled.
 367 *
 368 * Please note that code can not execute in flash while any part of the flash
 369 * is being programmed or erased.
 370 *
 371 ******************************************************************************/
 372 extern void flash_disable_sectors_for_write(void);
 373
 374 #ifdef __cplusplus
 375 }
 376 #endif
 377
 378 #endif /* #ifndef OPENOCD_LOADERS_FLASH_CC26XX_FLASH_H */