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. -->
12 >HAL Coding Conventions</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE=" Porting Guide"
23 HREF="hal-porting-guide.html"><LINK
25 TITLE="Virtual Vectors (eCos/ROM Monitor Calling Interface)"
26 HREF="hal-calling-if.html"><LINK
28 TITLE="Platform HAL Porting"
29 HREF="hal-porting-platform.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="hal-calling-if.html"
65 >Chapter 11. Porting Guide</TD
71 HREF="hal-porting-platform.html"
85 NAME="HAL-PORTING-CODING-CONVENTIONS">HAL Coding Conventions</H1
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
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
103 NAME="AEN9361">Implementation issues</H2
105 >There are a few implementation issues that should be kept in mind:</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
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
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
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
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
166 NAME="AEN9385">Source code details</H2
176 >Keep line length below 78 columns whenever possible.</P
182 >Whenever possible, use // comments instead of /**/.</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
198 CLASS="PROGRAMLISTING"
199 >;;=================================================================
200 ;; eCos C/C++ mode Setup.
202 ;; bsd mode: indent = 4
203 ;; tail comments are at col 40.
204 ;; uses spaces not tabs in C
206 (defun ecos-c-mode ()
207 "C mode with adjusted defaults for use with the eCos sources."
211 (setq comment-column 40)
212 (setq indent-tabs-mode nil)
214 (setq c-basic-offset 4)
216 (set-variable 'add-log-full-name "Your Name")
217 (set-variable 'add-log-mailing-address "Your email address"))
219 (defun ecos-asm-mode ()
220 "ASM mode with adjusted defaults for use with the eCos sources."
222 (setq comment-column 40)
223 (setq indent-tabs-mode nil)
225 (setq c-basic-offset 4)
227 (set-variable 'add-log-full-name "Your Name")
228 (set-variable 'add-log-mailing-address "Your email address"))
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
253 NAME="AEN9401">Nested Headers</H2
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
259 >The architecture header (usually <TT
263 variant equivalent of the header (<TT
267 includes the platform equivalent of the header
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
283 CLASS="PROGRAMLISTING"
284 >hal_intr.h: #include <var_intr.h>
286 #ifndef MACRO_DEFINED
288 # define MACRO_DEFINED
293 var_intr.h: #include <plf_intr.h>
295 #ifndef MACRO_DEFINED
297 # define MACRO_DEFINED
304 # define MACRO_DEFINED</PRE
309 >This means a platform can opt to rely on the variant or
310 architecture implementation of a feature, or implement it itself.</P
318 SUMMARY="Footer navigation table"
329 HREF="hal-calling-if.html"
347 HREF="hal-porting-platform.html"
357 >Virtual Vectors (eCos/ROM Monitor Calling Interface)</TD
363 HREF="hal-porting-guide.html"
371 >Platform HAL Porting</TD