The goal of this article is to describe how BeOS device drivers communicate with devices on the most common busses—ISA and PCI.

There are many types of hardware busses in the current PCs and Macs: ISA, ADB, SCSI, PCI USB, AGP, VLB, IEEE 1394, I2C, etc., but the majority of devices are located on ISA and PCI busses, so this article will focus on them. The question I'll answer is how a BeOS device driver can access a hardware device on ISA and PCI busses. But before going into the BeOS details I'll briefly describe the software-visible characteristics of ISA and PCI.

ISA appeared on the first IBM PC (8088), and was slightly refined in the later IMB PC AT (80286). Since then there have been no changes and ISA has become old and difficult to use. Fortunately, it's begun to be replaced. The latest Intel chipset i810 doesn't directly support ISA.

There are two address spaces on ISA: one is a 64kB I/O space and another is a 16 MB memory space. An ISA device may occupy portions of both address spaces and respond to I/O and memory read/write cycles initiated by another device on the bus, usually a CPU. In this case the device is passive and the CPU has to read/write data from/to the device to/from system RAM.

An ISA device can be more active and can transfer data without constant attention from a CPU by using an 8237-style DMA controller (as the majority of ISA sound cards do) or by being an ISA bus master (a few SCSI and LAN adapters do this). ISA DMA is obsolete and convoluted; this article does not discuss it.

The PCI bus is a modern, sane replacement for ISA and has multiple advantages over it. A system can have multiple PCI busses, PCI has *good* PnP, it's faster (132 MB/s theoretical bandwidth, 100 MB/s throughput with the real hardware: Matrox Millennium II and Intel 440LX chipset), etc.

In general PCI is a 32-bit bus. There are 64-bit data transfer and 64-bit addressing versions of PCI but they are currently used only in high-end servers.

PCI (32-bit version) has three address spaces:

PCI configuration address space. This supports 256 busses; each bus can have 32 devices; each device can have eight functions; and each function can have 256 bytes of registers. The configuration address of a device is fixed by the PCI slot it's plugged into or by the motherboard if it is a fixed motherboard device.

This address space is used to provide information about devices, to configure PCI devices before they can appear in I/O or memory space, and to set up device specific options.

Many PCI devices, especially high-performance ones, can be PCI bus masters, which lets them transfer data from/to RAM or another PCI device without direct intervention from the CPU. How then, does a BeOS kernel device driver interact with ISA and PCI? By way of BeOS ISA and PCI kernel modules, defined in ISA.h and PCI.h. The relevant portion of these modules is as follows:

typedef struct isa_module_info isa_module_info;
struct_isa_module_info {
..............................
    uint8           (*read_io_8) (int mapped_io_addr);
    void            (*write io 8) (int mapped_io_addr,
                uint8 value);
    uint16          (*read_io_16) (int mapped_io_addr);
    void            (*write io 16) (int mapped_io_addr,
uint16 value);
    uint32          (*read io 32) (int mapped_io_addr);
    void            (*write io 32) (int mapped_io_addr,
uint32 value);


    void *          (*ram address) (const void *
physical_address_in_system_memory);
 ........................
};

struct pci_module_info {
    bus_manager_info    binfo;

    uint8 (*read_io_8) (int mapped_io_addr);
    void (*write_io_8) (int mapped_io_addr, uint8 value);
    uint16 (*read_io_16) (int mapped_io_addr);
    void (*write_io_16) (int mapped_io_addr, uint16 value);
    uint32 (*read_io_32) (int mapped_io_addr);
    void (*write_io_32) (int mapped_io_addr, uint32 value);

    long (*get_nth_pci_info) (
        long index, /* index into pci device table */
        pci_info *info  /*caller-supplied buffer for info*/
        );

    uint32 (*read_pci_config) (
        uchar   bus,    /* bus number */
        uchar   device, /* device # on bus*/
        uchar   function,   /* function # in device */
        uchar   offset, /* offset in configuration space */
        uchar   size    /* # bytes to read (1, 2 or 4) */
        );

    void (*write_pci_config) (
        uchar   bus,        /* bus number */
        uchar   device,     /* device # on bus */
        uchar   function,   /* function # in device */
        uchar   offset, /* offset in configuration space */
        uchar   size, /* # bytes to write (1, 2 or 4) */
        uint32  value       /* value to write */
        );

    void* (*ram_address) (
        const void *physical_address_in_system_memory);
};

The general API of BeOS modules has already been described in a previous newsletter article, "Be Engineering Insights: BeOS Kernel Programming Part IV: Bus Managers," by Brian Swetland

So I'll focus on ISA and PCI specifics.

Among other important improvements in BeOS Release 4.5 is the BMediaFile, which gives access to various kinds of media file formats, and BGameSound (with subclasses), which allows simple but efficient playback of sound effects and background sounds. The BSoundFile class has been with us for a long time, and was starting to show its age. Many older programs that still run on PowerPC depend on idiosyncrasies of this class, so rather than make it use the same mechanism as BMediaFile to access data, which would break the previous semantic of the file (we tried this), we decided to stay compatible, and suggest that all newer applications use BMediaFile for all their media reading/writing needs.

However, if you have an application which uses BSoundFile, you may need some features that BMediaFile and BMediaTrack don't provide. Most notably, BMediaTrack reads audio frames in blocks of a predetermined size, whereas BSoundFile lets you read any number of frames at any time. BMediaTrack also may not be precise in seeking to a specified frame location (because of compression algorithm constraints). I present here a simple wrapper for BMediaTrack, known as ATrackReader. It lets you treat a generic media file, accessed internally through a BMediaFile object, much like a BSoundFile. It's also a good introduction to using BMediaFile/BMediaTrack to read data in general.

