Home | History | Annotate | Line # | Download | only in alpha 
      1 $NetBSD: STYLE,v 1.7 2002/09/06 13:18:43 gehenna Exp $
      2 
      3 Style guide for NetBSD/alpha kernel files.
      4 
      5 This file is meant to supplement the NetBSD KNF style guide (which covers
      6 most of the rest of the system, and can be found in /usr/share/misc/style).
      7 
      8 
      9 SECTIONS
     10 
     11 	* INCLUDE FILES
     12 	* RCS IDS
     13 	* COMPILATION FLAGS
     14 	* MACRO DEFINITIONS
     15 	* BLOCKS AND EXPRESSIONS
     16 
     17 
     18 INCLUDE FILES
     19 
     20 (1) All option headers should be included first, and sorted, like:
     21 
     22 #include "opt_dec_3000_300.h"
     23 #include "opt_dec_3000_500.h"
     24 
     25 (2) All C sources should include <sys/cdefs.h> as the first header to
     26 be included after any option headers, with a line like:
     27 
     28 #include <sys/cdefs.h>			/* RCS ID & Copyright macro defns */
     29 
     30 
     31 RCS IDS
     32 
     33 (1) NetBSD RCS ID tags ($NetBSD: STYLE,v 1.7 2002/09/06 13:18:43 gehenna Exp $ tags) in C sources and headers should
     34 appear at the top of the file in a single-line comment of the form
     35 
     36 /*<space>$NetBSD: STYLE,v 1.7 2002/09/06 13:18:43 gehenna Exp $<space>*/
     37 
     38 which differs from the normal NetBSD style, in that it uses spaces
     39 rather than tabs to separate the tag from the comment start and end
     40 delimiters.
     41 
     42 (2) All C and assembler sources should include an RCS ID tag which can
     43 be compiled into the binary, with a line like:
     44 
     45 __KERNEL_RCSID(0, "$NetBSD: STYLE,v 1.7 2002/09/06 13:18:43 gehenna Exp $");
     46 
     47 after the inclusion of cdefs.h.  Source files which include other source
     48 files should change the number '0' to a different number, so that it
     49 doesn't conflict with the RCS ID definitions in included sources.
     50 Generation of these RCS IDs is disabled if the kernel option
     51 NO_KERNEL_RCSIDS is defined.  (In some cases, picking the number to use
     52 may not be so straightforward, but the rule above usually works.)
     53 
     54 
     55 COMPILATION FLAGS
     56 
     57 By default, NetBSD/alpha kernel files are compiled with the following gcc
     58 warning flags:
     59 
     60 	-Werror
     61 	-Wall
     62 	-Wstrict-prototypes
     63 	-Wmissing-prototypes
     64 	-Wno-format
     65 
     66 NetBSD/alpha kernel code should compile cleanly with those flags.  At some
     67 point in the future (when the nonstandard extensions have been removed
     68 from the kernel printf() function), -Wformat will be re-enabled, so sources
     69 should be able to compile with it enabled as well.
     70 
     71 
     72 MACRO DEFINITIONS
     73 
     74 (1) Macros which use C blocks (i.e. are of the form "{ ... expressions
     75 ... }") should always be defined like:
     76 
     77 #define	MACRO(arg1, arg2, argN)					\
     78 do {								\
     79 	...							\
     80 	expressions						\
     81 	...							\
     82 } while (0)
     83 
     84 so that they behave like functions or macros which don't use blocks (e.g.
     85 for the purpose of "if (foo) MACRO(); else ...").
     86 
     87 
     88 BLOCKS AND EXPRESSIONS
     89 
     90 (1) Surround blocks with { and } more often than is absolutely necessary.
     91 For instance:
     92 
     93 	if (foo)
     94 		bar();
     95 
     96 is acceptable, but:
     97 
     98 	if (foo) {
     99 		bar();
    100 	}
    101 
    102 is preferred.  (In contrast, NetBSD KNF says that no braces are to be
    103 used for control statements with zero or one statements.)
    104 
    105 (2) Use extra parentheses when it makes expressions clearer.  For instance,
    106 
    107 	(foo == 10 && bar == 20)
    108 
    109 is acceptable, but:
    110 
    111 	((foo == 10) && (bar == 20))
    112 
    113 is preferred.  (In contrast, NetBSD KNF says to avoid using parentheses
    114 except where necessary unless the expression is very confusing without
    115 them.)
    116