Constants and Defined Types

Declared in: be/drivers/Drivers.h
more...

This section covers constants and types defined for use by kernel drivers and modules.

Constants

Current Driver API Version

#define B_CUR_DRIVER_API_VERSION N

The B_CUR_DRIVER_API_VERSION constant indicates what version of the driver API your driver will be built to.
See also: "Symbols Drivers Export"

Driver Control Opcodes

Constant Meaning
B_GET_DEVICE_SIZE Returns a size_t indicating the device size in bytes.
B_SET_DEVICE_SIZE Sets the device size to the value pointed to by data.
B_SET_NONBLOCKING_IO Sets the device to use nonblocking I/O.
B_SET_BLOCKING_IO Sets the device to use blocking I/O.
B_GET_READ_STATUS Returns true if the device can read without blocking, otherwise false.
B_GET_WRITE_STATUS Returns true if the device can write without blocking, otherwise false.
B_GET_GEOMETRY Fills out the specified device_geometry structure to describe the device.
B_GET_DRIVER_FOR_DEVICE Returns the path of the driver executable handling the device.
B_GET_PARTITION_INFO Returns a partition_info structure for the device.
B_SET_PARTITION Creates a user-defined partition. data points to a partition_info structure.
B_FORMAT_DEVICE Formats the device. data should point to a boolean value: If true, the device is formatted low-level. If it's false, the formatting is <<??>>
B_EJECT_DEVICE Ejects the device.
B_GET_ICON Fills out the specified device_icon structure to describe the device's icon.
B_GET_BIOS_GEOMETRY Fills out a device_geometry structure to describe the device as the BIOS sees it.
B_GET_MEDIA_STATUS Gets the status of the media in the device by placing a status_t at the location pointed to by data. (See the list below.)
B_LOAD_MEDIA Loads the media.
B_GET_BIOS_DRIVE_ID Returns the BIOS ID for the device.
B_SET_UNINTERRUPTABLE_IO Prevents control-C from interrupting I/O.
B_SET_INTERRUPTABLE_IO Allows control-C to interrupt I/O.
B_FLUSH_DRIVE_CACHE Flushes the drive's cache.
B_GET_NEXT_OPEN_DEVICE Iterates through open devices; data points to an open_device_iterator.
B_ADD_FIXED_DRIVER For internal use only.
B_REMOVE_FIXED_DRIVER For internal use only.
B_AUDIO_DRIVER_BASE Base for codes in audio_driver.h.
B_MIDI_DRIVER_BASE Base for codes in midi_driver.h.
B_JOYSTICK_DRIVER_BASE Base for codes in joystick.h.
B_GRAPHIC_DRIVER_BASE Base for codes in graphic_driver.h.
B_DEVICE_OP_CODES_END End of Be-defined control IDs.

B_GET_MEDIA_STATUS returns one of these values in data:

B_NO_ERROR. The media is ready.

B_DEV_NO_MEDIA. No media in the device

B_DEV_NOT_READY. The device isn't ready.

B_DEV_MEDIA_CHANGED. The media changed since the time that the device was opened, or since the time of the last B_GET_MEDIA_STATUS request.

B_DEV_MEDIA_CHANGE_REQUEST. The user wants to remove the media.

B_DEV_DOOR_OPEN. The drive "door" is open.

Defined Types

device_geometry

typedef struct {
      uint32 bytes_per_sector;
      uint32 sectors_per_track;
      uint32 cylinder_count;
      uint32 head_count;
      uchar device_type;
      bool removable;
      bool read_only;
      bool write_once;
      } device_geometry

The device_geometry structure is returned by the B_GET_GEOMETRY driver control function. Its fields are:

bytes_per_sector indicates how many bytes each sector of the disk contains.

sectors_per_track indicates how many sectors each disk track contains.

cylinder_count indicates the number of cylinders the disk contains.

head_count indicates how many heads the disk has.

device_type specifies the type of device; there's a list of device type definitions below.

removable is true if the device's media can be removed from the drive, and is false otherwise.

read_only is true if the media is read-only (such as CD-ROM), or false if the media can be both read from and written .

write_once is true if the media can only be written to once (such as CD-recordable), or false if there's no limit to the number of times the media can be written to.

