hal.sgml

ecos实时嵌入式操作系统

range. In future other exceptions generated by the system software
(such as stack overflow) may be added.
</PARA>

<PARA>
<literal>CYGNUM_HAL_ISR_COUNT</literal>, <literal>CYGNUM_HAL_VSR_COUNT</literal> and
<literal>CYGNUM_HAL_EXCEPTION_COUNT</literal> define the number of
ISRs, VSRs and EXCEPTIONs respectively for the purposes of defining
arrays etc. There might be a translation from the supplied vector
numbers into array offsets. Hence
<literal>CYGNUM_HAL_XXX_COUNT</literal> may not simply be
<literal>CYGNUM_HAL_XXX_MAX</literal> - <literal>CYGNUM_HAL_XXX_MIN</literal> or <literal>CYGNUM_HAL_XXX_MAX</literal>&plus;1.
</PARA>

</SECTION>


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

<SECTION>
<TITLE>Interrupt state control</TITLE>

<PROGRAMLISTING>
CYG_INTERRUPT_STATE
HAL_DISABLE_INTERRUPTS( old )
HAL_RESTORE_INTERRUPTS( old )
HAL_ENABLE_INTERRUPTS()
HAL_QUERY_INTERRUPTS( state )
</PROGRAMLISTING>

<PARA>
These macros provide control over the state of the CPUs interrupt mask
mechanism. They should normally manipulate a CPU status register to
enable and disable interrupt delivery. They should not access an
interrupt controller.
</PARA>


<para>
<literal>CYG_INTERRUPT_STATE</literal> is a data type that should be
used to store the interrupt state returned by
<function>HAL_DISABLE_INTERRUPTS()</function> and
<function>HAL_QUERY_INTERRUPTS()</function> and passed to
<function>HAL_RESTORE_INTERRUPTS()</function>.
</para>

<PARA>
<FUNCTION>HAL_DISABLE_INTERRUPTS()</FUNCTION> disables the delivery of
interrupts and stores the original state of the interrupt mask in the
variable passed in the <parameter>old</parameter> argument.
</PARA>

<PARA>
<FUNCTION>HAL_RESTORE_INTERRUPTS()</FUNCTION> restores the state of
the interrupt mask to that recorded in <parameter>old</parameter>.
</PARA>

<PARA>
<FUNCTION>HAL_ENABLE_INTERRUPTS()</FUNCTION> simply enables interrupts
regardless of the current state of the mask.
</PARA>

<PARA>
<FUNCTION>HAL_QUERY_INTERRUPTS()</FUNCTION> stores the state of the
interrupt mask in the variable passed in the <parameter>
state</parameter> argument. The state stored here should also be
capable of being passed to
<function>HAL_RESTORE_INTERRUPTS()</function> at a later point.
</PARA>

