porting.sgml

eCos操作系统源码

<entry><filename>include/hal_cache.h</filename></entry>
  <entry>Cache definitions and cache control macros.</entry>
</row>
<row>
<entry><filename>include/hal_intr.h</filename></entry>
  <entry>Exception and interrupt definitions. Macros for configuring and
  controlling interrupts. eCos real-time clock control macros.</entry>
</row>
<row>
<entry><filename>include/hal_io.h</filename></entry>
  <entry>Macros for accessing IO devices.</entry>
</row>
<row>
<entry><filename>include/&lt;arch&gt;_regs.h</filename></entry>
  <entry>Architecture register definitions.</entry>
</row>
<row>
<entry><filename>include/&lt;arch&gt;_stub.h</filename></entry>
  <entry>Architecture stub definitions. In particular the register frame
  layout used by GDB. This may differ from the one used by eCos.</entry>
</row>
<row>
<entry><filename>include/&lt;arch&gt;.inc</filename></entry>
  <entry>Architecture convenience assembly macros.</entry>
</row>
<row>
<entry><filename>src/&lt;arch&gt;.ld</filename></entry>
  <entry>Linker macros.</entry>
</row>
<row>
<entry><filename>src/context.S</filename></entry>
  <entry>Functions handling context switching and setjmp/longjmp.</entry>
</row>
<row>
<entry><filename>src/hal_misc.c</filename></entry>
  <entry>Exception and interrupt handlers in C. Various other utility
  functions.</entry>
</row>
<row>
<entry><filename>src/hal_mk_defs.c</filename></entry>
  <entry>Used to export definitions from C header files to assembler
  header files.</entry>
</row>
<row>
<entry><filename>src/hal_intr.c</filename></entry>
  <entry>Any necessary interrupt handling functions.</entry>
</row>
<row>
<entry><filename>src/&lt;arch&gt;stub.c</filename></entry>
  <entry>Architecture stub code. Contains functions for translating eCos
  exceptions to UNIX signals and functions for single-stepping.</entry>
</row>
<row>
<entry><filename>src/vectors.S</filename></entry>
  <entry>Exception, interrupt and early initialization code.</entry>
</row>
</tbody>
</tgroup>
</informaltable>


</section>

<!-- }}} -->
<!-- {{{ Variant HAL -->

<section>
<title>Variant HAL</title>

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

<para>Note that these files may be mostly empty if the CPU variant can be
controlled by the generic architecture macros. The definitions present
are only conditionally defined - if the equivalent platform headers
provide the definitions, those override the variant 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/var_arch.h</filename></entry>
  <entry>Saved register frame format, various thread, register and stack
  related macros.</entry>
</row>
<row>
<entry><filename>include/var_cache.h</filename></entry>
  <entry>Cache related macros.</entry>
</row>
<row>
<entry><filename>include/var_intr.h</filename></entry>
  <entry>Interrupt related macros.</entry>
</row>
<row>
<entry><filename>include/var_regs.h</filename></entry>
  <entry>Extra register definitions for the CPU variant.</entry>
</row>
<row>
<entry><filename>include/variant.inc</filename></entry>
  <entry>Various assembly macros used during system initialization.</entry>
</row>
<row>
<entry><filename>src/var_intr.c</filename></entry>
  <entry>Interrupt functions if necessary.</entry>
</row>
<row>
<entry><filename>src/var_misc.c</filename></entry>
  <entry>hal_variant_init function and any necessary extra functions.</entry>
</row>
<row>
<entry><filename>src/variant.S</filename></entry>
  <entry>Interrupt handler table definition.</entry>
</row>
<row>
<entry><filename>src/&lt;arch&gt;_&lt;variant&gt;.ld</filename></entry>
  <entry>Linker macros.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</section>

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

<section>
<title>Platform HAL</title>

<para>Extras files may be added for platform specific serial
drivers. Extra files for handling interrupts and exceptions will be
present if it makes sense.</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/hal_diag.h</filename></entry>
  <entry>Defines functions used for HAL diagnostics output. This would
  normally be the ROM calling interface wrappers, but may also be the
  low-level IO functions themselves, saving a little overhead.</entry>
</row>
<row>
<entry><filename>include/platform.inc</filename></entry>

  <entry>Platform initialization code. This includes memory controller,
  vectors, and monitor initialization. Depending on the architecture,
  other things may need defining here as well: interrupt decoding,
  status register initialization value, etc.</entry>

</row>
<row>
<entry><filename>include/plf_cache.h</filename></entry>
  <entry>Platform specific cache handling.</entry>
</row>
<row>
<entry><filename>include/plf_intr.h</filename></entry>
  <entry>Platform specific interrupt handling.</entry>
</row>
<row>
<entry><filename>include/plf_io.h</filename></entry>
  <entry>PCI IO definitions and macros. May also be used to override
  generic HAL IO macros if the platform endianness differs from that of
  the CPU.</entry>
</row>
<row>
<entry><filename>include/plf_stub.h</filename></entry>
  <entry>Defines stub initializer and board reset details.</entry>
</row>
<row>
<entry><filename>src/hal_diag.c</filename></entry>
  <entry>May contain the low-level device drivers. But these may also
  reside in plf_stub.c</entry>
</row>
<row>
<entry><filename>src/platform.S</filename></entry>
  <entry>Memory controller setup macro, and if necessary interrupt
  springboard code.</entry>
</row>
<row>
<entry><filename>src/plf_misc.c</filename></entry>
  <entry>Platform initialization code.</entry>
</row>
<row>
<entry><filename>src/plf_mk_defs.c</filename></entry>
  <entry>Used to export definitions from C header files to assembler
  header files.</entry>
</row>
<row>
<entry><filename>src/plf_stub.c</filename></entry>
  <entry>Platform specific stub initialization and possibly the low-level
  device driver.</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>The platform HAL also contains files specifying the platform's
memory layout. These files are located in
<filename>include/pkgconf</filename>.</para>

</section>

<!-- }}} -->
<!-- {{{ Auxiliary HAL -->

<section>
<title>Auxiliary HAL</title>

<para>Auxiliary HALs contain whatever files are necessary to provide the
required functionality. There are no predefined set of files required
in an auxiliary HAL.</para>

</section>

<!-- }}} -->

