16.5. Quick Reference

16.5. Quick Reference

#include
int register_blkdev(unsigned int major, const char *name);
int unregister_blkdev(unsigned int major, const char *name);

register_blkdev registers a block driver with the kernel and, optionally, obtains a major number. A driver can be unregistered with unregister_blkdev.

struct block_device_operations

Structure that holds most of the methods for block drivers.

#include
struct gendisk;

Structure that describes a single block device within the kernel.

struct gendisk *alloc_disk(int minors);
void add_disk(struct gendisk *gd);

Functions that allocate gendisk structures and return them to the system.

void set_capacity(struct gendisk *gd, sector_t sectors);

Stores the capacity of the device (in 512-byte sectors) within the gendisk structure.

void add_disk(struct gendisk *gd);

Adds a disk to the kernel. As soon as this function is called, your disk's methods can be invoked by the kernel.

int check_disk_change(struct block_device *bdev);

A kernel function that checks for a media change in the given disk drive and takes the required cleanup action when such a change is detected.

#include
request_queue_t blk_init_queue(request_fn_proc *request, spinlock_t *lock);
void blk_cleanup_queue(request_queue_t *);

Functions that handle the creation and deletion of block request queues.

struct request *elv_next_request(request_queue_t *queue);
void end_request(struct request *req, int success);

elv_next_request obtains the next request from a request queue; end_request may be used in very simple drivers to mark the completion of (or part of) a request.

void blkdev_dequeue_request(struct request *req);
void elv_requeue_request(request_queue_t *queue, struct request *req);

Functions that remove a request from a queue and put it back on if necessary.

void blk_stop_queue(request_queue_t *queue);
void blk_start_queue(request_queue_t *queue);

If you need to prevent further calls to your request method, a call to blk_stop_queue does the trick. A call to blk_start_queue is necessary to cause your request method to be invoked again.

void blk_queue_bounce_limit(request_queue_t *queue, u64 dma_addr);
void blk_queue_max_sectors(request_queue_t *queue, unsigned short max);
void blk_queue_max_phys_segments(request_queue_t *queue, unsigned short max);
void blk_queue_max_hw_segments(request_queue_t *queue, unsigned short max);
void blk_queue_max_segment_size(request_queue_t *queue, unsigned int max);
blk_queue_segment_boundary(request_queue_t *queue, unsigned long mask);
void blk_queue_dma_alignment(request_queue_t *queue, int mask);
void blk_queue_hardsect_size(request_queue_t *queue, unsigned short max);

Functions that set various queue parameters that control how requests are created for a particular device; the parameters are described in the Section
16.3.3.3.

#include
struct bio;

Low-level structure representing a portion of a block I/O request.

bio_sectors(struct bio *bio);
bio_data_dir(struct bio *bio);

Two macros that yield the size and direction of a transfer described by a bio structure.

bio_for_each_segment(bvec, bio, segno);

A pseudocontrol structure used to loop through the segments that make up a bio structure.

char *_ _bio_kmap_atomic(struct bio *bio, int i, enum km_type type);
void _ _bio_kunmap_atomic(char *buffer, enum km_type type);
_ _bio_kmap_atomic may be used to create a kernel virtual address for a given segment within a bio structure. The mapping must be undone with _ _bio_kunmap_atomic.
struct page *bio_page(struct bio *bio);
int bio_offset(struct bio *bio);
int bio_cur_sectors(struct bio *bio);
char *bio_data(struct bio *bio);
char *bio_kmap_irq(struct bio *bio, unsigned long *flags);
void bio_kunmap_irq(char *buffer, unsigned long *flags);

A set of accessor macros that provide access to the "current" segment within a bio structure.

void blk_queue_ordered(request_queue_t *queue, int flag);
int blk_barrier_rq(struct request *req);

Call blk_queue_ordered if your driver implements barrier requests—as it should.
The macro blk_barrier_rq returns a nonzero value if the current request is a barrier request.

int blk_noretry_request(struct request *req);

This macro returns a nonzero value if the given request should not be retried on errors.

int end_that_request_first(struct request *req, int success, int count);
void end_that_request_last(struct request *req);

Use end_that_request_first to indicate completion of a portion of a block I/O request. When that function returns 0, the request is complete and should be passed to end_that_request_last.

rq_for_each_bio(bio, request)

Another macro-implemented control structure; it steps through each bio that makes up a request.

int blk_rq_map_sg(request_queue_t *queue, struct request *req, struct
scatterlist *list);

Fills the given scatterlist with the information needed to map the buffers in the given request for a DMA transfer.

typedef int (make_request_fn) (request_queue_t *q, struct bio *bio);

The prototype for the make_request function.

void bio_endio(struct bio *bio, unsigned int bytes, int error);

Signal completion for a given bio. This function should be used only if your driver obtained the bio directly from the block layer via the make_request function.

request_queue_t *blk_alloc_queue(int flags);
void blk_queue_make_request(request_queue_t *queue, make_request_fn *func);

Use blk_alloc_queue to allocate a request queue that is used with a custom make_request function. That function should be set with blk_queue_make_request.

typedef int (prep_rq_fn) (request_queue_t *queue, struct request *req);
void blk_queue_prep_rq(request_queue_t *queue, prep_rq_fn *func);

The prototype and setup functions for a command preparation function, which can be used to prepare the necessary hardware command before the request is passed to your request function.

int blk_queue_init_tags(request_queue_t *queue, int depth, struct
blk_queue_tag *tags);
int blk_queue_resize_tags(request_queue_t *queue, int new_depth);
int blk_queue_start_tag(request_queue_t *queue, struct request *req);
void blk_queue_end_tag(request_queue_t *queue, struct request *req);
struct request *blk_queue_find_tag(request_queue_t *qeue, int tag);
void blk_queue_invalidate_tags(request_queue_t *queue);
Support functions for drivers using tagged command queueing.