hal.sgml

ecos实时嵌入式操作系统

      thread will be stored.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
  <VARLISTENTRY>
    <TERM>to</TERM>
    <LISTITEM>
      <PARA>
      A pointer to a location from where the stack pointer of the next
      thread will be read.
      </PARA>
    </LISTITEM>
  </VARLISTENTRY>
</VARIABLELIST>

<para>
For <function>HAL_THREAD_LOAD_CONTEXT()</function> the current CPU
state is discarded and the state of the destination thread is
loaded. This is only used once, to load the first thread when the
scheduler is started.
</para>

<PARA>
For <function>HAL_THREAD_SWITCH_CONTEXT()</function> the state of the
current thread is saved onto its stack, using the current value of the
stack pointer, and the address of the saved state placed in
<parameter>*from</parameter>.  The value in
<parameter>*to</parameter> is then read and the state of the new
thread is loaded from it.
</PARA>

<para>
While these two operations may be implemented with inline assembler,
they are normally implemented as calls to assembly code functions in
the HAL. There are two advantages to doing it this way. First, the
return link of the call provides a convenient PC value to be used in
the saved context. Second, the calling conventions mean that the
compiler will have already saved the caller-saved registers before the
call, so the HAL need only save the callee-saved registers.
</para>

<para>
The implementation of <function>HAL_THREAD_SWITCH_CONTEXT()</function>
saves the current CPU state on the stack, including the current
interrupt state (or at least the register that contains it). For
debugging purposes it is useful to save the entire register set, but
for performance only the ABI-defined callee-saved registers need be
saved. If it is implemented, the option
<literal>CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM</literal> controls
how many registers are saved.
</para>

<para>
The implementation of <function>HAL_THREAD_LOAD_CONTEXT()</function>
loads a thread context, destroying the current context. With a little
care this can be implemented by sharing code with
<function>HAL_THREAD_SWITCH_CONTEXT()</function>. To load a thread
context simply requires the saved registers to be restored from the
stack and a jump or return made back to the saved PC.
</para>

<PARA>
Note that interrupts are not disabled during this process, any
interrupts that occur will be delivered onto the stack to which the
current CPU stack pointer points. Hence the stack pointer
should never be invalid, or loaded with a value that might cause the
saved state to become corrupted by an interrupt. However, the current
interrupt state is saved and restored as part of the thread
context. If a thread disables interrupts and does something to cause a
context switch, interrupts may be re-enabled on switching to another
thread. Interrupts will be disabled again when the original thread
regains control.
</PARA>

</SECTION>

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

<SECTION>
<TITLE>Bit indexing</TITLE>

<PROGRAMLISTING>
HAL_LSBIT_INDEX( index, mask )
HAL_MSBIT_INDEX( index, mask )
</PROGRAMLISTING>

<PARA>
These macros place in <parameter>index</parameter> the bit index of
the least significant bit in <parameter>mask</parameter>. Some
architectures have instruction level support for one or other of these
operations. If no architectural support is available, then these
macros may call C functions to do the job.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>Idle thread activity</TITLE>

<PROGRAMLISTING>
HAL_IDLE_THREAD_ACTION( count )
</PROGRAMLISTING>

<PARA>
It may be necessary under some circumstances for the HAL to execute
code in the kernel idle thread's loop. An example might be to execute
a processor halt instruction. This macro provides a portable way of
doing this. The argument is a copy of the idle thread's loop counter,
and may be used to trigger actions at longer intervals than every
loop.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>Reorder barrier</TITLE>

<PROGRAMLISTING>
HAL_REORDER_BARRIER()
</PROGRAMLISTING>

<PARA>
When optimizing the compiler can reorder code. In some parts of
multi-threaded systems, where the order of actions is vital, this can
sometimes cause problems. This macro may be inserted into places where
reordering should not happen and prevents code being migrated across
it by the compiler optimizer. It should be placed between statements
that must be executed in the order written in the code.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>Breakpoint support</TITLE>

<PROGRAMLISTING>
HAL_BREAKPOINT( label )
HAL_BREAKINST
HAL_BREAKINST_SIZE
</PROGRAMLISTING>

