Provides the implementation-independent structure that defines all of the callbacks required by OpenOCD flash drivers. More...

Collaboration diagram for flash_driver:

[legend]

Public Member Functions
	__FLASH_BANK_COMMAND ((*flash_bank_command))
	Finish the "flash bank" command for bank. More...

Data Fields
int(*	auto_probe )(struct flash_bank *bank)
	A more gentle flavor of flash_driver_s::probe, performing setup with less noise. More...

const struct command_registration *	commands
	An array of driver-specific commands to register. More...

int(*	erase )(struct flash_bank *bank, unsigned int first, unsigned int last)
	Bank/sector erase routine (target-specific). More...

int(*	erase_check )(struct flash_bank *bank)
	Check the erasure status of a flash bank. More...

void(*	free_driver_priv )(struct flash_bank *bank)
	Deallocates private driver structures. More...

int(*	info )(struct flash_bank bank, struct command_invocation cmd)
	Display human-readable information about the flash bank. More...

const char *	name
	Gives a human-readable name of this flash driver, This field is used to select and initialize the driver. More...

int(*	probe )(struct flash_bank *bank)
	Probe to determine what kind of flash is present. More...

int(*	protect )(struct flash_bank *bank, int set, unsigned int first, unsigned int last)
	Bank/sector protection routine (target-specific). More...

int(*	protect_check )(struct flash_bank *bank)
	Determine if the specific bank is "protected" or not. More...

int(*	read )(struct flash_bank bank, uint8_t buffer, uint32_t offset, uint32_t count)
	Read data from the flash. More...

const char *	usage
	Gives a human-readable description of arguments. More...

int(*	verify )(struct flash_bank bank, const uint8_t buffer, uint32_t offset, uint32_t count)
	Verify data in flash. More...

int(*	write )(struct flash_bank bank, const uint8_t buffer, uint32_t offset, uint32_t count)
	Program data into the flash. More...

Detailed Description

Provides the implementation-independent structure that defines all of the callbacks required by OpenOCD flash drivers.

Driver authors must implement the routines defined here, providing an instance with the fields filled out. After that, the instance must be registered in flash.c, so it can be used by the driver lookup system.

Specifically, the user can issue the command:

: flash bank DRIVERNAME ...parameters...

bank
uint8_t bank
Definition: esirisc.c:135

OpenOCD will search for the driver with a flash_driver_s::name that matches DRIVERNAME.

The flash subsystem calls some of the other drivers routines a using corresponding static flash_driver_callback() routine in flash.c.

Definition at line 39 of file nor/driver.h.

Member Function Documentation

◆ __FLASH_BANK_COMMAND()

flash_driver::__FLASH_BANK_COMMAND ( * flash_bank_command )

Finish the "flash bank" command for bank.

The bank parameter will have been filled in by the core flash layer when this routine is called, and the driver can store additional information in its struct flash_bank::driver_priv field.

The CMD_ARGV are:

: CMD_ARGV[0] = bank

CMD_ARGV[1] = drivername {name above}

CMD_ARGV[2] = baseaddress

CMD_ARGV[3] = lengthbytes

CMD_ARGV[4] = chip_width_in bytes

CMD_ARGV[5] = bus_width_in_bytes

CMD_ARGV[6] = driver-specific parameters

CMD_ARGV
#define CMD_ARGV
Use this macro to access the arguments for the command being handled, rather than accessing the varia...
Definition: command.h:155

flash_driver::name
const char * name
Gives a human-readable name of this flash driver, This field is used to select and initialize the dri...
Definition: nor/driver.h:44

For example, CMD_ARGV[4] = 2 (for 16 bit flash), CMD_ARGV[5] = 4 (for 32 bit bus).

If extra arguments are provided (CMD_ARGC > 6), they will start in CMD_ARGV[6]. These can be used to implement driver-specific extensions.

Returns: ERROR_OK if successful; otherwise, an error code.

Field Documentation

◆ auto_probe

int(* flash_driver::auto_probe) (struct flash_bank *bank)

A more gentle flavor of flash_driver_s::probe, performing setup with less noise.

Generally, driver routines should test to see if the bank has already been probed; if it has, the driver probably should not perform its probe a second time.

This callback is often called from the inside of other routines (e.g. GDB flash downloads) to autoprobe the flash as it is programming the flash.

Parameters

bank	- the bank to probe

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 219 of file nor/driver.h.

Referenced by COMMAND_HANDLER(), get_flash_bank_by_addr(), get_flash_bank_by_num(), and virtual_auto_probe().

◆ commands

const struct command_registration* flash_driver::commands

An array of driver-specific commands to register.

When called during the "flash bank" command, the driver can register addition commands to support new flash chip functions.

Definition at line 56 of file nor/driver.h.

Referenced by COMMAND_HANDLER().

