Starting this summer we'll have new customer-oriented BeOS packaging, flyers, posters, and other materials. We'll be advertising and getting the retail outlets in place to deliver BeOS and third-party products to buyers.

BeDepot is a great place to sell your BeOS product, especially to users who buy a new computer that ships with BeOS pre-installed. But BeDepot does not sell your product on retail store shelves. You've got to get the product into a box for that.

We're doing our part. We've been working hard to get distribution channels in place to handle BeOS retail store orders. Starting this summer some opportunities to sell through major chains may be available to you, but your product must be finished and in a box.

Our retail channel sales are international. In Europe Stephan Landier <slandier@beeurope.com> has been working hard for you. He needs products with manuals and boxes in English, German and French. In Japan Takeaki Akahoshi <akahoshi@be.com> is looking for products with Japanese boxes and manuals, and which support our Japanese input method.

In case you missed it, the message of this article is that Be has been working to establish retail store sales to end users for sales of R4.5 with the intention of enabling you to make money with your BeOS products. These resellers and distributors are asking for additional third-party products to recommend to their BeOS customers. "Would you like fries with that, sir?" It's part of the retail equation—resellers want add-ons to sell at time of purchase and customers want those products to use. Will it be YOUR product? Only if you finish it and get it into a box.

We're beyond the "chicken-and-egg" paradox, where the conventional wisdom had it that there was a need for BeOS applications to bring in customers and customers to bring in the applications. We're now arriving at the point where there is serious customer and reseller interest in the BeOS, but there aren't enough boxed products to satisfy customer demand. This is great news for you, the developer. It's the beginning of the expected "green field" effect for the early (smart) BeOS developers, where good products in good boxes along side the BeOS can enjoy good store sales with little competition. This helps Be and it helps you. It helps us because third-party products help persuade even more customers to purchase BeOS. It helps you because the customers who buy the BeOS want third- party products to use. Assuming, of course, that they are finished and in a box.

To sell in a retail store your product must be in a box. Visit a few computer stores and look at the packaging used by different software companies, if you need ideas. The box must have a UPC bar-code, consisting of your manufacturer ID and a product number. The Uniform Code Council is the organization that assigns manufacturer ID numbers for use in UPC retail bar codes. Check the following web site to arrange to get your manufacturer ID: http://www.uc-council.org/. A company that provides software for printing bar codes, as well as good general bar code info is at http://www.mecsw.com/.

Provide end-user-oriented copy on the back listing BENEFITS. Customers don't care what the product is called and—you'll be surprised to know -- their interest is not so much what the product is. Customers are selfish. They want to know WHAT'S IN IT FOR THEM. They want to know how using this product benefits them, what they can DO with it. Here's an example:

"The BeBop bop program is a utility that will bop your hard drive seven times a day. It is the only bop program that has a special symbop doopap doobopper."

The customer doesn't care. But—the same information put a different way will work wonders:

"With BeBop your hard drive is bopped clean so often that you'll never worry about a bop problem again. Our unique symbop doopap doobopper ensures swift debopping action."

ADVERTISE. Whether you're selling at BeDepot or in stores people aren't likely to purchase your product if they don't know about it. It just ain't so that if you build it they will come. That worked in a movie, but the likelihood of selling to customers who don't know about your product is about as high as the likelihood of a dead pitcher stepping out of a cornfield into your yard. You can wait for that to happen or you can advertise.

BeOS news web sites are visited by thousands of BeOS users and their ad rates are reasonable. You should place ads at these sites to build name recognition and mind share for your products. Eventually these BeOS users will find their way to BeDepot or stores to purchase your products.

I think it's important to understand that you and I and most of the people we know are computer sophisticates. We know more about computers and the industry than the people we're selling to and this has major implications. We probably don't understand what the average end-user, cruising an aisle in a store in Ohio, sees or thinks or wants or needs.

