hal.sgml

ecos实时嵌入式操作系统

      <PARA>
      Hints to the cache that the region is going to be read from
      in the near future. This may cause the region to be speculatively
      read into the cache.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_WRITE_HINT() </TERM>
    <LISTITEM>
      <PARA>
      Hints to the cache that the region is going to be written
      to in the near future. This may have the identical behavior to
      HAL_DCACHE_READ_HINT().
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_DCACHE_ZERO()</TERM>
    <LISTITEM>
      <PARA>
      Allocates and zeroes lines in the cache for the given
      region without reading memory. This is useful if a large area of
      memory is to be cleared.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

</SECTION>
</SECTION>

<!-- }}} -->
<!-- {{{ Linker Scripts -->

<SECTION id="hal-linker-scripts">
<TITLE><!-- <xref> -->Linker Scripts</TITLE>

<para>
When an eCos application is linked it must be done under the control
of a linker script. This script defines the memory areas, addresses
and sized, into which the code and data are to be put, and allocates
the various sections generated by the compiler to these.
</para>

<para>
The linker script actually used is in
<filename>lib/target.ld</filename> in the install directory. This is
actually manufactured out of two other files: a base linker script and
an <literal>.ldi</literal> file that was generated by the memory
layout tool.
</para>

<para>
The base linker script is usually supplied either by the architecture
HAL or the variant HAL. It consists of a set of linker script
fragments, in the form of C preprocessor macros, that define the major
output sections to be generated by the link operation. The
<literal>.ldi</literal> file, which is <literal>#include'ed</literal>
by the base linker script, uses these macro definitions to assign the
output sections to the required memory areas and link addresses.
</para>

<para>
The <literal>.ldi</literal> file is supplied by the platform HAL, and
contains knowledge of the memory layout of the target platform. These
files generally conform to a standard naming convention, each file
being of the form:
</para>
<para>
<filename>pkgconf/mlt_&lt;architecture&gt;_&lt;variant&gt;_&lt;platform&gt;_&lt;startup&gt;.ldi</filename>
</para>
<para>
where <literal>&lt;architecture&gt;</literal>,
<literal>&lt;variant&gt;</literal> and
<literal>&lt;platform&gt;</literal> are the respective HAL package
names and <literal>&lt;startup&gt;</literal> is the startup type which
is usually one of <literal>ROM</literal>, <literal>RAM</literal> or
<literal>ROMRAM</literal>.
</para>

<para>
In addition to the <literal>.ldi</literal> file, there is also a
congruously name <literal>.h</literal> file. This may be used by the
application to access information defined in the
<literal>.ldi</literal> file. Specifically it contains the memory
layout defined there, together with any additional section names
defined by the user. Examples of the latter are heap areas or PCI bus
memory access windows.
</para>

<para>
The <literal>.ldi</literal> is manufactured by the <application>Memory
Layout Tool</application> (MLT). The <application>MLT</application> saves the memory
configuration into a file named
</para>
<para>
<filename>include/pkgconf/mlt_&lt;architecture&gt;_&lt;variant&gt;_&lt;platform&gt;_&lt;startup&gt;.mlt</filename>
</para>
<para>
in the platform HAL. This file is used by the
<application>MLT</application> to manufacture both the
<literal>.ldi</literal> and <literal>.h</literal> files. Users should
beware that direct edits the either of these files may be overwritten
if the <application>MLT</application> is run and regenerates them from the
<literal>.mlt</literal> file.
</para>

<para>
The names of the <literal>.ldi</literal> and <literal>.h</literal>
files are defined by macro definitions in
<FILENAME>pkgconf/system.h</FILENAME>. These are
<literal>CYGHWR_MEMORY_LAYOUT_LDI</literal> and
<literal>CYGHWR_MEMORY_LAYOUT_H</literal> respectively. While there
will be little need for the application to refer to the
<literal>.ldi</literal> file directly, it may include the
<literal>.h</literal> file as follows:
</para>

<programlisting>
#include CYGHWR_MEMORY_LAYOUT_H
</programlisting>

</SECTION>

<!-- }}} -->
<!-- {{{ Diagnostic Support -->

<SECTION id="hal-diagnostic-support">
<TITLE>Diagnostic Support</TITLE>

<para>
The HAL provides support for low level diagnostic IO. This is
particularly useful during early development as an aid to bringing up
a new platform. Usually this diagnostic channel is a UART or some
other serial IO device, but it may equally be a a memory
buffer, a simulator supported output channel, a ROM emulator virtual
UART, and LCD panel, a memory mapped video buffer or any other output
device.
</para>

<PARA>
<FUNCTION>HAL_DIAG_INIT()</FUNCTION> performs any initialization
required on the device being used to generate diagnostic output. This
may include, for a UART, setting baud rate, and stop, parity and
character bits. For other devices it may include initializing a
controller or establishing contact with a remote device.
</PARA>

<PARA>
<FUNCTION>HAL_DIAG_WRITE_CHAR(c)</FUNCTION> writes
the character supplied to the diagnostic output device.
</PARA>

<PARA>
<FUNCTION>HAL_DIAG_READ_CHAR(c)</FUNCTION> reads a character from the
diagnostic device into the supplied variable. This is not supported
for all diagnostic devices.
</PARA>

<para>
These macros are defined in the header file
<filename>cyg/hal/hal_diag.h</filename>. This file is usually supplied
by the variant or platform HAL, depending on where the IO device being
used is located. For example for on-chip UARTs it would be in the
variant HAL, but for a board-level LCD panel it would be in the
platform HAL.
</para>

</section>

<!-- }}} -->
<!-- {{{ SMP Support -->

<section id="hal-smp-support">
<TITLE>SMP Support</TITLE>

<para>
eCos contains support for limited Symmetric Multi-Processing
(SMP). This is only available on selected architectures and platforms.
</para>

<section>
<title>Target Hardware Limitations</title>

<para>
To allow a reasonable implementation of SMP, and to reduce the
disruption to the existing source base, a number of assumptions have
been made about the features of the target hardware.
</para>

<itemizedlist>
<listitem>
<para>
Modest multiprocessing. The typical number of CPUs supported is two
to four, with an upper limit around eight. While there are no
inherent limits in the code, hardware and algorithmic limitations
will probably become significant beyond this point.
</para>
</listitem>

<listitem>
<para>
SMP synchronization support. The hardware must supply a mechanism to
allow software on two CPUs to synchronize. This is normally provided
as part of the instruction set in the form of test-and-set,
compare-and-swap or load-link/store-conditional instructions. An
alternative approach is the provision of hardware semaphore
registers which can be used to serialize implementations of these
operations. Whatever hardware facilities are available, they are
used in eCos to implement spinlocks.
</para>
</listitem>

<listitem>
<para>
Coherent caches. It is assumed that no extra effort will be required
to access shared memory from any processor. This means that either
there are no caches, they are shared by all processors, or are
maintained in a coherent state by the hardware. It would be too
disruptive to the eCos sources if every memory access had to be
bracketed by cache load/flush operations. Any hardware that requires
this is not supported.
</para>
</listitem>

<listitem>
<para>
Uniform addressing. It is assumed that all memory that is
shared between CPUs is addressed at the same location from all
CPUs. Like non-coherent caches, dealing with CPU-specific address
translation is considered too disruptive to the eCos source
base. This does not, however, preclude systems with non-uniform
access costs for different CPUs.
</para>
</listitem>

<listitem>
<para>
Uniform device addressing. As with access to memory, it is assumed
that all devices are equally accessible to all CPUs. Since device
access is often made from thread contexts, it is not possible to
restrict access to device control registers to certain CPUs, since
there is currently no support for binding or migrating threads to CPUs.
</para>
</listitem>

<listitem>
<para>
Interrupt routing. The target hardware must have an interrupt
controller that can route interrupts to specific CPUs. It is
acceptable for all interrupts to be delivered to just one CPU, or
for some interrupts to be bound to specific CPUs, or for some
interrupts to be local to each CPU. At present dynamic routing,
where a different CPU may be chosen each time an interrupt is
delivered, is not supported. ECos cannot support hardware where all
interrupts are delivered to all CPUs simultaneously with the
expectation that software will resolve any conflicts.
</para>
</listitem>

<listitem>
<para>
Inter-CPU interrupts. A mechanism to allow one CPU to interrupt
another is needed. This is necessary so that events on one CPU can
cause rescheduling on other CPUs.
</para>
</listitem>

<listitem>
<para>
CPU Identifiers. Code running on a CPU must be able to determine
which CPU it is running on. The CPU Id is usually provided either in
a CPU status register, or in a register associated with the
inter-CPU interrupt delivery subsystem. ECos expects CPU Ids to be
small positive integers, although alternative representations, such
as bitmaps, can be converted relatively easily. Complex mechanisms
for getting the CPU Id cannot be supported. Getting the CPU Id must
be a cheap operation, since it is done often, and in performance
critical places such as interrupt handlers and the scheduler.
</para>
</listitem>
</itemizedlist>

</section>  

<section>
<title>HAL Support</title>

<para>
SMP support in any platform depends on the HAL supplying the
appropriate operations. All HAL SMP support is defined in the
<filename>cyg/hal/hal_smp.h</filename> header. Variant and platform
specific definitions will be in <filename>cyg/hal/var_smp.h</filename>
and <filename>cyg/hal/plf_smp.h</filename> respectively. These files
are include automatically by this header, so need not be included
explicitly.
</para>

<para>
SMP support falls into a number of functional groups.
</para>

<section>
<title>CPU Control</title>

<para>
This group consists of descriptive and control macros for managing the
CPUs in an SMP system.
</para>

<variablelist>
<varlistentry>
<term><literal>HAL_SMP_CPU_TYPE</literal></term>
<listitem>
<para>
A type that can contain a CPU id. A CPU id is
usually a small integer that is used to index
arrays of variables that are managed on an
per-CPU basis.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_MAX</literal></term>
<listitem>
<para>
The maximum number of CPUs that can be
supported. This is used to provide the size of
any arrays that have an element per CPU.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_COUNT()</literal></term>
<listitem>
<para>
Returns the number of CPUs currently
operational. This may differ from
HAL_SMP_CPU_MAX depending on the runtime
environment.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_THIS()</literal></term>
<listitem>
<para>
Returns the CPU id of the current CPU.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_NONE</literal></term>
<listitem>
<para>
A value that does not match any real CPU
id. This is uses where a CPU type variable
must be set to a null value.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_START( cpu )</literal></term>
<listitem>
<para>
Starts the given CPU executing at a defined
HAL entry point. After performing any HAL
level initialization, the CPU calls up into
the kernel at <function>cyg_kernel_cpu_startup()</function>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_RESCHEDULE_INTERRUPT( cpu, wait )</literal></term>
<listitem>
<para>
Sends the CPU a reschedule interrupt, and if
<parameter>wait</parameter> is non-zero, waits for an
acknowledgment. The interrupted CPU should call
<function>cyg_scheduler_set_need_reschedule()</function> in its DSR to
cause the reschedule to occur.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><literal>HAL_SMP_CPU_TIMESLICE_INTERRUPT( cpu, wait )</literal></term>
<listitem>
<para>
Sends the CPU a timeslice interrupt, and if
<parameter>wait</parameter> is non-zero, waits for an
acknowledgment. The interrupted CPU should call
<function>cyg_scheduler_timeslice_cpu()</function> to cause the
timeslice event to be processed.
</para>
</list