porting.sgml

eCos/RedBoot for勤研ARM AnywhereII(4510) 含全部源代码

entry should always point to a raw channel.</para>

<para>During normal console output (i.e., diagnostic output) the console
table will be used to handle IO if defined. If not defined, the debug
table will be used.</para>

<para>This means that debuggers (such as GDB) which require text streams
to be mangled (O-packetized in the case of GDB), can rely on the ROM
monitor install mangling IO routines in the special mangler table and
select this for console output. The mangler will pass the mangled data
on to the selected debugging channel.</para>

<para>If the eCos configuration specifies a different console channel
from that used by the debugger, the console entry will point to the
selected raw channel, thus overriding any mangler provided by the ROM
monitor.</para>

<para>See hal_if_diag_* routines in hal_if.c for more details of the stream
path of diagnostic output. See <function>cyg_hal_gdb_diag_*()</function> routines in
<filename>hal_stub.c</filename> for the mangler used for GDB communication.</para>

<!--
FIXME: Other special channels are reserved for ethernet communication.
-->

</section>

<!-- }}} -->
<!-- {{{ New Platform Ports -->

<section>
<title>New Platform Ports</title>

<para>Define CDL options <literal>CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS</literal>,
<literal>CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL</literal>, and
<literal>CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</literal>.
</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