I just finished reading the book, "Why We Buy," by Paco Underhill http://www.amazon.com/exec/obidos/ASIN/0684849135. I strongly recommend this book to anyone selling a product. It's about a consulting firm that sends people out to follow customers around in stores to see what they actually do. It contains example after example of what happens when marketing people come up with "brilliant" ideas without understanding their customers, and describes what happens when the customer is confronted with these examples of marketing foolishness in a store.

Here's a good example from the book: Some casino hotels don't provide lobby seating, hoping to drive people into the casino. Instead, this practice results in gloomy lobbies where incoming guests are confronted with lots of tired, unhappy people (the losers) sitting on the floor along the edges of the lobby waiting for their tour vans and buses. This book will help adjust your brain around how to think about retail channels and end-users and about using marketing research. So will one of my previous articles, "Testing and Tracking."

The kernel manages device drivers through devfs, the file system mounted at /dev during the boot process. Communication between user space and drivers occurs through entries published by the driver in the /dev hierarchy. Therefore, the basic primitives for interacting with drivers map to basic file operations: open, read, write, readv, writev, ioctl, and close.

Drivers tell devfs which entries they want to appear in /dev through a mechanism known as "publishing." Devfs publishes drivers as needed. Typically, this means it publishes drivers the first time a program iterates through the directory entries for a subdirectory in /dev. The kernel knows which drivers publish entries in any given portion of the /dev hierarchy through a simple mapping mechanism: binaries appear in /boot/beos/system/add-ons/kernel/drivers/dev in locations that correlate to their published entries in /dev. For example, the atapi driver publishes drivers in /dev/disk/ide/atapi, so its binary appears in /boot/beos/system/add-ons/kernel/drivers/dev/disk/ide/atapi.

Actually, this is a lie. Since drivers may publish entries in more than one location in the /dev hierarchy, the entries in /boot/beos/system/add-ons/kernel/drivers/dev are typically symbolic links to the actual binaries which live in /boot/beos/system/add-ons/kernel/drivers/bin. Of course, the same discussion applies to user-installed drivers in /boot/home/config/add-ons/kernel/drivers/...

The driver entry points are the scaffolding required for communication with devfs:

status_t init_hardware(void);

This function is called when the system is booted, allowing the driver to detect and reset the hardware. The function should return B_OK if the initialization is successful or an error code if it is not. If the function returns an error, the driver will not be used.

status_t init_driver(void);

Devfs loads and unloads drivers on an as-needed basis. This function is called when the driver is loaded into memory, allowing it to allocate any system resources it needs to function properly.

void uninit_driver(void);

Conversely, this function is called when the driver is unloaded from memory, allowing it to clean up after itself.

const char **publish_devices(void);

Devfs calls this hook to discover the names, relative to /dev, of the driver's supported devices. The driver should return a NULL-terminated array of strings enumerating the list of installed devices supported by the driver. For example, a network device driver might return the following:

static char *devices[] = {
    "net/ether",
    NULL
};

Devfs will then create the pseudo-file /dev/net/ether, through which user level programs can access the driver.

Only one instance of the driver will ever be loaded, so it must be prepared to gracefully field requests for multiple devices. Typically, this is handled by exporting a separate entry for each device present in the system. For example, the serial driver exports /dev/ports/serial1, /dev/ports/serial2, and so on, up to the number of serial ports present in the system.

device_hooks *find_device(const char *name);

When an exported /dev entry is accessed, devfs calls a set of driver hook functions to fulfill the request. find_device() reports the hooks for the entry name in a device_hooks structure. The structure, detailed in be/drivers/Drivers.h, is composed of function pointers, described below in the section "Device Hooks."

int32 api_version;

This variable defines the API version to which the driver was written; it should always be set to B_CUR_DRIVER_API_VERSION (whose value, naturally, changes with the driver API).

status_t open_hook(const char *name, uint32 flags, void **cookie)

This hook is called when a program opens one of the entries exported by the driver. The name of the entry is passed in name, along with the flags passed to the open() call. cookie is a pointer to a region of memory large enough to hold a single pointer. This can be used to store state information associated with the open instance; typically the driver allocates a chunk of memory as large as it needs and stores a pointer to that memory in this area.

