Contributing to the UDI Reference Implementation

We welcome contributions.  There are many ways you can help: new environments; new drivers; bug fixes;  adding missing features;  enhancing existing code; documentation updates and others.
 

Index:
    Coding Standards
    Environnmental Hazards
    Documentation
    License
    Test Requirements
    Submitting Patches

Coding Standards

• All code
• 8 space tabs.
• Curlies (exception for function open curlies) go on the same line.  Use


if (x) {

not

if (x)
{

• Every function should be preceeded by a block comment describing the purpose of the function as well as expected callers, visible side effects, and so on.
• Don't use the source code for descriptions of what you change. Use the CVS logs for that. In particular, comments in the code containing dates describing changes and names of changers are distracting; that's what revision control is for.
• Try not to have personal names or conversations in the code. If you need to talk to someone, talk to them.
• Be consistent with comment blocks. Here's the convention.
• Code

 

 

/*
 * File: env/common/udi_MA.c
 *
 * Comment about this file.
 */

/*
 * $Copyright udi_reference:
...
 * $
 */

• Shell scripts

 

 

Shell scripts look like:
#!/bin/sh   - if a shell script
# File: env/common/Make_udibuild
#
# Description
#

#
# $Copyright udi_reference:
....
# $
#

• Better yet, we provide a set of options for GNU indent 2.2.6 that we've used on the code. Install this set of options in your ~/.indent.pro and use indent to help keep code consistent. The most recent copy of this file is also checked into the top of the udiref tree.
• Drivers
• UDI Drivers must be strictly conforming.
• Must include a README describing exactly what hardware is supported, where it can be obtained, support contacts, and locations of additional documentation.
• Environment
• Assume C89.  We don't care about K&R C and C99 isn't yet common enough to use. No C++ because many kernel environments don't allow C++ code.
• Prototypes are required.
• Vendor extensions are acceptable in osdep code, but prohibited in the common code.
• Detect flagrant driver bugs with _OSDEP_ASSERT; don't attempt recovery from driver mistakes.
• Handle runtime errors gracefully; propogate errors back to the caller.
• Be prepared to deal with other environment maintainers.  What may be a logicial interface for your operating system may be painful to implement in another.
• Global data or functions should be tagged as STATIC. In most cases, this will get #defined to static. This convention is so users of tools that can't grok static identifiers can still #define it away.
• Anything can be STATIC or static should be.
• Identifiers not meant to be exposed but that cannot be static should start with a '_udi'.  This is consistent with the ISO requirment of "implementation" and legal in the environment.   It is illegal in drivers.
• When possible, use enums instead of #defines so they show up nicely in debuggers.

Environmental Hazards

• The common environment runs on a number of disparate host OSes. That _OSDEP stuff isn't meant to be obfuscating, it's meant to allow flexibility for abstracting OS interfaces into something usable on all the OSes. Sometimes it can be done as a macro. Sometimes it requires a macro that turns into a function and then providing a function.
• The _OSDEP_MUTEX and OSDEP_EVENT families of services have some very detailed (and non-obvious) restrictions in their use.   These are spelled out in env/common/udi_osdep_defaults.h.
• You must be extremely careful about stack [mis]use around the waits.  In particular, you must never hold an address of a local variable across WAIT operation. I.e. don't do this:


{
        udi_status_t status;
        _OSDEP_EVENT_INIT(&event);
        do_something_with(&event, &status);
        _OSDEP_EVENT_WAIT(&event);
        return status;
}

On some OSes, the stacks of all the CPUs may share the same virtual address and on some OSes, local stacks aren't preserved across a context switch (which may be inspired by the _OSDEP_EVENT_WAIT).    So the `status' value seen by the return may well be different memory than what was populated by the called function.
 

• Stack usage must be well-guarded because many OSes have very tiny kernel stacks.   A good guideline is to use no more than 200 bytes in a local frame.

Documentation Standards

The documentation for this project is all CVS controlled.   Changes to it are via commits to the tree, just like code.

Generated HTML (as from Netscape Composer) is adequate, though hand-edits on the files are probably more common for day-to-day changes.

License Requirement

Whereas the following parties, having contributed significantly to the REFERENCE IMPLEMENTATION, are empowered, singly or jointly, to publish and maintain current and future versions of the REFERENCE IMPLEMENTATION: Hewlett-Packard Company, The Santa Cruz Operation, Inc., Compaq Computer Corporation, International Business Machines, Interphase Corporation, Sun Microsystems, Inc., Intel Corporation, Software Technologies Group, Inc., and American Megatrends, Inc. (collectively, the "Maintainers");

The Contributor hereby grants to the Maintainers and their successors and assigns, a world-wide, unrestricted, perpetual, non-exclusive, fully paid-up and royalty-free right and license to (i) prepare and/or have prepared DERIVATIVE WORKS of such CONTRIBUTED CODE; (ii) internally use, execute, copy, reproduce, display, perform, modify and have modified, such CONTRIBUTED CODE and such DERIVATIVE WORKS; and (iii) to distribute and sublicense such CONTRIBUTED CODE and DERIVATIVE WORKS, in the form of Source Code, under the terms of the Project UDI Open Source License.

The Contributor retains sole ownership of its CONTRIBUTED CODE. Nothing in this Contributors Agreement shall be deemed to transfer ownership of any portion of such CONTRIBUTED CODE from one Party (or its suppliers) to another Party. Subject to the non-exclusive licenses granted in this Contributors Agreement or other written agreement between the Parties, the owning Party shall be free in all respects to exercise or dispose of any or all of its ownership rights in its own CONTRIBUTED CODE, without accounting to any other Party.

Test Requirements

If possible, you should ensure that your change will at least compile on another OS.   Shell accounts on Linux  and BSD systems are available through SourceForge's compilefarm facility.

The POSIX environment is a handy test fixture to allow debugging & development of code that doesn't require DMA or "real" interrupts as a user-space application.  A 'make torture'  delivers a suprising amount of coverage of env/common; over 85% last time it was checked.   It simulates things like memory allocation failures, regions being busy across a udi_mei_call, and control block reallocation on every channel operation.   When combined with a multiple CPU system (it uses POSIX threads) and an instrumented memory checking library like Electric Fence or that avilable in many mallocs, it can help find a number of problems that are hard to expose in kernel code.
 

Submitting Patches

• A brief description of the problem solved.
• A description of how and where the change has been tested.
• A GNU-style ChangeLog entry. If you're not familiar with this, there is a good reference in the Guile doc.
• The patch itself as generated by a cvs diff -u -p -N

.
• When possible, a testcase that exercises the new functionality or bug fixed. The POSIX framework is handy for this.

File last modified: 00:00 Thu January 1, 1970