Chapter

6
Writing Block Drivers

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-1

How block drivers are integrated into the I/O system Block driver entry points. Supporting multiple partitions on a physical disk. Managing removable media.

Writing Block Drivers

6.1

Introduction Block Drivers

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-2

Denition of a block driver. How block drivers differ from character drivers. How the le system libraries connect to block drivers. Overview of DOS and raw le systems.

Denition of Block Device

File-structured device such as hard or oppy disk drive. Random access capability. Data transferred only in multi-byte blocks.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-3

Block Device Overview

Devices Non-Block Drivers I/O System open creat read write File Systems ioctl close DOS delete -----Raw Application A B

Block Drivers

C D

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-4

I/O System calls (open, close, etc.) map directly to le system routines, not to driver routines. The le system makes calls to the block driver. This diagram was shown earlier. The point is to remind the students about the difference between character and block drivers by building on what they have already learned.

Overview of DOS File System

Compatible with MS-DOS through version 6.2 Hierarchical le system Uses disk space efciently by not requiring les to be contiguous (default) Optionally, permits creation of contiguous les for faster access Uses restrictive 8+3 le names (default) with the option of using UNIX style le names

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-5

Avoid using the RT-11 le system, as the DOS le system is more exible and tends to be faster. To create a contiguous le, use the FIOCONTIG ioctl command. To use UNIX style le naming, see the section Using Extended File Names in the dosFsLib manual pages. Using this option makes the le system no longer DOS compatible.

Overview of Raw File System

Handles entire logical disk (partition) as one le No directories or other organizational structure imposed on disk Fastest access

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-6

File System Conguration

Initialize the block driver
xxDrv();

Create the logical disk (partition)

pBlkDev = xxDevCreate (..);

Initialize a DOS le system

q

New le system
dosFsMkfsOptionsSet (options); /* if needed */ dosFsMkfs (fsName, pBlkDev);

or

dosFsConfigInit (pConfig, ...); dosFsDevInit (fsName, pBlkDev, pConfig); fd = open (fsName, O_RDWR, 0); ioctl (fd, DISKINIT, 0); close (fd);
Tornado Device Driver Workshop Copyright Wind River Systems

Wind River Systems

6-7

The dosFsMkfs( ) routine creates a le system with default parameters. Use dosFsDevInit( ) with an ioctl( ) FIODISKINT command to control parameters yourself. The dosFsCongInit( ) routine initializes a DOS_VOL_CONFIG structure, pCong in the example above. The structure may also be initialized directly. The dosFsMkfsOptionsSet( ) is optional. It allows setting VxWorksspecic options when creating le systems with dosFsMkfs( ).

Conguration (contd)
q

Existing le system
pVolDesc = dosFsDevInit (fsName, pBlkDev, NULL); /* Set volatile options, if needed */ dosFsVolOptionsSet (pVolDesc, options);

Initialize a Raw le system:

rawFsDevInit (fsName, pBlkDev);

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-8

Using dosFsDevInit( ) with a NULL third argument, causes the volume conguration to be read from the le system existing on the disk. The dosFsVolOptionsSet( ) above is optional. It allows setting VxWorks options which are not stored on disk such as DOS_OPT_CHANGENOWARN and DOS_OPT_AUTOSYNC.

Data Integrity
dosFsLib buffers FAT and directory information for efciency. To ush buffers use:
q q

dosFsVolUnmount( ) the FIOFLUSH ioctl command the DOS_OPT_AUTOSYNC ag

For removable media, consider setting the DOS_OPT_CHANGENOWARN ag

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-9

FAT (File Allocation Table) is the data structure used by DOS to manage disk blocks. The DOS_OPT_AUTOSYNC and DOS_OPT_CHANGENOWARN ags are set by bitwise ORing them into the dosvc_options eld of the DOS_VOL_CONFIG structure. The DOS_OPT_CHANGENOWARN ag:
q

Remounts the volume on each open( ) or creat( ) Sets the DOS_OPT_AUTOSYNC ag

Block Driver Overview

File Systems Drivers

DOS

DOS

DOS DOS Raw Raw

Raw

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-10

A driver may support multiple devices. Multiple le systems may reside on a single physical device. Driver has no information about le systems on the device. See the Local File Systems of the Programmers Guide for additional information.

Opening A File On A Block Device

open (/dos/myFile, O_READ, 0)
Device List

"/dos" 1

