# include/block/device.h File Reference

Block Device interface. More...

`#include <buffer.h>`
`#include <slist.h>`
`#include <types.h>`

Include dependency graph for device.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | block_request
| A block device request. More...
struct | block_device
| A block device. More...
## Defines
#define | blk_req_for_each_buffer(req, buf) slist_for_each(&req->buf_list, buf, node)
| Iterate over each buffer buf associated with the block request req.
#define | blk_req_for_each_buffer_safe(req, buf, next) slist_for_each_safe(&req->buf_list, buf, next, node)
| Iterate over each buffer buf associated with the block request req, allowing removal of buf. next holds the buffer following buf.
## Typedefs
typedef uint32_t | block_addr_t
| Type for holding a logical block address (LBA).
typedef uint32_t | block_len_t
| Type for holding a block length (i.e. number of blocks).
## Enumerations
enum | block_device_flag { BDEV_UNIT_ATTENTION, BDEV_PRESENT, BDEV_WRITEABLE }
| Flags representing the state of a block device. More...
enum | block_operation { BLK_OP_READ, BLK_OP_WRITE }
| Block device operation codes. More...
## Functions
struct block_request * | block_alloc_request (struct block_device *bdev)
| Allocate a block request.
void | block_free_request (struct block_device *bdev, struct block_request *req)
| Free a block request previously allocated using block_alloc_request().
static void | block_prepare_req (struct block_device *bdev, struct block_request *req, block_addr_t lba, uint32_t nr_blocks, enum block_operation operation)
| Prepare a block request.
static void | block_submit_req (struct block_device *bdev, struct block_request *req)
| Submit a request for I/O.
static int | block_submit_buf_list (struct block_device *bdev, struct block_request *breq, struct slist *buf_list)
| Submit a list of buffers for an already-queued request.
static block_len_t | blk_req_get_blocks_xfered (struct block_device *bdev, struct block_request *breq)
| Get the number of blocks actually transfered for a request.
static size_t | blk_req_get_bytes_xfered (struct block_device *bdev, struct block_request *breq)
| Get the number of bytes actually transfered for a request.
static void | blk_req_add_buffer (struct block_request *req, struct buffer *buf)
| Associate the buffer buf with the block request req.
static void | blk_req_add_buffer_list (struct block_request *req, struct slist *list)
| Associated the list of buffers list with the block request req.
static void | blk_req_free_all_buffers (struct block_request *req)
| Free all buffers associated with the block request req.

## Detailed Description

Block Device interface.

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All devices
- AppNote:

Author:
  Atmel Corporation: http://www.atmel.com
  Support and FAQ: http://support.atmel.no/

Definition in file device.h.

## Define Documentation

#define blk_req_for_each_buffer | ( | req,
|  | buf |  | ) | slist_for_each(&req->buf_list, buf, node)

Iterate over each buffer buf associated with the block request req.

Definition at line 292 of file device.h.

#define blk_req_for_each_buffer_safe | ( | req,
|  | buf,
|  | next |  | ) | slist_for_each_safe(&req->buf_list, buf, next, node)

Iterate over each buffer buf associated with the block request req, allowing removal of buf. next holds the buffer following buf.

Definition at line 299 of file device.h.

Referenced by blk_req_free_all_buffers().

## Typedef Documentation

typedef uint32_t block_addr_t

Type for holding a logical block address (LBA).

Definition at line 51 of file device.h.

typedef uint32_t block_len_t

Type for holding a block length (i.e. number of blocks).

Definition at line 56 of file device.h.

## Enumeration Type Documentation

enum block_device_flag

Flags representing the state of a block device.

Enumerator:

  BDEV_UNIT_ATTENTION | Information about the device changed.
  BDEV_PRESENT | Device is present.
  BDEV_WRITEABLE | Device can be written to.

Definition at line 114 of file device.h.

enum block_operation

Block device operation codes.

Enumerator:

  BLK_OP_READ | Read data from the device.
  BLK_OP_WRITE | Write data to the device.

Definition at line 123 of file device.h.

## Function Documentation

static void blk_req_add_buffer | ( | struct block_request * | req,
|  | struct buffer * | buf |
| ) |  |  | `[inline, static]`

Associate the buffer buf with the block request req.

Definition at line 305 of file device.h.

References block_request::buf_list, buffer::node, and slist_insert_tail().

Here is the call graph for this function:

static void blk_req_add_buffer_list | ( | struct block_request * | req,
|  | struct slist * | list |
| ) |  |  | `[inline, static]`

Associated the list of buffers list with the block request req.

list will be empty when this function returns

