porting.sgml

eCos操作系统源码

</para>

<para>If <literal>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</literal> is set, make sure the infra diag
code uses the hal_if diag functions:</para>

<programlisting>
 #define HAL_DIAG_INIT() hal_if_diag_init()
 #define HAL_DIAG_WRITE_CHAR(_c_) hal_if_diag_write_char(_c_)
 #define HAL_DIAG_READ_CHAR(_c_) hal_if_diag_read_char(&_c_)
</programlisting>

<para>In addition to the above functions, the platform HAL must also
provide a function cyg_hal_plf_comms_init which initializes the
drivers and the channel procedure tables.
</para>

<para>Most of the other functionality in the table is more or less
possible to copy unchanged from existing ports. Some care is necessary
though to ensure the proper handling of interrupt vectors and timeouts
for various devices handled by the same driver. See PowerPC/Cogent
platform HAL for an example implementation.</para>

<note>
<title>Note:</title>
<para> When vector table console code is <emphasis>not</emphasis> used,
the platform HAL must map the HAL_DIAG_INIT, HAL_DIAG_WRITE_CHAR and
HAL_DIAG_READ_CHAR macros directly to the low-level IO functions,
hardwired to use a compile-time configured channel.</para>
</note>

<note>
<title>Note:</title>
<para> On old ports the hardwired <literal>HAL_DIAG_INIT</literal>,
<literal>HAL_DIAG_WRITE_CHAR</literal> and
<literal>HAL_DIAG_READ_CHAR</literal> implementations will also
contain code to O-packetize the output for GDB. This should
<emphasis>not</emphasis> be adopted for new ports! On new ports the
ROM monitor is guaranteed to provide the necessary mangling via the
vector table. The hardwired configuration should be reserved for ROM
startups where achieving minimal image size is crucial.
</para>
</note>

</section>

<!-- }}} -->

</section>

<!-- }}} -->


</section>

