This document attempts to describe how to develop device drivers for the BeOS (and BeIA) operating systems. It is also useful to the developer of an application which has to talk to a device driver. In order to set the stage for the driver development discussion, I will first discuss how to use a device driver from an application.
Typically, a user-level application will not use a BeOS device driver directly, instead using some higher-level API which calls a user-level add-on which calls the driver. However, there is nothing that prevents an application from talking directly to a driver just like an appropriate add-on would; indeed, in some cases there is no appropritate add-on API and you have to talk to the driver directly from an application. It is also useful to talk directly to the driver while developing and testing the driver. We will call the entity (application or add-on) using the driver a "client" of the driver.
First, finding the device. The driver will export one or more devices in sub-directories of the "/dev" directory. For instance, the sonic_vibes audio card driver export in /dev/audio/raw/sonic_vibes/ as well as in other locations. Because most BeOS drivers support handling more than one installed card of the same kind, the convention is to number the installed cards, starting at 1. Thus, the first installed sonic_vibes card is found as /dev/audio/raw/sonic_vibes/1. You can use the BDirectory class or the opendir() C function to look through a directory for available devices.
Once you know what device you want to use, you should open it using the open() C call:
int fd = open("/dev/audio/raw/sonic_vibes/1", O_RDWR);
You will use this file descriptor to refer to the open device from now on. The file descriptor should be closed with close() when you are done with it. If the process (team) that opened the device crashes or otherwise goes away without closing the file descriptor, it will be garbage collected and closed by the kernel.
Many devices implement the read() and write() protocols. Thus, to record some audio from the default input source, using the raw audio file descriptor opened above, all you have to do is:
short * data = (short *)malloc(200000);
ssize_t rd = read(fd, data, 200000);
"rd" will contain the number of bytes actually read, or -1 if an error occured (in which case the thread-local macro "errno" will contain the error code).
The format of the data returned by the device varies with what device it is; the default format of the sonic_vibes driver is stereo 16-bit signed native-endian 44.1 kHz PCM sample data. To play back this data using the write() call, do this:
ssize_t wr = write(fd, data, rd);
"wr" will contain the actual number of bytes written, or -1 for error, in which case "errno" contains the error code.
Many devices do not work well with the simple read() and write() protocol; for instance, video capture cards often require a contiguous locked area of memory, which typically is not found in a buffer passed in by the user to read() or write(). Then you can implement your protocol as ioctl() selectors. There are a number of well-defined ioctl() values that your device can implement if they make sense for the class of device you're dealing with; specific sub-directories of /dev may require certain ioctl() protocols to be implemented (such as /dev/joystick, /dev/midi, or /dev/audio).
Supposing we're using a video capture driver which implements the following protocol:
enum {
drvOpSetBuffers = B_DEVICE_OP_CODES_END+10001,
drvOpStart,
drvOpStop,
drvOpWaitForFrame,
};
struct drv_buffer_info {
color_space in_space;
int in_width;
int in_height;
int in_rowbytes;
void * in_buffers[2]; /* even, odd */
};
struct drv_frame_info {
int out_frame_number;
};
The client could then configure the driver like so:
drv_buffer_info buf_info;
buf_info.in_space = B_YUV422;
buf_info.in_width = 640;
buf_info.in_height = 240;
buf_info.in_rowbytes = 640*2; /* 422 is 16bpp */
area_id buf_area = create_area("capture buffers", &buf_info.in_buffers[0],
B_ANY_ADDRESS, buf_info.in_rowbytes*buf_info.in_height*2,
B_CONTIGUOUS, B_READ_AREA|B_WRITE_AREA);
buf_info.in_buffers[1] = ((char *)buf_info.in_buffers[0])+buf_info.in_rowbytes*buf_info.in_height;
int err = ioctl(fd, drvOpSetBuffers, &buf_info);
if (err == -1) err = errno;
It would start video capture like so:
int err = ioctl(fd, drvOpStart);
if (err == -1) err = errno;
It would wait for each frame to arrive like so:
while (running) {
drv_frame_info frm_info;
int err = ioctl(fd, drvOpWaitForFrame, &frm_info);
if (err == -1) err = errno;
process_frame(frm_info.out_frame_number, buf_info.in_buffers[frm_info.out_frame_number & 1]);
}
Last, it would stop the capture like so:
int err = ioctl(fd, drvOpStop);
if (err == -1) err = errno;
In real life, a typical protocol will be more capable, and thus more complicated, than shown here, but it should be enough to give you an idea of how the protocol between a user-level client and a driver can be structured. Also, in real life, drivers know better about their buffering requirements than applications, so the API would probably have an ioctl() to allocate buffer(s) and return information about them to the client, rather than have the client tell the driver which buffer(s) to use.
OK, now that you know how to use a device driver, and have some idea of how to structure the protocol between the client and the driver, it's time to get down and dirty with the actual process of creating a driver. Creating a driver on BeOS is done using ANSI C; the C++ language requires certain support which is not available in the BeOS kernel environment. If you already have a large C++ library that talks to your hardware device and want to port it to BeOS, we suggest that you make your driver very shallow and use it just to read/write card registers and service interrupts, and put all your C++ code in a user-level add-on. Some readers may know "interrupts" by the name "IRQ"; we will call them "interrupts" because that's the terminology used by the BeOS kernel kit.
A driver is a loadable shared library (add-on) which exports certain well-known function names such as init_driver() and publish_devices(). The driver gets loaded by the "devfs" file system (which runs in the kernel) in response to some client calling file system functions opendir(), open(), and others. A driver may get loaded and unloaded several times, not necessarily being opened just because it's loaded. It will, however, never be unloaded while it is open. The moral of this story is that you cannot expect global or static variables to retain their values after uninit_driver() has been called, or before init_driver() is called.
First, you have to decide on what to call your driver and your devices. Typically, one driver will service any number of installed cards of the same kind, and each of those cards may cause the driver to publish multiple device names under /dev. These device names will be referred to as "devices"; the actual binary add-on will be called the "driver" and the pieces of hardware serviced by the driver will be called the "hardware".
Typically, you will name your driver something close to the name of the main chip serviced by the driver. The sonic_vibes driver drives the S3 Sonic Vibes chip; the bt848 driver drives the Brooktree Bt848/878 chips; the awe64 driver drives the Creative Labs SoundBlaster AWE32/64 cards; etc.
Your device names will then be derived from the protocols they implent, as well as the driver name. Thus, sonic_vibes publishes devices in /dev/audio/raw/sonic_vibes, /dev/audio/old/sonic_vibes, /dev/audio/mix/sonic_vibes, /dev/audio/mux/sonic_vibes, /dev/midi/sonic_vibes and /dev/joystick/sonic_vibes, each device implementing the protocol that's defined for that part of the /dev directory tree. If there is no protocol defined for your kind of device, you can implement whatever protocol you wish. Try to stay consistent in your naming, however. For instance, a video capture driver for a chip named Pixtor might publish devices in /dev/video/pixtor/. By convention, each card will be numbered from 1 and up, so the first "pixtor" device would be called /dev/video/pixtor/1.
If your device is of some irregular kind, you can always publish in /dev/misc/your-name. Please avoid publishing directly under /dev, and avoid inventing new classes of devices under /dev/. If you feel you have to, please first contact BeOS developer support or your favourite Be engineer to check that your scheme will work well with the rest of the system.
The first function called in your driver, if you implement and export it, is the init_hardware() hook. Please refer to the skeleton driver for the C function prototype of each driver function.
init_hardware() will only be called the first time your driver is loaded, to find and reset your hardware and get it into some known state, if necessary. Many drivers can do without implementing this hook at all. If you implement this hook, but don't find any of your cards installed, you should return a negative error code, such as ENODEV. Note: on BeOS, all the POSIX error codes (EXXX) are negative numbers, so you should return them as-is to signify error.
The next driver hook being called is init_driver(), which definitely should be implemented by all drivers. If your device is an ISA card, you will want to call get_module() on the ISA bus manager module to initialize a global variable to refer to that module for easy access (typically, this variable will be named "isa"). For PCI cards, use the PCI bus manager module, found in <PCI.h>.
Then, use the bus manager module to iterate over available hardware, looking for instances of the hardware you support. For each piece of hardware, make sure you enable its PCI bus interface in the configuration registers if it isn't already. Then allocate whatever memory you need to keep track of the hardware and the devices that hardware will cause to be published, and make sure the hardware is in some safe, well-behaved state and not generating spurious interrupts or other bad behaviour. To allocate memory, use malloc(). To later deallocate this memory, use free().
/* a global variable for the PCI module */
pci_module_info * pci;
/* in init_driver() */
pci_info info;
int ix = 0;
int cards_found = 0;
if (get_module(B_PCI_MODULE_NAME, (module_info **)&pci) < 0)
return ENOSYS;
while ((*pci->get_nth_pci_info)(ix, &info) == B_OK) {
if (info.vendor_id == MY_VENDOR && info.device_id == MY_DEVICE) {
cards_found++;
my_card_array[ix].info = info;
}
ix++;
if (cards_found == MAX_CARDS) break;
}
if (cards_found < 1) return ENODEV;
names[cards_found] = NULL;
/* in uninit_driver() */
put_module(B_PCI_MODULE_NAME);
If you find no hardware, return ENODEV. If you find hardware, but something is wrong and you're not prepared to publish any devices, return ENOSYS or ENOENT. If all is OK, return B_OK.
Next, the hook publish_devices() will be called. It should return a pointer to an array of C string pointers, one per device you want to publish, and terminated by a NULL pointer. For a hypothetical "Pixtor" driver which publishes one device per installed hardware card, up to a maximum of four installed cards, you will typically have a global variable "names" like so:
static char * names[5] = {
"video/pixtor/1",
"video/pixtor/2",
"video/pixtor/3",
"video/pixtor/4",
NULL /* init_driver() sets unavailable slots to NULL */
};
In init_driver() you will allocate a name string per device you find (unless a static array will work, as shown), and make the corresponding slot in "names" point to that string. Then you can just return the "names" array in publish_devices():
const char ** publish_devices() {
if (names[0] == NULL) return NULL;
return names;
}
Note that the names assume to live under "/dev/" and thus should NOT contain that part; a typical name may be "video/pixtor/1".
How does the devfs file system know which driver to open when a program asks for the device named "/dev/foo/bar/1"? Under R3, devfs opened all drivers when the system booted and called their publish_devices() function, so it could know what devices were available. However, this mechanism doesn't scale well with an increasing number of drivers available for BeOS, and a new mechanism was introduced in R4.
Inside /system/add-ons/kernel/drivers (and ~/config/add-ons/kernel/drivers) there are now two folders, "dev" and "bin". All driver binaries go into "bin", and symlinks to the drivers go into the appropriate subdirectory of "dev". Thus the hypothetical Pixtor driver would put the driver in ...kernel/drivers/bin, and put a symlink to that driver in ...kernel/drivers/dev/video. The symlink has to be put there by the installation program or script for the driver, or, for development purposes, by the driver build process.
Thus, when a client calls open("/dev/video/pixtor/1") or opendir("/dev/video/"), devfs will scan all symlinks found in ...kernel/drivers/dev/video (and subdirectories thereof) and open the referenced drivers to call their init_driver() and publish_devices() functions, in order to figure out which driver(s) publish devices that would interest the client. Devfs is reasonably smart about only doing this once, and it uses the modification date of the driver in .../bin to do that, so when you replace your driver with a newer copy, subsequent open() calls for your driver will cause devfs to load the new version (once all the old clients have closed the old driver). Not having to reboot for the new driver to be found is one of my favourite features of BeOS for driver development.
Note: as of Release 4.5, the kernel may be even smarter about not loading a driver again, so your make file can use the rescanshell command to tell devfs that your driver is updated. Give it the name of your driver binary (found in ...kernel/drivers/bin) like so:
rescan sonic_vibes
When a client decides to open one of your devices, the kernel will call your find_device() hook with the name in question. It is up to you to map this name (which you previously published in publish_devices()) to the right device type within your driver. If you support only one device type, this is easy, and even if you support more than one, a simple strncmp() will typically be sufficient.
A "device type" consists of a set of function pointers that define the interface for a device. In <Drivers.h> you will find the struct device_hooks which is what should be returned from find_device(). The hooks for open, close, free, read, write and control are required to be implemented; the hooks for select, deselect, readv and writev are optional. If you don't implement select/deselect, the kernel will return an error to the client of your file descriptor if the hook is used. If you don't implement readv/writev, the kernel will emulate these functions by repeatedly calling your read/write hooks, which may be less efficient than if you supported the readv/writev functions directly. Don't confuse the hook name "select()" with the net kit function "select()"; currently they have nothing to do with each other.
Once you have returned a device_hooks structure, the kernel will call the open hook therein, letting you turn the device name into a unique "cookie" which your other hooks will use to find the open device in other hook calls. The open mode is O_RDONLY, O_WRONLY, or O_RDWR. Depending on your driver's capabilities, you might want to ensure exclusive access to reading and writing respectively, and return a EPERM error if someone tries to open the same device with the same mode twice in a row. It may, however, make sense to allow one open() for O_RDONLY and another open() for O_WRONLY.
The kernel will never dereference the "cookie" value, so it can be a pointer to some private data you malloc(), or a pointer to some element in a global array, or just an index of some sort. Suffice to say that you must be able to get all necessary state information for the open device, and the hardware associated therewith, when given this cookie in later hook function calls.
Your open() hook will typically need to call install_io_interrupt_handler() to install an interrupt service routine for the hardware in question the first time it is opened, if you didn't already do that in init_driver(). For PCI devices, you find the values to pass to this function in the pci_info struct for your hardware. The "data" value will be passed to your interrupt handler, and thus is typically your "cookie" value.
Note that the device_hooks structure may acquire more functions in later versions of BeOS. To tell the kernel what version of the interface you were compiled with, you should export an int32 variable named api_version, it should be initialized to B_CUR_DRIVER_API_VERSION. Assuming you put your device_hooks structs in static or global memory, the compiler will clear out any slots you don't define at the end to NULL for the version of the device_hooks struct you compile with; thus the value of B_CUR_DRIVER_API_VERSION will change when the size of the device_hooks struct changes. Just adding this line to your driver is enough, as long as you include <Drivers.h> before it:
int32 api_version = B_CUR_DRIVER_API_VERSION;
When the user is done with your device, he will call close() on the file descriptor that references it. When the file descriptor is closed (or, when the last file descriptor is closed, if the user uses dup()), the kernel will call your close() hook. You should start shutting down the device; set a status bit so that future read(), write() and control() hook calls will return an error, and preferrably un-wedge any outstanding blocking I/O requests and have them return EINTR. One technique of doing this is to simply delete the semaphores you use for synchronizing I/O. The acquire_sem() calls in your driver hooks should then detect the B_BAD_SEM_ID error and take that to mean that the device is being shut down, and return EINTR to the calling client.
Once all outstanding I/O requests have returned out of your driver, the free() hook will be called. Here is where you can deallocate all memory you allocated in open() or during the course of dealing with the specific open device (as indicated by the cookie), and re-set your driver to accept a future open() for that device name. Note that there will be exactly one call to the free() hook for each call to the open() hook, and that call to free() for the cookie returned by open() will always come after a call to close() for that cookie. There is no relation between different cookies returned by different calls to open(), as far as the kernel knows they are independent.
The free() hook is a good place to call remove_io_interrupt_handler() to remove the interrupt handler for your device if you installed it in open(). If you allow multiple open()s, it's easier to install the handler (once) in init_driver() and remove it in uninit_driver(); don't install a handler more than once for the same hardware! Pass the same "data" value as you passed to install_io_interrupt_handler() in open() (i e, for most devices, your "cookie" value).
Your interrupt handler will be called whenever an interrupt on your interrupt number occurs. Because of interrupt sharing, your hardware may not be the hardware that generated the interrupt. Your interrupt handler will be called on to figure out whether the interrupt was caused by your hardware, and if so, to handle it. You should read the appropriate status register on your hardware the first thing you do in the interrupt handler, and if the interrupt was not generated by your hardware, immediately return B_UNHANDLED_INTERRUPT. This will let the kernel move on to other interrupt handlers installed for the same interrupt number and see if they can handle the interrupt.
If the interrupt was indeed generated by your hardware, you can go ahead and handle the interrupt, and then return B_HANDLED_INTERRUPT.
While your interrupt handler runs, interrupts are turned off. Thus, threads cannot be re-scheduled, and other interrupts cannot be handled. This means that your interrupt handler should run as fast as possible. A typical interrupt handler just acquires a spinlock (for mutual exclusion with user-level threads), adjusts some internal data structure, and quite possibly releases a semaphore which the user thread (read(), write() or control()) is waiting on. Because re-scheduling with interrupts disabled can cause a total system hang, you should release semaphores using release_sem_etc() and pass the B_DO_NOT_RESCHEDULE flag like so:
release_sem_etc(my_cookie->some_semaphore, 1, B_DO_NOT_RESCHEDULE);
The scheduling quantum on BeOS is 3000 microseconds. Thus, if you release a semaphore without re-scheduling, the longest you may have to wait before a re-schedule happens, and the schduler gets a chance to notice that your semaphore has become available, and thus be able to schedule the thread waiting on the semaphore, is 3 milliseconds. If this is too long time (for low-latency media devices like audio and MIDI, for example) your interrupt handler routine can return the special value B_INVOKE_SCHEDULER, which means that you handled the interrupt, and want a thread reschedule to happen at the earliest possible time. The kernel will then call resched() as soon as it leaves interrupt level, which will give the scheduler a chance for noticing that your semaphore has been released and your waiting thread is now ready to run.
Note that, because of multi-threading and thread priorities, your thread may not be the thread chosen to run just because a reschedule happens. If you have really low latency requirements, and can't afford to have lower-priority threads come between your interrupt handler and your waiting thread getting scheduled, you have to use real-time priority for the thread waiting for the interrupt. Using real-time priority for threads is dangerous, however, because they may completely lock out other threads from the system, including the graphics threads that draw to the screen, making the system appear "hung" if your real-time thread does too much work without synchronizing with a blocking primitive (like a semaphore).
Now that you know how your device gets loaded and unloaded, and how to handle interrupts generated by your hardware, you can design the rest of your device API to be used by user-level clients.
The read() hook gets called in repsonse to a call to the user-level function read() on a file descriptor that references your device. The cookie for your device will be passed to the read() hook, as well as the current position, as maintained by the kernel file descriptor layer. If your device does not support positioning (seeking) you can ignore the position parameter.
Your job inside the read() hook is to transfer data into the buffer passed into the read() hook. The buffer has a size of *numBytes. You should transfer at most that many bytes, and then set *numBytes to the number of bytes transferred. If any bytes were transferred, return B_OK. If some error occured and/or no data was transferred, set *numBytes to 0 and return a negative error code.
Please note that the buffer pointed at by "data" will typically be in the user space of the team calling read(). It will typically be in discontiguous memory, and it will not be locked in physical RAM. Thus, it is not accessible from an interrupt service routine, nor can you DMA directly into it without first locking the buffer and getting the physical memory mapping for it:
status_t
read_hook(void *cookie, off_t position, void *buffer, size_t *numBytes)
{
status_t err;
long entries = 2+*numBytes/B_PAGE_SIZE;
physical_entry * pe = (physical_entry *)
malloc(sizeof(physical_entry)*entries);
status_t err;
my_device * md = (my_device *)cookie;
err = acquire_sem_etc(md->lock_sem, 1, B_CAN_INTERRUPT);
if (err < 0) {
/* delete_sem() from close(), or signal interrupting */
free(pe);
return err;
}
err = lock_memory(buffer, *numBytes, B_DMA_IO);
if (err < B_OK) {
free(pe);
release_sem_etc(md->lock_sem, 1, B_DO_NOT_RESCHEDULE);
return err;
}
entries = get_memory_map(buffer, *numBytes, pe, entries);
/* set up and start your DMA here */
...
/* assume your interrupt handler will release this sempahore when DMA done */
err = acquire_sem(md->my_dma_sempahore);
unlock_memory(buffer, *numBytes, B_DMA_IO);
if (err < B_OK) {
*numBytes = 0;
}
free(pe);
/* use B_DO_NOT_RESCHEDULE because we want to return to caller */
/* with data without further delay */
release_sem_etc(md->lock_sem, 1, B_DO_NOT_RESCHEDULE);
return err;
}
The same rules apply for the write() hook, except of course the data transfer direction is from the buffer passed by the client to your hardware.
An alternative is to use a contiguous buffer in kernel space that you allocate and copy to/from in read() and write(). If you have a sound card that uses a cyclic auto-repeat DMA buffer, this is often a good solution, for example. However, if the data rate is high, such as for live video or fast mass storage devices, you want to avoid copies. You might choose to just have read() and write() return an error, and use ioctl() exclusively for communicating with your device. Another option is to make ioctl() the preferred protocol, but have read() and write() call the appropriate ioctl() functions for convenience.
These kinds of decisions are easier if you're implementing a device for which Be has defined a protocol, because then you just follow the protocol. However, if your're implementing a driver for a device for which there is no pre-defined protocol, or if your device will have significantly better performance using some other protocol, you will have to design the driver protocol on your own.
The control() hook is called in response to the user level client calling the ioctl() function:
struct the_args {
int a;
int * b;
};
int foo;
struct the_args args;
args.a = 1;
args.b = &foo;
err = ioctl(fd, SOME_CONSTANT, &args);
if (err == -1) err = errno;
The control() hook will receive the integer constant passed to ioctl(), as well as the pointer argument. Currently, the "size" argument will always be 0 when passed to the hook, so you can ignore it. Assume that the pointer argument is correct for the integer constant in question.
You can start numbering your own operation constants from B_DEVICE_OP_CODES_END+1 (in <Drivers.h>). If you want to avoid the risk of clashing with someone trying to use a protocol you do not know about on your device, you can choose some arbitrary, larger number to start numbering from, such as your birthday or something. As long as the numbers (when read as signed 32-bit integers) are larger than B_DEVICE_OP_CODES_END.
In the example above, your device control hook can look like this:
status_t
control_hook(void * cookie, uint32 operation, void * data, size_t length)
{
my_device * md = (my_device *)cookie;
status_t err = B_OK;
switch (operation) {
case SOME_CONSTANT: {
struct the_args * ta = (struct the_args *)data;
int i;
if (ta->a > MAX_INDEX_FOR_MY_DEVICE) {
ta->a = MAX_INDEX_FOR_MY_DEVICE;
}
if (ta->b == NULL) {
err = B_BAD_VALUE;
}
else {
err = acquire_sem(md->lock_sem);
if (err < B_OK) {
return err;
}
for (i=0; i<ta->a; i++) {
ta->b[i] = md->some_value[i];
}
release_sem(md->lock_sem);
}
}
break;
default:
err = B_DEV_INVALID_IOCTL;
break;
}
return err;
}
Semaphores may cause a re-schedule to another thread when released. Thus, you should not release a semaphore from an interrupt handler, or with interrupts disabled, without passing the B_DO_NOT_RESCHEDULE flag (using release_sem_etc()).
It is generally a good idea to put as much code as possible at the user level, and make your driver as shallow as possible even if you aren't forced to by porting C++ code. The less code there is in the driver, the less locked memory will be used, and the less code there is that may crash the kernel. All of your driver's code and global/static data, as well as all memory returned by malloc() called from a driver, is locked (and thus safe to access from an interrupt handler). Be gentle on the system.
Disabling interrupts is NOT sufficient to guarantee atomicity, because on a SMP system, the other CPU may be calling into your driver at the same time. For synchronization with data accessed by interrupt handlers, you have to use a spinlock. Spinlocks are the most primitive synchronization mechanism available; basically they use some atomic memory operation to test-and-set a variable. When the test-and-set fails, the calling thread just keeps trying (busy-waiting) until it succeeds. Thus, contention for spinlocks can be quite CPU intensive. Therefore, they should be used sparingly, and only to synchronize data that really has to be touched by an interrupt handler (since semaphores cannot be used by interrupt handlers).
A spinlock is simply a int32 value in some permanent storage (a global, or some memory you malloc() as part of opening your device) that is initialized to 0 before being used the first time. To acquire a spinlock, you turn off interrupts and then call acquire_spinlock():
/* These are global variables. */
int32 my_spinlock = 0;
char protected_data[128];
int protected_ctr = 0;
/* Acqurie spinlock. */
cpu_status cp = disable_interrupts();
acquire_spinlock(&my_spinlock);
/* Do protected operations -- this should be fast and not cause */
/* any reschedule, so don't call malloc() or any semaphore operations */
/* or any function that may call these functions. */
protected_data[protected_ctr++] = 0;
protected_ctr = protected_ctr & 127;
/* Release spinlock. */
release_spinlock(&my_spinlock);
restore_interrupts(cp);
/* in your interrupt handler */
/* serialize with user code, possibly on other CPUs */
acquire_spinlock(&my_spinlock);
/* Do protected operations like hardware register access */
release_spinlock(&my_spinlock);
If you fail to disable interrupts before acquiring the spinlock, you will deadlock on single-CPU machines, because your interrupt handler may then be called (and try to acquire_spinlock() your spinlock) while the regular thread is holding the spinlock. That would be bad.
Many people find it convenient to wrap spin-locking into two general-purpose lock() and unlock() routined to not forget to turn off interrupts. You can use the same routines inside your interrupt handler, because calling disable_interrupts() and later restore_interrupts() is OK even inside an interrupt handler (even though interrupt handlers run with interrupts already turned off). Spinlocks, like sempahores, don't nest like that, however, so think about what you're doing and don't call functions that may lock a spinlock from some function that already holds the same spinlock.
/* assuming you keep state information about your hardware in a */
/* struct named my_card, with a 0-initialized spinlock named hardware_lock */
cpu_status lock_hardware(my_card * card)
{
cpu_status ret = disable_interrupts();
acquire_spinlock(&card-<hardware_lock);
return ret;
}
void unlock_hardware(my_card * card, cpu_status previous)
{
release_spinlock(&card-<hardware_lock);
restore_interrupts(previous);
}
It is important to not disable interrupts for a long time. As a general rule, no more than 50 microseconds is allowable. If you disable interrupts for longer, you will jeopardize the overall performance of the BeOS and the machine it is running on. Similarly, your interrupt service routine should not run for more than 50 microseconds (and less is, of course, better).
You may find the lack of deferred procedure calls disturbing if you come from some other driver architecture. However, the time it takes for BeOS to service an interrupt, release a semaphore, and cause a re-schedule into a user-level real-time thread is often smaller than the time it takes for other operating systems just to handle the interrupt and get to the deferred procedure call level. Thus, we prefer to do what needs to be done in the user level client threads that call into the device hooks.
If at all possible, let the user of your device spawn whatever threads your device needs. Kernel threads are very tricky and live by different, undocumented rules. If you find a need for a periodic task, you can look into using timer interrupts (available as of BeOS R4.1). Look for add_timer() and cancel_timer() in <KernelExport.h>.
If you find a wish to use a kernel thread in your driver, there are several pitfalls that makes doing so a bad idea. The kernel team is a team just like any other team, and your kernel thread will have a stack in the upper half of the kernel team address space. This stack (and stacks of other kernel threads) is not accessible from user programs, and thus it is not accessible from device hooks called by user programs. Only the lower half of the kernel team address space (0x0-0x7fffffff) is accessible to all teams when they enter the kernel. This also implies that the stack of a kernel thread, or any other thread, is not accessible from an interrupt handler, since the MMU context of an interrupt handler is undefined; only the kernel space 0x0-0x7fffffff is accessible from an interrupt handler. Driver binaries and kernel malloc() memory live in this accessible space.
You also cannot use wait_for_thread() in your close() or free() hooks, because doing so will cause a deadlock with the psycho_killer thread which is responsible both for reaping dead threads and for freeing file descriptors and their associated devices. Thus, it is impossible for you to make perfectly sure that your kernel thread has terminated before your free() hook returns. This is a problem big enough that you should reconsider using kernel threads at all in your driver, if there is some other possibility. (This specific problem has been fixed in Release 4.5 of the BeOS, but all the other problems with kernel threads will still remain) Release 4.0 will be the baseline BeOS for some time to come, so a design without kernel threads is thus more widely compatible.
Again: Put the threads you need in the user-level client (add-on, application, whatever). If the driver needs to perform periodic tasks not in response to hardware interrupts, use timer interrupts. They are even more lightweight than threads, and have fewer of the problems mentioned above. As with any interrupt routine, timer interrupts still cannot access memory that is not in the kernel space; thus if you need to write into user-supplied buffers, do it in your driver read(), write() and control() hooks.
Good luck!