</section>

<!-- }}} -->

</section>

<!-- }}} -->
<!-- {{{ ROM Monitor Calling Interface -->

<section id="hal-calling-if">
<TITLE>Virtual Vectors (eCos/ROM Monitor Calling Interface)</TITLE>

<para>
Some eCos platforms have supported full debugging capabilities via
CygMon since day one. Platforms of the architectures PowerPC, ARM, and
SH do not provide those features unless a GDB stub is included in the
application.
</para>

<para>
This is going to change. All platforms will (eventually) support
all the debugging features by relying on a ROM/RAM calling interface
(also referred to as virtual vector table) provided by the ROM
monitor. This calling interface is based on the tables used by libbsp
and is thus backwards compatible with the existing CygMon supported
platforms.
</para>

<!-- {{{ Virtual Vectors -->

<section id="hal-porting-virtual-vectors">
<title>Virtual Vectors</title>

<para>What are virtual vectors, what do they do, and why are they
needed?
</para>

<para>
"Virtual vectors" is the name of a table located at a static
location in the target address space. This table contains 64 vectors
that point to <emphasis>service</emphasis> functions or data.
</para>

<para>The fact that the vectors are always placed at the same location in
the address space means that both ROM and RAM startup configurations
can access these and thus the services pointed to.</para>

<para>The primary goal is to allow services to be provided by ROM
configurations (ROM monitors such as RedBoot in particular) with
<emphasis>clients</emphasis> in RAM configurations being able to use these
services.</para>

<para>Without the table of pointers this would be impossible since the
ROM and RAM applications would be linked separately - in effect having
separate name spaces - preventing direct references from one to the
other.</para>

<para>This decoupling of service from client is needed by RedBoot,
allowing among other things debugging of applications which do not
contain debugging client code (stubs).</para>

<!-- {{{ Initialization -->

<section>
<title>Initialization (or Mechanism vs. Policy)</title>

<para>Virtual vectors are a <emphasis>mechanism</emphasis> for decoupling services
from clients in the address space.</para>

<para>The mechanism allows services to be implemented by a ROM
monitor, a RAM application, to be switched out at run-time, to be
disabled by installing pointers to dummy functions, etc.</para>

<para>The appropriate use of the mechanism is specified loosely by a
<emphasis>policy</emphasis>. The general policy dictates that the vectors are
initialized in whole by ROM monitors (built for ROM or RAM), or by
stand-alone applications.</para>

<para>For configurations relying on a ROM monitor environment, the policy
is to allow initialization on a service by service basis. The default
is to initialize all services, except COMMS services since these are
presumed to already be carrying a communication session to the
debugger / console which was used for launching the application.  This
means that the bulk of the code gets tested in normal builds, and not
just once in a blue moon when building new stubs or a ROM
configuration.</para>

<para>The configuration options are written to comply with this policy by
default, but can be overridden by the user if desired. Defaults
are:</para>

<itemizedlist>
<listitem><para>For application development: the ROM monitor provides
debugging and diagnostic IO services, the RAM application relies
on these by default.</para>
</listitem>
<listitem>
<para>For production systems: the application contains all the
necessary services.</para>
</listitem>

</itemizedlist>

</section>

<!-- }}} -->
<!-- {{{ Pros and Cons -->

<section>
<title>Pros and Cons of Virtual Vectors</title>

<para>
There are pros and cons associated with the use of virtual
vectors. We do believe that the pros generally outweigh the cons by a
great margin, but there may be situations where the opposite is
true.
</para>

<para>
The use of the services are implemented by way of macros, meaning
that it is possible to circumvent the virtual vectors if
desired. There is (as yet) no implementation for doing this, but it is
possible.
</para>

<para>Here is a list of pros and cons:</para>

<variablelist>
<varlistentry><term>Pro: Allows debugging without including stubs</term>

      <listitem><para>This is the primary reason for using virtual vectors. It