Upper level NOR flash interfaces. More...

Include dependency graph for nor/core.h:

This graph shows which files directly or indirectly include 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_sector *	alloc_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...

	COMMAND_HELPER (flash_command_get_bank_probe_optional, unsigned int name_index, struct flash_bank **bank, bool do_probe)
	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_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. 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_bank *	get_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

offset	Offset of first block.
size	Size of each block.
num_blocks	Number 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(), qn908x_probe(), rp2040_flash_probe(), rsl10_probe(), samd_probe(), same5_probe(), stm32l4_probe(), and stm32x_probe().

◆ COMMAND_HELPER() [1/2]

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_index	The index to the string in args containing the bank identifier.
bank	On 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.

◆ COMMAND_HELPER() [2/2]

COMMAND_HELPER	(	flash_command_get_bank_probe_optional	,
		unsigned int	name_index,
		struct flash_bank **	bank,
		bool	do_probe
	)

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_index	The index to the string in args containing the bank identifier.
bank	On output, contains a pointer to the bank or NULL.
do_probe	Does auto-probing when set, otherwise without probing.

Returns: ERROR_OK on success, or an error indicating the problem.

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

References bank, CMD_ARGV, COMMAND_PARSE_NUMBER, ERROR_FAIL, ERROR_OK, get_flash_bank_by_name(), get_flash_bank_by_name_noprobe(), get_flash_bank_by_num(), get_flash_bank_by_num_noprobe(), and name.

◆ 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

bank	The bank to read.
buffer	The data bytes read.
offset	The offset into the chip to read.
count	The 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

bank	The bank to verify.
buffer	The data bytes to verify.
offset	The offset into the chip to verify.
count	The 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 1412 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 1047 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
	)

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

References addr, flash_driver_unprotect(), flash_iterate_address_range(), and length.

Referenced by COMMAND_HANDLER(), and flash_write_unlock_verify().

◆ 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

target	The target with the flash to be programmed.
image	The image that will be programmed to flash.
written	On return, contains the number of bytes written.
erase	Indicates 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

bank	Pointer to bank descriptor structure
addr	Address 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

bank	Pointer to bank descriptor structure
addr	Address 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

target	The target, presumed to contain one or more banks.
addr	An address that is within the range of the bank.
check	return ERROR_OK and result_bank NULL if the bank does not exist
result_bank	The struct flash_bank located at addr, or NULL.