<!-- }}} -->
<!-- {{{ Coding Conventions  -->

<section id="hal-porting-coding-conventions">
<TITLE>HAL Coding Conventions</TITLE>


<para>
To get changes and larger submissions included into the eCos source
repository, we ask that you adhere to a set of coding conventions.
The conventions are defined as an attempt to make a consistent
tree. Consistency makes it easier for people to read, understand and
maintain the code, which is important when many people work on the
same project.
</para>

<para>
The below is only a brief, and probably incomplete, summary of the
rules. Please look through files in the area where you are making
changes to get a feel for any additional conventions. Also feel free
to ask on the list if you have specific questions.
</para>


<section>
<title>Implementation issues</title>

<para>
There are a few implementation issues that should be kept in mind:
</para>

<variablelist>
<varlistentry><term>HALs</term>
	<listitem><para>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
	usually the first part of eCos a newcomer will see, and in
	part to maintain the existing de facto standard.</para></listitem></varlistentry>

<varlistentry><term>IO access</term>
	<listitem><para>Use HAL IO access macros for code that might be reused on
	different platforms than the one you are writing it for.</para></listitem></varlistentry>

<varlistentry><term>MMU</term>
	<listitem><para>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
	possible. On most platforms where using the MMU is necessary,
	it will be possible to achieve the 1-1 mapping using the MMU's
	provision for mapping large continuous areas (hardwired TLBs or
	BATs). This reduces the footprint (no MMU table) and avoids
	execution overhead (no MMU-related exceptions).</para></listitem></varlistentry>

<varlistentry><term>Assertions</term> 
        <listitem><para>The code should contain assertions to validate argument
	values, state information and any assumptions the code may be
	making. Assertions are not enabled in production builds, so
	liberally sprinkling assertions throughout the code is
	good.</para></listitem></varlistentry>

<varlistentry><term>Testing</term>
	<listitem><para>The ability to test your code is very important. In
	general, do not add new code to the eCos runtime unless you
	also add a new test to exercise that code. The test also
	serves as an example of how to use the new code.</para></listitem></varlistentry>

</variablelist>

</section>

<section>
<title>Source code details</title>

<variablelist>
<varlistentry><term>Line length</term> 
	<listitem><para>Keep line length below 78 columns whenever possible.</para></listitem></varlistentry>

<varlistentry><term>Comments</term>
	<listitem><para>Whenever possible, use // comments instead of /**/.</para></listitem></varlistentry>

<varlistentry><term>Indentation</term>
	<listitem><para>Use spaces instead of TABs. Indentation level is 4. Braces
	start on the same line as the expression. See below for emacs
	mode details.</para>

<programlisting>
;;=================================================================
;; eCos C/C++ mode Setup.
;;
;; bsd mode: indent = 4
;; tail comments are at col 40.
;; uses spaces not tabs in C

(defun ecos-c-mode ()
  "C mode with adjusted defaults for use with the eCos sources."
  (interactive)
  (c++-mode)
  (c-set-style "bsd")
  (setq comment-column 40)
  (setq indent-tabs-mode nil)
  (show-paren-mode 1)
  (setq c-basic-offset 4)

  (set-variable 'add-log-full-name "Your Name")
  (set-variable 'add-log-mailing-address "Your email address"))

(defun ecos-asm-mode ()
  "ASM mode with adjusted defaults for use with the eCos sources."
  (interactive)
  (setq comment-column 40)
  (setq indent-tabs-mode nil)
  (asm-mode)
  (setq c-basic-offset 4)

  (set-variable 'add-log-full-name "Your Name")
  (set-variable 'add-log-mailing-address "Your email address"))

(setq auto-mode-alist
      (append '(("/local/ecc/.*\\.C$"   . ecos-c-mode)
                ("/local/ecc/.*\\.cc$"  . ecos-c-mode)
                ("/local/ecc/.*\\.cpp$" . ecos-c-mode)
                ("/local/ecc/.*\\.inl$" . ecos-c-mode)
                ("/local/ecc/.*\\.c$"   . ecos-c-mode)
                ("/local/ecc/.*\\.h$"   . ecos-c-mode)
		("/local/ecc/.*\\.S$"   . ecos-asm-mode) 
		("/local/ecc/.*\\.inc$" . ecos-asm-mode)
		("/local/ecc/.*\\.cdl$" . tcl-mode)
                ) auto-mode-alist))
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</section>

<section>

<title>Nested Headers</title>

<para>In order to allow platforms to define all necessary details, while
still maintaining the ability to share code between common platforms,
all HAL headers are included in a nested fashion.</para>

<para>The architecture header (usually <filename>hal_XXX.h</filename>) includes the
variant equivalent of the header (<filename>var_XXX.h</filename>) which in turn
includes the platform equivalent of the header
(<filename>plf_XXX.h</filename>).</para>

<para>All definitions that may need to be overridden by a platform are
then only conditionally defined, depending on whether a lower layer
has already made the definition:</para>

<programlisting>
hal_intr.h:     #include &lt;var_intr.h&gt;

                #ifndef MACRO_DEFINED
                # define MACRO ...
                # define MACRO_DEFINED
                #endif



var_intr.h:     #include &lt;plf_intr.h&gt;

                #ifndef MACRO_DEFINED
                # define MACRO ...
                # define MACRO_DEFINED
                #endif


plf_intr.h:

                # define MACRO ...
                # define MACRO_DEFINED
</programlisting>

<para>This means a platform can opt to rely on the variant or
architecture implementation of a feature, or implement it itself.</para>

</section>

</section>

<!-- }}} -->
<!-- {{{ Platform HAL Porting -->

<section id="hal-porting-platform">
<title>Platform HAL Porting</title>

<para>
This is the type of port that takes the least effort. It basically
consists of describing the platform (board) for the HAL: memory
layout, early platform initialization, interrupt controllers, and a
simple serial device driver.
</para>

<para>
Doing a platform port requires a preexisting architecture and
possibly a variant HAL port.
</para>

<!-- {{{ Porting Process -->

<section>
<TITLE>HAL Platform Porting Process</TITLE>

<!-- {{{ Brief Overview -->

<section>
<title>Brief overview</title>

<para>The easiest way to make a new platform HAL is simply to copy an
existing platform HAL of the same architecture/variant and change all
the files to match the new one. In case this is the first platform for
the architecture/variant, a platform HAL from another architecture
should be used as a template.
</para>

<para>
The best way to start a platform port is to concentrate on getting
RedBoot to run. RedBoot is a simpler environment than full eCos, it
does not use interrupts or threads, but covers most of the
basic startup requirements.
</para>

<para>
RedBoot normally runs out of FLASH or ROM and provides program loading
and debugging facilities.  This allows further HAL development to
happen using RAM startup configurations, which is desirable for the
simple reason that downloading an image which you need to test is
often many times faster than either updating a flash part, or indeed,
erasing and reprogramming an EPROM.
</para>

<para>There are two approaches to getting to this first goal:
</para>

<orderedlist>
<listitem>
<para>
The board is equipped with a ROM monitor which allows "load and go" of
ELF, binary, S-record or some other image type which can be created
using <application>objcopy</application>. This allows you to develop
RedBoot by downloading and running the code (saving time).
</para>

<para>
When the stub is running it is a good idea to examine the various
hardware registers to help you write the platform initialization code.
</para>

<para>
Then you may have to fiddle a bit going through step two (getting it
to run from ROM startup). If at all possible, preserve the original
ROM monitor so you can revert to it if necessary.
</para>
</listitem>

<listitem>
<para>
The board has no ROM monitor. You need to get the platform
initialization and stub working by repeatedly making changes, updating
flash or EPROM and testing the changes. If you are lucky, you have a
JTAG or similar CPU debugger to help you. If not, you will probably
learn to appreciate LEDs. This approach may also be needed during the
initial phase of moving RedBoot from RAM startup to ROM, since it is
very unlikely to work first time.
</para>
</listitem>
</orderedlist>

</section>

<!-- }}} -->
<!-- {{{ Step-by-step -->

<section>
<title>Step-by-step</title>

<para>Given that no two platforms are exactly the same, you may have to
deviate from the below. Also, you should expect a fair amount of
fiddling - things almost never go right the first time. See the hints
section below for some suggestions that might help debugging.
</para>

<para>The description below is based on the HAL layout used in the MIPS,
PC and MN10300 HALs. Eventually all HALs should be converted to look like
these - but in a transition period there will be other HALs which look
substantially different. Please try to adhere to the following as much is
possible without causing yourself too much grief integrating with a
HAL which does not follow this layout.
</para>

<!-- ====================================================================== -->

<section>
<title>Minimal requirements</title>

<para>
These are the changes you must make before you attempt to build
RedBoot. You are advised to read all the sources though.
</para>

<orderedlist>
<listitem><para>Copy an existing platform HAL from the same or another
    architecture. Rename the files as necessary to follow the
    standard: CDL and MLT related files should contain the
    &lt;arch&gt;_&lt;variant&gt;_&lt;platform&gt; triplet.</para>
</listitem>

<listitem><para>Adjust CDL options. Primarily opti