If you need to compute the total size of the device in bytes, you can obtain this figure using the following simple formula:

disk_size = geometry.cylinder_count * geometry.sectors_per_track * geometry.head_count * geometry.bytes_per_sector;

The device type returned in device_type is one of:

B_DISK. Hard disk, floppy disk, etc.

B_TAPE. Tape drive.

B_PRINTER. Printer.

B_CPU. CPU device.

B_WORM. Write-once, read-many device (such as CD-recordable).

B_CD. CD-ROM.

B_SCANNER. Scanner.

B_OPTICAL. Optical device

B_JUKEBOX. Jukebox device

B_NETWORK. Network device

device_hooks

typedef struct {
      device_open_hook open;
      device_close_hook close;
      device_free_hook free;
      device_control_hook control;
      device_read_hook read;
      device_write_hook write;
      device_select_hook select;
      device_deselect_hook deselect;
      device_readv_hook readv;
      device_writev_hook writev;
      } device_hooks

This structure is used by device drivers to export their function hooks to the kernel.

device_icon

typedef struct {
      int32 icon_size;
      void *icon_data;
      } device_icon

When you want to obtain an icon for a specific device, call ioctl() on the open device, specifying the B_GET_ICON opcode. Pass in data a pointer to a device_icon structure in which icon_size indicates the size of icon you want and icon_data points to a buffer large enough to receive the icon's data.
icon_size can be either B_MINI_ICON, in which case the buffer pointed to by icon_data should be large enough to receive a 16x16 8-bit bitmap (256-byte), or B_LARGE_ICON, in which case the buffer should be large enough to receive a 32x32 8-bit bitmap (1024-byte). The most obvious way to set up this buffer would be to create a BBitmap of the appropriate size and color depth and use its buffer, like this:

BBitmap bits(BRect(0, 0, B_MINI_ICON-1, B_MINI_ICON-1, 0, B_CMAP8)); device_icon iconrec; iconrec.icon_size = B_MINI_ICON; iconrec.icon_data = bits.Bits(); status_t err = ioctl(dev_fd, B_GET_ICON, &iconrec); if (err == B_OK) {    /* enjoy the icon */    ...    view->DrawBitmap(bits); } else {    /* I don't like icons anyway */    }

driver_path

typedef char driver_path[256];

Used by the B_GET_DRIVER_FOR_DEVICE control function to return the pathname of the specified device.

open_device_iterator

typedef struct {
      uint32 cookie;
      char device[256];
      } open_device_iterator

Used by the B_GET_NEXT_OPEN_DEVICE control function. The first time you call this function, your open_device_iterator should have cookie initialized to 0. Then just keep calling it over and over; each time you'll get the name of the next open device. When an error is returned, you're done.

partition_info

typedef struct {
      off_t offset;
      off_t size;
      int32 logical_block_size;
      int32 session;
      int32 partition;
      char device[256];
      } partition_info

The partition_info structure describes a disk partition, and is used by the B_GET_PARTITION_INFO and B_SET_PARTITION control commands.
The fields are:

offset is the offset, in bytes, from the beginning of the disk to the beginning of the partition.

size is the size, in bytes, of the partition.

logical_block_size is the block size with which the file system was written to the partition.

session and partition are the session and partition ID numbers for the partition.

device is the pathname of the physical device on which the partition is located.

The Be Book

Drivers

Drivers Index

Stephen van Egmond

Reader Comments

After writing my AGMSDeviceTest program (see BeBits.com), I figured out what the standard IOCtl operations do and added descriptions. Here's the list:

Standard IOCtl Codes and Their Meanings
Name IOCtl # Data Size Description

B_GET_DEVICE_SIZE 1 4 Returns a size_t in *Data with the device size in bytes. Obsolete, not 64 bits! Use B_GET_GEOMETRY instead and do the 64 bit math.

B_SET_DEVICE_SIZE 2 4 Sets the device size (in bytes) to the size_t value pointed to by *Data. Probably obsolete since it's only 32 bits. Good for RAM disks I guess, since they use 32 bit pointers.