Definition at line 317 of file device.h.

References block_request::buf_list, and slist_move_to_tail().

Here is the call graph for this function:

static void blk_req_free_all_buffers | ( | struct block_request * | req | ) | `[inline, static]`

Free all buffers associated with the block request req.

Definition at line 326 of file device.h.

References blk_req_for_each_buffer_safe.

static block_len_t blk_req_get_blocks_xfered | ( | struct block_device * | bdev,
|  | struct block_request * | breq |
| ) |  |  | `[inline, static]`

Get the number of blocks actually transfered for a request.

This function returns the number of blocks actually transfered. May be less than requested if an error occurred.

This number is updated before each time buf_list_done() and req_done() is called. Note that when buf_list_done() is called for write requests, this indicates the number of blocks transfered to the controller, which may be more than the number of blocks written to the underlying storage.

Definition at line 260 of file device.h.

References assert, block_request::bdev, block_device::block_size, and block_request::bytes_xfered.

static size_t blk_req_get_bytes_xfered | ( | struct block_device * | bdev,
|  | struct block_request * | breq |
| ) |  |  | `[inline, static]`

Get the number of bytes actually transfered for a request.

This function returns the number of bytes actually transfered. May be less than requested if an error occurred.

This number is updated before each time buf_list_done() and req_done() is called. Note that when buf_list_done() is called for write requests, this indicates the number of bytes transfered to the controller, which may be more than the number of bytes written to the underlying storage.

Definition at line 280 of file device.h.

References assert, block_request::bdev, and block_request::bytes_xfered.

struct block_request* block_alloc_request | ( | struct block_device * | bdev | ) | `[read]`

Allocate a block request.

Parameters:

  | bdev | Block device which will handle the request

Returns:
  A new block request object, or NULL if sufficient memory isn't available.

Definition at line 56 of file core.c.

References block_device::alloc_req, assert, block_request::bdev, dbg_warning, and likely.

Referenced by aesblk_alloc_req(), block_copy_set_dest(), and block_copy_set_source().

void block_free_request | ( | struct block_device * | bdev,
|  | struct block_request * | req |
| ) |  |  |

Free a block request previously allocated using block_alloc_request().

Parameters:

  | bdev | The block device for which req was allocated
  | req | The block request object to be freed.

Definition at line 80 of file core.c.

References assert, block_request::bdev, and block_device::free_req.

Referenced by aesblk_free_req(), and block_copy_free().

static void block_prepare_req | ( | struct block_device * | bdev,
|  | struct block_request * | req,
|  | block_addr_t | lba,
|  | uint32_t | nr_blocks,
|  | enum block_operation | operation |
| ) |  |  | `[inline, static]`

Prepare a block request.

This function will initialize a block_request structure with default values (no buffers, no bytes transferred, etc.) The req_submit() field will point to the function that will start the operation indicated by operation.

Parameters:

  | bdev | The block device which should handle the request
  | req | The block request to be initialized
  | lba | The Logical Block Address of the first block
  | nr_blocks | The number of blocks to operate on
  | operation | One of the operations defined by block_operation.

Precondition:
  bdev is the block device for which req was allocated

Definition at line 174 of file device.h.

References assert, block_request::bdev, and block_device::prepare_req.

Referenced by aesblk_prepare_req().

static int block_submit_buf_list | ( | struct block_device * | bdev,
|  | struct block_request * | breq,
|  | struct slist * | buf_list |
| ) |  |  | `[inline, static]`

Submit a list of buffers for an already-queued request.

This function will atomically submit a list of buffers for transfering data associated with a block request. If the request has already failed before the buffers are queued, this function will leave the buffers alone and return -STATUS_FLUSHED. The caller is responsible for cleaning up the buffer list when this happens.

Parameters:

  | bdev | The block device handling the request
  | breq | The block request associated with the buffers
  | buf_list | List of buffers to be submitted

Return values:

  | 0 | The buffers were successfully submitted
  | -STATUS_FLUSHED | breq is not queued (i.e. it might have encountered an error.)

Definition at line 239 of file device.h.

References assert, block_request::bdev, and block_request::req_submit_buf_list.

Referenced by msc_submit_read_buffers().

static void block_submit_req | ( | struct block_device * | bdev,
|  | struct block_request * | req |
| ) |  |  | `[inline, static]`

Submit a request for I/O.

Parameters:

  | bdev | The Block Device to handle the request.
  | req | This request

Precondition:
  bdev is the block device for which req was allocated and prepared.

Definition at line 192 of file device.h.

References assert, block_request::bdev, and block_request::req_submit.