|
|
Open Sound System
|
First of all this guide doesn't cover simple changes such as bug fixes. Just send them (diff -c or diff -u) to the oss-devel mailing list or to hannu@opensound.com. We will check the changes and apply them to the source tree if possible.
We are opening a source code repository (Mercurial) for OSS 4.1. This document was written for the period before Mercurial.
Here is a short summary about the procedure for submitting contributions to the Open Sound System project. However you should read the entire guide before submitting anything.
Join the oss-devel mailing list.
It is recommended that you propose the changes you have planned to do. There may be somebody else already working on the same feature or driver. In particular changes to the OSS API itself (soundcard.h) should be approved in advance.
Follow the rules for OSS programming (below).
Sign the contributor agreement and send it to 4Front Technologies.
Post your diffs (diff -c or diff -u) to the oss-devel mailing list. If this is a new driver then you can also post the whole driver directory as a tarball (do not include any other files of the OSS source tree). After the Mercurial site is up it will also be possible to make changes directly to the repository.
If the change is acceptable it will appear in the development sources within few weeks.
The programming style used in OSS is “legacy Unix”. It is different from Windows. It's also somehow different from Linux (not much). However there are just few strict rules.
Look at some existing OSS source files to see how the code is written.
The indentation of the sources uses the same rules as GNU indent utility (with default settings). This means that the corresponding '{' and '}' characters should always be in the same column (which differs from the style used in Linux). Also “if” and “else” should be on the same column. There is no point in using different indentation practice in new code because the whole OSS source tree will be autoindented periodically.
Open Sound System is designed to be compiled under any operating system (current or future) in the world. This means you are not allowed to include any header files for any operating system. This in turn means that you cannot call any operating system specific kernel functions. You can only use the services defined in the internal documentation of OSS.
You are not permitted to include/add any copyright or license statements to the sources. You can say you are the author of the code but you cannot put any “Copyright © by Yourself” statements to the comments or anywhere else in the code. You cannot state that the code is licensed under GPL, BSD, CDDL and/or any other license. You cannot restrict the code to be used under some operating system or not to be used under something else. All this is handled by the contributor agreement you have signed with 4Front. However see the section about the “Copyright tag” (below) for information about embedding your copyright info to the source.
Each source file should have a special comment in the beginning. See the “Initial comment” section (below) for more info.
The above rules are are mandatory. You have to follow them if you like to contribute anything to OSS. Here are few more rules you should follow if possible.
So called Hungarian notation is normally used in Windows programming. It means that each variable has a type prefix (for example pdwSomething, lpSomethingElse, sName and so on). Do not use this variable naming style in OSS unless you are porting existing code from Windows to OSS.
Do not export any symbols (variables, functions) unless there is some strong reason to export them. Instead declare all functions and top level variables as static.
You can name static variables/functions as you like provided that the name is descriptive (enough).
Use one character variable names (i, j, k, l, n, s, p, etc) and names like “tmp” only for loop counters and temporary variables that have limited span. Preferably the lines that use such variables should fit on the screen at the same time.
Globally exported symbols (variables and functions) should have some unique prefix. For example mydrv_.
Add reasonable amount of comments. Try to tell why the code does what it does. Do not waste time in trying to repeat the code in plain english (or any other human language).
What you must never ever do
Do not run GNU indent, cb or any other utility that changes the layout of the source code. This makes it impossible to check the changes you have made. In addition it may be impossible to apply your changes back to the official source tree. You can only run indent yourself before submitting the initial version of some new source file. You can also use indent before the code has been included in the official sources.
Do not touch the API (soundcard.h) or do changes to any of the global header or source files that belong to the OSS framework. This kind of changes can only be made by the persons who are responsible for such files. If you need this kind of changes to the common code then you should make a proposal to the oss-devel mailing list.
Each source file should have an initial comment in the beginning. This comment gives a subject for the file (visible in the source code index on the web site) and some other information about the source/module. Optionally it can contain a list of the authors who have developed or modified the file. Also a short change log is permitted (however change logs should preferably be kept in the .changelog files).
For example:
/* * Purpose: Driver for ACME123 turbo sound booster chipset * * This driver supports both the original ACME123 chip and the updated EMCA321 one. * * Authors: Me Original version, 2002-2003 * Myself Support for EMCA321, 2005 * I Modified for OSS 4.0, 2007 */
OSS source files included in the official (golden) source tree are not permitted to have any copyright statements or license restrictions mentioned in the comments or embedded in variables or display statements. When you sign the contributor agreement you give 4Front Technologies to redistribute your contribution under multiple different licenses. The corresponding license statement will be etched to the source files when the export tarball for that license is cut (as you have seen we have separate tarballs for GPL, CDDL and BSD licenses).
Each source file should have a copyright tag line after the initial comment. This line marks the location where the final copyright statement will be inserted. For example:
#define COPYING © Me, Myself and I, 2002-2007. Licensed to 4Front Technologies.
The above line is sitable for the C source files (.c). Header files (.h) cannot define the COPYING macro again because that may cause warnings about conflicting defines. Instead driver's private header files should use the COPYING2 to COPYING8 tags.
Take a look at the internal documentation of OSS. It explains how to write new drivers for OSS.