Kernel Normal Form - Revision history

Ebiggers: Introduction seemed very wordy

2013-09-11T21:45:30Z

Introduction seemed very wordy

Ebiggers: 'make indent' will mess up a lot of nicely formatted code; perhaps best not to mention it here.

2013-09-11T21:43:09Z

'make indent' will mess up a lot of nicely formatted code; perhaps best not to mention it here.

Ebiggers: /* Comments */

2013-09-11T21:39:21Z

Comments

Ebiggers: "Example" seems highly redundant as someone might as well read the source. Better to have smaller examples demonstrating each point.

2013-09-11T21:37:10Z

"Example" seems highly redundant as someone might as well read the source. Better to have smaller examples demonstrating each point.

Ebiggers: /* Miscellaneous */

2013-09-11T21:34:19Z

Miscellaneous

Ebiggers: /* Spacing */

2013-09-11T21:33:22Z

Spacing

Ebiggers: /* Functions */

2013-09-11T21:30:09Z

Functions

Ebiggers: /* Preprocessor */

2013-09-11T21:19:09Z

Preprocessor

Ebiggers: /* Comments */

2013-09-11T21:16:31Z

Comments

Michael at 20:41, 11 November 2008

2008-11-11T20:41:43Z

← Older revision		Revision as of 21:45, 11 September 2013
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 describes major aspects of the preferred style for kernel source files in the [[Xinu]] operating system source tree.

	== Comments ==		== Comments ==

← Older revision		Revision as of 21:43, 11 September 2013
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 ==

@@ Line 4: / Line 4: @@
 == Comments ==
 Generally, code should be well-commented.  However, comments should only mention things that are ''not'' already obvious.
 [http://www.stack.nl/~dimitri/doxygen/ Doxygen] is used to automatically generate documentation from comments.  Comments beginning with 2 asterisks are recognized by Doxygen; other comments are not.  Doxygen-style comments should generally be used to document files as well as any functions, variables, definitions, and structures that are meant to be an external interface--- that is, not internal to a file or component.  "Regular" comments should be used in other cases, such as explaining the code.
 The following shows the main forms of comments:
@@ Line 47: / Line 31: @@
 The first form of single-line comments must be placed above the code that it pertains to, whereas the second form may be placed either above the code or on the same line as the code it describes (if it fits).
 == Preprocessor ==

← Older revision		Revision as of 21:37, 11 September 2013
Line 235:		Line 235:

	Pointers which are used solely as references to memory locations (and not to a structure or array of a specific type) should be declared of type <code>void *</code>.		Pointers which are used solely as references to memory locations (and not to a structure or array of a specific type) should be declared of type <code>void *</code>.
−
−	~~== 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 <code>\t</code> character for indentation.~~
−
−	~~<source lang="c">~~
−	/**
−	* @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;~~
−	}
−	}
−	~~</source>~~

@@ Line 234: / Line 234: @@
 Function names should use [[w:CamelCase|lowerCamelCase]].  Avoid unnecessary abbreviation in function names as reasonable.
-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 (and not to a structure or array of a specific type) should be declared of type <code>void *</code>.
 == Example ==

@@ Line 138: / Line 138: @@
 == 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.  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</code>, <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.
 <source lang="c">
@@ Line 208: / Line 208: @@
 </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 require a space.
-<source lang="c">
+In cases where operator precedence is unclear, always error on the side of including additional parentheses.
 == Miscellaneous ==

@@ Line 108: / Line 108: @@
 == 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>static</code> modifier from <code>stddef.h</code>, which will declare it as static and not pollute the namespace.
+Functions used in more than one file are "global" and ''must'' have a prototype in a header file.
-Prototypes should not have a variable name associated with the type.  For example:
+Functions used in only one file are "local" and must be declared with the <code>static</code> modifier.  This prevents namespace pollution and lets the compiler possibly inline the function.  If local functions are used before being defined, a prototype must be placed towards the top of the file.
-<source lang="c">
+Global functions must be documented by Doxygen using a comment similar to the following:
 <source lang="c">
@@ Line 135: / Line 131: @@
+}
 </source>
 == Spacing ==

@@ Line 59: / Line 59: @@
 </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.
 <source lang="c">
@@ Line 68: / Line 68: @@
 </source>
-Now, if there are local header files include a blank line and then continue including files.
+Following that, if there are local header files include a blank line and then continue including files.
 <source lang="c">
@@ Line 74: / Line 74: @@
 </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 be in ALL CAPS unless it goes against a standard.  This includes macros that are used in lieu of a function.  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 of the macro to allow easier parsing of the code by humans and editors alike.
 <source lang="c">

@@ Line 8: / Line 8: @@
 /**
   * @file     style.guide
-  * @provides style, guide
+  * @provides style, guide.
   * This is the opening comment block for a file.
+  *
@@ Line 238: / Line 238: @@
 /**
   * @file     exampleFile.c
-  * @provides exampleFile, fileLoaded, getIO
+  * @provides exampleFile, fileLoaded, getIO.
   * While only an example this portion should contain general information
   * about the importance of this file.