doc/html/ref/hal-porting-coding-conventions.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >HAL Coding Conventions</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE=" Porting Guide"
  23 HREF="hal-porting-guide.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Virtual Vectors (eCos/ROM Monitor Calling Interface)"
  26 HREF="hal-calling-if.html"><LINK
  27 REL="NEXT"
  28 TITLE="Platform HAL Porting"
  29 HREF="hal-porting-platform.html"></HEAD
  30 ><BODY
  31 CLASS="SECTION"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="hal-calling-if.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 11. Porting Guide</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="hal-porting-platform.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECTION"
  82 ><H1
  83 CLASS="SECTION"
  84 ><A
  85 NAME="HAL-PORTING-CODING-CONVENTIONS">HAL Coding Conventions</H1
  86 ><P
  87 >To get changes and larger submissions included into the eCos source
  88 repository, we ask that you adhere to a set of coding conventions.
  89 The conventions are defined as an attempt to make a consistent
  90 tree. Consistency makes it easier for people to read, understand and
  91 maintain the code, which is important when many people work on the
  92 same project.</P
  93 ><P
  94 >The below is only a brief, and probably incomplete, summary of the
  95 rules. Please look through files in the area where you are making
  96 changes to get a feel for any additional conventions. Also feel free
  97 to ask on the list if you have specific questions.</P
  98 ><DIV
  99 CLASS="SECTION"
 100 ><H2
 101 CLASS="SECTION"
 102 ><A
 103 NAME="AEN9361">Implementation issues</H2
 104 ><P
 105 >There are a few implementation issues that should be kept in mind:</P
 106 ><P
 107 ></P
 108 ><DIV
 109 CLASS="VARIABLELIST"
 110 ><DL
 111 ><DT
 112 >HALs</DT
 113 ><DD
 114 ><P
 115 >HALs must be written in C and assembly only. C++ must not
 116         be used. This is in part to keep the HALs simple since this is
 117         usually the first part of eCos a newcomer will see, and in
 118         part to maintain the existing de facto standard.</P
 119 ></DD
 120 ><DT
 121 >IO access</DT
 122 ><DD
 123 ><P
 124 >Use HAL IO access macros for code that might be reused on
 125         different platforms than the one you are writing it for.</P
 126 ></DD
 127 ><DT
 128 >MMU</DT
 129 ><DD
 130 ><P
 131 >If it is necessary to use the MMU (e.g., to prevent
 132         caching of IO areas), use a simple 1-1 mapping of memory if
 133         possible. On most platforms where using the MMU is necessary,
 134         it will be possible to achieve the 1-1 mapping using the MMU's
 135         provision for mapping large continuous areas (hardwired TLBs or
 136         BATs). This reduces the footprint (no MMU table) and avoids
 137         execution overhead (no MMU-related exceptions).</P
 138 ></DD
 139 ><DT
 140 >Assertions</DT
 141 ><DD
 142 ><P
 143 >The code should contain assertions to validate argument
 144         values, state information and any assumptions the code may be
 145         making. Assertions are not enabled in production builds, so
 146         liberally sprinkling assertions throughout the code is
 147         good.</P
 148 ></DD
 149 ><DT
 150 >Testing</DT
 151 ><DD
 152 ><P
 153 >The ability to test your code is very important. In
 154         general, do not add new code to the eCos runtime unless you
 155         also add a new test to exercise that code. The test also
 156         serves as an example of how to use the new code.</P
 157 ></DD
 158 ></DL
 159 ></DIV
 160 ></DIV
 161 ><DIV
 162 CLASS="SECTION"
 163 ><H2
 164 CLASS="SECTION"
 165 ><A
 166 NAME="AEN9385">Source code details</H2
 167 ><P
 168 ></P
 169 ><DIV
 170 CLASS="VARIABLELIST"
 171 ><DL
 172 ><DT
 173 >Line length</DT
 174 ><DD
 175 ><P
 176 >Keep line length below 78 columns whenever possible.</P
 177 ></DD
 178 ><DT
 179 >Comments</DT
 180 ><DD
 181 ><P
 182 >Whenever possible, use // comments instead of /**/.</P
 183 ></DD
 184 ><DT
 185 >Indentation</DT
 186 ><DD
 187 ><P
 188 >Use spaces instead of TABs. Indentation level is 4. Braces
 189         start on the same line as the expression. See below for emacs
 190         mode details.</P
 191 ><TABLE
 192 BORDER="5"
 193 BGCOLOR="#E0E0F0"
 194 WIDTH="70%"
 195 ><TR
 196 ><TD
 197 ><PRE
 198 CLASS="PROGRAMLISTING"
 199 >;;=================================================================
 200 ;; eCos C/C++ mode Setup.
 201 ;;
 202 ;; bsd mode: indent = 4
 203 ;; tail comments are at col 40.
 204 ;; uses spaces not tabs in C
 205
 206 (defun ecos-c-mode ()
 207   "C mode with adjusted defaults for use with the eCos sources."
 208   (interactive)
 209   (c++-mode)
 210   (c-set-style "bsd")
 211   (setq comment-column 40)
 212   (setq indent-tabs-mode nil)
 213   (show-paren-mode 1)
 214   (setq c-basic-offset 4)
 215
 216   (set-variable 'add-log-full-name "Your Name")
 217   (set-variable 'add-log-mailing-address "Your email address"))
 218
 219 (defun ecos-asm-mode ()
 220   "ASM mode with adjusted defaults for use with the eCos sources."
 221   (interactive)
 222   (setq comment-column 40)
 223   (setq indent-tabs-mode nil)
 224   (asm-mode)
 225   (setq c-basic-offset 4)
 226
 227   (set-variable 'add-log-full-name "Your Name")
 228   (set-variable 'add-log-mailing-address "Your email address"))
 229
 230 (setq auto-mode-alist
 231       (append '(("/local/ecc/.*\\.C$"   . ecos-c-mode)
 232                 ("/local/ecc/.*\\.cc$"  . ecos-c-mode)
 233                 ("/local/ecc/.*\\.cpp$" . ecos-c-mode)
 234                 ("/local/ecc/.*\\.inl$" . ecos-c-mode)
 235                 ("/local/ecc/.*\\.c$"   . ecos-c-mode)
 236                 ("/local/ecc/.*\\.h$"   . ecos-c-mode)
 237                 ("/local/ecc/.*\\.S$"   . ecos-asm-mode)
 238                 ("/local/ecc/.*\\.inc$" . ecos-asm-mode)
 239                 ("/local/ecc/.*\\.cdl$" . tcl-mode)
 240                 ) auto-mode-alist))</PRE
 241 ></TD
 242 ></TR
 243 ></TABLE
 244 ></DD
 245 ></DL
 246 ></DIV
 247 ></DIV
 248 ><DIV
 249 CLASS="SECTION"
 250 ><H2
 251 CLASS="SECTION"
 252 ><A
 253 NAME="AEN9401">Nested Headers</H2
 254 ><P
 255 >In order to allow platforms to define all necessary details, while
 256 still maintaining the ability to share code between common platforms,
 257 all HAL headers are included in a nested fashion.</P
 258 ><P
 259 >The architecture header (usually <TT
 260 CLASS="FILENAME"
 261 >hal_XXX.h</TT
 262 >) includes the
 263 variant equivalent of the header (<TT
 264 CLASS="FILENAME"
 265 >var_XXX.h</TT
 266 >) which in turn
 267 includes the platform equivalent of the header
 268 (<TT
 269 CLASS="FILENAME"
 270 >plf_XXX.h</TT
 271 >).</P
 272 ><P
 273 >All definitions that may need to be overridden by a platform are
 274 then only conditionally defined, depending on whether a lower layer
 275 has already made the definition:</P
 276 ><TABLE
 277 BORDER="5"
 278 BGCOLOR="#E0E0F0"
 279 WIDTH="70%"
 280 ><TR
 281 ><TD
 282 ><PRE
 283 CLASS="PROGRAMLISTING"
 284 >hal_intr.h:     #include &lt;var_intr.h&gt;
 285
 286                 #ifndef MACRO_DEFINED
 287                 # define MACRO ...
 288                 # define MACRO_DEFINED
 289                 #endif
 290
 291
 292
 293 var_intr.h:     #include &lt;plf_intr.h&gt;
 294
 295                 #ifndef MACRO_DEFINED
 296                 # define MACRO ...
 297                 # define MACRO_DEFINED
 298                 #endif
 299
 300
 301 plf_intr.h:
 302
 303                 # define MACRO ...
 304                 # define MACRO_DEFINED</PRE
 305 ></TD
 306 ></TR
 307 ></TABLE
 308 ><P
 309 >This means a platform can opt to rely on the variant or
 310 architecture implementation of a feature, or implement it itself.</P
 311 ></DIV
 312 ></DIV
 313 ><DIV
 314 CLASS="NAVFOOTER"
 315 ><HR
 316 ALIGN="LEFT"
 317 WIDTH="100%"><TABLE
 318 SUMMARY="Footer navigation table"
 319 WIDTH="100%"
 320 BORDER="0"
 321 CELLPADDING="0"
 322 CELLSPACING="0"
 323 ><TR
 324 ><TD
 325 WIDTH="33%"
 326 ALIGN="left"
 327 VALIGN="top"
 328 ><A
 329 HREF="hal-calling-if.html"
 330 ACCESSKEY="P"
 331 >Prev</A
 332 ></TD
 333 ><TD
 334 WIDTH="34%"
 335 ALIGN="center"
 336 VALIGN="top"
 337 ><A
 338 HREF="ecos-ref.html"
 339 ACCESSKEY="H"
 340 >Home</A
 341 ></TD
 342 ><TD
 343 WIDTH="33%"
 344 ALIGN="right"
 345 VALIGN="top"
 346 ><A
 347 HREF="hal-porting-platform.html"
 348 ACCESSKEY="N"
 349 >Next</A
 350 ></TD
 351 ></TR
 352 ><TR
 353 ><TD
 354 WIDTH="33%"
 355 ALIGN="left"
 356 VALIGN="top"
 357 >Virtual Vectors (eCos/ROM Monitor Calling Interface)</TD
 358 ><TD
 359 WIDTH="34%"
 360 ALIGN="center"
 361 VALIGN="top"
 362 ><A
 363 HREF="hal-porting-guide.html"
 364 ACCESSKEY="U"
 365 >Up</A
 366 ></TD
 367 ><TD
 368 WIDTH="33%"
 369 ALIGN="right"
 370 VALIGN="top"
 371 >Platform HAL Porting</TD
 372 ></TR
 373 ></TABLE
 374 ></DIV
 375 ></BODY
 376 ></HTML
 377 >