Expand PMF_FN_* macros.
[netbsd-mini2440.git] / sys / arch / alpha / STYLE
blob55397c9f60713f1737e9110b9c99388be1890627
1 $NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 wiz Exp $
3 Style guide for NetBSD/alpha kernel files.
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).
9 SECTIONS
11         * INCLUDE FILES
12         * RCS IDS
13         * COMPILATION FLAGS
14         * MACRO DEFINITIONS
15         * BLOCKS AND EXPRESSIONS
18 INCLUDE FILES
20 (1) All option headers should be included first, and sorted, like:
22 #include "opt_dec_3000_300.h"
23 #include "opt_dec_3000_500.h"
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:
28 #include <sys/cdefs.h>                  /* RCS ID & Copyright macro defns */
31 RCS IDS
33 (1) NetBSD RCS ID tags ($NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 wiz Exp $ tags) in C sources and headers should
34 appear at the top of the file in a single-line comment of the form
36 /*<space>$NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 wiz Exp $<space>*/
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.
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:
45 __KERNEL_RCSID(0, "$NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 wiz Exp $");
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.)
55 COMPILATION FLAGS
57 By default, NetBSD/alpha kernel files are compiled with the following gcc
58 warning flags:
60         -Werror
61         -Wall
62         -Wstrict-prototypes
63         -Wmissing-prototypes
64         -Wno-format
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.
72 MACRO DEFINITIONS
74 (1) Macros which use C blocks (i.e. are of the form "{ ... expressions
75 ... }") should always be defined like:
77 #define MACRO(arg1, arg2, argN)                                 \
78 do {                                                            \
79         ...                                                     \
80         expressions                                             \
81         ...                                                     \
82 } while (0)
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 ...").
88 BLOCKS AND EXPRESSIONS
90 (1) Surround blocks with { and } more often than is absolutely necessary.
91 For instance:
93         if (foo)
94                 bar();
96 is acceptable, but:
98         if (foo) {
99                 bar();
100         }
102 is preferred.  (In contrast, NetBSD KNF says that no braces are to be
103 used for control statements with zero or one statements.)
105 (2) Use extra parentheses when it makes expressions clearer.  For instance,
107         (foo == 10 && bar == 20)
109 is acceptable, but:
111         ((foo == 10) && (bar == 20))
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.)