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 588

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.