OpenOCD
nor/core.h File Reference

Upper level NOR flash interfaces. More...

Include dependency graph for nor/core.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  flash_bank
 Provides details of a flash bank, available either on-chip or through a major interface. More...
 
struct  flash_sector
 Describes the geometry and status of a single flash sector within a flash bank. More...
 

Macros

#define FLASH_WRITE_ALIGN_SECTOR   UINT32_MAX
 Special value for write_start_alignment and write_end_alignment field. More...
 
#define FLASH_WRITE_CONTINUOUS   0
 Special values for minimal_write_gap field. More...
 
#define FLASH_WRITE_GAP_SECTOR   UINT32_MAX
 

Functions

struct flash_sectoralloc_block_array (uint32_t offset, uint32_t size, unsigned int num_blocks)
 Allocate and fill an array of sectors or protection blocks. More...
 
 COMMAND_HELPER (flash_command_get_bank, unsigned name_index, struct flash_bank **bank)
 Retrieves bank from a command argument, reporting errors parsing the bank identifier or retrieving the specified bank. More...
 
int default_flash_blank_check (struct flash_bank *bank)
 Provides default erased-bank check handling. More...
 
void default_flash_free_driver_priv (struct flash_bank *bank)
 Deallocates bank->driver_priv. More...
 
int default_flash_read (struct flash_bank *bank, uint8_t *buffer, uint32_t offset, uint32_t count)
 Provides default read implementation for flash memory. More...
 
int default_flash_verify (struct flash_bank *bank, const uint8_t *buffer, uint32_t offset, uint32_t count)
 Provides default verify implementation for flash memory. More...
 
int flash_erase_address_range (struct target *target, bool pad, target_addr_t addr, uint32_t length)
 Erases length bytes in the target flash, starting at addr. More...
 
void flash_free_all_banks (void)
 Deallocates all flash banks. More...
 
unsigned int flash_get_bank_count (void)
 
int flash_register_commands (struct command_context *cmd_ctx)
 Registers the 'flash' subsystem commands. More...
 
void flash_set_dirty (void)
 Forces targets to re-examine their erase/protection state. More...
 
int flash_unlock_address_range (struct target *target, target_addr_t addr, uint32_t length)
 
int flash_write (struct target *target, struct image *image, uint32_t *written, bool erase)
 Writes image into the target flash. More...
 
target_addr_t flash_write_align_end (struct flash_bank *bank, target_addr_t addr)
 Align end address of a flash write region according to bank requirements. More...
 
target_addr_t flash_write_align_start (struct flash_bank *bank, target_addr_t addr)
 Align start address of a flash write region according to bank requirements. More...
 
int get_flash_bank_by_addr (struct target *target, target_addr_t addr, bool check, struct flash_bank **result_bank)
 Returns the flash bank located at a specified address. More...
 
int get_flash_bank_by_name (const char *name, struct flash_bank **bank_result)
 Returns the flash bank specified by name, which matches the driver name and a suffix (option) specify the driver-specific bank number. More...
 
struct flash_bankget_flash_bank_by_name_noprobe (const char *name)
 Returns the flash bank specified by name, which matches the driver name and a suffix (option) specify the driver-specific bank number. More...
 
int get_flash_bank_by_num (unsigned int num, struct flash_bank **bank)
 Returns the flash bank like get_flash_bank_by_name(), without probing. More...
 
struct flash_bankget_flash_bank_by_num_noprobe (unsigned int num)
 Returns the flash bank like get_flash_bank_by_num(), without probing. More...
 

Detailed Description

Upper level NOR flash interfaces.

Definition in file nor/core.h.

Macro Definition Documentation

◆ FLASH_WRITE_ALIGN_SECTOR

#define FLASH_WRITE_ALIGN_SECTOR   UINT32_MAX

Special value for write_start_alignment and write_end_alignment field.

Definition at line 59 of file nor/core.h.

