RTEMS: Block Device Management

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Block Device Management
Device Drivers » Block Device Library

## Modules
| Flash Disk Device
| Generic Disk Device
| RAM Disk Device
| Sparse Disk Device

## Files
file | blkdev.h
| Block Device Management.
file | blkdev-blkstats.c
| Block Device Statistics Command.
file | blkdev-ioctl.c
| Common IO Control Primitive.
file | blkdev-ops.c
| Block device management.
file | blkdev-print-stats.c
| Prints the Block Device Statistics.
file | blkdev.c
| Block Device Management.

## Data Structures
struct | rtems_blkdev_sg_buffer
| Block device scatter or gather buffer structure. More...
struct | rtems_blkdev_request
| The block device transfer request is used to read or write a number of blocks from or to the device. More...

## Macros
#define | RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block)
| The start block in a request.

## Typedefs
typedef enum rtems_blkdev_request_op | rtems_blkdev_request_op
| Block device request type.
typedef void(* | rtems_blkdev_request_cb) (struct rtems_blkdev_request *req, rtems_status_code status)
| Block device request done callback function type.
typedef struct rtems_blkdev_sg_buffer | rtems_blkdev_sg_buffer
| Block device scatter or gather buffer structure.
typedef struct rtems_blkdev_request | rtems_blkdev_request
| The block device transfer request is used to read or write a number of blocks from or to the device.

## Enumerations
enum | rtems_blkdev_request_op { RTEMS_BLKDEV_REQ_READ , RTEMS_BLKDEV_REQ_WRITE , RTEMS_BLKDEV_REQ_SYNC }
| Block device request type. More...

## Functions
int | rtems_blkdev_ioctl (rtems_disk_device *dd, uint32_t req, void *argp)
| Common IO control primitive.
rtems_status_code | rtems_blkdev_create (const char *device, uint32_t media_block_size, rtems_blkdev_bnum media_block_count, rtems_block_device_ioctl handler, void *driver_data)
| Creates a block device.
rtems_status_code | rtems_blkdev_create_partition (const char *partition, const char *parent_block_device, rtems_blkdev_bnum media_block_begin, rtems_blkdev_bnum media_block_count)
| Creates a partition within a parent block device.
void | rtems_blkdev_print_stats (const rtems_blkdev_stats *stats, uint32_t media_block_size, uint32_t media_block_count, uint32_t block_size, const rtems_printer *printer)
| Prints the block device statistics.
void | rtems_blkstats (const rtems_printer *printer, const char *device, bool reset)
| Block device statistics command.

## IO Control Request Codes
#define | RTEMS_BLKIO_REQUEST _IOWR('B', 1, rtems_blkdev_request)
#define | RTEMS_BLKIO_GETMEDIABLKSIZE _IOR('B', 2, uint32_t)
#define | RTEMS_BLKIO_GETBLKSIZE _IOR('B', 3, uint32_t)
#define | RTEMS_BLKIO_SETBLKSIZE _IOW('B', 4, uint32_t)
#define | RTEMS_BLKIO_GETSIZE _IOR('B', 5, rtems_blkdev_bnum)
#define | RTEMS_BLKIO_SYNCDEV _IO('B', 6)
#define | RTEMS_BLKIO_DELETED _IO('B', 7)
#define | RTEMS_BLKIO_CAPABILITIES _IO('B', 8)
#define | RTEMS_BLKIO_GETDISKDEV _IOR('B', 9, rtems_disk_device *)
#define | RTEMS_BLKIO_PURGEDEV _IO('B', 10)
#define | RTEMS_BLKIO_GETDEVSTATS _IOR('B', 11, rtems_blkdev_stats *)
#define | RTEMS_BLKIO_RESETDEVSTATS _IO('B', 12)

## Block Device Driver Capabilities
#define | RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)
| Only consecutive multi-sector buffer requests are supported.
#define | RTEMS_BLKDEV_CAP_SYNC (1 << 1)
| The driver will accept a sync call.

## Detailed Description

Interface between device drivers and the block device buffer module.

The heart of the block device driver is the RTEMS_BLKIO_REQUEST IO control. This call puts IO requests to the block device for asynchronous processing. When a driver executes a request, it invokes the request done callback function to finish the request.

## Macro Definition Documentation

## ◆ RTEMS_BLKDEV_CAP_MULTISECTOR_CONT

#define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)

Only consecutive multi-sector buffer requests are supported.

This option means the cache will only supply multiple buffers that are inorder so the ATA multi-sector command for example can be used. This is a hack to work around the current ATA driver.

## ◆ RTEMS_BLKDEV_CAP_SYNC

