hal.sgml

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

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     HAL.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####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<part id="the-ecos-hardware-abstraction-layer">
<title>The eCos Hardware Abstraction Layer (HAL)</title>

<!-- {{{ Intro -->

<chapter id=hal-introduction>
<title>Introduction</title>
<PARA>
This is an initial specification of the <EMPHASIS>eCos</EMPHASIS> <!--
<index></index> -->Hardware Abstraction Layer (HAL). The HAL abstracts
the underlying hardware of a processor architecture and/or the
platform to a level sufficient for the eCos kernel to be ported onto
that platform.
</PARA>

<note>
<title>Caveat</title>
<PARA>
This document is an informal description of the HAL capabilities and
is not intended to be full documentation, although it may be used as a
source for such. It also describes the HAL as it is currently
implemented for the architectures targeted in this release. It most
closely describes the HALs for the MIPS, I386 and PowerPC HALs. Other
architectures are similar but may not be organized precisely as
described here.
</PARA>
</note>

</chapter>

<!-- }}} -->
<!-- {{{ Architecture, Variant and Platform  -->

<CHAPTER id="hal-architecture-variant-and-platform">
<TITLE>Architecture, Variant and Platform</TITLE>

<para>
We have identified three levels at which the HAL must operate.
</para>

<itemizedlist>
  <listitem>
    <para>
    The <!-- <index></index> --><firstterm>architecture
    HAL</firstterm> abstracts the basic CPU architecture and includes
    things like interrupt delivery, context switching, CPU startup
    etc.
    </para>
  </listitem>

  <listitem>
    <para>
    The <!-- <index></index> --> <firstterm>variant HAL</firstterm>
    encapsulates features of the CPU variant such as caches, MMU and
    FPU features. It also deals with any on-chip peripherals such as
    memory and interrupt controllers. For architectural variations,
    the actual implementation of the variation is often in the
    architectural HAL, and the variant HAL simply provides the correct
    configuration definitions.
    </para>
  </listitem>

    <listitem>
    <para>
    The <!-- <index></index> --><firstterm>platform HAL</firstterm>
    abstracts the properties of the current platform and includes
    things like platform startup, timer devices, I/O register access
    and interrupt controllers.
    </para>
  </listitem>

</itemizedlist>

<para>
The boundaries between these three HAL levels are necessarily blurred
since functionality shifts between levels on a target-by-target basis.
For example caches and MMU may be either an architecture feature or a
variant feature. Similarly, memory and interrupt controllers may be
on-chip and in the variant HAL, or off-chip and in the platform HAL.
</para>
<para>
Generally there is a separate package for each of the architecture,
variant and package HALs for a target. For some of the older targets,
or where it would be essentially empty, the variant HAL is omitted.
</para>
</CHAPTER>

<!-- }}} -->
<!-- {{{ General Principles -->

<CHAPTER id="hal-general-principles">
<TITLE>General principles</TITLE>

<PARA>
The HAL has been implemented according to the following general
principles:
</PARA>
<ORDEREDLIST>
<LISTITEM>
<PARA>	      The HAL is implemented in C and assembler, although the
	      eCos kernel is largely implemented in C&plus;&plus;.
	      This is to permit the HAL the widest possible
	      applicability.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>All interfaces to the HAL are implemented by
	      CPP macros. This allows them to be implemented as inline
	      C code, inline assembler or function calls to external C
	      or assembler code. This allows the most efficient
	      implementation to be selected without affecting the
	      interface. It also allows them to be redefined if the
	      platform or variant HAL needs to replace or enhance a definition
	      from the architecture HAL.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>The HAL provides simple, portable mechanisms for dealing
with the hardware of a wide range of architectures and platforms.
It is always possible to bypass the HAL and program the hardware
directly, but this may lead to a loss of portability. </PARA>
</LISTITEM>
</ORDEREDLIST>
</CHAPTER>

<!-- }}} -->
<!-- {{{ HAL Interfaces -->

<CHAPTER id="hal-interfaces">
<TITLE><!-- <index></index> --><!-- <xref> -->HAL Interfaces</TITLE>

<para>
This section describes the main HAL interfaces. 
</para>

<!-- {{{ Base Definitions -->

<SECTION id="hal-base-definitions">
<TITLE>Base Definitions</TITLE>

<para>
These are definitions that characterize the properties of the base
architecture that are used to compile the portable parts of the
kernel. They are concerned with such things a portable type
definitions, endianness, and labeling.
</para>

<PARA>
These definitions are supplied by the
<filename>cyg/hal/basetype.h</filename> header file which is supplied
by the architecture HAL. It is included automatically by
<FILENAME>cyg/infra/cyg_type.h</FILENAME>.
</PARA>

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

<SECTION>
<TITLE>Byte order</TITLE>
<VARIABLELIST>
  <VARLISTENTRY>
    <TERM><VARNAME>CYG_BYTEORDER</VARNAME></TERM>
    <LISTITEM>
      <PARA>
      This defines the byte order of the target and must be set to either
      <varname>CYG_LSBFIRST</varname> or <varname>CYG_MSBFIRST</varname>.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>
</SECTION>

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

<SECTION>
<TITLE>Label Translation</TITLE>

<VARIABLELIST>
  <VARLISTENTRY>
    <TERM><FUNCTION>CYG_LABEL_NAME(name)</FUNCTION></TERM>
    <LISTITEM>

      <PARA>
      This is a wrapper used in some C and C&plus;&plus; files which
      use labels defined in assembly code or the linker script.
      It need only be defined if the default implementation in
      <filename>cyg/infra/cyg_type.h</filename>, which passes the name
      argument unaltered, is inadequate. It should be paired with
      <function>CYG_LABEL_DEFN()</function>.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  <VARLISTENTRY>
    <TERM><FUNCTION>CYG_LABEL_DEFN(name)</FUNCTION></TERM>
    <LISTITEM>

      <PARA>
      This is a wrapper used in assembler sources and linker scripts
      which define labels.  It need only be defined if the default
      implementation in
      <filename>cyg/infra/cyg_type.h</filename>, which passes the name
      argument unaltered, is inadequate. The most usual alternative
      definition of this macro prepends an underscore to the label
      name. 
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>
</SECTION>


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

<SECTION>
<TITLE>Base types</TITLE>
<PROGRAMLISTING>
	cyg_halint8
	cyg_halint16
	cyg_halint32
	cyg_halint64
	cyg_halcount8
	cyg_halcount16
	cyg_halcount32
	cyg_halcount64
	cyg_halbool
</PROGRAMLISTING>
<PARA>
These macros define the C base types that should be used to define
variables of the given size. They only need to be defined if the
default types specified in <filename>cyg/infra/cyg_type.h</filename>
cannot be used. Note that these are only the base types, they will be
composed with <literal>signed</literal> and
<literal>unsigned</literal> to form full type specifications.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>Atomic types</TITLE>
<PROGRAMLISTING>
	cyg_halatomic CYG_ATOMIC
</PROGRAMLISTING>
<PARA>
These types are guaranteed to be read or written in a single
uninterruptible operation. It is architecture defined what size this
type is, but it will be at least a byte.
</PARA>
</SECTION>

</SECTION>

<!-- }}} -->
<!-- {{{ Architecture Characterization  -->

<SECTION id="hal-architecture-characterization">
<TITLE>Architecture Characterization</TITLE>

<para>
These are definition that are related to the basic architecture of the
CPU. These include the CPU context save format, context switching, bit
twiddling, breakpoints, stack sizes and address translation.
</para>

<PARA>
Most of these definition are found in
<filename>cyg/hal/hal_arch.h</filename>.  This file is supplied by the
architecture HAL. If there are variant or platform specific
definitions then these will be found in
<filename>cyg/hal/var_arch.h</filename> or
<filename>cyg/hal/plf_arch.h</filename>. These files are include
automatically by this header, so need not be included explicitly.
</PARA>

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

<SECTION>
<TITLE>Register Save Format</TITLE>
<PROGRAMLISTING>
typedef struct HAL_SavedRegisters
{
    /* architecture-dependent list of registers to be saved */ 
} HAL_SavedRegisters;
</PROGRAMLISTING>
<PARA>
This structure describes the layout of a saved machine state on the
stack. Such states are saved during thread context switches,
interrupts and exceptions. Different quantities of state may be saved
during each of these, but usually a thread context state is a subset
of the interrupt state which is itself a subset of an exception state.
For debugging purposes, the same structure is used for all three
purposes, but where these states are significantly different, this
structure may contain a union of the three states.
</PARA>
</SECTION>


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

<SECTION>
<TITLE>Thread Context Initialization</TITLE>

<PROGRAMLISTING>
HAL_THREAD_INIT_CONTEXT( sp, arg, entry, id )
</PROGRAMLISTING>

<PARA>
This macro initializes a thread's context so that
it may be switched to by <FUNCTION>HAL_THREAD_SWITCH_CONTEXT()</FUNCTION>.
The arguments are:
</PARA>
<VARIABLELIST>
  <VARLISTENTRY>
    <TERM>sp</TERM>
    <LISTITEM>
      <PARA>
      A location containing the current value of the thread's stack
      pointer. This should be a variable or a structure field. The SP
      value will be read out of here and an adjusted value written
      back.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>arg</TERM>
    <LISTITEM>
      <PARA>
      A value that is passed as the first argument to the entry
      point function.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  <VARLISTENTRY>
    <TERM>entry</TERM>
    <LISTITEM>
      <PARA>
      The address of an entry point function. This will be called
      according the C calling conventions, and the value of
      <parameter>arg</parameter> will be passed as the first
      argument. This function should have the following type signature
      <function>void entry(CYG_ADDRWORD arg)</function>.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  <VARLISTENTRY>
    <TERM>id</TERM>
    <LISTITEM>
      <PARA>
      A thread id value. This is only used for debugging purposes,
      it is ORed into the initialization pattern for unused registers
      and may be used to help identify the thread from its register dump.
      The least significant 16 bits of this value should be zero to allow
      space for a register identifier.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>
</SECTION>

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