Device Identifiers

Device ids are allocated sequentially by BlockDevices as devices are registered, starting from 1. The value 0 (DeviceId_Invalid in BlockDevices.h) is never allocated to a real device, and is used both to mean "no parent device" in a device's information block, and to mean "start enumeration from the beginning" in the enumeration SWIs.

A device id remains valid, and continues to refer to the same device, for as long as that device stays registered. Deregistering a device (SWI BlockDevice_Deregister) invalidates its id permanently; the id is not reused. Rescanning a device (SWI BlockDevice_Rescan) does not change its id.

Device Information Block

Every device is described by a device information block, a structure of type device_info_t defined in BlockDevices.h. A pointer to this structure is what is passed to a driver at registration, and what is returned by SWI BlockDevice_Info, SWI BlockDevice_Enumerate and SWI BlockDevice_EnumerateChildren.

BlockDevices.h is built for both 32-bit and 64-bit RISC OS. The name and description fields are ordinary pointers, and block_count is always a genuine 64-bit value; the byte offset of every field after the first pointer therefore differs between a 32-bit build, where pointers are 4 bytes, and a 64-bit build, where they are 8 bytes. Code that needs the structure's exact in-memory layout should always do so via the supplied header rather than by assuming fixed byte offsets.

Device, Interface, Connection and Media Types

A device's classification is recorded along four independent axes. Each is a small enumeration:

Each of the four enumerations also defines a value of -1, named Parent in each case (for example BlockDevice_DeviceType_Parent). This value is only meaningful when registering a new device: it tells BlockDevices to copy that particular classification from the device's parent, rather than have the registering driver state it explicitly. If Parent is used but the device has no valid parent - either because parent_device is 0, or because it does not refer to a currently registered device - registration fails with Error_RegisterFailed.

Device Flags

The flags field of the device information block is a bit mask:

Transfer Block

Read, write and verify requests describe the data to be transferred using a transfer block, of type transfer_block_t:

The transfer block is passed by reference and is updated in place by the device driver, even when the transfer fails partway through, so that the caller can see exactly how much of the request was actually completed.

FIXME: The bounds check applied to a transfer block before it is passed to a device driver currently differs between 32-bit and 64-bit builds of this module: one treats "count" consistently as a number of blocks, as documented above and in the header, while the other divides it by the device's block size as though it were a byte count. Until this is resolved, do not rely on a request being accepted or rejected identically across architectures right at the edge of a device's capacity.

Device Naming

When a device is registered, BlockDevices takes the name supplied in the device information block and appends a sequence number to it, separated by a hyphen, to guarantee that the name presented to client software is unique.

If device_index is non-zero, that value is used directly as the sequence number. If it is zero, BlockDevices allocates the next unused sequence number itself, counting separately for each combination of supplied name and parent device; the first device registered with a given name under a given parent is given sequence number 1, the second is given sequence number 2, and so on, regardless of the order in which they are later deregistered.

A registering driver that wants its device to appear with a name reflecting its position in the device hierarchy (see Overview) is responsible for constructing that name itself before calling SWI BlockDevice_Register, typically by reading its parent's registered name with SWI BlockDevice_Info and appending an identifying component to it. BlockDevices does not build this hierarchy on the driver's behalf, and does not require the name to start with a / character or to contain any particular separator.

A device information block with no name at all (a null pointer) is rejected by SWI BlockDevice_Register, which fails with Error_RegisterFailed; an empty string is accepted, and produces a name consisting only of a hyphen and the sequence number.

Enumerating registered devices

The following walks every device currently registered, printing its id and description:

#include "kernel.h"
#include "swis.h"
#include "BlockDevices.h"

void list_devices(void)
{
    int device_id = 0;
    device_info_t *info;

    for (;;)
    {
        _kernel_oserror *err = _swix(BlockDevice_Enumerate, _INR(0,0) | _OUTR(0,1),
                                      device_id, &device_id, &info);
        if (err || device_id == 0)
            break;

        printf("%d: %s\n", device_id, info->description);
    }
}

Reading blocks from a device

Given a device id, a buffer to read into and a starting block address, a single read is issued like this:

#include "kernel.h"
#include "swis.h"
#include "BlockDevices.h"

_kernel_oserror *read_blocks(int device_id, blockaddr_t lba,
                             void *buffer, unsigned count)
{
    transfer_block_t transfer;

    transfer.lba     = lba;
    transfer.address = buffer;
    transfer.count   = count;

    return _swix(BlockDevice_Read, _INR(0,2), device_id, 0, &transfer);
}

Writing and registering a block device driver

A driver registers each device it controls once it has identified it, supplying a description of the device and an entry point through which BlockDevices will call it back:

#include "kernel.h"
#include "swis.h"
#include "BlockDevices.h"

static device_info_t my_device =
{
    "mydriver",                          /* name       */
    0,                                    /* flags      */
    0,                                    /* parent     */
    0,                                    /* auto index */
    2097152,                              /* blocks     */
    512,                                  /* block size */
    BlockDevice_DeviceType_Disc,
    BlockDevice_InterfaceType_SCSI,
    BlockDevice_ConnectionType_USB,
    BlockDevice_MediaType_HardDisc,
    "My Example Disc"
};

extern void mydriver_entry(void); /* implemented in assembler, or as a
                                      generic veneer, calling
                                      mydriver_handler below */

int mydriver_register(void *private_word, void *unit_reference)
{
    int device_id;
    _kernel_oserror *err;

    err = _swix(BlockDevice_Register, _INR(0,4) | _OUTR(0,0),
                0, &my_device, mydriver_entry, private_word, unit_reference,
                &device_id);
    if (err)
        return -1;

    return device_id;
}

The registered entry point dispatches on the reason code it is given in R8, handling at least reads and writes:

_kernel_oserror *mydriver_handler(_kernel_swi_regs *r, void *pw)
{
    switch (r->r[8])
    {
        case BlockDevices_Reason_Read:
            return mydriver_read(pw, r->r[9],
                                  (transfer_block_t *)r->r[2]);

        case BlockDevices_Reason_Write:
            return mydriver_write(pw, r->r[9],
                                   (transfer_block_t *)r->r[2]);

        default:
            return err_BadMiscOp;
    }
}

When the underlying hardware is later removed, the driver deregisters the device it created for it:

void mydriver_remove(int device_id)
{
    _swix(BlockDevice_Deregister, _INR(0,0), device_id);
}