Collaboration diagram for Abstract I/O Block Device:

Detailed Description

Driver State Machine

The drivers implementing this interface shall implement the following state machine internally. Not all the driver functionalities can be used in any moment, any transition not explicitly shown in the following diagram has to be considered an error and shall be captured by an assertion (if enabled).

This module defines an abstract interface for accessing generic block devices.
Note that no code is present, just abstract interfaces-like structures, you should look at the system as to a set of abstract C++ classes (even if written in C). This system has then advantage to make the access to block devices independent from the implementation logic.

Macros
#define	_base_block_device_methods
	`BaseBlockDevice` specific methods. More...

#define	_base_block_device_data
	`BaseBlockDevice` specific data. More...

Macro Functions (BaseBlockDevice)
#define	blkGetDriverState(ip) ((ip)->state)
	Returns the driver state. More...

#define	blkIsTransferring(ip)
	Determines if the device is transferring data. More...

#define	blkIsInserted(ip) ((ip)->vmt->is_inserted(ip))
	Returns the media insertion status. More...

#define	blkIsWriteProtected(ip) ((ip)->vmt->is_protected(ip))
	Returns the media write protection status. More...

#define	blkConnect(ip) ((ip)->vmt->connect(ip))
	Performs the initialization procedure on the block device. More...

#define	blkDisconnect(ip) ((ip)->vmt->disconnect(ip))
	Terminates operations on the block device. More...

#define	blkRead(ip, startblk, buf, n) ((ip)->vmt->read(ip, startblk, buf, n))
	Reads one or more blocks. More...

#define	blkWrite(ip, startblk, buf, n) ((ip)->vmt->write(ip, startblk, buf, n))
	Writes one or more blocks. More...

#define	blkSync(ip) ((ip)->vmt->sync(ip))
	Ensures write synchronization. More...

#define	blkGetInfo(ip, bdip) ((ip)->vmt->get_info(ip, bdip))
	Returns a media information structure. More...

Data Structures
struct	BlockDeviceInfo
	Block device info. More...

struct	BaseBlockDeviceVMT
	`BaseBlockDevice` virtual methods table. More...

struct	BaseBlockDevice
	Base block device class. More...

Enumerations

Macro Definition Documentation

#define _base_block_device_methods

Value:

_base_object_methods                                                      \
  /* Removable media detection.*/                                           \
  bool (*is_inserted)(void *instance);                                      \
  /* Removable write protection detection.*/                                \
  bool (*is_protected)(void *instance);                                     \
  /* Connection to the block device.*/                                      \
  bool (*connect)(void *instance);                                          \
  /* Disconnection from the block device.*/                                 \
  bool (*disconnect)(void *instance);                                       \
  /* Reads one or more blocks.*/                                            \
  bool (*read)(void *instance, uint32_t startblk,                           \
                 uint8_t *buffer, uint32_t n);                              \
  /* Writes one or more blocks.*/                                           \
  bool (*write)(void *instance, uint32_t startblk,                          \
                  const uint8_t *buffer, uint32_t n);                       \
  /* Write operations synchronization.*/                                    \
  bool (*sync)(void *instance);                                             \
  /* Obtains info about the media.*/                                        \
  bool (*get_info)(void *instance, BlockDeviceInfo *bdip);

BaseBlockDevice specific methods.

Definition at line 63 of file hal_ioblock.h.

#define _base_block_device_data

Value:

_base_object_data                                                         \
  /* Driver state.*/                                                        \
  blkstate_t            state;

BaseBlockDevice specific data.

Definition at line 87 of file hal_ioblock.h.

#define blkGetDriverState ( ip ) ((ip)->state)

Returns the driver state.

Note: Can be called in ISR context.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The driver state.

Function Class:Special function, this function has special requirements see the notes.

Definition at line 125 of file hal_ioblock.h.

#define blkIsTransferring ( ip )

Value:

((((ip)->state) == BLK_CONNECTING) ||         \
                               (((ip)->state) == BLK_DISCONNECTING) ||      \
                               (((ip)->state) == BLK_READING) ||            \
                               (((ip)->state) == BLK_WRITING))

Determines if the device is transferring data.

Note: Can be called in ISR context.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The driver state.

Return values

false	the device is not transferring data.
true	the device not transferring data.

Function Class:Special function, this function has special requirements see the notes.

Definition at line 139 of file hal_ioblock.h.

#define blkIsInserted ( ip ) ((ip)->vmt->is_inserted(ip))

Returns the media insertion status.

Note: On some implementations this function can only be called if the device is not transferring data. The function blkIsTransferring() should be used before calling this function.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The media state.

Return values

false	media not inserted.
true	media inserted.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 159 of file hal_ioblock.h.

#define blkIsWriteProtected ( ip ) ((ip)->vmt->is_protected(ip))

Returns the media write protection status.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The media state.

Return values

false	writable media.
true	non writable media.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 172 of file hal_ioblock.h.

#define blkConnect ( ip ) ((ip)->vmt->connect(ip))

Performs the initialization procedure on the block device.

This function should be performed before I/O operations can be attempted on the block device and after insertion has been confirmed using blkIsInserted().

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 188 of file hal_ioblock.h.

#define blkDisconnect ( ip ) ((ip)->vmt->disconnect(ip))

Terminates operations on the block device.

This operation safely terminates operations on the block device.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 202 of file hal_ioblock.h.

#define blkRead	(	ip,
		startblk,
		buf,
		n
	)	((ip)->vmt->read(ip, startblk, buf, n))

Reads one or more blocks.

Parameters

[in]	ip	pointer to a `BaseBlockDevice` or derived class
[in]	startblk	first block to read
[out]	buf	pointer to the read buffer
[in]	n	number of blocks to read

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 218 of file hal_ioblock.h.

#define blkWrite	(	ip,
		startblk,
		buf,
		n
	)	((ip)->vmt->write(ip, startblk, buf, n))

Writes one or more blocks.

Parameters

[in]	ip	pointer to a `BaseBlockDevice` or derived class
[in]	startblk	first block to write
[out]	buf	pointer to the write buffer
[in]	n	number of blocks to write

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 235 of file hal_ioblock.h.

#define blkSync ( ip ) ((ip)->vmt->sync(ip))

Ensures write synchronization.

Parameters

[in] ip pointer to a BaseBlockDevice or derived class

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 249 of file hal_ioblock.h.

#define blkGetInfo	(	ip,
		bdip
	)	((ip)->vmt->get_info(ip, bdip))

Returns a media information structure.

Parameters

[in]	ip	pointer to a `BaseBlockDevice` or derived class
[out]	bdip	pointer to a `BlockDeviceInfo` structure

Returns: The operation status.

Return values

HAL_SUCCESS	operation succeeded.
HAL_FAILED	operation failed.

Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 263 of file hal_ioblock.h.

Enumeration Type Documentation

enum blkstate_t

Driver state machine possible states.

Enumerator
BLK_UNINIT	Not initialized.
BLK_STOP	Stopped.
BLK_ACTIVE	Interface active.
BLK_CONNECTING	Connection in progress.
BLK_DISCONNECTING	Disconnection in progress.
BLK_READY	Device ready.
BLK_READING	Read operation in progress.
BLK_WRITING	Write operation in progress.
BLK_SYNCING	Sync. operation in progress.

Definition at line 40 of file hal_ioblock.h.

Detailed Description

Driver State Machine

Macros

Macro Functions (BaseBlockDevice)

Data Structures

Enumerations

Macro Definition Documentation

Enumeration Type Documentation