status_t close_hook(void **cookie)

This hook is called when an open instance of the driver is closed. Note that there may still be outstanding transactions on this instance in other threads, so this function should not be used to reclaim instance-wide resources. Blocking drivers must unblock ongoing transactions when the close hook is called.

status_t free_hook(void **cookie)

This hook is called after an open instance of the driver has been closed and all the outstanding transactions have completed. This is the proper place to perform uninitialization activities.

status_t read_hook(void *cookie, off_t position, void *data, size_t *len)

This hook handles read requests on an open instance of the device. The function reads *len bytes from offset position to the memory buffer data. Precisely what this means is device specific. The driver should set *len to the number of bytes processed and return either B_OK or an error code, as appropriate.

status_t readv_hook(void *cookie, off_t position,
const struct iovec *vec, size_t count, size_t *numBytes)

This is the scatter-gather equivalent of read. The function is passed an array of count iovec entries describing address/length pairs to put data read starting at position. As with read_hook, the function should set *numBytes to the number of bytes processed and return an appropriate error code.

status_t write_hook(void *cookie, off_t position,
void *data, size_t len)

status_t writev_hook(void *cookie, off_t position,
const struct iovec *vec, size_t count, size_t *numBytes)

Conversely, these hooks handle write requests. Again, the meaning of "write" is device specific.

status_t control_hook(void *cookie, uint32 op, void *data, size_t len)

This hook handles ioctl() requests. The control hook provides a means of instructing the driver to perform actions that don't map directly to read() or write(). It is passed the cookie for the open instance as well as a command code op and parameters data and len supplied by the caller. data and len have no intrinsic relation; they are simply two arguments to ioctl(). The interpretation of the command codes and the parameter information is defined by the driver. Common command codes can be found in be/drivers/Drivers.h.

NOTE: len is only valid when ioctl() is called from user space; the kernel implementation of ioctl always passes 0 in the len field.

status_t select_hook(void *cookie, uint8 event, uint32 ref,
                                        selectsync *sync);

status_t deselect_hook(void *cookie, uint8 event,
                                        selectsync *sync);

These hooks are for future use; their corresponding entries in the device_hooks structure should be set to NULL for now.

The following rules apply for any given open instance of a driver:

I've put together a sample device driver that you can find at <ftp://ftp.be.com/pub/samples/drivers/digit.zip>. After you build it, you should place the binary in ~/config/add-ons/kernel/drivers/bin. You should also create a link to it in ~/config/add-ons/kernel/drivers/dev/misc, i.e.:

mkdir -p ~/config/add-ons/kernel/drivers/dev/misc
cd ~/config/add-ons/kernel/drivers/dev/misc
ln -s ../../bin/digit .

Writing media applications to use offline nodes is straightforward, though a little more complicated than more standard real time apps. Our advice boils down to two main points:

Following these two rules will help make sure that the output from offline nodes is what you expect.

Nodes that are derived from BMediaEventLooper (and why would you want to do it any other way?), already have a good deal of infrastructure for handling offline mode. BMediaEventLoopers have an internal sense of time in offline mode which can be accessed and set through SetOfflineTime() and OfflineTime(). For most nodes, this simple value is sufficient, but if necessary, OfflineTime() can be overridden to provide more specific behavior.

The BMediaEventLooper has a different control loop in offline mode that bases actions on the offline time. The loop looks like this:

The gist of the loop is to wait for messages and add events to the event queue until the offline time is updated for the node. Then handle all events in the event queue up to and including the new offline time.

Only a node can determine the exact conditions required to advance its internal sense of time, but there are some general guidelines. Offline time advances under two circumstances: when starting and stopping the node, and through buffer flow.

When Start() is called and the looper is currently stopped, set offline time to the start time and add the start event to the queue. When handling a B_STOP event in HandleEvent(), look to see if there is another start event in the queue, and advance offline time to that event's time. This will ensure that events start to be handled appropriately.

Advancing offline time based on buffer flow varies depending on the type of node: producer, consumer, or both.