Difference between revisions of "Kernel Normal Form"

From Embedded Xinu
Jump to navigation Jump to search
m (→‎Comments: Aligned file and provides lines)
Line 1: Line 1:
This page specifies the preferred style for kernel source files in the [[XINU]] operating system source tree.  It also provides a guide for preferred userland code style.  Many style rules will not be explicitly stated, but rather implicit through examples in this guide.  Be careful to check the example before assuming that this guide is silent on an issue.
+
This page specifies the preferred style for kernel source files in the [[Xinu]] operating system source tree.  It also provides a guide for preferred userland code style.  Many style rules will not be explicitly stated, but rather implicit through examples in this guide.  Be careful to check the example before assuming that this guide is silent on an issue.
 +
 
 +
Xinu now includes an <code>indent</code> target in the Makefile which will automatically parse all the source code into a [[w:Indent_style#K.26R_style|K&R]]-like format.
  
 
== Comments ==
 
== Comments ==
  
/**
+
<source lang="c">
  * @file    style.guide
+
/**
  * @provides style, guide
+
* @file    style.guide
  * This is the opening comment block for a file.
+
* @provides style, guide
  *
+
* This is the opening comment block for a file.
  * $Id$
+
*
  */
+
* $Id$
 +
*/
 +
</source>
  
 
The copyright header should be a single-line comment that immediately follows the opening comment block.
 
The copyright header should be a single-line comment that immediately follows the opening comment block.
  
/* Embedded XINU, Copyright (C) 2007, 2008.  All rights reserved. */
+
<source lang="c">
 +
/* Embedded Xinu, Copyright (C) 2008.  All rights reserved. */
  
/*
+
/*
  * Immensely important comments look like this.
+
* Immensely important comments look like this.
  */
+
*/
  
/* Typical single-line comments look like this. */
+
/* Typical single-line comments look like this. */
  
/**
+
/**
  * Multi-line comments that should appear in the autogenerated documentation
+
* Multi-line comments that should appear in the autogenerated documentation
  * should look like this.
+
* should look like this.
  */
+
*/
  
/** Single-line comments to appear in documentation look like this. */
+
/** Single-line comments to appear in documentation look like this. */
/**< or they look like this. */
+
/**< or they look like this, if appearing on the same line as code. */
 +
</source>
  
 
The first form of single-line comments goes above the code that it pertains to, whereas the second form will appear on the same line as the code it describes.
 
The first form of single-line comments goes above the code that it pertains to, whereas the second form will appear on the same line as the code it describes.
Line 37: Line 43:
 
As a precaution against multiple definitions every include file should protect itself against redefining its material.
 
As a precaution against multiple definitions every include file should protect itself against redefining its material.
  
#ifndef _INCLUDE_H_
+
<source lang="c">
#define _INCLUDE_H_
+
#ifndef _INCLUDE_H_
[...]
+
#define _INCLUDE_H_
#endif /* _INCLUDE_H_ */
+
[...]
 +
#endif                           /* _INCLUDE_H_ */
 +
</source>
  
 
After the opening comment block and copyright of a file, include one blank line and begin including non-local header files.  Typically these should be ordered from most important (kernel-level) to least important (user-level).
 
After the opening comment block and copyright of a file, include one blank line and begin including non-local header files.  Typically these should be ordered from most important (kernel-level) to least important (user-level).
  
#include <kernel.h>
+
<source lang="c">
#include <device.h>
+
#include <kernel.h>
#include <memory.h>
+
#include <device.h>
#include <string.h>
+
#include <memory.h>
 +
#include <string.h>
 +
</source>
  
 
Now, if there are local header files include a blank line and then continue including files.
 
Now, if there are local header files include a blank line and then continue including files.
  
#include "local.h"
+
<source lang="c">
 +
#include "local.h"
 +
</source>
  
 
Macro definitions should typically be in ALL CAPS, unless it goes against a standard.  If a macro is being used in lieu of a function the macro should be defined in ALL CAPS.  If the macro consumes multiple lines, align the backslashes one space to the right of the longest line.  Any final statement-terminating semicolon should not appear in the macro, rather it will be supplied by the invocation on the macro to allow easier parsing of the code by humans and editors alike.
 
Macro definitions should typically be in ALL CAPS, unless it goes against a standard.  If a macro is being used in lieu of a function the macro should be defined in ALL CAPS.  If the macro consumes multiple lines, align the backslashes one space to the right of the longest line.  Any final statement-terminating semicolon should not appear in the macro, rather it will be supplied by the invocation on the macro to allow easier parsing of the code by humans and editors alike.
  
#define MACRO(x, y)      \
+
<source lang="c">
    (x) = (x) + 5 * (y); \
+
#define MACRO(x, y)      \
    (x) /= 3
+
    (x) = (x) + 5 * (y); \
 +
    (x) /= 3
 +
</source>
  
 
When using conditional directives such as <code>#if</code> or <code>#ifdef</code>, it is recommended to place a comment following the matching <code>#else</code> or <code>#endif</code> to make the reader have an easier time discerning where conditionally compiled code begins and ends.
 
When using conditional directives such as <code>#if</code> or <code>#ifdef</code>, it is recommended to place a comment following the matching <code>#else</code> or <code>#endif</code> to make the reader have an easier time discerning where conditionally compiled code begins and ends.
  
#ifdef MIPS
+
<source lang="c">
/* MIPS specific code goes here. */
+
#ifdef MIPS
#else /* not MIPS */
+
/* MIPS specific code goes here. */
/* generic code goes here. */
+
#else                           /* not MIPS */
#endif /* MIPS */
+
/* generic code goes here. */
 +
#endif                           /* MIPS */
 +
</source>
  
 
== Structs and Typedefs ==
 
== Structs and Typedefs ==
Line 71: Line 87:
 
Structures should have logically named members with a comment describing what each member is for.  Structures do not have to have a typedef, but if they do have one it should be inline with the structure definition.
 
Structures should have logically named members with a comment describing what each member is for.  Structures do not have to have a typedef, but if they do have one it should be inline with the structure definition.
  
typedef struct dentry
+
<source lang="c">
{
+
typedef struct dentry
    ushort  major; /**< major device number          */
+
{
    ushort  minor; /**< minor device number          */
+
    int major;                   /**< major device number          */
    void   *csr;   /**< control and status registers */
+
    int minor;                   /**< minor device number          */
    [...]
+
    void *csr;                   /**< control and status registers */
} device;
+
    [...]
 +
} device;
 +
</source>
  
 
== Functions ==
 
== Functions ==
  
All functions '''must''' be prototyped somewhere.  Global functions should have a prototype in a system header file, local functions can be prototyped at the top of its respective source file (or in a local header file).  If the function is local it should use the <code>local</code> type from <code>stddef.h</code>, which will declare it as static and not pollute the namespace.
+
All functions '''must''' be prototyped somewhere.  Global functions should have a prototype in a system header file, local functions can be prototyped at the top of its respective source file (or in a local header file).  If the function is local it should use the <code>static</code> modifier from <code>stddef.h</code>, which will declare it as static and not pollute the namespace.
  
 
Prototypes should not have a variable name associated with the type.  For example:
 
Prototypes should not have a variable name associated with the type.  For example:
void foo(int, int *);
 
  
With multiple prototypes lined up, after the type declarations there should be at least one space before an <code>*</code> and the function names should line up.
+
<source lang="c">
  extern devcall  freemem(void *);
+
void foo(int, int *);
extern void    *getmem(ulong);
+
</source>
 +
 
 +
When creating a function it should be preceded by document comment describing what it does, the parameters it takes, and what it will return, if applicable.  The return type, function name, and parameters should be on the same line unless that line is over 74 characters wideIn that case the remaining parameters should be aligned with the first parameter on the line above.
  
When creating a function it should be preceeded by document comment describing what it does, the parameters it takes, and what it will return, if applicable.  The return type, function name, and parameters should be on the same line unless that line is over 75 characters wide.  In that case the remaining parameters should be aligned with the first parameter on the line above.
+
<source lang="c">
/**
+
/**
  * The main function of the program will parse the input for the arguments passed.
+
* The main function of the program will parse the input for the arguments
  * @param argc  number of arguments passed to function
+
* passed.
  * @param argv  array of char *s containing passed arguments
+
* @param argc  number of arguments passed to function
  * @param func  pointer to function that takes two int parameters
+
* @param argv  array of char *s containing passed arguments
  * @param offset offset into char * array to read
+
* @param func  pointer to function that takes two int parameters
  * @param length length to read at offset
+
* @param offset offset into char * array to read
  * @return 0 on successful completion, non-0 if unsuccessful.
+
* @param length length to read at offset
  */
+
* @return zero on successful completion, non-zero if unsuccessful.
int foo(int argc, char **argv, devcall (*func)(int, int), int offset,
+
*/
        int length)
+
int foo(int argc, char **argv, devcall (*func)(int, int), int offset,
{
+
        int length)
    /* well written code. */
+
{
 +
    /* well written code. */
 +
}
 +
</source>
  
 
== Spacing ==
 
== Spacing ==
  
Languages keywords (such as <code>if</code>, <code>while</tt>, <code>for</code>, <code>switch</code>) all have one space following their use.  This helps differentiate keywords from function calls.  Braces (<code>{</code> and <code>}</code>) should always be used in control statements.  If the control statement is a single-line, the braces can exist on the same line as the statement (and if it's really short the same line as the keyword!).  The use of brackets in all cases helps minimize the risk of bugs occurring when adding new lines to a statement.
+
Languages keywords (such as <code>if</code>, <code>while</tt>, <code>for</code>, <code>switch</code>) all have one space following their use.  This helps differentiate keywords from function calls.  Braces (<code>{</code> and <code>}</code>) should always be used in control statements.  The use of brackets in all cases helps minimize the risk of bugs occurring when adding new lines to a statement.
  
for (i = 0; i < length; i++)
+
<source lang="c">
{
+
for (i = 0; i < length; i++)
    a = i + 1;
+
{
    b *= a;
+
    a = i + 1;
}
+
    b *= a;
 +
}
 
   
 
   
if (NULL != value)
+
if (NULL != value)
{ *value = new_value; }
+
{
 +
    *value = new_value;
 +
}
 
   
 
   
while (TRUE) { /* Do nothing. */ }
+
while (TRUE)
 +
{
 +
    /* Do nothing. */
 +
}
 +
</source>
  
 
Avoid declarations within new statement blocks when possible, certain versions of compilers may not recognize them for what they are.
 
Avoid declarations within new statement blocks when possible, certain versions of compilers may not recognize them for what they are.
  
Indentations are done through the tab (<code>\t</code>) character, allowing each coder their own preference for the size of a tab stop.  This only applies to indentation at the beginning of lines, for spacing (such as aligning comments) use the space character.  If a conditional statement wraps around place the operator at the beginning of the next line (lining up with first variable above).
+
Indentations are done using 4 spaces per level.  If a conditional statement wraps around place the operator at the beginning of the next line (lining up with first variable above).
  
while (count > 30 && TRUE == this_variable_is_true
+
<source lang="c">
        && NULL != value)
+
while (count > 30 && TRUE == this_variable_is_true
{
+
      && NULL != value)
    /* Do something. */
+
{
 +
    /* Do something. */
 +
}
  
if (foo)
+
if (foo)
{
+
{
    /* foo case. */
+
    /* foo case. */
}
+
}
else if (bar)
+
else if (bar)
{
+
{
    /* bar case. */
+
    /* bar case. */
}
+
}
else
+
else
{
+
{
    /* else case. */
+
    /* else case. */
}
+
}
 +
</source>
  
 
Switch statements should be formatted with each case lining up with the braces as follows:
 
Switch statements should be formatted with each case lining up with the braces as follows:
switch (test)
 
{
 
case 0:
 
case 1:
 
    /* Process. */
 
    break;
 
default:
 
    /* Normal case. */
 
    break;
 
}
 
  
There should be no spaces after function names.  Commas should be followed by a space.  Spaces are optional after parentheses and square braces.  Typically there are only spaces with more complex statements.  Code readability is king.  Binary operators should be padded with a space on either side.
+
<source lang="c">
 +
switch (test)
 +
{
 +
case 0:
 +
case 1:
 +
    /* Process. */
 +
    break;
 +
default:
 +
    /* Normal case. */
 +
    break;
 +
}
 +
</source>
 +
 
 +
There should be no spaces after function names.  Commas should be followed by a space.  Typically there are only spaces with more complex statements.  Code readability is king.  Binary operators should be padded with a space on either side.
  
error = function(a1, a2);
+
<source lang="c">
if ( (OK != error) && (5 < error) )
+
error = function(a1, a2);
{ exit(error); }
+
if ((OK != error) && (5 < error))
 +
{
 +
    exit(error);
 +
}
 +
</source>
  
 
Unary operators do not requires a space.  Use parentheses only when they are required to override precedence rules or to maintain readability with complicated statements.  Other people may get more easily confused then you.  Can you parse the following:
 
Unary operators do not requires a space.  Use parentheses only when they are required to override precedence rules or to maintain readability with complicated statements.  Other people may get more easily confused then you.  Can you parse the following:
  
a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
+
<source lang="c">
 +
a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
 +
</source>
  
 
Perhaps that statement would benefit with parentheses.
 
Perhaps that statement would benefit with parentheses.
Line 170: Line 211:
 
It is permissible to declare multiple variables on one line, but do not initialize variables until everything has been declared.
 
It is permissible to declare multiple variables on one line, but do not initialize variables until everything has been declared.
  
struct foo one, *two;
+
<source lang="c">
int       three, four, five;
+
struct foo one, *two;
+
int three, four, five;
five = 5;
+
 
four = four();
+
five = 5;
 +
four = four();
 +
</source>
  
 
Type casts and <code>sizeof</code> should not be followed by a space.  <code>sizeof</code> should always be written with parentheses.
 
Type casts and <code>sizeof</code> should not be followed by a space.  <code>sizeof</code> should always be written with parentheses.
a = (ushort)sizeof(struct memblock);
 
  
Committed code should never produce warnings.
+
<source lang="c">
 +
a = (ushort)sizeof(struct memblock);
 +
</source>
 +
 
 +
Committed code should never produce warnings or errors.
  
 
Function names should use [[w:CamelCase|lowerCamelCase]].  Avoid unnecessary abbreviation in function names as reasonable.
 
Function names should use [[w:CamelCase|lowerCamelCase]].  Avoid unnecessary abbreviation in function names as reasonable.
 
To avoid machine type size issues, the <code>int</code> and other #define types are deprecated.  Instead, all code should use: <code>long</code>, <code>ulong</code>, <code>short</code>, <code>ushort</code>, <code>char</code>, <code>uchar</code>.
 
  
 
Pointers which are used solely as references to memory locations should be declared of type <code>void *</code>.
 
Pointers which are used solely as references to memory locations should be declared of type <code>void *</code>.
Line 191: Line 235:
 
It should be noted that since HTML does not allow the tab character, this example should reflect someone who has their tab stop set to 4 spaces. Use the <code>\t</code> character for indentation.
 
It should be noted that since HTML does not allow the tab character, this example should reflect someone who has their tab stop set to 4 spaces. Use the <code>\t</code> character for indentation.
  
/**
+
<source lang="c">
  * @file    exampleFile.c
+
/**
  * @provides exampleFile, fileLoaded, getIO
+
* @file    exampleFile.c
  * While only an example this portion should contain general information
+
* @provides exampleFile, fileLoaded, getIO
  * about the importance of this file.
+
* While only an example this portion should contain general information
  *
+
* about the importance of this file.
  * $Id$
+
*
  */
+
* $Id$
/* Embedded XINU, Copyright (C) 2007.  All rights reserved. */
+
*/
+
/* Embedded Xinu, Copyright (C) 2008.  All rights reserved. */
#include <kernel.h>
+
 
#include <proc.h>
+
#include <kernel.h>
#include <queue.h>
+
#include <proc.h>
+
#include <queue.h>
/* End of file marker */
+
 
#define FILE_END 0x255          /**< Magic number to designate end-of-file */
+
/* End of file marker */
+
#define FILE_END 0x255          /**< Marker to designate end-of-file   */
/*
+
 
  * Processor Registers
+
/*
  */
+
* Processor Registers
#define zero $0                /**< hardwired zero                       */
+
*/
#define a0  $4                /**< first passed argument                 */
+
#define zero $0                /**< hardwired zero                     */
#define s0  $16                /**< callee saved                         */
+
#define a0  $4                /**< first passed argument             */
+
#define s0  $16                /**< callee saved                       */
extern ulong getData(int *register);
+
 
extern ulong data_register;
+
extern int getData(int *register);
+
extern int data_register;
static ulong getIO();
+
 
local fileLoaded(ushort fd);
+
static int getIO();
+
static int fileLoaded(int fd);
/**
+
 
  * Load an example file into XINU.
+
/**
  * @param fd      descriptor of file to load
+
* Load an example file into XINU.
  * @param timeout how long to wait before error.
+
* @param fd      descriptor of file to load
  * @return OK for success, SYSERR for failure to load
+
* @param timeout how long to wait before error.
  */
+
* @return OK for success, SYSERR for failure to load
devcall exampleFile(ushort fd, ulong timeout)
+
*/
{
+
devcall exampleFile(int fd, uint timeout)
    ulong counter; /* number of cycles we've been waiting   */
+
{
    ulong data;   /* 64-bits for storing a section of data */
+
    uint counter;               /* number of cycles we've been waiting */
+
    int data;                   /* 32-bits for storing data             */
    for ( counter = 0; counter < timeout; counter++ )
+
 
    {
+
    for (counter = 0; counter < timeout; counter++)
        data = getIO();
+
    {
+
        data = getIO();
        /* TODO: perform operation on data */
+
 
+
        /* TODO: perform operation on data */
        /* We have finished reading the file */
+
 
        if ( loadXinu(fd) == OK )
+
        /* We have finished reading the file */
        { return OK; }
+
        if (loadXinu(fd) == OK)
    }
+
        {
+
            return OK;
    return SYSERR;
+
        }
}
+
    }
+
 
/**
+
    return SYSERR;
  * Search for the end of the file
+
}
  * @param fd file descriptor to finish reading
+
 
  * @return OK if complete, SYSERR if incomplete
+
/**
  */
+
* Search for the end of the file
local fileLoaded(ushort fd)
+
* @param fd file descriptor to finish reading
{
+
* @return OK if complete, SYSERR if incomplete
    /* check for end of file marker */
+
*/
    if ( filetab[fd].buffer == FILE_END )
+
static int fileLoaded(int fd)
    {
+
{
        /* other code if needed */
+
    /* check for end of file marker */
        return OK;
+
    if (FILE_END == filetab[fd].buffer)
    }
+
    {
    else
+
        /* other code if needed */
    {
+
        return OK;
        /* other code if needed */
+
    }
        return SYSERR;
+
    else
    }
+
    {
}
+
        /* other code if needed */
+
        return SYSERR;
/**
+
    }
  * Read data from the s0 register through an assembly function.
+
}
  * @return data from register s0
+
 
  */
+
/**
static ulong getIO()
+
* Read data from the s0 register through an assembly function.
{
+
* @return data from register s0
    switch (data_register)
+
*/
    {
+
static int getIO()
    case S0: case S1:
+
{
        return getData(s0);
+
    switch (data_register)
    case A0: case A1: case A2: case A3:
+
    {
        return getData(a0);
+
    case S0:
    default:  
+
    case S1:
        return SYSERR;
+
        return getData(s0);
    }
+
    case A0:
}
+
    case A1:
 +
    case A2:
 +
    case A3:
 +
        return getData(a0);
 +
    default:
 +
        return SYSERR;
 +
    }
 +
}
 +
</source>

Revision as of 19:44, 3 October 2008

This page specifies the preferred style for kernel source files in the Xinu operating system source tree. It also provides a guide for preferred userland code style. Many style rules will not be explicitly stated, but rather implicit through examples in this guide. Be careful to check the example before assuming that this guide is silent on an issue.

Xinu now includes an indent target in the Makefile which will automatically parse all the source code into a K&R-like format.

Comments

/**
 * @file     style.guide
 * @provides style, guide
 * This is the opening comment block for a file.
 *
 * $Id$
 */

The copyright header should be a single-line comment that immediately follows the opening comment block.

/* Embedded Xinu, Copyright (C) 2008.  All rights reserved. */

/*
 * Immensely important comments look like this.
 */

/* Typical single-line comments look like this. */

/**
 * Multi-line comments that should appear in the autogenerated documentation
 * should look like this.
 */

/** Single-line comments to appear in documentation look like this. */
/**< or they look like this, if appearing on the same line as code. */

The first form of single-line comments goes above the code that it pertains to, whereas the second form will appear on the same line as the code it describes.

An automatic script (Doxygen) will collect comments that begin with the ** and parse them into the documentation for this project. In the opening comment block there is a line containing $Id$, if that file has the subversion property svn:keywords "Id" set, it will be filled out with the name of the file, the last revision that file was updated, the date and time of the last update, and the user who last modified the file.

Preprocessor

As a precaution against multiple definitions every include file should protect itself against redefining its material.

#ifndef _INCLUDE_H_
#define _INCLUDE_H_
[...]
#endif                           /* _INCLUDE_H_ */

After the opening comment block and copyright of a file, include one blank line and begin including non-local header files. Typically these should be ordered from most important (kernel-level) to least important (user-level).

#include <kernel.h>
#include <device.h>
#include <memory.h>
#include <string.h>

Now, if there are local header files include a blank line and then continue including files.

#include "local.h"

Macro definitions should typically be in ALL CAPS, unless it goes against a standard. If a macro is being used in lieu of a function the macro should be defined in ALL CAPS. If the macro consumes multiple lines, align the backslashes one space to the right of the longest line. Any final statement-terminating semicolon should not appear in the macro, rather it will be supplied by the invocation on the macro to allow easier parsing of the code by humans and editors alike.

#define MACRO(x, y)      \
    (x) = (x) + 5 * (y); \
    (x) /= 3

When using conditional directives such as #if or #ifdef, it is recommended to place a comment following the matching #else or #endif to make the reader have an easier time discerning where conditionally compiled code begins and ends.

#ifdef MIPS
/* MIPS specific code goes here. */
#else                            /* not MIPS */
/* generic code goes here. */
#endif                           /* MIPS */

Structs and Typedefs

Structures should have logically named members with a comment describing what each member is for. Structures do not have to have a typedef, but if they do have one it should be inline with the structure definition.

typedef struct dentry
{
    int major;                   /**< major device number          */
    int minor;                   /**< minor device number          */
    void *csr;                   /**< control and status registers */
    [...]
} device;

Functions

All functions must be prototyped somewhere. Global functions should have a prototype in a system header file, local functions can be prototyped at the top of its respective source file (or in a local header file). If the function is local it should use the static modifier from stddef.h, which will declare it as static and not pollute the namespace.

Prototypes should not have a variable name associated with the type. For example:

void foo(int, int *);

When creating a function it should be preceded by document comment describing what it does, the parameters it takes, and what it will return, if applicable. The return type, function name, and parameters should be on the same line unless that line is over 74 characters wide. In that case the remaining parameters should be aligned with the first parameter on the line above.

/**
 * The main function of the program will parse the input for the arguments
 * passed.
 * @param argc   number of arguments passed to function
 * @param argv   array of char *s containing passed arguments
 * @param func   pointer to function that takes two int parameters
 * @param offset offset into char * array to read
 * @param length length to read at offset
 * @return zero on successful completion, non-zero if unsuccessful.
 */
int foo(int argc, char **argv, devcall (*func)(int, int), int offset,
        int length)
{
    /* well written code. */
}

Spacing

Languages keywords (such as if, while, for, switch) all have one space following their use. This helps differentiate keywords from function calls. Braces ({ and }) should always be used in control statements. The use of brackets in all cases helps minimize the risk of bugs occurring when adding new lines to a statement.

for (i = 0; i < length; i++)
{
    a = i + 1;
    b *= a;
}
 
if (NULL != value)
{
    *value = new_value;
}
 
while (TRUE)
{
    /* Do nothing. */
}

Avoid declarations within new statement blocks when possible, certain versions of compilers may not recognize them for what they are.

Indentations are done using 4 spaces per level. If a conditional statement wraps around place the operator at the beginning of the next line (lining up with first variable above).

while (count > 30 && TRUE == this_variable_is_true
       && NULL != value)
{
    /* Do something. */
}

if (foo)
{
    /* foo case. */
}
else if (bar)
{
    /* bar case. */
}
else
{
    /* else case. */
}

Switch statements should be formatted with each case lining up with the braces as follows:

switch (test)
{
case 0:
case 1:
    /* Process. */
    break;
default:
    /* Normal case. */
    break;
}

There should be no spaces after function names. Commas should be followed by a space. Typically there are only spaces with more complex statements. Code readability is king. Binary operators should be padded with a space on either side.

error = function(a1, a2);
if ((OK != error) && (5 < error))
{
    exit(error);
}

Unary operators do not requires a space. Use parentheses only when they are required to override precedence rules or to maintain readability with complicated statements. Other people may get more easily confused then you. Can you parse the following:

a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;

Perhaps that statement would benefit with parentheses.

Miscellaneous

It is permissible to declare multiple variables on one line, but do not initialize variables until everything has been declared.

struct foo one, *two;
int three, four, five;

five = 5;
four = four();

Type casts and sizeof should not be followed by a space. sizeof should always be written with parentheses.

a = (ushort)sizeof(struct memblock);

Committed code should never produce warnings or errors.

Function names should use lowerCamelCase. Avoid unnecessary abbreviation in function names as reasonable.

Pointers which are used solely as references to memory locations should be declared of type void *.

Example

It should be noted that since HTML does not allow the tab character, this example should reflect someone who has their tab stop set to 4 spaces. Use the \t character for indentation.

/**
 * @file     exampleFile.c
 * @provides exampleFile, fileLoaded, getIO
 * While only an example this portion should contain general information
 * about the importance of this file.
 *
 * $Id$
 */
/* Embedded Xinu, Copyright (C) 2008.  All rights reserved. */

#include <kernel.h>
#include <proc.h>
#include <queue.h>

/* End of file marker */
#define FILE_END 0x255          /**< Marker to designate end-of-file    */

/*
 * Processor Registers
 */
#define zero $0                 /**< hardwired zero                     */
#define a0   $4                 /**< first passed argument              */
#define s0   $16                /**< callee saved                       */

extern int getData(int *register);
extern int data_register;

static int getIO();
static int fileLoaded(int fd);

/**
 * Load an example file into XINU.
 * @param fd      descriptor of file to load
 * @param timeout how long to wait before error.
 * @return OK for success, SYSERR for failure to load
 */
devcall exampleFile(int fd, uint timeout)
{
    uint counter;               /* number of cycles we've been waiting  */
    int data;                   /* 32-bits for storing data             */

    for (counter = 0; counter < timeout; counter++)
    {
        data = getIO();

        /* TODO: perform operation on data */

        /* We have finished reading the file */
        if (loadXinu(fd) == OK)
        {
            return OK;
        }
    }

    return SYSERR;
}

/**
 * Search for the end of the file
 * @param fd file descriptor to finish reading
 * @return OK if complete, SYSERR if incomplete
 */
static int fileLoaded(int fd)
{
    /* check for end of file marker */
    if (FILE_END == filetab[fd].buffer)
    {
        /* other code if needed */
        return OK;
    }
    else
    {
        /* other code if needed */
        return SYSERR;
    }
}

/**
 * Read data from the s0 register through an assembly function.
 * @return data from register s0
 */
static int getIO()
{
    switch (data_register)
    {
    case S0:
    case S1:
        return getData(s0);
    case A0:
    case A1:
    case A2:
    case A3:
        return getData(a0);
    default:
        return SYSERR;
    }
}