| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
Each driver must have a name that is unique to that project. The name must be something that nobody else will not select. It must also be intuitive so that the name tells clearly which device the driver controls. In addition the name should be as short as possible. Good names are base on the family or model name of the device or the primary (controller) chip used in it. Using device/chip manufacturer company names is not a good idea since the same company may produce different devices (some of them may even not be sound devices). In addition it's recommended tha the name doesn't end with a digit since device instance names will have a digit (0-9) appended to them. Changing the driver name will be very difficult after the initial release so please be carefull (it's easier until you release the code).
After you have decided the name of the driver you can proceed by creating the source directory. Driver directories will be created under the kernel/drv directory of the OSS source tree (not the build directory tree but the source one).
In the following discussion we will assume the driver name is "myossdev". So you will need to create the directory using mknod kernel/drv/myossdev.
It's not permitted to have subdirectories in the driver source directory. Each subdirectory will be handled as a separate driver by the build tools.
After the directory is created you need to cd to it and start creating the initial files.
The key philosophy of OSS is that the (OS dependent) build environment will be created based on the config files available in the source directory of the driver. Another goal is to avoid redundant information. This approach guarantees maximum portability because the driver source files don't contain anything that depends on the target operating system.
The driver source directory will contain few hidden files (names starting with ".") which the configure script (and the srcconf.c program) will use when creating the environment. In addition the directory will contain one or more source (.c or .cpp) and header (.h) files that contain the actual driver code. Name of the main source file doesn't matter but usually it's named lime myossdev.c. If there are multiple C/C++ sources then (by convention) the driver should have a common definition header file (myossdev.h) that contains common variable/structure/macro declarations and function prototypes.
In addition to the C/C++ source and header files there are several control files used by the build environment creation tools. There is uusually no Makefile which is automatically created by the tools. It is possible to have a precreated Makefile but in general this is not recommended for portability reasons.
The possible control files are defined below.
The .nomake file is very simple and straightforward. If a .nomake file exists in any directory the build tools will skip the directory and all it's subdirectories. This file is only useful if you (for asny reason) want to disable the driver from being compiled.
This file contains the key settings for the driver. Every subdirectory in the source tree inherits all the settings defined in the parent directories (recursively). All local settings will override the inherited settings. For this reason drivers developers must be very carefull when adding unknown or unclear definitions to this file. Take a look at the .config file for a similar driver when creating a .config file.
The .config file is optional and only necessary if the any of the default values need to be overwritten. The defaults are suitable for a PCI driver that works under all operating systems and processor architectures.
Lines starting with '#' are comments and they will be ignored by the build tools.
Under construction
The .devices file contains a list of devices supported by the driver. This file is mandatory and must be present in every driver directory. This file is used by the build tools to connect the supported devices to the right driver. Each line of the file defines one device id and has the following format:
drivername device_id Free form name/explanation.
It's very important that the separators between the fields are a tab character instead of a space. Spaces are only permitted in the explanation field. In the above example there is a space just for typesetting reasons.
The drivername field contains the name of the driver (such as myossdev. This field must match exactly the name selected for the driver.
The device_id field contains the device ID of the device/model defined by this line. For PCI devices it is pciVENDOR,DEVICE where vendor is the hexadecimal PCI vendor ID (without leading zeros) and DEVICE is the PCI device ID (without eading zeros). For example pci1102,2 is the Sound Blaster Live family. In some cases the device can be identified more precisely by it's PCI subvendor/device ID. In this case the device ID format is pcsSUBVENDOR, SUBDEVICE. Use of subvendor ID might be usefull (but not necessary) if it makes it possible to identify the device more precisely (using the "major" PCI id is enough to connect the device to the right driver). If subdevice IDs are used it's necessary to have entries for the master PCI device ID also defined in the .devices file.
For USB devices the device entries must be defined in the .devices file of the ossusb driver (there cannot be separate drivers for USB devices).
For Virtual/pseudo drivers the device_id field must be an upper case name of the driver. For example MYOSSDEV.
The Free form name/explanation field gives the descriptive textual name of the device (for example "Sound Blaster Live family"). It gives the name of the device shown in the configuration utilities.
Lines starting with '#' in column 1 are comments. However '#' is only valid in column 1. Anywhere else it's regarded as a part of the content. Comment lines will be stripped when the .devices files are collected to the central devices.list file. So comments in .devices are only usefull for information targeted to developers and maintainers of the driver. Empty lines are not permitted.
OSS device drivers can have private run-time parameters. Such parameters are signed integer (int) values that are automatically initialized when the driver loads. The driver can declare them as extern int variables which are used when the driver loads. This file is optional and not required if the driver doesn't have any configuration options.
The .params file syntax is C source file with int variable definitions (with initialization to the default value). Each parameter variable definition willbe followed an ANSI C comment that describes usage of the parameter). The .params file may have an initial comment (before all variable definitions) that gives general guidelines for the parameter usage of the driver.
Each configuration option name must be prefixed by the driver name. In some operating environments all drivers may share the same name space. Using the same option name in multiple drivers may cause serious problems.
The exact mechanism for loading the parameter variables is operating system dependent. However in all cases the parameter variables are valid when the attach routine of the driver is called. After the attach routine these variables may have been initialized for the next instance of the device so they must not be accessed after the attach entry point is finished.
The driver code can access these variables by declaring them as extern int in the beginning of the source (or in the header files). The .params file will be automatically converted to the format used by the target operating system. Usually the configuration files will be located in /usr/lib/oss/conf in the target system.
If this special flag file exists the build tools will not create the Makefile for this driver. Instead the Makefile present in the driver directory will be used. For portability reasons use of this method is not recommended.
Each driver should have a manual file describing usage of the driver an (in particular) i's config variables (.params). The format of this file is not traditional manpage format (nroff) but a simple text file. Each line containing just upper case letters starts a new section. If the section name line has initial spaces then the line will start an subsection. The number of initial spaces gives the subsection level. See a .man file of some existing driver as an example.
The commands and procedures used to manage the drivers will slightly different between operating systems. For this reason driver man files should not refer to any specific commands or file names/locations.
This optional file contains the change log for this driver in the usual format. The latest changes are in the beginning of the file. For each change it's necessary to give the modification date, name/e-mail of the author, previous OSS version (which the change is based on) and description of the change and it's possible effects.
This file contains the name and e-mail of the author or current maintainer of this driver. It is also possible to give web site of the driver sub-project working on this driver. If there is no .maintainer file then it's assumed that 4Front Technologies is maintaining the driver.
Drivers must not create files named like myossdev_cfg.c or myossdev_cfg.h. The build tools will automatically generate these files and overwrite any earlier files with the same name.