B_SET_NONBLOCKING_IO 3 0 Sets the device to use nonblocking I/O (calls return immediately rather than waiting for the IO operation to complete).

B_SET_BLOCKING_IO 4 0 Sets the device to use blocking I/O (calls to the driver return only once the operation is complete).

B_GET_READ_STATUS 5 1 Returns a true bool in *Data if the device can read without blocking, otherwise sets *Data to false. I presume for blocking mode, this means true if there is some data ready in the buffers for you to read.

B_GET_WRITE_STATUS 6 1 Returns a true bool in *Data if the device can write without blocking, otherwise sets *Data to false. I presume for blocking mode this means true if there are some empty intermediate buffers ready to receive your data.

B_GET_GEOMETRY 7 20 Gets the device geometry (sector size / sectors / tracks / heads) and other characteristics of the device and writes it into the device_geometry structure the caller provided at *Data. If media isn't present, sizes could be zero.

B_GET_DRIVER_FOR_DEVICE 8 256 Writes the path of the driver executable handling this device into the buffer the caller provided in *Data. Note that the header defines a buffer smaller than B_PATH_NAME_LENGTH (1024) for some reason.

B_GET_PARTITION_INFO 9 284 Returns a partition_info structure for the device in *Data, fortunately it uses 64 bit values. The DevFS does this for you, making fake devices for partitions, so the driver writer doesn't have to handle this message. Only works when you use it on the partition's file: if your device is */raw, then */S_P (S is session, P is partition) are the partition files. For example */0_0 for the first partition, */0_1 for the second and so on.

B_SET_PARTITION 10 284 Finishes setting up a user-defined partition. *Data points to a partition_info structure, fortunately with 64 bit values. The DevFS makes fake devices for partitions, when you "creat()" the */S_P file, where S is a session number (mostly for multisession CD-ROMs, else 0) and P is the partition number (0 & upwards). Then use this IOCtl operation to set the size and offset of the partition, with the device name field set to your */raw device. Note that sizes may have to be a multiple of cylinder size. See the article http://www-classic.be.com/aboutbe/benewsletter/volume_II/Issue23.html for details.

B_FORMAT_DEVICE 11 1 Low level formats the device. This can erase everything, watch out! *Data points to a bool: true for full format, false for a quick format (device should test for presence of an existing format by attempting to read the first & last sectors, then do a full format if errors were encountered).

B_EJECT_DEVICE 12 0 Ejects the media from the device. For CD-ROMs this means opening the tray or otherwise popping out the CD. You can guess what this does for Internet toasters.

B_GET_ICON 13 8 Gets a graphic icon from the device. The device will use the device_icon structure pointed to by *Data to get the size desired (square icons this many pixels wide, usually 16 or 32) and the buffer to write the icon bitmap to (B_CMAP8 style bitmap).

B_GET_BIOS_GEOMETRY 14 20 Fills out the device_geometry structure pointed to by *Data with a description of the device as the BIOS sees it. I presume it's mostly for disk type devices used during bootup, also may be needed when making partitions on a disk device.

B_GET_MEDIA_STATUS 15 4 Writes the media status (ready, empty drive, door open, ...) into the status_t pointed to by *Data. Also clears the media changed flag, so read / write calls will start working again rather than returning B_DEV_MEDIA_CHANGED.

B_LOAD_MEDIA 16 0 Loads the media into the drive. For CD-ROMs this closes the tray or sucks in the CD. May also be useful for Internet toaster appliances. Also see is_computer_on_fire().

B_GET_BIOS_DRIVE_ID 17 1 Returns the BIOS ID for disks in a single byte. $80 is usually the C: boot drive.

B_SET_UNINTERRUPTABLE_IO 18 0 Prevents control-C and I presume other signals from interrupting I/O (well, maybe not SIGTERM?). The call to read/write will return when it is finished, not any earlier.

