The first exported symbol is the easiest to implement: it's the int32 value api_version, and a driver simply needs to include the line

int32 api_version = B_CUR_DRIVER_API_VERSION;

to fulfill its obligation. B_CUR_DRIVER_API_VERSION is defined in Drivers.h, and as you might guess, it lets the kernel know which version of the driver API a driver uses.

init_hardware() is called only once in a particular runtime session (i.e., from boot to shutdown). For devices that remain connected to the computer for an entire runtime session—such as ISA and PCI cards—it may make sense to use init_hardware() to see if the device is indeed connected and put it into a known initial state. However, it's not too useful in drivers for devices that can be hot-plugged while BeOS is running— such as USB devices—because the device may not be plugged until after the first time the kernel loads its driver. Therefore, if you're one of those short attention span types who's been looking for init_hardware() in CPiA.c, stop—it's not there. Implementing it is optional, and I chose not to for this driver.

init_driver(), on the other hand, is called every time a driver is loaded by the kernel, and must be implemented by all drivers. init_driver() should allocate resources that will be needed as long as the driver remains loaded. USB drivers should take this opportunity to introduce themselves to the USB (Bus) Manager like so:

/* declare these globally */
static char* usb_name = B_USB_MODULE_NAME;
static usb_module_info *usb;

usb_support_descriptor supported_devices[] =
{
    0, 0, 0, VENDOR_ID, PRODUCT_ID }
};

...

/* do this in init_driver() */
if (get_module(usb_name,(module_info**)&usb) != B_OK) {
    dprintf(ID "cannot get module \"%s\"\n", usb_name);
    return B_ERROR;
}
dprintf(ID "usb module at %p\n", usb);

usb->register_driver(DEVICE_NAME, supported_devices, 1,
    NULL);
usb->install_notify(DEVICE_NAME, &notify_hooks);

(Okay, you don't have to use dprintf() so gratuitously, but I like to. To review, dprintf() works just like good 'ol printf(), but it spews its bits to COM 1 so you can catch them on another computer using a null modem cable and a terminal program set to 19200 baud, 8 data bits, no parity, 1 stop bit, and no flow control. This is serial debugging, and it's pretty much indispensable for driver development. You can turn on serial debugging by hitting the delete key as soon as the BeOS boot screen comes up, or during runtime by hitting alt+printscreen+d to jump into the kernel debugger, then typing c to continue.)

The code above gets a pointer to the USB Manager module by calling get_module() with the name B_USB_MODULE_NAME. Then it calls the USB Manager's register_driver() function to tell the Manager which devices it would like to receive notifications about. For CPiA, I specify the vendor and product fields of the usb_support_descriptor explicitly; for more generic drivers, you can specify something other than the wildcard 0 for dev_class, dev_subclass, and/or dev_protocol fields. How can you find out what the vendor and product IDs of some random USB device are? It's as simple as plugging the device in with serial debugging turned on. Among lots of other useful output, you'll see a line like

vendor/product id: 0x0553 / 0x0002

Next, the USB Manager's install_notify() function is called. This provides addresses of the hook functions that will be called when various events occur on the USB bus. Currently only two hooks are defined:

typedef struct usb_notify_hooks {
    status_t (*device_added)(constusb_device *device,
        void **cookie);
    status_t (*device_removed)(void *cookie);
} usb_notify_hooks;

As you may have guessed, device_added() is called whenever a device matching the usb_support_descriptor provided in register_driver() is added to the USB, and device_removed() is called when it is removed. You may not have guessed that device_added() is also called after you call install_notify(), and device_removed() is called after you call uninstall_notify(), if the device is connected at those times.

Lastly, CPiA's implementation of init_driver() creates a semaphore to synchronize access to the information about the currently connected camera (remember that multiple threads can be executing a driver's code, so protect that global data!). The semaphore name refers to a "table" of devices, but currently the CPiA driver only supports one camera as a simplification. However, next week's version may support more than one camera, and some code in this version is designed for that possibility. The number of devices a driver may support has no artificial limit in BeOS, but there are some practical concerns specific to each device that should be considered. For example, USB bandwidth is theoretically 12Mbps, so supporting two 10Mbps USB devices may not work out well.

