Block Media Interface

Detailed Description

Interface for block media memory access.

Summary

The block media interface supports reading, writing, and erasing media devices. All functions are non-blocking if possible. The callback is used to determine when an operation completes.

Data Structures
struct	rm_block_media_info_t
struct	rm_block_media_callback_args_t
struct	rm_block_media_cfg_t
struct	rm_block_media_status_t
struct	rm_block_media_api_t
struct	rm_block_media_instance_t

Typedefs
typedef void	rm_block_media_ctrl_t

Enumerations
enum	rm_block_media_event_t

---

Data Structure Documentation

rm_block_media_info_t

struct rm_block_media_info_t

Block media device information supported by the instance

Data Fields
uint32_t	sector_size_bytes	Sector size in bytes.
uint32_t	num_sectors	Total number of sectors.
bool	reentrant	True if connected block media driver is reentrant.
bool	write_protected	True if connected block media device is write protected.

rm_block_media_callback_args_t

struct rm_block_media_callback_args_t

Callback function parameter data

Data Fields
rm_block_media_event_t	event	The event can be used to identify what caused the callback.
void const *	p_context	Placeholder for user data.

rm_block_media_cfg_t

struct rm_block_media_cfg_t

User configuration structure, used in open function

Data Fields
void(*	p_callback )(rm_block_media_callback_args_t *p_args)
	Pointer to callback function.
void const *	p_context
	User defined context passed into callback function.
void const *	p_extend
	Extension parameter for hardware specific settings.

rm_block_media_status_t

struct rm_block_media_status_t

Current status

Data Fields
bool	initialized	False if rm_block_media_api_t::mediaInit has not been called since media was inserted, true otherwise.
bool	busy	True if media is busy with a previous write/erase operation.
bool	media_inserted	Media insertion status, true if media is not removable.

rm_block_media_api_t

struct rm_block_media_api_t

Block media interface API.

Data Fields
fsp_err_t(*	open )(rm_block_media_ctrl_t *const p_ctrl, rm_block_media_cfg_t const *const p_cfg)
fsp_err_t(*	mediaInit )(rm_block_media_ctrl_t *const p_ctrl)
fsp_err_t(*	read )(rm_block_media_ctrl_t *const p_ctrl, uint8_t *const p_dest_address, uint32_t const block_address, uint32_t const num_blocks)
fsp_err_t(*	write )(rm_block_media_ctrl_t *const p_ctrl, uint8_t const *const p_src_address, uint32_t const block_address, uint32_t const num_blocks)
fsp_err_t(*	erase )(rm_block_media_ctrl_t *const p_ctrl, uint32_t const block_address, uint32_t const num_blocks)
fsp_err_t(*	callbackSet )(rm_block_media_ctrl_t *const p_ctrl, void(*p_callback)(rm_block_media_callback_args_t *), void const *const p_context, rm_block_media_callback_args_t *const p_callback_memory)
fsp_err_t(*	statusGet )(rm_block_media_ctrl_t *const p_ctrl, rm_block_media_status_t *const p_status)
fsp_err_t(*	infoGet )(rm_block_media_ctrl_t *const p_ctrl, rm_block_media_info_t *const p_info)
fsp_err_t(*	close )(rm_block_media_ctrl_t *const p_ctrl)

Field Documentation

open

fsp_err_t(* rm_block_media_api_t::open) (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_cfg_t const *const p_cfg)

Initialize block media device. rm_block_media_api_t::mediaInit must be called to complete the initialization procedure.

Parameters

[in]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

mediaInit

fsp_err_t(* rm_block_media_api_t::mediaInit) (rm_block_media_ctrl_t *const p_ctrl)

Initializes a media device. If the device is removable, it must be plugged in prior to calling this API. This function blocks until media initialization is complete.

Parameters

[in]

p_ctrl

Control block set in rm_block_media_api_t::open call.

read

fsp_err_t(* rm_block_media_api_t::read) (rm_block_media_ctrl_t *const p_ctrl, uint8_t *const p_dest_address, uint32_t const block_address, uint32_t const num_blocks)

Reads blocks of data from the specified memory device address to the location specified by the caller.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[out]	p_dest_address	Destination to read the data into.
[in]	block_address	Block address to read the data from.
[in]	num_blocks	Number of blocks of data to read.

write

fsp_err_t(* rm_block_media_api_t::write) (rm_block_media_ctrl_t *const p_ctrl, uint8_t const *const p_src_address, uint32_t const block_address, uint32_t const num_blocks)

Writes blocks of data to the specified device memory address.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[in]	p_src_address	Address to read the data to be written.
[in]	block_address	Block address to write the data to.
[in]	num_blocks	Number of blocks of data to write.

erase

fsp_err_t(* rm_block_media_api_t::erase) (rm_block_media_ctrl_t *const p_ctrl, uint32_t const block_address, uint32_t const num_blocks)

Erases blocks of data from the memory device.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[in]	block_address	Block address to start the erase process at.
[in]	num_blocks	Number of blocks of data to erase.

callbackSet

fsp_err_t(* rm_block_media_api_t::callbackSet) (rm_block_media_ctrl_t *const p_ctrl, void( *p_callback)(rm_block_media_callback_args_t *), void const *const p_context, rm_block_media_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[in]	p_callback	Callback function to register
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

statusGet

fsp_err_t(* rm_block_media_api_t::statusGet) (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_status_t *const p_status)

Get status of connected device.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[out]	p_status	Pointer to store current status.

infoGet

fsp_err_t(* rm_block_media_api_t::infoGet) (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_info_t *const p_info)

Returns information about the block media device.

Parameters

[in]	p_ctrl	Control block set in rm_block_media_api_t::open call.
[out]	p_info	Pointer to information structure. All elements of this structure will be set by the function.

close

fsp_err_t(* rm_block_media_api_t::close) (rm_block_media_ctrl_t *const p_ctrl)

Closes the module.

Parameters

[in]

p_ctrl

Control block set in rm_block_media_api_t::open call.

rm_block_media_instance_t

struct rm_block_media_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
rm_block_media_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
rm_block_media_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
rm_block_media_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

rm_block_media_ctrl_t

typedef void rm_block_media_ctrl_t

Block media API control block. Allocate an instance specific control block to pass into the block media API calls.

Enumeration Type Documentation

rm_block_media_event_t

enum rm_block_media_event_t

Events that can trigger a callback function

Enumerator
RM_BLOCK_MEDIA_EVENT_MEDIA_REMOVED	Media removed event.
RM_BLOCK_MEDIA_EVENT_MEDIA_INSERTED	Media inserted event.
RM_BLOCK_MEDIA_EVENT_OPERATION_COMPLETE	Read, write, or erase completed.
RM_BLOCK_MEDIA_EVENT_ERROR	Error on media operation.
RM_BLOCK_MEDIA_EVENT_POLL_STATUS	Poll rm_block_media_api_t::statusGet for write/erase completion.
RM_BLOCK_MEDIA_EVENT_MEDIA_SUSPEND	Media suspended event.
RM_BLOCK_MEDIA_EVENT_MEDIA_RESUME	Media resumed event.
RM_BLOCK_MEDIA_EVENT_WAIT	Indication to user that they should wait for an interrupt on a pending operation.
RM_BLOCK_MEDIA_EVENT_WAIT_END	Indication to user that interrupt has been received and waiting can end.