<!-- Copyright (C) 2003 Red Hat, Inc. -->
|
<!-- Copyright (C) 2003 Red Hat, Inc. -->
|
<!-- This material may be distributed only subject to the terms -->
|
<!-- This material may be distributed only subject to the terms -->
|
<!-- and conditions set forth in the Open Publication License, v1.0 -->
|
<!-- and conditions set forth in the Open Publication License, v1.0 -->
|
<!-- or later (the latest version is presently available at -->
|
<!-- or later (the latest version is presently available at -->
|
<!-- http://www.opencontent.org/openpub/). -->
|
<!-- http://www.opencontent.org/openpub/). -->
|
<!-- Distribution of the work or derivative of the work in any -->
|
<!-- Distribution of the work or derivative of the work in any -->
|
<!-- standard (paper) book form is prohibited unless prior -->
|
<!-- standard (paper) book form is prohibited unless prior -->
|
<!-- permission is obtained from the copyright holder. -->
|
<!-- permission is obtained from the copyright holder. -->
|
<HTML
|
<HTML
|
><HEAD
|
><HEAD
|
><TITLE
|
><TITLE
|
>HAL Coding Conventions</TITLE
|
>HAL Coding Conventions</TITLE
|
><meta name="MSSmartTagsPreventParsing" content="TRUE">
|
><meta name="MSSmartTagsPreventParsing" content="TRUE">
|
<META
|
<META
|
NAME="GENERATOR"
|
NAME="GENERATOR"
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
"><LINK
|
"><LINK
|
REL="HOME"
|
REL="HOME"
|
TITLE="eCos Reference Manual"
|
TITLE="eCos Reference Manual"
|
HREF="ecos-ref.html"><LINK
|
HREF="ecos-ref.html"><LINK
|
REL="UP"
|
REL="UP"
|
TITLE=" Porting Guide"
|
TITLE=" Porting Guide"
|
HREF="hal-porting-guide.html"><LINK
|
HREF="hal-porting-guide.html"><LINK
|
REL="PREVIOUS"
|
REL="PREVIOUS"
|
TITLE="Virtual Vectors (eCos/ROM Monitor Calling Interface)"
|
TITLE="Virtual Vectors (eCos/ROM Monitor Calling Interface)"
|
HREF="hal-calling-if.html"><LINK
|
HREF="hal-calling-if.html"><LINK
|
REL="NEXT"
|
REL="NEXT"
|
TITLE="Platform HAL Porting"
|
TITLE="Platform HAL Porting"
|
HREF="hal-porting-platform.html"></HEAD
|
HREF="hal-porting-platform.html"></HEAD
|
><BODY
|
><BODY
|
CLASS="SECTION"
|
CLASS="SECTION"
|
BGCOLOR="#FFFFFF"
|
BGCOLOR="#FFFFFF"
|
TEXT="#000000"
|
TEXT="#000000"
|
LINK="#0000FF"
|
LINK="#0000FF"
|
VLINK="#840084"
|
VLINK="#840084"
|
ALINK="#0000FF"
|
ALINK="#0000FF"
|
><DIV
|
><DIV
|
CLASS="NAVHEADER"
|
CLASS="NAVHEADER"
|
><TABLE
|
><TABLE
|
SUMMARY="Header navigation table"
|
SUMMARY="Header navigation table"
|
WIDTH="100%"
|
WIDTH="100%"
|
BORDER="0"
|
BORDER="0"
|
CELLPADDING="0"
|
CELLPADDING="0"
|
CELLSPACING="0"
|
CELLSPACING="0"
|
><TR
|
><TR
|
><TH
|
><TH
|
COLSPAN="3"
|
COLSPAN="3"
|
ALIGN="center"
|
ALIGN="center"
|
>eCos Reference Manual</TH
|
>eCos Reference Manual</TH
|
></TR
|
></TR
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="10%"
|
WIDTH="10%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
><A
|
><A
|
HREF="hal-calling-if.html"
|
HREF="hal-calling-if.html"
|
ACCESSKEY="P"
|
ACCESSKEY="P"
|
>Prev</A
|
>Prev</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="80%"
|
WIDTH="80%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
>Chapter 11. Porting Guide</TD
|
>Chapter 11. Porting Guide</TD
|
><TD
|
><TD
|
WIDTH="10%"
|
WIDTH="10%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="bottom"
|
VALIGN="bottom"
|
><A
|
><A
|
HREF="hal-porting-platform.html"
|
HREF="hal-porting-platform.html"
|
ACCESSKEY="N"
|
ACCESSKEY="N"
|
>Next</A
|
>Next</A
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><HR
|
><HR
|
ALIGN="LEFT"
|
ALIGN="LEFT"
|
WIDTH="100%"></DIV
|
WIDTH="100%"></DIV
|
><DIV
|
><DIV
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><H1
|
><H1
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><A
|
><A
|
NAME="HAL-PORTING-CODING-CONVENTIONS">HAL Coding Conventions</H1
|
NAME="HAL-PORTING-CODING-CONVENTIONS">HAL Coding Conventions</H1
|
><P
|
><P
|
>To get changes and larger submissions included into the eCos source
|
>To get changes and larger submissions included into the eCos source
|
repository, we ask that you adhere to a set of coding conventions.
|
repository, we ask that you adhere to a set of coding conventions.
|
The conventions are defined as an attempt to make a consistent
|
The conventions are defined as an attempt to make a consistent
|
tree. Consistency makes it easier for people to read, understand and
|
tree. Consistency makes it easier for people to read, understand and
|
maintain the code, which is important when many people work on the
|
maintain the code, which is important when many people work on the
|
same project.</P
|
same project.</P
|
><P
|
><P
|
>The below is only a brief, and probably incomplete, summary of the
|
>The below is only a brief, and probably incomplete, summary of the
|
rules. Please look through files in the area where you are making
|
rules. Please look through files in the area where you are making
|
changes to get a feel for any additional conventions. Also feel free
|
changes to get a feel for any additional conventions. Also feel free
|
to ask on the list if you have specific questions.</P
|
to ask on the list if you have specific questions.</P
|
><DIV
|
><DIV
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><H2
|
><H2
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><A
|
><A
|
NAME="AEN9361">Implementation issues</H2
|
NAME="AEN9361">Implementation issues</H2
|
><P
|
><P
|
>There are a few implementation issues that should be kept in mind:</P
|
>There are a few implementation issues that should be kept in mind:</P
|
><P
|
><P
|
></P
|
></P
|
><DIV
|
><DIV
|
CLASS="VARIABLELIST"
|
CLASS="VARIABLELIST"
|
><DL
|
><DL
|
><DT
|
><DT
|
>HALs</DT
|
>HALs</DT
|
><DD
|
><DD
|
><P
|
><P
|
>HALs must be written in C and assembly only. C++ must not
|
>HALs must be written in C and assembly only. C++ must not
|
be used. This is in part to keep the HALs simple since this is
|
be used. This is in part to keep the HALs simple since this is
|
usually the first part of eCos a newcomer will see, and in
|
usually the first part of eCos a newcomer will see, and in
|
part to maintain the existing de facto standard.</P
|
part to maintain the existing de facto standard.</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>IO access</DT
|
>IO access</DT
|
><DD
|
><DD
|
><P
|
><P
|
>Use HAL IO access macros for code that might be reused on
|
>Use HAL IO access macros for code that might be reused on
|
different platforms than the one you are writing it for.</P
|
different platforms than the one you are writing it for.</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>MMU</DT
|
>MMU</DT
|
><DD
|
><DD
|
><P
|
><P
|
>If it is necessary to use the MMU (e.g., to prevent
|
>If it is necessary to use the MMU (e.g., to prevent
|
caching of IO areas), use a simple 1-1 mapping of memory if
|
caching of IO areas), use a simple 1-1 mapping of memory if
|
possible. On most platforms where using the MMU is necessary,
|
possible. On most platforms where using the MMU is necessary,
|
it will be possible to achieve the 1-1 mapping using the MMU's
|
it will be possible to achieve the 1-1 mapping using the MMU's
|
provision for mapping large continuous areas (hardwired TLBs or
|
provision for mapping large continuous areas (hardwired TLBs or
|
BATs). This reduces the footprint (no MMU table) and avoids
|
BATs). This reduces the footprint (no MMU table) and avoids
|
execution overhead (no MMU-related exceptions).</P
|
execution overhead (no MMU-related exceptions).</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>Assertions</DT
|
>Assertions</DT
|
><DD
|
><DD
|
><P
|
><P
|
>The code should contain assertions to validate argument
|
>The code should contain assertions to validate argument
|
values, state information and any assumptions the code may be
|
values, state information and any assumptions the code may be
|
making. Assertions are not enabled in production builds, so
|
making. Assertions are not enabled in production builds, so
|
liberally sprinkling assertions throughout the code is
|
liberally sprinkling assertions throughout the code is
|
good.</P
|
good.</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>Testing</DT
|
>Testing</DT
|
><DD
|
><DD
|
><P
|
><P
|
>The ability to test your code is very important. In
|
>The ability to test your code is very important. In
|
general, do not add new code to the eCos runtime unless you
|
general, do not add new code to the eCos runtime unless you
|
also add a new test to exercise that code. The test also
|
also add a new test to exercise that code. The test also
|
serves as an example of how to use the new code.</P
|
serves as an example of how to use the new code.</P
|
></DD
|
></DD
|
></DL
|
></DL
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><H2
|
><H2
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><A
|
><A
|
NAME="AEN9385">Source code details</H2
|
NAME="AEN9385">Source code details</H2
|
><P
|
><P
|
></P
|
></P
|
><DIV
|
><DIV
|
CLASS="VARIABLELIST"
|
CLASS="VARIABLELIST"
|
><DL
|
><DL
|
><DT
|
><DT
|
>Line length</DT
|
>Line length</DT
|
><DD
|
><DD
|
><P
|
><P
|
>Keep line length below 78 columns whenever possible.</P
|
>Keep line length below 78 columns whenever possible.</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>Comments</DT
|
>Comments</DT
|
><DD
|
><DD
|
><P
|
><P
|
>Whenever possible, use // comments instead of /**/.</P
|
>Whenever possible, use // comments instead of /**/.</P
|
></DD
|
></DD
|
><DT
|
><DT
|
>Indentation</DT
|
>Indentation</DT
|
><DD
|
><DD
|
><P
|
><P
|
>Use spaces instead of TABs. Indentation level is 4. Braces
|
>Use spaces instead of TABs. Indentation level is 4. Braces
|
start on the same line as the expression. See below for emacs
|
start on the same line as the expression. See below for emacs
|
mode details.</P
|
mode details.</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
>;;=================================================================
|
>;;=================================================================
|
;; eCos C/C++ mode Setup.
|
;; eCos C/C++ mode Setup.
|
;;
|
;;
|
;; bsd mode: indent = 4
|
;; bsd mode: indent = 4
|
;; tail comments are at col 40.
|
;; tail comments are at col 40.
|
;; uses spaces not tabs in C
|
;; uses spaces not tabs in C
|
|
|
(defun ecos-c-mode ()
|
(defun ecos-c-mode ()
|
"C mode with adjusted defaults for use with the eCos sources."
|
"C mode with adjusted defaults for use with the eCos sources."
|
(interactive)
|
(interactive)
|
(c++-mode)
|
(c++-mode)
|
(c-set-style "bsd")
|
(c-set-style "bsd")
|
(setq comment-column 40)
|
(setq comment-column 40)
|
(setq indent-tabs-mode nil)
|
(setq indent-tabs-mode nil)
|
(show-paren-mode 1)
|
(show-paren-mode 1)
|
(setq c-basic-offset 4)
|
(setq c-basic-offset 4)
|
|
|
(set-variable 'add-log-full-name "Your Name")
|
(set-variable 'add-log-full-name "Your Name")
|
(set-variable 'add-log-mailing-address "Your email address"))
|
(set-variable 'add-log-mailing-address "Your email address"))
|
|
|
(defun ecos-asm-mode ()
|
(defun ecos-asm-mode ()
|
"ASM mode with adjusted defaults for use with the eCos sources."
|
"ASM mode with adjusted defaults for use with the eCos sources."
|
(interactive)
|
(interactive)
|
(setq comment-column 40)
|
(setq comment-column 40)
|
(setq indent-tabs-mode nil)
|
(setq indent-tabs-mode nil)
|
(asm-mode)
|
(asm-mode)
|
(setq c-basic-offset 4)
|
(setq c-basic-offset 4)
|
|
|
(set-variable 'add-log-full-name "Your Name")
|
(set-variable 'add-log-full-name "Your Name")
|
(set-variable 'add-log-mailing-address "Your email address"))
|
(set-variable 'add-log-mailing-address "Your email address"))
|
|
|
(setq auto-mode-alist
|
(setq auto-mode-alist
|
(append '(("/local/ecc/.*\\.C$" . ecos-c-mode)
|
(append '(("/local/ecc/.*\\.C$" . ecos-c-mode)
|
("/local/ecc/.*\\.cc$" . ecos-c-mode)
|
("/local/ecc/.*\\.cc$" . ecos-c-mode)
|
("/local/ecc/.*\\.cpp$" . ecos-c-mode)
|
("/local/ecc/.*\\.cpp$" . ecos-c-mode)
|
("/local/ecc/.*\\.inl$" . ecos-c-mode)
|
("/local/ecc/.*\\.inl$" . ecos-c-mode)
|
("/local/ecc/.*\\.c$" . ecos-c-mode)
|
("/local/ecc/.*\\.c$" . ecos-c-mode)
|
("/local/ecc/.*\\.h$" . ecos-c-mode)
|
("/local/ecc/.*\\.h$" . ecos-c-mode)
|
("/local/ecc/.*\\.S$" . ecos-asm-mode)
|
("/local/ecc/.*\\.S$" . ecos-asm-mode)
|
("/local/ecc/.*\\.inc$" . ecos-asm-mode)
|
("/local/ecc/.*\\.inc$" . ecos-asm-mode)
|
("/local/ecc/.*\\.cdl$" . tcl-mode)
|
("/local/ecc/.*\\.cdl$" . tcl-mode)
|
) auto-mode-alist))</PRE
|
) auto-mode-alist))</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
></DD
|
></DD
|
></DL
|
></DL
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><H2
|
><H2
|
CLASS="SECTION"
|
CLASS="SECTION"
|
><A
|
><A
|
NAME="AEN9401">Nested Headers</H2
|
NAME="AEN9401">Nested Headers</H2
|
><P
|
><P
|
>In order to allow platforms to define all necessary details, while
|
>In order to allow platforms to define all necessary details, while
|
still maintaining the ability to share code between common platforms,
|
still maintaining the ability to share code between common platforms,
|
all HAL headers are included in a nested fashion.</P
|
all HAL headers are included in a nested fashion.</P
|
><P
|
><P
|
>The architecture header (usually <TT
|
>The architecture header (usually <TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>hal_XXX.h</TT
|
>hal_XXX.h</TT
|
>) includes the
|
>) includes the
|
variant equivalent of the header (<TT
|
variant equivalent of the header (<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>var_XXX.h</TT
|
>var_XXX.h</TT
|
>) which in turn
|
>) which in turn
|
includes the platform equivalent of the header
|
includes the platform equivalent of the header
|
(<TT
|
(<TT
|
CLASS="FILENAME"
|
CLASS="FILENAME"
|
>plf_XXX.h</TT
|
>plf_XXX.h</TT
|
>).</P
|
>).</P
|
><P
|
><P
|
>All definitions that may need to be overridden by a platform are
|
>All definitions that may need to be overridden by a platform are
|
then only conditionally defined, depending on whether a lower layer
|
then only conditionally defined, depending on whether a lower layer
|
has already made the definition:</P
|
has already made the definition:</P
|
><TABLE
|
><TABLE
|
BORDER="5"
|
BORDER="5"
|
BGCOLOR="#E0E0F0"
|
BGCOLOR="#E0E0F0"
|
WIDTH="70%"
|
WIDTH="70%"
|
><TR
|
><TR
|
><TD
|
><TD
|
><PRE
|
><PRE
|
CLASS="PROGRAMLISTING"
|
CLASS="PROGRAMLISTING"
|
>hal_intr.h: #include <var_intr.h>
|
>hal_intr.h: #include <var_intr.h>
|
|
|
#ifndef MACRO_DEFINED
|
#ifndef MACRO_DEFINED
|
# define MACRO ...
|
# define MACRO ...
|
# define MACRO_DEFINED
|
# define MACRO_DEFINED
|
#endif
|
#endif
|
|
|
|
|
|
|
var_intr.h: #include <plf_intr.h>
|
var_intr.h: #include <plf_intr.h>
|
|
|
#ifndef MACRO_DEFINED
|
#ifndef MACRO_DEFINED
|
# define MACRO ...
|
# define MACRO ...
|
# define MACRO_DEFINED
|
# define MACRO_DEFINED
|
#endif
|
#endif
|
|
|
|
|
plf_intr.h:
|
plf_intr.h:
|
|
|
# define MACRO ...
|
# define MACRO ...
|
# define MACRO_DEFINED</PRE
|
# define MACRO_DEFINED</PRE
|
></TD
|
></TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
><P
|
><P
|
>This means a platform can opt to rely on the variant or
|
>This means a platform can opt to rely on the variant or
|
architecture implementation of a feature, or implement it itself.</P
|
architecture implementation of a feature, or implement it itself.</P
|
></DIV
|
></DIV
|
></DIV
|
></DIV
|
><DIV
|
><DIV
|
CLASS="NAVFOOTER"
|
CLASS="NAVFOOTER"
|
><HR
|
><HR
|
ALIGN="LEFT"
|
ALIGN="LEFT"
|
WIDTH="100%"><TABLE
|
WIDTH="100%"><TABLE
|
SUMMARY="Footer navigation table"
|
SUMMARY="Footer navigation table"
|
WIDTH="100%"
|
WIDTH="100%"
|
BORDER="0"
|
BORDER="0"
|
CELLPADDING="0"
|
CELLPADDING="0"
|
CELLSPACING="0"
|
CELLSPACING="0"
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="hal-calling-if.html"
|
HREF="hal-calling-if.html"
|
ACCESSKEY="P"
|
ACCESSKEY="P"
|
>Prev</A
|
>Prev</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="34%"
|
WIDTH="34%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="ecos-ref.html"
|
HREF="ecos-ref.html"
|
ACCESSKEY="H"
|
ACCESSKEY="H"
|
>Home</A
|
>Home</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="hal-porting-platform.html"
|
HREF="hal-porting-platform.html"
|
ACCESSKEY="N"
|
ACCESSKEY="N"
|
>Next</A
|
>Next</A
|
></TD
|
></TD
|
></TR
|
></TR
|
><TR
|
><TR
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="left"
|
ALIGN="left"
|
VALIGN="top"
|
VALIGN="top"
|
>Virtual Vectors (eCos/ROM Monitor Calling Interface)</TD
|
>Virtual Vectors (eCos/ROM Monitor Calling Interface)</TD
|
><TD
|
><TD
|
WIDTH="34%"
|
WIDTH="34%"
|
ALIGN="center"
|
ALIGN="center"
|
VALIGN="top"
|
VALIGN="top"
|
><A
|
><A
|
HREF="hal-porting-guide.html"
|
HREF="hal-porting-guide.html"
|
ACCESSKEY="U"
|
ACCESSKEY="U"
|
>Up</A
|
>Up</A
|
></TD
|
></TD
|
><TD
|
><TD
|
WIDTH="33%"
|
WIDTH="33%"
|
ALIGN="right"
|
ALIGN="right"
|
VALIGN="top"
|
VALIGN="top"
|
>Platform HAL Porting</TD
|
>Platform HAL Porting</TD
|
></TR
|
></TR
|
></TABLE
|
></TABLE
|
></DIV
|
></DIV
|
></BODY
|
></BODY
|
></HTML
|
></HTML
|
|
|