◆ erase

int(* flash_driver::erase) (struct flash_bank *bank, unsigned int first, unsigned int last)

Bank/sector erase routine (target-specific).

When called, the flash driver should erase the specified sectors using whatever means are at its disposal.

Parameters

bank	The bank of flash to be erased.
first	The number of the first sector to erase, typically 0.
last	The number of the last sector to erase, typically N-1.

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 96 of file nor/driver.h.

Referenced by virtual_erase().

◆ erase_check

int(* flash_driver::erase_check) (struct flash_bank *bank)

Check the erasure status of a flash bank.

When called, the driver routine must perform the required checks and then set the flash_sector_s::is_erased field for each of the flash banks's sectors.

Parameters

bank	The bank to check

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 179 of file nor/driver.h.

Referenced by COMMAND_HANDLER(), and virtual_blank_check().

◆ free_driver_priv

void(* flash_driver::free_driver_priv) (struct flash_bank *bank)

Deallocates private driver structures.

Use default_flash_free_driver_priv() to simply free(bank->driver_priv)

Parameters

bank	- the bank being destroyed

Definition at line 227 of file nor/driver.h.

◆ info

int(* flash_driver::info) (struct flash_bank *bank, struct command_invocation *cmd)

Display human-readable information about the flash bank.

Parameters

bank	- the bank to get info about
cmd	- command invocation instance for which to generate the textual output

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 204 of file nor/driver.h.

Referenced by COMMAND_HANDLER().

◆ name

const char* flash_driver::name

Gives a human-readable name of this flash driver, This field is used to select and initialize the driver.

Definition at line 44 of file nor/driver.h.

Referenced by COMMAND_HANDLER().

◆ probe

int(* flash_driver::probe) (struct flash_bank *bank)

Probe to determine what kind of flash is present.

This is invoked by the "probe" script command.

Parameters

bank	The bank to probe

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 168 of file nor/driver.h.

Referenced by COMMAND_HANDLER(), and virtual_probe().

◆ protect

int(* flash_driver::protect) (struct flash_bank *bank, int set, unsigned int first, unsigned int last)

Bank/sector protection routine (target-specific).

If protection is not implemented, set method to NULL

When called, the driver should enable/disable protection for MINIMUM the range covered by first..last sectors inclusive. Some chips have alignment requirements will cause the actual range to be protected / unprotected to be larger than the first..last range.

Parameters

bank	The bank to protect or unprotect.
set	If non-zero, enable protection; if 0, disable it.
first	The first sector to (un)protect, typically 0.
last	The last sector to (un)project, typically N-1.

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 116 of file nor/driver.h.

◆ protect_check

int(* flash_driver::protect_check) (struct flash_bank *bank)

Determine if the specific bank is "protected" or not.

When called, the driver routine must must perform the required protection check(s) and then set the flash_sector_s::is_protected field for each of the flash bank's sectors.

If protection is not implemented, set method to NULL

Parameters

bank	- the bank to check

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 193 of file nor/driver.h.

Referenced by COMMAND_HANDLER(), and virtual_protect_check().

◆ read

int(* flash_driver::read) (struct flash_bank *bank, uint8_t *buffer, uint32_t offset, uint32_t count)

Read data from the flash.

Note CPU address will be "bank->base + offset", while the physical address is dependent upon current target MMU mappings.

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 144 of file nor/driver.h.

◆ usage

const char* flash_driver::usage

Gives a human-readable description of arguments.

Definition at line 49 of file nor/driver.h.

Referenced by COMMAND_HANDLER().

◆ verify

int(* flash_driver::verify) (struct flash_bank *bank, const uint8_t *buffer, uint32_t offset, uint32_t count)

Verify data in flash.

Note CPU address will be "bank->base + offset", while the physical address is dependent upon current target MMU mappings.

Parameters

bank	The bank to verify
buffer	The data bytes to verify against.
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 158 of file nor/driver.h.

◆ write

int(* flash_driver::write) (struct flash_bank *bank, const uint8_t *buffer, uint32_t offset, uint32_t count)

Program data into the flash.

Note CPU address will be "bank->base + offset", while the physical address is dependent upon current target MMU mappings.

Parameters

bank	The bank to program
buffer	The data bytes to write.
offset	The offset into the chip to program.
count	The number of bytes to write.

Returns: ERROR_OK if successful; otherwise, an error code.

Definition at line 130 of file nor/driver.h.

Referenced by virtual_write().

The documentation for this struct was generated from the following file:

nor/driver.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ __FLASH_BANK_COMMAND()

Field Documentation

◆ auto_probe

◆ commands

◆ erase

◆ erase_check

◆ free_driver_priv

◆ info

◆ name

◆ probe

◆ protect

◆ protect_check

◆ read

◆ usage

◆ verify

◆ write