Kernel Normal Form

This article or section needs to be updated. Parts of this article or section have been identified as no longer being up to date. Please update the article to reflect recent changes, and remove this template when finished.

---

Tabs

• Use tabs to indent code.
• Use spaces to position comments that appear to the right of code.

Braces

• For functions and control blocks, the brace goes on its own line.
• Control blocks can be compressed to

Spaces

• Spaces around operators are recommended, around = are required.
• The parenthesis following a keyword is always prefixed by a space.
• Following a function call or declaration, there is no space between the name and the opening parenthesis.

Function Naming

• Function names use Java style lowerCamelCase, following Java conventions on capitalization edge cases.
• Avoid unnecessary abbreviation in function names as reasonable.

Global Variables

• Global tables are named after the related structure with the suffix "tab", such as devicetab, processtab, etc.

Types

To avoid machine type size issues, the int and other #define types are deprecated. Instead, all code should use: long, ulong, short, ushort, char, uchar.

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

Comments

• The top of any file should contain a comment with the file name and major public functions (as well as the copyright once it is determined)
• Functions should follow normal javadoc (doxygen in our case) style
• Comments should be follow /* ... */ style and vary depending on line size

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.

/**
 * @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) 2007.  All rights reserved. */

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

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

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

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

/**
 * 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(ushort fd, ulong timeout)
{
    ulong counter; /* number of cycles we've been waiting   */
    ulong data;    /* 64-bits for storing a section of 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
 */
local fileLoaded(ushort fd)
{
    /* check for end of file marker */
    if ( filetab[fd].buffer == FILE_END )
    {
        /* 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
 */
ulong 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;
    }
}