◆ FLASH_WRITE_CONTINUOUS

#define FLASH_WRITE_CONTINUOUS   0

Special values for minimal_write_gap field.

Definition at line 62 of file nor/core.h.

◆ FLASH_WRITE_GAP_SECTOR

#define FLASH_WRITE_GAP_SECTOR   UINT32_MAX

Definition at line 63 of file nor/core.h.

Function Documentation

◆ alloc_block_array()

struct flash_sector* alloc_block_array ( uint32_t  offset,
uint32_t  size,
unsigned int  num_blocks 
)

Allocate and fill an array of sectors or protection blocks.

Parameters
offsetOffset of first block.
sizeSize of each block.
num_blocksNumber of blocks in array.
Returns
A struct flash_sector pointer or NULL when allocation failed.

Definition at line 1002 of file flash/nor/core.c.

References flash_sector::is_erased, flash_sector::is_protected, NULL, flash_sector::offset, offset, flash_sector::size, and size.

Referenced by esirisc_flash_probe(), FLASH_BANK_COMMAND_HANDLER(), kinetis_probe(), nrf5_probe(), psoc4_probe(), rp2040_flash_probe(), rsl10_probe(), samd_probe(), same5_probe(), stm32l4_probe(), and stm32x_probe().

◆ COMMAND_HELPER()

COMMAND_HELPER ( flash_command_get_bank  ,
unsigned  name_index,
struct flash_bank **  bank 
)

Retrieves bank from a command argument, reporting errors parsing the bank identifier or retrieving the specified bank.

The bank may be identified by its bank number or by name.instance, where instance is driver-specific.

Parameters
name_indexThe index to the string in args containing the bank identifier.
bankOn output, contains a pointer to the bank or NULL.
Returns
ERROR_OK on success, or an error indicating the problem.

Definition at line 51 of file flash/nor/tcl.c.

References bank, and CALL_COMMAND_HANDLER.

◆ default_flash_blank_check()

int default_flash_blank_check ( struct flash_bank bank)

Provides default erased-bank check handling.

Checks to see if the flash driver knows they are erased; if things look uncertain, this routine will call default_flash_mem_blank_check() to confirm.

Returns
ERROR_OK if successful; otherwise, an error code.

Definition at line 380 of file flash/nor/core.c.

References target_memory_check_block::address, bank, default_flash_mem_blank_check(), ERROR_NOT_IMPLEMENTED, ERROR_OK, ERROR_TARGET_NOT_HALTED, LOG_ERROR, LOG_USER, target_memory_check_block::result, target_memory_check_block::size, target_blank_check_memory(), and TARGET_HALTED.

Referenced by at91sam7_erase_check(), and nrf5_erase_page().

◆ default_flash_free_driver_priv()

void default_flash_free_driver_priv ( struct flash_bank bank)

Deallocates bank->driver_priv.

Definition at line 210 of file flash/nor/core.c.

References bank, and NULL.

◆ default_flash_read()

int default_flash_read ( struct flash_bank bank,
uint8_t *  buffer,
uint32_t  offset,
uint32_t  count 
)

Provides default read implementation for flash memory.

Parameters
bankThe bank to read.
bufferThe data bytes read.
offsetThe offset into the chip to read.
countThe number of bytes to read.
Returns
ERROR_OK if successful; otherwise, an error code.

Definition at line 121 of file flash/nor/core.c.

References bank, buffer, count, offset, and target_read_buffer().

Referenced by mdr_read().

◆ default_flash_verify()

int default_flash_verify ( struct flash_bank bank,
const uint8_t *  buffer,
uint32_t  offset,
uint32_t  count 
)

Provides default verify implementation for flash memory.

Parameters
bankThe bank to verify.
bufferThe data bytes to verify.
offsetThe offset into the chip to verify.
countThe number of bytes to verify.
Returns
ERROR_OK if successful; otherwise, an error code.