B_SET_INTERRUPTABLE_IO 19 0 Allows control-C and I presume other signals to interrupt I/O. I presume that means that a call to read/write which is waiting for data can return with partial data or a B_INTERRUPTED error code or both (probably best to not do both since the C read() API can't represent both).

B_FLUSH_DRIVE_CACHE 20 0 Flushes cached data from internal caches and lower level hardware caches to the actual media, then returns. This guarantees that your data has actually been written. Useful to do just before shutting off the power.

B_GET_NEXT_OPEN_DEVICE 1000 260 Iterates through open devices. *Data points to an open_device_iterator structure which gives you a name for each open thing. Set the cookie to zero to start. Seems to only work if you apply it to /dev, giving you a list of all loaded devices.

B_DEVICE_OP_CODES_END 9999 0 User defined control codes follow this one.

--Alexander G. M. Smith on December 26, 2000

Standard IOCtl Codes and Their Meanings
Name	IOCtl #	Data Size	Description
B_GET_DEVICE_SIZE	1	4	Returns a size_t in *Data with the device size in bytes. Obsolete, not 64 bits! Use B_GET_GEOMETRY instead and do the 64 bit math.
B_SET_DEVICE_SIZE	2	4	Sets the device size (in bytes) to the size_t value pointed to by *Data. Probably obsolete since it's only 32 bits. Good for RAM disks I guess, since they use 32 bit pointers.
B_SET_NONBLOCKING_IO	3	0	Sets the device to use nonblocking I/O (calls return immediately rather than waiting for the IO operation to complete).
B_SET_BLOCKING_IO	4	0	Sets the device to use blocking I/O (calls to the driver return only once the operation is complete).
B_GET_READ_STATUS	5	1	Returns a true bool in Data if the device can read without blocking, otherwise sets Data to false. I presume for blocking mode, this means true if there is some data ready in the buffers for you to read.
B_GET_WRITE_STATUS	6	1	Returns a true bool in Data if the device can write without blocking, otherwise sets Data to false. I presume for blocking mode this means true if there are some empty intermediate buffers ready to receive your data.
B_GET_GEOMETRY	7	20	Gets the device geometry (sector size / sectors / tracks / heads) and other characteristics of the device and writes it into the device_geometry structure the caller provided at *Data. If media isn't present, sizes could be zero.
B_GET_DRIVER_FOR_DEVICE	8	256	Writes the path of the driver executable handling this device into the buffer the caller provided in *Data. Note that the header defines a buffer smaller than B_PATH_NAME_LENGTH (1024) for some reason.
B_GET_PARTITION_INFO	9	284	Returns a partition_info structure for the device in Data, fortunately it uses 64 bit values. The DevFS does this for you, making fake devices for partitions, so the driver writer doesn't have to handle this message. Only works when you use it on the partition's file: if your device is /raw, then /S_P (S is session, P is partition) are the partition files. For example /0_0 for the first partition, */0_1 for the second and so on.
B_SET_PARTITION	10	284	Finishes setting up a user-defined partition. Data points to a partition_info structure, fortunately with 64 bit values. The DevFS makes fake devices for partitions, when you "creat()" the /S_P file, where S is a session number (mostly for multisession CD-ROMs, else 0) and P is the partition number (0 & upwards). Then use this IOCtl operation to set the size and offset of the partition, with the device name field set to your */raw device. Note that sizes may have to be a multiple of cylinder size. See the article http://www-classic.be.com/aboutbe/benewsletter/volume_II/Issue23.html for details.
B_FORMAT_DEVICE	11	1	Low level formats the device. This can erase everything, watch out! *Data points to a bool: true for full format, false for a quick format (device should test for presence of an existing format by attempting to read the first & last sectors, then do a full format if errors were encountered).
B_EJECT_DEVICE	12	0	Ejects the media from the device. For CD-ROMs this means opening the tray or otherwise popping out the CD. You can guess what this does for Internet toasters.
B_GET_ICON	13	8	Gets a graphic icon from the device. The device will use the device_icon structure pointed to by *Data to get the size desired (square icons this many pixels wide, usually 16 or 32) and the buffer to write the icon bitmap to (B_CMAP8 style bitmap).
B_GET_BIOS_GEOMETRY	14	20	Fills out the device_geometry structure pointed to by *Data with a description of the device as the BIOS sees it. I presume it's mostly for disk type devices used during bootup, also may be needed when making partitions on a disk device.
B_GET_MEDIA_STATUS	15	4	Writes the media status (ready, empty drive, door open, ...) into the status_t pointed to by *Data. Also clears the media changed flag, so read / write calls will start working again rather than returning B_DEV_MEDIA_CHANGED.
B_LOAD_MEDIA	16	0	Loads the media into the drive. For CD-ROMs this closes the tray or sucks in the CD. May also be useful for Internet toaster appliances. Also see is_computer_on_fire().
B_GET_BIOS_DRIVE_ID	17	1	Returns the BIOS ID for disks in a single byte. $80 is usually the C: boot drive.
B_SET_UNINTERRUPTABLE_IO	18	0	Prevents control-C and I presume other signals from interrupting I/O (well, maybe not SIGTERM?). The call to read/write will return when it is finished, not any earlier.
B_SET_INTERRUPTABLE_IO	19	0	Allows control-C and I presume other signals to interrupt I/O. I presume that means that a call to read/write which is waiting for data can return with partial data or a B_INTERRUPTED error code or both (probably best to not do both since the C read() API can't represent both).
B_FLUSH_DRIVE_CACHE	20	0	Flushes cached data from internal caches and lower level hardware caches to the actual media, then returns. This guarantees that your data has actually been written. Useful to do just before shutting off the power.
B_GET_NEXT_OPEN_DEVICE	1000	260	Iterates through open devices. *Data points to an open_device_iterator structure which gives you a name for each open thing. Set the cookie to zero to start. Seems to only work if you apply it to /dev, giving you a list of all loaded devices.
B_DEVICE_OP_CODES_END	9999	0	User defined control codes follow this one.

Add a comment

Constant	Meaning
`B_GET_DEVICE_SIZE`	Returns a `size_t` indicating the device size in bytes.
`B_SET_DEVICE_SIZE`	Sets the device size to the value pointed to by data.
`B_SET_NONBLOCKING_IO`	Sets the device to use nonblocking I/O.
`B_SET_BLOCKING_IO`	Sets the device to use blocking I/O.
`B_GET_READ_STATUS`	Returns `true` if the device can read without blocking, otherwise `false`.
`B_GET_WRITE_STATUS`	Returns `true` if the device can write without blocking, otherwise `false`.
`B_GET_GEOMETRY`	Fills out the specified `device_geometry` structure to describe the device.
`B_GET_DRIVER_FOR_DEVICE`	Returns the path of the driver executable handling the device.
`B_GET_PARTITION_INFO`	Returns a `partition_info` structure for the device.
`B_SET_PARTITION`	Creates a user-defined partition. data points to a `partition_info` structure.
`B_FORMAT_DEVICE`	Formats the device. data should point to a boolean value: If `true`, the device is formatted low-level. If it's `false`, the formatting is <<??>>
`B_EJECT_DEVICE`	Ejects the device.
`B_GET_ICON`	Fills out the specified `device_icon` structure to describe the device's icon.
`B_GET_BIOS_GEOMETRY`	Fills out a `device_geometry` structure to describe the device as the BIOS sees it.
`B_GET_MEDIA_STATUS`	Gets the status of the media in the device by placing a `status_t` at the location pointed to by data. (See the list below.)
`B_LOAD_MEDIA`	Loads the media.
`B_GET_BIOS_DRIVE_ID`	Returns the BIOS ID for the device.
`B_SET_UNINTERRUPTABLE_IO`	Prevents control-C from interrupting I/O.
`B_SET_INTERRUPTABLE_IO`	Allows control-C to interrupt I/O.
`B_FLUSH_DRIVE_CACHE`	Flushes the drive's cache.
`B_GET_NEXT_OPEN_DEVICE`	Iterates through open devices; data points to an `open_device_iterator`.
`B_ADD_FIXED_DRIVER`	For internal use only.
`B_REMOVE_FIXED_DRIVER`	For internal use only.
`B_AUDIO_DRIVER_BASE`	Base for codes in audio_driver.h.
`B_MIDI_DRIVER_BASE`	Base for codes in midi_driver.h.
`B_JOYSTICK_DRIVER_BASE`	Base for codes in joystick.h.
`B_GRAPHIC_DRIVER_BASE`	Base for codes in graphic_driver.h.
`B_DEVICE_OP_CODES_END`	End of Be-defined control IDs.