If you use a BSoundPlayer with a number of BSounds to play sound effects, you'll probably want to change over to the new BGameSound system the next time you overhaul your code. BGameSound is designed to allow for hardware acceleration in a future version of BeOS (when this will happen is TBD), and it's also designed to be really simple to use! If you used BSound with a chunk of data in memory as your data, you now create a BSimpleGameSound object. If you use BSound with a large-ish sound file on disk for background music or other something similar, you now create a BFileGameSound.

BSimpleGameSound can be created either with a pointer to data and a description of the data pointed to (it should be uncompressed PCM sample data), or with an entry ref, in which case it will load the sound file from disk (uncompressing, if necessary) into memory so it's always readily available to be played. The BGameSound system makes a copy of the data you provide it, so you can free that memory as soon as the object is created. If you need more than one copy of the same sound running, you can call Clone() to get a second BSimpleGameSound which references the same data as the first. When you make a Clone(), that clone references the same internal copy with a reference count, so no extra memory is wasted. The Be Book accidentally documents an earlier behaviour where data was copied inside Clone().

To play the sound, just call StartPlaying() on it.

BFileGameSound is created with an entry_ref as argument, and can optionally be set to looping or non-looping mode. When you call StartPlaying(), it will start playing, and keep going until you stop it with StopPlaying(), or, if it's not looping, until it reaches the end of the file.

It's important to note that the first BGameSound instance you create determines the format of the connection between BGameSound and the Audio Mixer. In our sample program, we create a dummy 44 kHz stereo sound and immediately delete it to establish the connection in a known format, since otherwise the first file the user drags into the program will determine the format that all files will be played back as.

All BGameSound instances that are playing are mixed into one connection to the Audio Mixer; this connection is currently named after your application with no way of changing it. In some future version of the API, we may let you create more than one connection, and name these connections. That's what the BGameSoundDevice argument is for in the constructors for these classes; however, we currently only support the default (NULL) device, so you can leave it to the default value without worrying about it.

If you want to set the pan position or gain (volume) of a BGameSound, you do that by calling SetPan() and SetGain(). The "duration" parameter (which is optional) allows you to specify that the change should take place over some amount of time, if the sound is currently playing. Thus, if a file was playing, and you wanted to fade it out over the course of two seconds for a soft ending, you could call SetGain(0.0, 2000000LL).

You can also change the effective sampling rate of a BGameSound. This changes both the pitch and duration of the sound. The BGameSound system contains a built-in software resampler which uses a fast, reasonable quality 0-th order resampler. There is no additional overhead of playing a sound at some other sampling frequency than the one you initially specify. However, there is no SetSamplingRate() function; instead, you have to use the low-level SetAttributes() function to change the B_GS_SAMPLING_RATE attribute. Again, you can specify a duration during which the change ramps in. Thus, if you're playing a sound at a 22000 Hz sampling rate, and ramp it to 12000 Hz with a duration of 500000, it will take approximately half a second for the full change to take effect. The resulting sound effect is similar to a tape deck or record slowing down. Specific details are found in the gameplay.cpp file in the source code that goes with this article:

<ftp://ftp.be.com/pub/samples/game_kit/gameplay.zip>.

In the next couple of installments, we'll delve into the gory details of what happens when you send a BMessage in the BeOS. I won't be discussing archival or other ancillary uses of BMessages here. We'll just look at pure, simple messaging—BeOS-style.

BMessage myMsg;
myMsg.what = 'RUSH';
myMsg.AddInt32("shrug", 2112);
be_app->PostMessage(&myMsg);

BMessage* myMsg = new BMessage(B_QUIT_REQUESTED);
BMenuItem* item = new BMenuItem("Quit", myMsg, 'Q');
// item now owns myMsg, and will delete myMsg when it's
// done with it

BMessage myMsg('BARF');
float* buf = new float[256];
...
myMsg.AddData("stuff", MY_STUFF_TYPE, &buf, 256*sizeof(float));
// buf still belongs to us, so we have to clean it up!
delete [] buf;

// the wrong way
BMessage* msg = ...
const char* msgstr = msg->FindString("my string");
delete msg;
// msg has been deleted, so msgstr is now invalid!

// the right way
BMessage* msg = ...
const char* msgstr = msg->FindString("my string");
// copy the data out of the message, so that
// it'll be valid when msg goes away!
// BString does this for us . . .
BString str(msgstr);
delete msg;

Concerned readers have written to ask why I stopped writing my weekly column. The cheeky answer is that I've been suspended by the SEC, but the truth is quite the contrary, as you'll read in a moment.

For the past four weeks, we've been involved in what is ritually called an IPO Road Show, touring the U.S. and Europe to meet with institutional investors. During that time, and for 25 days following today's IPO, we're in what is called a "quiet period." This means that we cannot make any comments that could be construed as "promoting" our public offering. The company's only allowable public statement on this matter is contained in the prospectus, a document filed under SEC supervision.

Under such conditions, given my occasional recourse to poetic license, I decided that temporary silence was the safest choice of words. Also, the Road Show process undeniably consumed a great deal of time and psychic energy.

But to return to the SEC—I come from a different culture. Not so long ago in France and other European countries, insider trading wasn't a crime. In any case, Europe's clubby, opaque business culture makes enforcement of prohibitions on such things difficult. Publicly traded companies publish their numbers months, not days after the close, and shareholders are subjects, not bosses.

Consequently, I like the climate of greater trust the SEC fosters in its watchdog and, I might add, guide dog role here in the U.S. I've read many complaints about the "Plain English" rule. From my perspective, however, purging prospectuses and other filings of "whereases" and "foregoings" can only benefit normal humans who want to trust the investment process. In our case, the SEC was extremely punctual, helpful, civil, and service oriented, right through the very last nervous moments of the process.

I'll be back soon with road stories and other anecdotes—stand by.