<PARA>
It is at the HAL implementer&rsquo;s discretion exactly
which interrupts are masked by this mechanism. Where a CPU has more
than one interrupt type that may be masked separately (e.g. the
ARM's IRQ and FIQ) only those that can raise DSRs need
to be masked here. A separate architecture specific mechanism may
then be used to control the other interrupt types.
</PARA>

</SECTION>

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

<SECTION>
<TITLE>ISR and VSR management</TITLE>

<PROGRAMLISTING>
HAL_INTERRUPT_IN_USE( vector, state )
HAL_INTERRUPT_ATTACH( vector, isr, data, object )
HAL_INTERRUPT_DETACH( vector, isr )
HAL_VSR_SET( vector, vsr, poldvsr )
HAL_VSR_GET( vector, pvsr )
HAL_VSR_SET_TO_ECOS_HANDLER( vector, poldvsr )
</PROGRAMLISTING>

<PARA>
These macros manage the attachment of interrupt and vector service
routines to interrupt and exception vectors respectively.
</PARA>

<para>
<function>HAL_INTERRUPT_IN_USE()</function> tests the state of the
supplied interrupt vector and sets the value of the state parameter to
either 1 or 0 depending on whether there is already an ISR attached to
the vector. The HAL will only allow one ISR to be attached to each
vector, so it is a good idea to use this function before using
<function>HAL_INTERRUPT_ATTACH()</function>.
</para>

<PARA>
<FUNCTION>HAL_INTERRUPT_ATTACH()</FUNCTION> attaches
the ISR, data pointer and object pointer to the given
<parameter>vector</parameter>. When an interrupt occurs on this
vector the ISR is called using the C calling convention and the vector
number and data pointer are passed to it as the first and second
arguments respectively.
</PARA>

<PARA>
<FUNCTION>HAL_INTERRUPT_DETACH()</FUNCTION> detaches the ISR from the
vector.
</PARA>

<PARA>
<FUNCTION>HAL_VSR_SET()</FUNCTION> replaces the VSR attached to the
<parameter>vector</parameter> with the replacement supplied in
<parameter>vsr</parameter>. The old VSR is returned in the location
pointed to by <parameter>pvsr</parameter>.
</PARA>

<PARA>
<FUNCTION>HAL_VSR_GET()</FUNCTION> assigns
a copy of the VSR to the location pointed to by <parameter>pvsr</parameter>.
</PARA>

<para>
<function>HAL_VSR_SET_TO_ECOS_HANDLER()</function> ensures that the
VSR for a specific exception is pointing at the eCos exception VSR and
not one for RedBoot or some other ROM monitor. The default when
running under RedBoot is for exceptions to be handled by RedBoot and
passed to GDB. This macro diverts the exception to eCos so that it may
be handled by application code. The arguments are the VSR vector to be
replaces, and a location in which to store the old VSR pointer, so
that it may be replaced at a later point.
</para>

</SECTION>

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

<SECTION>
<TITLE>Interrupt controller management</TITLE>

<PROGRAMLISTING>
HAL_INTERRUPT_MASK( vector )
HAL_INTERRUPT_UNMASK( vector )
HAL_INTERRUPT_ACKNOWLEDGE( vector )
HAL_INTERRUPT_CONFIGURE( vector, level, up )
HAL_INTERRUPT_SET_LEVEL( vector, level )
</PROGRAMLISTING>

<PARA>
These macros exert control over any prioritized interrupt
controller that is present. If no priority controller exists, then
these macros should be empty.
</para>

<note>
  <para>
  These macros may not be reentrant, so care should be taken to
  prevent them being called while interrupts are enabled. This means
  that they can be safely used in initialization code before
  interrupts are enabled, and in ISRs. In DSRs, ASRs and thread code,
  however, interrupts must be disabled before these macros are
  called. Here is an example for use in a DSR where the interrupt
  source is unmasked after data processing:
  </para>
<PROGRAMLISTING>
 ...
 HAL_DISABLE_INTERRUPTS(old);
 HAL_INTERRUPT_UNMASK(CYGNUM_HAL_INTERRUPT_ETH);
 HAL_RESTORE_INTERRUPTS(old);
 ...
</PROGRAMLISTING>
</note>

<PARA>
<FUNCTION>HAL_INTERRUPT_MASK()</FUNCTION> causes the interrupt
associated with the given vector to be blocked.
</PARA>

<PARA>
<FUNCTION>HAL_INTERRUPT_UNMASK()</FUNCTION> causes the interrupt
associated with the given vector to be unblocked.
</PARA>

<PARA>
<FUNCTION>HAL_INTERRUPT_ACKNOWLEDGE()</FUNCTION> acknowledges the
current interrupt from the given vector. This is usually executed from
the ISR for this vector when it is prepared to allow further
interrupts.  Most interrupt controllers need some form of acknowledge
action before the next interrupt is allowed through. Executing this
macro may cause another interrupt to be delivered. Whether this
interrupts the current code depends on the state of the CPU interrupt
mask.
</PARA>

<PARA>
<FUNCTION>HAL_INTERRUPT_CONFIGURE()</FUNCTION> provides
control over how an interrupt signal is detected. The arguments
are:
</PARA>
<VARIABLELIST>
  <VARLISTENTRY>
    <TERM>vector</TERM>
    <LISTITEM>
      <PARA>The interrupt vector to be configured.</PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>level</TERM>
    <LISTITEM>
      <PARA>
      Set to <varname>true</varname> if the interrupt is detected by
      level, and <varname>false</varname> if it is edge triggered.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>up</TERM>
    <LISTITEM>
      <PARA>
      If the interrupt is set to level detect, then if this is
      <VARNAME>true</VARNAME> it is detected by a high signal level,
      and if <VARNAME>false</VARNAME> by a low signal level. If the
      interrupt is set to edge triggered, then if this is
      <VARNAME>true</VARNAME> it is triggered by a rising edge and if
      <VARNAME>false</VARNAME> by a falling edge.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

<PARA>
<FUNCTION>HAL_INTERRUPT_SET_LEVEL()</FUNCTION> provides control over
the hardware priority of the interrupt. The arguments are:
</PARA>

<VARIABLELIST>
  <VARLISTENTRY>
    <TERM>vector</TERM>
    <LISTITEM>
      <PARA>The interrupt whose level is to be set.</PARA>
    </LISTITEM>
  </VARLISTENTRY>
  
  <VARLISTENTRY>
    <TERM>level</TERM>
    <LISTITEM>
      <PARA>
      The priority level to which the interrupt is to set. In some
      architectures the masking of an interrupt is achieved by
      changing its priority level. Hence this function,
      <FUNCTION>HAL_INTERRUPT_MASK()</FUNCTION> and
      <FUNCTION>HAL_INTERRUPT_UNMASK()</FUNCTION> may interfere with
      each other.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

</SECTION>

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

<SECTION>
<TITLE>Clock control</TITLE>

<PROGRAMLISTING>
HAL_CLOCK_INITIALIZE( period )
HAL_CLOCK_RESET( vector, period )
HAL_CLOCK_READ( pvalue )
</PROGRAMLISTING>

<PARA>
These macros provide control over a clock or timer device that may be
used by the kernel to provide time-out, delay and scheduling
services. The clock is assumed to be implemented by some form of
counter that is incremented or decremented by some external source and
which raises an interrupt when it reaches a predetermined value.
</PARA>

<PARA>
<FUNCTION>HAL_CLOCK_INITIALIZE()</FUNCTION> initializes the timer
device to interrupt at the given period. The period is essentially the
value used to initialize the timer counter and must be calculated from
the timer frequency and the desired interrupt rate. The timer device
should generate an interrupt every <varname>period</varname> cycles.
</PARA>

<PARA>
<FUNCTION>HAL_CLOCK_RESET()</FUNCTION> re-initializes the timer to
provoke the next interrupt. This macro is only really necessary when
the timer device needs to be reset in some way after each interrupt.
</PARA>

<PARA>
<FUNCTION>HAL_CLOCK_READ()</FUNCTION> reads the current value of the
timer counter and puts the value in the location pointed to by
<parameter>pvalue</parameter>. The value stored will always be the
number of timer cycles since the last interrupt, and hence ranges
between zero and the initial period value. If this is a count-down
cyclic timer, some arithmetic may be necessary to generate this value.
</PARA>

</SECTION>

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

<section>
<title>Microsecond Delay</title>

<programlisting width=72>
HAL_DELAY_US(us)
</programlisting>

<para>
This is an optional definition. If defined the macro implements a busy
loop delay for the given number of microseconds. This is usually
implemented by waiting for the required number of hardware timer ticks
to pass. 
</para>

<para>
This operation should normally be used when a very short delay is
needed when controlling hardware, programming FLASH devices and similar
situations where a wait/timeout loop would otherwise be used. Since it
may disable interrupts, and is implemented by busy waiting, it should
not be used in code that is sensitive to interrupt or context switch
latencies.
</para>

</section>

</SECTION>

<!-- }}} -->
<!-- {{{ Input and Output -->

<SECTION id="hal-input-and-output">
<TITLE>HAL I/O</TITLE>

<PARA>
This section contains definitions for supporting access
to device control registers in an architecture neutral
fashion.
</PARA>

<para>
These definitions are normally found in the header file
<FILENAME>cyg/hal/hal_io.h</FILENAME>.  This file itself contains
macros that are generic to the architecture. If there are variant or
platform specific IO access macros then these will be found in
<filename>cyg/hal/var_io.h</filename> and
<filename>cyg/hal/plf_io.h</filename> in the variant or platform HALs
respectively. These files are include automatically by this header, so
need not be included explicitly.
</para>

<para>
This header (or more likely <filename>cyg/hal/plf_io.h</filename>) also
defines the PCI access macros. For more information on these see <xref
linkend="pci-library-reference">.
</para>

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

<SECTION>
<TITLE>Register address</TITLE>

<PROGRAMLISTING>
HAL_IO_REGISTER
</PROGRAMLISTING>

<PARA>
This type is used to store the address of an I/O register. It will
normally be a memory address, an integer port address or an offset
into an I/O space. More complex architectures may need to code an
address space plus offset pair into a single word, or may represent it
as a structure.
</PARA>

<PARA>
Values of variables and constants of this type will usually be
supplied by configuration mechanisms or in target specific headers.
</PARA>

</SECTION>

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

<SECTION>
<TITLE>Register read</TITLE>

<PROGRAMLISTING>