The kernel calls publish_devices() after init_driver() to get the names by which the driver wishes to be known in the /dev hierarchy. CPiA is a USB video device, so it returns video/usb/CPiA/0 from this function if there is a device connected at the time it's called. If the driver supported more than one device, it would be published as /dev/video/usb/CPiA/0, /dev/video/usb/CPiA/1, and so on. Furthermore, a single driver can publish multiple logical devices of different functionality if the physical device has such capabilities. For example, many sound cards also have a MIDI port; a driver for such a card might publish devices in both /dev/audio/ and /dev/midi/.

Before the dev_names string array is filled out, though, it is freed if it remains filled out from a previous call. The only safe times to free this array are in publish_devices() after the first time it is called, and in uninit_driver(). At any other time the array may still be in use.

find_device() is called by the kernel when a potential client calls the POSIX function open() on a driver, so the driver can provide its implementation of open() and its friends close(), ioctl(), read() write(), etc. It does this by returning a device_hooks structure filled out with the addresses of its implementations of those functions. If a device supports multiple logical devices of different functionality as described above, it should check the argument of find_device() to see which logical device is being opened, and provide the corresponding set of hooks. More on the implementation of these hook functions in my next article.

uninit_driver() is called just before a driver is unloaded by the kernel. It's the last chance to free resources allocated in init_driver() and elsewhere. In the CPiA implementation, the dev_names string array used in publish_devices() is freed, the USB Manager function uninstall_notify() is called to inform the Manager that the driver will no longer be requiring notifications, the dev_table_lock semaphore is recycled, and -- lastly—the "connection" to the USB Manager is severed. At this point, that certain lady has finished singing for the CPiA driver.

The main tasks to accomplish in device_added() are creating and initializing a cookie that contains device state information and resources, and verifying that the device has the capabilities we expect and that it is working properly.

The CPiA device cookie is defined in CPiA_priv.h and looks like so:

typedef struct device device;
struct device {
    usb_device* dev; /* opaque handle */
    bool     connected; /* is the device plugged into the
                         ** USB? */
    int32     open_count; /* number of clients of the
                         ** device */
    int32     num; /* instance number of the device */
    uchar     vers[4]; /* data returned from
                         ** GetCPIAVersion command */
    sem_id     lock; /* synchronize access to the device */
    sem_id     cmd_complete; /* available on completion
                         ** of CPiA command */
    area_id     buf_id; /* ID of buffer for data returned
                         ** from CPiA command */
    void*         buf; /* data returned from CPiA command */
    size_t         actual_len; /* length of data returned by
                         ** CPiA command */
    status_t     cmd_status; /* result of command */
    /* temp */
    usb_pipe*     video_in;
    uint16     max_packet_size;
};

The comments should give you a rudimentary idea what each field is used for. Perhaps the most important field is dev, which is the handle to the USB stack's notion of the device. It's opaque to clients of the stack, but must be passed to any USB Manager functions that need to know which device you'd like to operate on. The fields after /* temp */ will most likely be moved to another cookie next week.

For CPiA, I've broken out the cookie creation and initialization process into two additional functions. add_device() allocates memory for a device structure and adds it to the device "table," which is currently a single pointer named connected_device. Again, only one connected device is supported right now for simplicity. add_device() in turn calls init_device(), which sets the fields to sane values and allocates the resources they represent.

If add_device() succeeds, device_added()'s cookie parameter is set to point to the newly created device structure. This pointer is passed to the device_removed() USB notification hook so its resources can be properly reclaimed. It will also be passed to each of the device hooks described below. Any device-specific data that needs to persist between USB notification hook calls and device hook calls must live in the cookie.

After successfully setting up the cookie, the CPiA driver issues two CPiA commands to the camera, to get its version information and to check it for any errors that may have been discovered during its Power On Self Test (POST). The workings of issue_cpia_command() will be discussed in the next section.

device_removed() marks the device as being removed. If the device's ref count (dev->open_count) is zero, no clients have the device open, so its cookie is freed by calling remove_device(), which calls deinit_device() to free the cookie's dynamically allocated resources.