The 2.4 kernel gendisk
structure is used almost as an
afterthought; its main purpose is to help in keeping track of disk
partitions. In 2.6, the gendisk
is at the core of the block
subsystem; if you need to work with or find something out about a disk,
probably has what you need.
This article will cover the details of the gendisk
a disk driver's perspective. If you have not already read them, a quick
look at the LWN block driver overview
and simple block driver
articles is probably
The best way of looking at the contents of a gendisk
from a block driver's point of view is to examine what that driver must do
to set the structure up in the first place. If your driver makes a disk (or
disk-like) device available to the system, it will have to provide an
structure. (Note, however, that it is
necessary - or correct - to set up gendisk
for disk partitions).
The first step is to create the gendisk structure itself; the
function you need is alloc_disk() (which is declared in
struct gendisk *alloc_disk(int minors);
The argument minors is the maximum number of minor numbers that
this disk can have. Minor numbers correspond to partitions, of course
(except the first, which is the "whole disk" device), so the value passed
here controls the maximum number of partitions. If a single minor number
the device cannot be partitioned at all. The return value is a pointer to
the gendisk structure; the allocation can fail, so this value
should always be checked against NULL before proceeding.
There are several fields of the gendisk structure which must be
initialized by the block driver. They include:
- int major;
- The major number of this device; either a static major assigned to a
specific driver, or one that was obtained dynamically from
- int first_minor;
- The first minor device number corresponding to this disk. This number
will be determined by how your driver divides up its minor number
- char disk_name;
- The name of this disk (i.e. hda). This name is used in places
like /proc/partitions and in creating a sysfs directory for
- struct block_device_operations *fops;
- The device operations (open, release, ioctl, media_changed, and
revalidate_disk) for this device. Each disk has its own set of
operations in 2.6.
- struct request_queue *queue;
- The request queue which will handle the list of pending operations for
this disk. The queue must be created and initialized separately.
- int flags;
- A set of flags controlling the management of this device. They
include GENHD_FL_REMOVABLE for removable devices,
GENHD_FL_CD for CDROM devices, and
GENHD_FL_DRIVERFS which certainly means something interesting,
but which is not actually used anywhere.
- void *private_data;
- This field is reserved for the driver; the rest of the block subsystem
will not touch it. Usually it holds a pointer to a driver-specific
data structure describing this device.
The gendisk structure also holds the size of the disk, in
sectors. As part of the initialization process, the driver should set that
void set_capacity(struct gendisk *disk, sector_t size);
The size value should be in 512-byte sectors, even if the hardware
sector size used by your device is different.
For removable disks, setting its capacity to zero indicates to the block
subsystem that there is currently no media present in the device.
Once you have your gendisk
structure set up, you have to add it to
the list of active disks; that is done with:
void add_disk(struct gendisk *disk);
After this call, your device is active. There are a few things worth
keeping in mind about add_disk():
- add_disk() can create I/O to the device (to read partition
tables and such). You should not call add_disk() until your
driver is sufficiently initialized to handle requests.
- If you are calling add_disk() in your driver initialization
routine, you should not fail the initialization process after the
- The call to add_disk() increments the disk's reference count;
if the disk structure is ever to be released, the driver is
responsible for decrementing that count (with put_disk()).
Should you need to remove a disk from the system, that is accomplished
void del_gendisk(struct gendisk *disk);
This function cleans up all of the information associated with the given
disk, and generally removes it from the system. After a call to
del_gendisk(), no more operations will be sent to the given
device. Your driver's reference to the gendisk object remains,
though; you must explicitly release it with:
void put_disk(struct gendisk *disk);
That call will cause the gendisk structure to be freed, as long as
no other part of the kernel retains a reference to it.
Should you need to set a disk into a read-only mode, use:
void set_disk_ro(struct gendisk *disk, int flag);
If flag is nonzero, all partitions on the disk will be marked
read-only. The kernel can track read-only status individually for each
partition, but no utility function has been exported to manipulate that
status for single partitions.
Partition management is handled within the block subsystem in 2.6; drivers
need not worry about partitions at all. Should the need arise, the
functions add_partition() and delete_partition() can be
used to manipulate the (in-kernel) partition table directly. These
functions are used in the generic block ioctl() code; there should
be no need for a block driver to call them directly.
Registering block device number ranges
A call to add_disk()
implicitly allocates the a set of minor
numbers (under the given major number) from first_minor
. If your driver must only respond to
operations to disks that exist at initialization time, there is no need to
worry further about number allocation. Even the traditional call to
is optional, and may be removed soon. Some
drivers, however, need to be able to claim responsibility for a larger
range of device numbers at initialization time.
If this is your case, the answer is to call blk_register_region(),
which has this rather involved prototype:
void blk_register_region(dev_t dev,
unsigned long range,
struct module *module,
struct kobject *(*probe)(dev_t, int *, void *),
int (*lock)(dev_t, void *),
Here, dev is a device number (created with MKDEV())
containing the major and first minor number of the region of interest;
range is the number of minor numbers to allocate, module
is the loadable module (if any) containing the driver, probe is a
driver-supplied function to probe for a single disk, lock is a
driver-supplied locking function, and data is a driver-private
pointer which is passed to probe() and lock().
When blk_register_region() is called, it simply makes a note of
the desired region and returns. Note that there can be more than one
registration within a specific region! At lookup time, the most "specific"
registration (the one with the smallest range) wins.
At some point in the future, an attempt
may be made to access a device number within the allocated region. At that
point, there will be a call to the lock() function (if it was not
passed as NULL) with the device
number of interest. If lock() succeeds, probe() will be
called to find the specific disk of interest. The full prototype of the
probe function is:
struct kobject *(*probe)(dev_t dev, int *partition, void *data);
Here, dev is the device number of interest, partition is
a pointer to a partition number (sort of), and data is the
driver-private pointer passed to blk_register_region(). The
partition number is actually just the offset into the allocated range; it's
the minor number from dev with the beginning of the range
The probe() function should attempt to identify a specific
gendisk structure which corresponds to the requested number. If
it is successful, it should return a pointer to the kobject
structure contained within the gendisk. Kobjects are covered in
a separate article; for all, all you really
need to know is that you should call get_disk() with the
gendisk structure as the argument, and return the value from
get_disk() to the caller.
The probe() function can also modify the
partition number so that it corresponds to the actual partition offset in
the returned device. If the function cannot handle the request at all, it
can return NULL.
Some probe() functions do not, themselves, locate and initialize
the device of interest. Instead, they call some other function to set in
motion that whole process. For example, a number of probe()
functions simply call request_module() in an attempt to load a
module which can handle the device. In this mode of operation, the
function should return NULL, which will cause the block layer to
look at the device number allocations one more time. If a "better"
allocation (with a smaller range) has happened in the mean time, the
probe() function for the new driver will be called. So, for
example, if a module is loaded which allocates a smaller device number
range corresponding to the devices it actually implements, its
probe() routine will be called on the next iteration.
Of course, there is the usual assocated unregister function:
void blk_unregister_region(dev_t dev, unsigned long range);
The next step
Once you have a handle on how the gendisk structure works, the
next thing to do is to learn about BIO
to post comments)