A device driver is an add-on that recognizes a specific device (or class of devices) and provides a means for the rest of the system to communicate with it. Usually this communication involves some form of device-specific protocol. For example, if the system wants to use an Ethernet card or graphics card, it needs to load a device driver add-on that knows how to communicate with that card. Similarly, code that knows how to talk to a class of devices (SCSI disks, ATA devices, ATAPI disks, or USB input devices, etc.) must be implemented as a device driver add-on.

Modules provide a uniform API for use by other modules and drivers. A module is like a library in that it acts as a repository for common code that's shared among several drivers.

For example: Let's say you have a device driver that talks to a SCSI device connected to a SCSI bus. A computer can have multiple SCSI busses. Because all SCSI devices use the same command set independent of the particular controller used to send the commands, the command set can be (and is) implemented as a module. The SCSI module knows how to handle all SCSI cards the BeOS supports; the API that the SCSI module defines is adopted by and augmented by the modules for specific SCSI device types (hard disks, scanners, CD drives, etc). The SCSI device modules are managed by a SCSI bus manager module, which knows how to cope with multiple busses and presents them in encapulated form to the drivers. The drivers then only need to deal with the bus manager's API, which makes the life of a driver author much simpler.

Be provides bus managers for SCSI, USB, IDE, and PCMCIA.

File system add-ons provide support for disk and network file systems, such as BFS, HFS, FAT, ISO 9660, CIFS, and so forth. By creating new file system add-ons, developers can provide access to disks that are formatted using other file system.

While your spinlock is running, you can perform the following actions. If it's not on this list, you can't do it.

• You can examine and alter hardware registers by using the appropriate bus manager hooks.

• You can examine and alter any locked-down memory.

• You can call the following kernel functions: system_time(), atomic_add(), atomic_or(), atomic_and().

• You can call the following bus manager functions: read_io_*() and write_io*().

If you do anything else inside your spinlock, you're breaking the rules, so don't do it.

You need to be sure that your calls to acquire_spinlock() and release_spinlock() are balanced. In addition, if you nest spinlocks, they must be released in logical order—that is, in the opposite order in which they're acquired.

The kernel keeps track of which spinlocks are being held and which are being waited upon. The kernel assumes that spinlocks are initialized to 0, and then acquired and released in logical order.

By keeping track of spinlocks, the kernel can detect and break deadlocks on multiprocessor systems.

If you have interrupts disabled and aren't in a spinlock, you can do the following things in addition to those listed above in "Functions Available During Spinlocks":

• You can call release_sem_etc() with the B_DO_NOT_RESCHEDULE flag set.

• You can call get_sem_count(), add_timer(), cancel_timer(), and dprintf().

If you feel that you need to call a function not explicitly listed as permitted here, please contact Be Developer Support at devsupport@be.com and explain your needs; we'd be happy to discuss the situation with you.

It's crucial that your interrupt handler never block, whether directly (by acquiring a semaphore, for example) or indirectly (by calling a function that might block).

Blocking can happen in a surprisingly large number of BeOS functions. It's obvious that acquire_sem() can block, but you might not be aware that functions such as malloc() or read_port() can block. Even touching unlocked memory areas can block because of virtual memory hits.

The point is this: If the BeOS function you want to call isn't explicitly listed in this section as one you can use, don't call it.

Your interrupt handler or spinlock section can't be preempted. Preemption could occur if you call release_sem() or release_sem_etc() without specifying the B_DO_NOT_RESCHEDULE flag. Normally, release_sem() lets the scheduler preempt your thread to allow other threads to acquire the semaphore as fast as possible. By specifying B_DO_NOT_RESCHEDULE, you tell the scheduler to allow your thread to continue running after it releases the semaphore.

If your interrupt handler wants to ensure that any preemption is handled immediately, it should specify B_DO_NOT_RESCHEDULE when calling release_sem(), then return B_INVOKE_SCHEDULER. This causes the scheduler to immediately handle preemption after your interrupt handler returns, instead of resuming the interrupted task. This is especially useful if your code called release_sem_etc() to release a semaphore that will allow other code to run elsewhere (such as in your driver's corresponding user-space code).

Warning

Again, when you call release_sem_etc(), be sure to specify the B_DO_NOT_RESCHEDULE flag to avoid any chance of preemption.

In summary, the order in which you should do things is this:

• Disable interrupts.

• Acquire the spinlock.

• Perform your tasks.

• Release the spinlock.

• Restore the original interrupt state.

Sometimes a driver needs to be able to access disk files. Perhaps the driver has a preference file it needs to read. There are two ways to do this. You can use Posix I/O calls, or you can use the driver settings API provided by BeOS. The latter is preferred.

int readv(int fd, const struct iovec*vector, size_t count);

int writev(int fd, const struct iovec*vector, size_t count);

struct iovec {
   __ptr_t iov_base;
   size_t iov_len;
};

struct iovec v[2];
v[0].iov_base = &buffer1;
v[0].iov_len = 1024;
v[1].iov_base = &buffer2;
v[1].iov_len = 1024;
if (writev(fd, &v, 2) != B_OK) {
   /* error */
}