<PARA>
These macros provide support for breakpoints.
</PARA>

<PARA>
<FUNCTION>HAL_BREAKPOINT()</FUNCTION> executes a breakpoint
instruction. The label is defined at the breakpoint instruction so
that exception code can detect which breakpoint was executed.
</PARA>

<PARA>
<literal>HAL_BREAKINST</literal> contains the breakpoint instruction
code as an integer value. <literal>HAL_BREAKINST_SIZE</literal> is
the size of that breakpoint instruction in bytes. Together these
may be used to place a breakpoint in any code.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>GDB support</TITLE>

<PROGRAMLISTING>
HAL_THREAD_GET_SAVED_REGISTERS( sp, regs )
HAL_GET_GDB_REGISTERS( regval, regs )
HAL_SET_GDB_REGISTERS( regs, regval )
</PROGRAMLISTING>

<PARA>
These macros provide support for interfacing GDB to the HAL.
</PARA>

<PARA>
<FUNCTION>HAL_THREAD_GET_SAVED_REGISTERS()</FUNCTION> extracts a
pointer to a <STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
from a stack pointer value. The stack pointer passed in should be the
value saved by the thread context macros. The macro will assign a
pointer to the <STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
to the variable passed as the second argument.
</PARA>

<PARA>
<FUNCTION>HAL_GET_GDB_REGISTERS()</FUNCTION> translates a register
state as saved by the HAL and into a register dump in the format
expected by GDB. It takes a pointer to a
<STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure in the
<parameter>regs</parameter> argument and a pointer to the memory to
contain the GDB register dump in the <parameter>regval</parameter>
argument.
</PARA>

<PARA>
<FUNCTION>HAL_SET_GDB_REGISTERS()</FUNCTION> translates a GDB format
register dump into a the format expected by the HAL.  It takes a
pointer to the memory containing the GDB register dump in the
<parameter>regval</parameter> argument and a pointer to a
<STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
in the <parameter>regs</parameter> argument.
</PARA>
</SECTION>

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

<SECTION>
<TITLE>Setjmp and longjmp support</TITLE>

<PROGRAMLISTING>
CYGARC_JMP_BUF_SIZE
hal_jmp_buf[CYGARC_JMP_BUF_SIZE]
hal_setjmp( hal_jmp_buf env )
hal_longjmp( hal_jmp_buf env, int val )
</PROGRAMLISTING>

<PARA>
These functions provide support for the C
<FUNCTION>setjmp()</FUNCTION> and <FUNCTION>longjmp()</FUNCTION>
functions.  Refer to the C library for further information.
</PARA>

</SECTION>

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

<section>
<title>Stack Sizes</title>
<programlisting>
CYGNUM_HAL_STACK_SIZE_MINIMUM
CYGNUM_HAL_STACK_SIZE_TYPICAL
</programlisting>

<para>
The values of these macros define the minimum and typical sizes of
thread stacks.
</para>

<para>
<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal> defines the minimum
size of a thread stack. This is enough for the thread to function
correctly within eCos and allows it to take interrupts and context
switches. There should also be enough space for a simple thread entry
function to execute and call basic kernel operations on objects like
mutexes and semaphores. However there will not be enough room for much
more than this. When creating stacks for their own threads,
applications should determine the stack usage needed for application
purposes and then add
<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal>.
</para>

<para>
<literal>CYGNUM_HAL_STACK_SIZE_TYPICAL</literal> is a reasonable increment over
<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal>, usually about 1kB. This should be
adequate for most modest thread needs. Only threads that need to
define significant amounts of local data, or have very deep call trees
should need to use a larger stack size.
</para>

</section>


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

<section>
<title>Address Translation</title>

<programlisting>
CYGARC_CACHED_ADDRESS(addr)
CYGARC_UNCACHED_ADDRESS(addr)
CYGARC_PHYSICAL_ADDRESS(addr)
</programlisting>

<para>
These macros provide address translation between different views of
memory. In many architectures a given memory location may be visible
at different addresses in both cached and uncached forms. It is also
possible that the MMU or some other address translation unit in the
CPU presents memory to the program at a different virtual address to
its physical address on the bus.
</para>