Driver Table
creat 0 1 2
dosFsCreate dosFsDelete dosFsOpen dosFsClose dosFsRead dosFsWrite dosFsIoctl

delete

open

close

read

write

ioctl

dosFsOpen (pDevHdr, /myFile, O_READ, 0)

Tornado Device Driver Workshop Copyright Wind River Systems Wind River Systems

6-11

Application calls for block devices invoke le system routines directly, not driver routines. The driver may or may not be called at all. There is no block driver open routine. The dosFsLib routines may make calls to the driver, including:
q q

xxStatusChk( ) routine (if provided) xxBlkRd( ) when a new open on removable media that has changed

The xxStatusChk( ) and xxBlkRd( ) will be discussed later.

Reading From A Block Device

read (fd, &buf, nBytes)
File Descriptor Table Driver Table
creat 0 1 2
dosFsCreate dosFsDelete dosFsOpen dosFsClose dosFsRead dosFsWrite dosFsIoctl

delete

open

close

read

write

ioctl

dosFsRead (devId, &buf, nBytes) xxBlkRd (pBlkDev, startBlk, nBlks, pBuf)

Tornado Device Driver Workshop Copyright Wind River Systems Wind River Systems

6-12

The block drivers read routine is called by the le system. Note that the request is specied in blocks, not bytes. The xxBlkRd( ) routine will be discussed in detail later.

Writing Block Drivers

Introduction 6.2 Block Drivers

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-13

Block driver initialization. The BLK_DEV structure. Block driver entry points.

Difference from Character Drivers

Drivers entry points are not entered in driver table (le systems entry points entered). Drivers device descriptor is not linked into device list (le systems descriptor linked into device list). Driver supports different entry points. Data transfers are counted in blocks, not bytes.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-14

Block Driver Initialization

STATUS xxDrv (args...)
Allocates and initializes driver data structures, if any. Takes driver-dependent arguments. Does not call iosDrvInstall( ).

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-15

Block drivers often have null xxDrv routines. E.g.:

STATUS fooDrv (void) { return (OK); }

Block Device Creation

BLK_DEV * xxDevCreate (args...)
Denes logical disk (partition). Takes driver-dependent arguments. Does not call iosDevAdd( ). Must return a pointer to a device descriptor for which rst member is a BLK_DEV structure or NULL on error. Must initialize members of the BLK_DEV structure.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-16

Major differences between block and character xxDevCreate( ):

q q

The rst argument is not the device name. The block driver does not call iosDevAdd( ). A character driver returns STATUS; a block driver returns a pointer to a BLK_DEV structure.

The le system is responsible for adding the device descriptor to the device list. The le systems xxDevInit() routine denes the logical devices name. The block drivers xxDevCreate() is preparing a partition (which may be the entire disk) to hold a le system. The pointer to a BLK_DEV structure returned is used by the le system routines to connect the le system to the physical partition.

BLK_DEV Structure
bd_blkRd bd_blkWrt bd_ioctl bd_reset bd_statusChk bd_removable bd_nBlocks Address of block drivers read routine Address of block drivers write routine Address of block drivers ioctl routine Address of block drivers reset routine (optional) Address of block drivers routine to check disk status (optional) if device uses removable media, otherwise FALSE
TRUE

Size of partition in blocks

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-17

The BLK_DEV structure serves the same role as the driver table does for character drivers, i.e. provides the driver entry points. BLK_DEV structure is dened in blkIo.h. Read, write and ioctl routines are required in a block driver. Note that bd_nBlocks is the size of the partition, i.e. logical device, not the physical device. Discuss the reset and statusChk routines later.

BLK_DEV Structure (contd)

bd_bytesPerBlk bd_blksPerTrack bd_nHeads bd_retry bd_mode bd_readyChanged Number of bytes per block Number of blocks per track Number of heads Retry count for I/O errors Device mode: O_RDONLY or O_RDWR Set to TRUE

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-18

Include ioLib.h and blkIo.h Discuss the readyChanged ag later.

Supporting Multiple Partitions

To support multiple le systems on the same physical device, you must save the partition offset. Example implementation:
typedef struct { BLK_DEV blkDev; int partitionOffset; } MY_DEV; BLK_DEV * myDevCreate (int offset, int size, ...) { ... pMyDev->partitionOffset = offset; return (&pMyDev->blkDev); }

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-19

The above code assumes that pMyDev is the address of a MY_DEV structure. The partitionOffset must then be used by the xxBlkRd( ) and xxBlkWrt( ) routines to perform I/O in the correct partition. The number of blocks in the partition is part of the BLK_DEV structure (bd_nBlocks).

