porting.sgml

eCos操作系统源码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     porting.sgml                                                -->
<!--                                                                 -->
<!--     eCos common HAL documentation                               -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<CHAPTER id="hal-porting-guide">
<TITLE><!-- <index></index> -->	Porting Guide</TITLE>

<!-- {{{ Intro -->

<section id="hal-porting-intro">
<title>Introduction</title>

<para>
eCos has been designed to be fairly easy to port to new targets. A
target is a specific platform (board) using a given architecture (CPU
type). The porting is facilitated by the hierarchical layering of the
eCos sources - all architecture and platform specific code is
implemented in a HAL (hardware abstraction layer).
</para>

<para>
By porting the eCos HAL to a new target the core functionality of eCos
(infra, kernel, uITRON, etc) will be able to run on the target. It may
be necessary to add further platform specific code such as serial
drivers, display drivers, ethernet drivers, etc. to get a fully
capable system.
</para>

<para>
This document is intended as a help to the HAL porting process. Due to
the nature of a porting job, it is impossible to give a complete
description of what has to be done for each and every potential
target. This should not be considered a clear-cut recipe - you will
probably need to make some implementation decisions, tweak a few
things, and just plain have to rely on common sense.
</para>

<para>
However, what is covered here should be a large part of the
process. If you get stuck, you are advised to read the
<ulink url="http://sourceware.cygnus.com/ml/ecos-discuss/">
ecos-discuss archive
</ulink>
where you may find discussions which apply to the problem at
hand. You are also invited to ask questions on the
<ulink url="http://sourceware.cygnus.com/ecos/intouch.html">
ecos-discuss mailing list
</ulink>
to help you resolve problems - but as is always the case
with community lists, do not consider it an oracle for any and all
questions. Use common sense - if you ask too many questions which
could have been answered by reading the
<ulink
url="http://sourceware.cygnus.com/ecos/docs-latest/">documentation</ulink>,
<ulink url="http://sourceware.cygnus.com/fom/ecos">FAQ</ulink> or
<ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/?cvsroot=ecos">
source code
</ulink>, you are likely to be ignored.
</para>

<para>
This document will be continually improved by Red Hat engineers as
time allows. Feedback and help with improving the document is sought,
so if you have any comments at all, please do not hesitate to post
them on
<ulink url="mailto:[e-mail]?subject=[porting]<subject>">
ecos-discuss
</ulink>
(please prefix the subject with [porting]).
</para>

<para>
At the moment this document is mostly an outline. There are many
details to fill in before it becomes complete. Many places you'll just
find a list of keywords / concepts that should be described (please
post on ecos-discuss if there are areas you think are not covered).
</para>

<para>
All pages or sections where the caption ends in [TBD] contain little
more than key words and/or random thoughts - there has been no work
done as such on the content. The word FIXME may appear in the text to
highlight places where information is missing.
</para>

</section>

<!-- }}} -->
<!-- {{{ HAL Structure -->

<section id="hal-porting-structure">
<title>HAL Structure</title>

<para>
In order to write an eCos HAL it's a good idea to have at least a
passing understanding of how the HAL interacts with the rest of the
system.
</para>

<!-- {{{ HAL Classes -->

<section>
<title>HAL Classes</title>

<para>
The eCos HAL consists of four HAL sub-classes. This table gives a
brief description of each class and partly reiterates the description
in <xref linkend="hal-architecture-variant-and-platform">. The links
refer to the on-line CVS tree (specifically to the sub-HALs used by
the PowerPC MBX target).
</para>

<informaltable frame=all>
<tgroup cols=3 align=left colsep=1 rowsep=1>
<thead>
<row>
<entry>HAL type</entry>
<entry>Description</entry>
<entry>Functionality Overview</entry>
</row>
</thead>
<tbody>
<row>
<entry>
Common HAL <ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/common/current?cvsroot=ecos">(hal/common)</ulink>
</entry>
<entry>Configuration options and functionality shared by all HALs.</entry>
<entry>Generic debugging functionality, driver API, eCos/ROM monitor
      calling interface, and tests.</entry>
</row>
<row>
  <entry>Architecture HAL <ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/arch/current?cvsroot=ecos">(hal/&lt;architecture&gt;/arch)</ulink></entry>
  <entry>Functionality specific to the given architecture. Also default
  implementations of some functionality which can be overridden by
  variant or platform HALs.</entry>
  <entry>Architecture specific debugger functionality (handles single
     stepping, exception-to-signal conversion, etc.),
     exception/interrupt vector definitions and handlers, cache
     definition and control macros, context switching code, assembler
     functions for early system initialization, configuration options,
     and possibly tests. </entry>
</row>
<row>
  <entry>Variant HAL <ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/mpc8xx/current?cvsroot=ecos">(hal/&lt;architecture&gt;/&lt;variant&gt;)</ulink></entry>
  <entry>Some CPU architectures consist of a number variants, for example
     MIPS CPUs come in both 32 and 64 bit versions, and some variants
     have embedded features additional to the CPU core.
</entry>
  <entry>Variant extensions to the architecture code (cache,
     exception/interrupt), configuration options, possibly drivers for
     variant on-core devices, and possibly tests.</entry>
</row>
<row>
  <entry>Platform HAL <ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/mbx/current?cvsroot=ecos">(hal/&lt;architecture&gt;/&lt;platform&gt;)</ulink></entry>
  <entry>Contains functionality and configuration options specific to the
      platform.
</entry>
  <entry>Early platform initialization code, platform memory layout
     specification, configuration options (processor speed, compiler
     options), diagnostic IO functions, debugger IO functions,
     platform specific extensions to architecture or variant code
     (off-core interrupt controller), and possibly tests.</entry>
</row>
<row>
  <entry>Auxiliary HAL <ulink url="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/quicc/current?cvsroot=ecos">(hal/&lt;architecture&gt;/&lt;module&gt;)</ulink></entry>
  <entry>Some variants share common modules on the core. Motorola's PowerPC
      QUICC is an example of such a module.
</entry>
  <entry>Module specific functionality (interrupt controller, simple
      device drivers), possibly tests.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</section>

<!-- }}} -->
<!-- {{{ File Descriptions -->

<section>
<title>File Descriptions</title>

<para>
Listed below are the files found in various HALs, with a short
description of what each file contains. When looking in existing HALs
beware that they do not necessarily follow this naming scheme.
If you are writing a new HAL, please try to follow it as
closely as possible. Still, no two targets are the same, so sometimes
it makes sense to use additional files.
</para>

<!-- {{{ Common HAL -->

<section>
<title>Common HAL</title>

<informaltable frame=all>
<tgroup cols=2 align=left colsep=1 rowsep=1>
<thead>
<row>
<entry>File</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>

<row>
<entry><filename>include/dbg-thread-syscall.h</filename></entry>
  <entry>Defines the thread debugging syscall function. This is used by
  the ROM monitor to access the thread debugging API in the RAM
  application.  <!-- FIXME: link thread debug description -->.</entry>
</row>
<row>
<entry><filename>include/dbg-threads-api.h</filename></entry>
  <entry>Defines the thread debugging API. <!-- FIXME: link thread
  debug description -->.</entry>
</row>
<row>
<entry><filename>include/drv_api.h</filename></entry>
  <entry>Defines the driver API.</entry>
</row>
<row>
<entry><filename>include/generic-stub.h</filename></entry>
  <entry>Defines the generic stub features.</entry>
</row>
<row>
<entry><filename>include/hal_if.h</filename></entry>
  <entry>Defines the ROM/RAM calling interface API.</entry>
</row>
<row>
<entry><filename>include/hal_misc.h</filename></entry>
  <entry>Defines miscellaneous helper functions shared by all HALs.</entry>
</row>
<row>
<entry><filename>include/hal_stub.h</filename></entry>
  <entry>Defines eCos mappings of GDB stub features.</entry>
</row>
<row>
<entry><filename>src/dbg-threads-syscall.c</filename></entry>
  <entry>Thread debugging implementation.</entry>
</row>
<row>
<entry><filename>src/drv_api.c</filename></entry>
  <entry>Driver API implementation. Depending on configuration this
  provides either wrappers for the kernel API, or a minimal
  implementation of these features. This allows drivers to be written
  relying only on HAL features.</entry>
</row>
<row>
<entry><filename>src/dummy.c</filename></entry>
  <entry>Empty dummy file ensuring creation of libtarget.a.</entry>
</row>
<row>
<entry><filename>src/generic-stub.c</filename></entry>
  <entry>Generic GDB stub implementation. This provides the
  communication protocol used to communicate with GDB over a serial
  device or via the network.</entry>
</row>
<row>
<entry><filename>src/hal_if.c</filename></entry>
  <entry>ROM/RAM calling interface implementation. Provides wrappers from
  the calling interface API to the eCos features used for the
  implementation.</entry>
</row>
<row>
<entry><filename>src/hal_misc.c</filename></entry>
  <entry>Various helper functions shared by all platforms and
  architectures.</entry>
</row>
<row>
<entry><filename>src/hal_stub.c</filename></entry>
  <entry>Wrappers from eCos HAL features to the features required by the
  generic GDB stub.</entry>
</row>
<row>
<entry><filename>src/stubrom/stubrom.c</filename></entry>
  <entry>The file used to build eCos GDB stub images. Basically a
  cyg_start function with a hard coded breakpoint.</entry>
</row>
<row>
<entry><filename>src/thread-packets.c</filename></entry>
  <entry>More thread debugging related functions.</entry>
</row>
<row>
<entry><filename>src/thread-pkts.h</filename></entry>
  <entry>Defines more thread debugging related function.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</section>

<!-- }}} -->
<!-- {{{ Architecture HAL -->

<section>
<title>Architecture HAL</title>

<para>Some architecture HALs may add extra files for architecture
specific serial drivers, or for handling interrupts and exceptions if it
makes sense.</para>

<para>Note that many of the definitions in these files are only
conditionally defined - if the equivalent variant or platform headers
provide the definitions, those override the generic architecture
definitions.</para>

<informaltable frame=all>
<tgroup cols=2 align=left colsep=1 rowsep=1>
<thead>
<row>
<entry>File</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>

<row>
<entry><filename>include/arch.inc</filename></entry>
  <entry>Various assembly macros used during system initialization.</entry>
</row>
<row>
<entry><filename>include/basetype.h</filename></entry>
  <entry>Endian, label, alignment, and type size definitions. These
  override common defaults in CYGPKG_INFRA.</entry>
</row>
<row>
<entry><filename>include/hal_arch.h</filename></entry>
  <entry>Saved register frame format, various thread, register and stack
  related macros.</entry>
</row>
<row>