Definition at line 142 of file flash/nor/core.c.

References bank, buffer, count, ERROR_FAIL, ERROR_OK, image_calculate_checksum(), LOG_DEBUG, offset, TARGET_ADDR_FMT, and target_checksum_memory().

Referenced by flash_driver_verify().

◆ flash_erase_address_range()

int flash_erase_address_range ( struct target target,
bool  pad,
target_addr_t  addr,
uint32_t  length 
)

Erases length bytes in the target flash, starting at addr.

The range addr to addr + length - 1 must be strictly sector aligned, unless pad is true. Setting pad true extends the range, at beginning and/or end, if needed for sector alignment.

Returns
ERROR_OK if successful; otherwise, an error code.

Definition at line 613 of file flash/nor/core.c.

References addr, flash_driver_erase(), flash_iterate_address_range(), length, and NULL.

Referenced by COMMAND_HANDLER(), flash_write_unlock_verify(), and gdb_v_packet().

◆ flash_free_all_banks()

void flash_free_all_banks ( void  )

Deallocates all flash banks.

Definition at line 216 of file flash/nor/core.c.

References bank, flash_banks, LOG_WARNING, flash_bank::next, and NULL.

Referenced by openocd_main().

◆ flash_get_bank_count()

unsigned int flash_get_bank_count ( void  )
Returns
The number of flash banks currently defined.

Definition at line 201 of file flash/nor/core.c.

References flash_banks, and flash_bank::next.

Referenced by gdb_memory_map(), gdb_new_connection(), and gdb_query_packet().

◆ flash_register_commands()

int flash_register_commands ( struct command_context cmd_ctx)

Registers the 'flash' subsystem commands.

Definition at line 1423 of file flash/nor/tcl.c.

References flash_command_handlers, NULL, and register_commands().

Referenced by setup_command_handler().

◆ flash_set_dirty()

void flash_set_dirty ( void  )

Forces targets to re-examine their erase/protection state.

This routine must be called when the system may modify the status.

Definition at line 1046 of file flash/nor/tcl.c.

References flash_bank_list(), flash_sector::is_erased, flash_bank::next, flash_bank::num_sectors, and flash_bank::sectors.

Referenced by COMMAND_HANDLER(), flash_write_unlock_verify(), and gdb_v_packet().

◆ flash_unlock_address_range()

int flash_unlock_address_range ( struct target target,
target_addr_t  addr,
uint32_t  length 
)

◆ flash_write()

int flash_write ( struct target target,
struct image image,
uint32_t *  written,
bool  erase 
)

Writes image into the target flash.

The written parameter will contain the

Parameters
targetThe target with the flash to be programmed.
imageThe image that will be programmed to flash.
writtenOn return, contains the number of bytes written.
eraseIndicates whether the flash driver should first erase the corresponding banks or sectors before programming.
Returns
ERROR_OK if successful; otherwise, an error code.

Definition at line 996 of file flash/nor/core.c.

References flash_write_unlock_verify().

Referenced by gdb_v_packet().

◆ flash_write_align_end()

target_addr_t flash_write_align_end ( struct flash_bank bank,
target_addr_t  addr 
)

Align end address of a flash write region according to bank requirements.

Note: Use address of the last byte to write, not the next after the region.

Parameters
bankPointer to bank descriptor structure
addrAddress to align (address of the last byte to write)
Returns
Aligned address (address of the last byte of padded region)

Align end address of a flash write region according to bank requirements.

Definition at line 678 of file flash/nor/core.c.

References addr, bank, FLASH_WRITE_ALIGN_SECTOR, and offset.

Referenced by COMMAND_HANDLER(), flash_write_check_gap(), and flash_write_unlock_verify().

◆ flash_write_align_start()

target_addr_t flash_write_align_start ( struct flash_bank bank,
target_addr_t  addr 
)

Align start address of a flash write region according to bank requirements.

