hal.sgml

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

      restore the previous state.
      </PARA>
      <note>
        <para>
	If this macro is called after
	<function>HAL_XCACHE_SYNC()</function> with the intention of clearing
	the cache (invalidating the cache after writing dirty data back to
	memory), you must prevent interrupts from happening between the two
	calls:
	</para>
<PROGRAMLISTING>
 ...
 HAL_DISABLE_INTERRUPTS(old);
 HAL_XCACHE_SYNC();
 HAL_XCACHE_INVALIDATE_ALL();
 HAL_RESTORE_INTERRUPTS(old);
 ...
</PROGRAMLISTING>
        <para>
	Since the operation may take a very long time, real-time
	responsiveness could be affected, so only do this when it is
	absolutely required and you know the delay will not interfere
	with the operation of drivers or the application.
	</para>
      </note>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_XCACHE_SYNC()</TERM>
    <LISTITEM>
      <PARA>
      Causes the contents of the cache to be brought into synchronization
      with the contents of memory. In some implementations this may be
      equivalent to <function>HAL_XCACHE_INVALIDATE_ALL()</function>.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_XCACHE_BURST_SIZE()</TERM>
    <LISTITEM>
      <PARA>
      Allows the size of cache to/from memory bursts to
      be controlled. This macro will only be defined if this functionality
      is available.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_WRITE_MODE()</TERM>
    <LISTITEM>
      <PARA>
      Controls the way in which data cache lines are written back to
      memory. There will be definitions for the possible
      modes. Typical definitions are
      <literal>HAL_DCACHE_WRITEBACK_MODE</literal> and
      <literal>HAL_DCACHE_WRITETHRU_MODE</literal>. This macro will
      only be defined if this functionality is available.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_XCACHE_LOCK()</TERM>
    <LISTITEM>
      <PARA>
      Causes data to be locked into the cache. The base and size
      arguments define the memory region that will be locked into the
      cache. It is architecture dependent whether more than one locked
      region is allowed at any one time, and whether this operation
      causes the cache to cease acting as a cache for addresses
      outside the region during the duration of the lock. This macro
      will only be defined if this functionality is available.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_XCACHE_UNLOCK()</TERM>
    <LISTITEM>
      <PARA>
      Cancels the locking of the memory region given. This should
      normally correspond to a region supplied in a matching lock
      call.  This macro will only be defined if this functionality is
      available.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>

  <VARLISTENTRY>
    <TERM>HAL_XCACHE_UNLOCK_ALL()</TERM>
    <LISTITEM>
      <PARA>
      Cancels all existing locked memory regions. This may be required
      as part of the cache initialization on some architectures. This
      macro will only be defined if this functionality is available.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

</SECTION>

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

<SECTION>
<TITLE>Cache Line Control</TITLE>

<PROGRAMLISTING>
HAL_DCACHE_ALLOCATE( base , size )
HAL_DCACHE_FLUSH( base , size )
HAL_XCACHE_INVALIDATE( base , size )
HAL_DCACHE_STORE( base , size )
HAL_DCACHE_READ_HINT( base , size )
HAL_DCACHE_WRITE_HINT( base , size )
HAL_DCACHE_ZERO( base , size )
</PROGRAMLISTING>

<PARA>
All of these macros apply a cache operation to all cache lines that
match the memory address region defined by the base and size
arguments. These macros will only be defined if the described
functionality is available. Also, it is not guaranteed that the cache
function will only be applied to just the described regions, in some
architectures it may be applied to the whole cache.
</PARA>

<VARIABLELIST>
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_ALLOCATE()</TERM>
    <LISTITEM>
      <PARA>
      Allocates lines in the cache for the given region without
      reading their contents from memory, hence the contents of the lines
      is undefined. This is useful for preallocating lines which are to
      be completely overwritten, for example in a block copy
      operation.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_FLUSH()</TERM>
    <LISTITEM>
      <PARA>
      Invalidates all cache lines in the region after writing any
      dirty lines to memory.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_XCACHE_INVALIDATE() </TERM>
    <LISTITEM>
      <PARA>
      Invalidates all cache lines in the region. Any dirty lines
      are invalidated without being written to memory.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_STORE() </TERM>
    <LISTITEM>
      <PARA>
      Writes all dirty lines in the region to memory, but does not
      invalidate any lines.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>HAL_DCACHE_READ_HINT() </TERM>
    <LISTITEM>
      <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 spin