Supporting Multiple Partitions

File System A Requests Request A3 Request A2 Request A1 Block Driver Requests File System B Requests Request B3 Request B2 Request B1

A B
6-20

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

Requests on the same le system are synchronous:

q q

Request A2 will not be made to the driver until A1 is completed Request A3 will not be made to the driver until A2 is completed Request B1 may occur before, during or after A1. Request B2 may occur before, during or after A1 (but it will only occur after B1 is completed) Use mutex semaphores to insure exclusive access, or Allow only one partition on a physical device

Requests from different le systems are asynchronous:

q q

Typically, block drivers either:

q q

Block Read/Write Routines

STATUS xxBlkRd (pDev, startBlk, nBlks, pBuf) STATUS xxBlkWrt (pDev, startBlk, nBlks, pBuf)
pDev startBlk nBlks pBuf Pointer to BLK_DEV structure Block number to begin reading or writing Number of blocks to read or write Pointer to buffer to put data read or get data to write
Copyright Wind River Systems Wind River Systems

Tornado Device Driver Workshop

6-21

Must supply a xxBlkWrt( ) routine. For read-only devices, just return ERROR. Must supply a xxBlkRd( ) routine. For write-only devices, just return ERROR. If you are supporting multiple le systems on the same device, remember that the startBlk is relative to the beginning of the partition (logical disk, not physical). The rst block is block number zero (not one).

Block Ioctl Routine

ioctl ( ) dosFsIoctl ( ) xxIoctl ( )

Application

File System

Driver

int xxIoctl (pBlkDev, cmd, arg)

Same as non-block driver ioctl( ). If cmd is not recognized by the le system, the drivers xxIoctl( ) is called. Unknown cmds should be failed by setting errno to S_ioLib_UNKNOWN_REQUEST and returning ERROR.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-22

An xxIoctl( ) must be supplied, even if it does nothing but fail requests as above. The ioctl commands supported by dosFsLib and rawFsLib are documented in the respective man pages. The drivers ioctl commands should be dened to be numbers above 0x1000 to avoid conicts with the le system ioctl commands.

Block Reset Routine

STATUS xxReset (pBlkDev)
If provided, called by le system library when:
q q

File system is rst mounted on device. After a failed read or write and before a retry.

Return STATUS.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-23

Note that a driver may control more than one device. Only the device in question (identied by pBlkDev) should be reset when this routine is called. The xxReset( ) routine is optional.

Block Status-Check Routine

STATUS xxStatusChk (pBlkDev)
Called by le system for each open( ) or creat( ) on the device. Should return STATUS:
q q

If ERROR returned, open( ) will fail. When failing a request set errno to indicate reason. If media changed, set bd_readyChanged to TRUE. Return OK.

Purpose is to handle removable media:

q q

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-24

Another use of xxStatusChk( ) is to check for write-protected media. If write-protected, set bd_mode to O_RDONLY. Setting bd_readyChanged is equivalent to executing either: the le system ready-change routine, e.g. dosFsReadyChanged(), or the le systems ioctl() with the FIODISKCHANGE command. It remounts the le system. This routine was designed to handle removable media. An example of why you might want to fail a xxStatusChk() call is if no disk is in the disk drive or your device is hung. Modifying bd_mode lets the le system fail the open() if the user requested O_WRONLY or O_RDWR access.

Handling Removable Media

Whenever the driver identies that the user has changed media, the bd_readyChanged ag should be set to TRUE. When the le system nds the ag set, it remounts the le system. The driver should never reset bd_readyChanged.

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-25

Summary
Block driver initialization xxDrv( ) xxDevCreate( ) returns a BLK_DEV pointer Do not install driver in driver table or add device to the device list.
q q

Block driver entry points

q q

xxBlkRd( ) xxBlkWrt( ) xxIoctl( ) xxReset( ) xxStatusChk( )

Copyright Wind River Systems

Tornado Device Driver Workshop

Wind River Systems

6-26

Summary
Supporting partitions
q q

Store partition offset in device descriptor In xxBlkRd and xxBlkWrt routines, add the partition offset to the start block to determine region to read or write Write a xxStatusChk routine Set bd_readyChanged eld in the BLK_DEV structure when media has changed Update bd_mode to O_RDONLY or O_RDWR

Removable Media
q q

Tornado Device Driver Workshop

Copyright Wind River Systems

Wind River Systems

6-27