#define RTEMS_BLKDEV_CAP_SYNC (1 << 1)

The driver will accept a sync call.

A sync call is made to a driver after a bdbuf cache sync has finished.

## ◆ RTEMS_BLKDEV_START_BLOCK

#define RTEMS_BLKDEV_START_BLOCK | ( |  | req | ) | (req->bufs[0].block)

The start block in a request.

Only valid if the driver has returned the RTEMS_BLKDEV_CAP_MULTISECTOR_CONT capability.

## Typedef Documentation

## ◆ rtems_blkdev_request

typedef struct rtems_blkdev_request rtems_blkdev_request

The block device transfer request is used to read or write a number of blocks from or to the device.

Transfer requests are issued to the disk device driver with the RTEMS_BLKIO_REQUEST IO control. The transfer request completion status must be signalled with rtems_blkdev_request_done(). This function must be called exactly once per request. The return value of the IO control will be ignored for transfer requests.

See also
  rtems_blkdev_create().

## ◆ rtems_blkdev_request_op

typedef enum rtems_blkdev_request_op rtems_blkdev_request_op

Block device request type.

Warning
  The sync request is an IO one and only used from the cache. Use the Block IO when operating at the device level. We need a sync request to avoid requests looping for ever.

## Enumeration Type Documentation

## ◆ rtems_blkdev_request_op

enum rtems_blkdev_request_op

Block device request type.

Warning
  The sync request is an IO one and only used from the cache. Use the Block IO when operating at the device level. We need a sync request to avoid requests looping for ever.

Enumerator
RTEMS_BLKDEV_REQ_READ | Read the requested blocks of data.
RTEMS_BLKDEV_REQ_WRITE | Write the requested blocks of data.
RTEMS_BLKDEV_REQ_SYNC | Sync any data with the media.

## Function Documentation

## ◆ rtems_blkdev_create()

rtems_status_code rtems_blkdev_create | ( | const char * | device,
|  | uint32_t | media_block_size,
|  | rtems_blkdev_bnum | media_block_count,
|  | rtems_block_device_ioctl | handler,
|  | void * | driver_data
| ) |  |

Creates a block device.

The block size is set to the media block size.

Parameters

  [in] | device | The path for the new block device.
  [in] | media_block_size | The media block size in bytes. Must be positive.
  [in] | media_block_count | The media block count. Must be positive.
  [in] | handler | The block device IO control handler. Must not be `NULL`.
  [in] | driver_data | The block device driver data.

Return values

  RTEMS_SUCCESSFUL | Successful operation.
  RTEMS_INVALID_NUMBER | Media block size or count is not positive.
  RTEMS_NO_MEMORY | Not enough memory.
  RTEMS_UNSATISFIED | Cannot create generic device node.
  RTEMS_INCORRECT_STATE | Cannot initialize bdbuf.

See also
  rtems_blkdev_create_partition(), rtems_bdbuf_set_block_size(), and rtems_blkdev_request.

## ◆ rtems_blkdev_create_partition()

rtems_status_code rtems_blkdev_create_partition | ( | const char * | partition,
|  | const char * | parent_block_device,
|  | rtems_blkdev_bnum | media_block_begin,
|  | rtems_blkdev_bnum | media_block_count
| ) |  |

Creates a partition within a parent block device.

A partition manages a subset of consecutive blocks contained in a parent block device. The blocks must be within the range of blocks managed by the associated parent block device. The media block size and IO control handler are inherited by the parent block device. The block size is set to the media block size.

Parameters

  [in] | partition | The path for the new partition device.
  [in] | parent_block_device | The parent block device path.
  [in] | media_block_begin | The media block begin of the partition within the parent block device.
  [in] | media_block_count | The media block count of the partition.

Return values

  RTEMS_SUCCESSFUL | Successful operation.
  RTEMS_INVALID_ID | Block device node does not exist.
  RTEMS_INVALID_NODE | File system node is not a block device.
  RTEMS_NOT_IMPLEMENTED | Block device implementation is incomplete.
  RTEMS_INVALID_NUMBER | Block begin or block count is invalid.
  RTEMS_NO_MEMORY | Not enough memory.
  RTEMS_UNSATISFIED | Cannot create generic device node.

See also
  rtems_blkdev_create() and rtems_bdbuf_set_block_size().

## ◆ rtems_blkdev_ioctl()

int rtems_blkdev_ioctl | ( | rtems_disk_device * | dd,
|  | uint32_t | req,
|  | void * | argp
| ) |  |

Common IO control primitive.

Use this in all block devices to handle the common set of IO control requests.