<para>
<function>CYGARC_CACHED_ADDRESS()</function> translates the given
address to its location in cached memory. This is typically where the
application will access the memory.
</para>

<para>
<function>CYGARC_UNCACHED_ADDRESS()</function> translates the given
address to its location in uncached memory. This is typically where
device drivers will access the memory to avoid cache problems. It may
additionally be necessary for the cache to be flushed before the
contents of this location is fully valid.
</para>

<para>
<function>CYGARC_PHYSICAL_ADDRESS()</function> translates the given
address to its location in the physical address space. This is
typically the address that needs to be passed to device hardware such
as a DMA engine, ethernet device or PCI bus bridge. The physical
address may not be directly accessible to the program, it may be
re-mapped by address translation.
</para>

</section>


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

<section>
<title>Global Pointer</title>

<programlisting>
CYGARC_HAL_SAVE_GP()
CYGARC_HAL_RESTORE_GP()
</programlisting>

<para>
These macros insert code to save and restore any global data pointer
that the ABI uses. These are necessary when switching context between
two eCos instances - for example between an eCos application and
RedBoot.
</para>

</section>

</SECTION>

<!-- }}} -->
<!-- {{{ Interrupt Handling -->

<SECTION id="hal-interrupt-handling">
<TITLE>Interrupt Handling</TITLE>

<para>
These interfaces contain definitions related to interrupt
handling. They include definitions of exception and interrupt numbers,
interrupt enabling and masking, and realtime clock operations.
</para>

<PARA>
These definitions are normally found in
<FILENAME>cyg/hal/hal_intr.h</FILENAME>.  This file is supplied by the
architecture HAL.  Any variant or platform specific definitions will
be found in <filename>cyg/hal/var_intr.h</filename>,
<filename>cyg/hal/plf_intr.h</filename> or
<filename>cyg/hal/hal_platform_ints.h</filename> in the variant or platform
HAL, depending on the exact target. These files are include
automatically by this header, so need not be included explicitly.
</PARA>

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

<SECTION>
<TITLE>Vector numbers</TITLE>

<PROGRAMLISTING>
CYGNUM_HAL_VECTOR_XXXX
CYGNUM_HAL_VSR_MIN
CYGNUM_HAL_VSR_MAX
CYGNUM_HAL_VSR_COUNT

CYGNUM_HAL_INTERRUPT_XXXX
CYGNUM_HAL_ISR_MIN
CYGNUM_HAL_ISR_MAX
CYGNUM_HAL_ISR_COUNT

CYGNUM_HAL_EXCEPTION_XXXX
CYGNUM_HAL_EXCEPTION_MIN
CYGNUM_HAL_EXCEPTION_MAX
CYGNUM_HAL_EXCEPTION_COUNT
</PROGRAMLISTING>

<PARA>
All possible VSR, interrupt and exception vectors are specified here,
together with maximum and minimum values for range checking. While the
VSR and exception numbers will be defined in this file, the interrupt
numbers will normally be defined in the variant or platform HAL file
that is included by this header. 
</PARA>

<PARA>
There are two ranges of numbers, those for the vector service
routines and those for the interrupt service routines. The relationship
between these two ranges is undefined, and no equivalence should
be assumed if vectors from the two ranges coincide.
</PARA>

<PARA>
The VSR vectors correspond to the set of exception vectors that can be
delivered by the CPU architecture, many of these will be internal
exception traps. The ISR vectors correspond to the set of external
interrupts that can be delivered and are usually determined by extra
decoding of the interrupt controller by the interrupt VSR.
</PARA>

<PARA>
Where a CPU supports synchronous exceptions, the range of such
exceptions allowed are defined by <literal>CYGNUM_HAL_EXCEPTION_MIN</literal> and
<literal>CYGNUM_HAL_EXCEPTION_MAX</literal>. The
<literal>CYGNUM_HAL_EXCEPTION_XXXX</literal> definitions are
standard names used by target independent code to test for the
presence of particular exceptions in the architecture. The actual
exception numbers will normally correspond to the VSR exception