OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [hal-porting-coding-conventions.html] - Blame information for rev 587

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.