Parameters
bankPointer to bank descriptor structure
addrAddress to align
Returns
Aligned address

Align start address of a flash write region according to bank requirements.

Definition at line 654 of file flash/nor/core.c.

References addr, bank, FLASH_WRITE_ALIGN_SECTOR, and offset.

Referenced by COMMAND_HANDLER(), flash_write_check_gap(), and flash_write_unlock_verify().

◆ get_flash_bank_by_addr()

int get_flash_bank_by_addr ( struct target target,
target_addr_t  addr,
bool  check,
struct flash_bank **  result_bank 
)

Returns the flash bank located at a specified address.

Parameters
targetThe target, presumed to contain one or more banks.
addrAn address that is within the range of the bank.
checkreturn ERROR_OK and result_bank NULL if the bank does not exist
result_bankThe struct flash_bank located at addr, or NULL.
Returns
ERROR_OK on success, or an error indicating the problem.

Definition at line 300 of file flash/nor/core.c.

References addr, flash_driver::auto_probe, flash_bank::base, flash_bank::driver, ERROR_FAIL, ERROR_OK, flash_banks, LOG_ERROR, flash_bank::next, NULL, flash_bank::size, flash_bank::target, and TARGET_ADDR_FMT.

Referenced by COMMAND_HANDLER(), flash_iterate_address_range(), flash_iterate_address_range_inner(), and flash_write_unlock_verify().

◆ get_flash_bank_by_name()

int get_flash_bank_by_name ( const char *  name,
struct flash_bank **  bank_result 
)

Returns the flash bank specified by name, which matches the driver name and a suffix (option) specify the driver-specific bank number.

The suffix consists of the '.' and the driver-specific bank number: when two str9x banks are defined, then 'str9x.1' refers to the second.

Definition at line 261 of file flash/nor/core.c.

References bank, ERROR_OK, get_flash_bank_by_name_noprobe(), LOG_ERROR, and name.

Referenced by COMMAND_HELPER().

◆ get_flash_bank_by_name_noprobe()

struct flash_bank* get_flash_bank_by_name_noprobe ( const char *  name)

Returns the flash bank specified by name, which matches the driver name and a suffix (option) specify the driver-specific bank number.

The suffix consists of the '.' and the driver-specific bank number: when two str9x banks are defined, then 'str9x.1' refers to the second.

Definition at line 243 of file flash/nor/core.c.

References bank, flash_banks, flash_driver_name_matches(), get_flash_name_index(), name, and NULL.

Referenced by COMMAND_HANDLER(), COMMAND_HELPER(), FLASH_BANK_COMMAND_HANDLER(), get_flash_bank_by_name(), and virtual_get_master_bank().

◆ get_flash_bank_by_num()

int get_flash_bank_by_num ( unsigned int  num,
struct flash_bank **  bank 
)

Returns the flash bank like get_flash_bank_by_name(), without probing.

Parameters
numThe flash bank number.
bankreturned bank if fn returns ERROR_OK
Returns
ERROR_OK if successful

Definition at line 280 of file flash/nor/core.c.

References flash_driver::auto_probe, bank, flash_bank::driver, ERROR_FAIL, ERROR_OK, get_flash_bank_by_num_noprobe(), and LOG_ERROR.

Referenced by COMMAND_HELPER(), gdb_memory_map(), and gdb_new_connection().

◆ get_flash_bank_by_num_noprobe()

struct flash_bank* get_flash_bank_by_num_noprobe ( unsigned int  num)

Returns the flash bank like get_flash_bank_by_num(), without probing.

Parameters
numThe flash bank number.
Returns
A struct flash_bank for flash bank num, or NULL.

Definition at line 188 of file flash/nor/core.c.

References flash_banks, LOG_ERROR, flash_bank::next, and NULL.

Referenced by COMMAND_HANDLER(), COMMAND_HELPER(), gdb_memory_map(), gdb_new_connection(), and get_flash_bank_by_num().