--- /dev/null
+<!-- Copyright (C) 2003 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 is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>Architecture Characterization</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE="HAL Interfaces"
+HREF="hal-interfaces.html"><LINK
+REL="PREVIOUS"
+TITLE="HAL Interfaces"
+HREF="hal-interfaces.html"><LINK
+REL="NEXT"
+TITLE="Interrupt Handling"
+HREF="hal-interrupt-handling.html"></HEAD
+><BODY
+CLASS="SECTION"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="hal-interfaces.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 9. HAL Interfaces</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="hal-interrupt-handling.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="HAL-ARCHITECTURE-CHARACTERIZATION">Architecture Characterization</H1
+><P
+>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.</P
+><P
+>Most of these definition are found in
+<TT
+CLASS="FILENAME"
+>cyg/hal/hal_arch.h</TT
+>. This file is supplied by the
+architecture HAL. If there are variant or platform specific
+definitions then these will be found in
+<TT
+CLASS="FILENAME"
+>cyg/hal/var_arch.h</TT
+> or
+<TT
+CLASS="FILENAME"
+>cyg/hal/plf_arch.h</TT
+>. These files are include
+automatically by this header, so need not be included explicitly.</P
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7787">Register Save Format</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>typedef struct HAL_SavedRegisters
+{
+ /* architecture-dependent list of registers to be saved */
+} HAL_SavedRegisters;</PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7791">Thread Context Initialization</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_THREAD_INIT_CONTEXT( sp, arg, entry, id )</PRE
+></TD
+></TR
+></TABLE
+><P
+>This macro initializes a thread's context so that
+it may be switched to by <TT
+CLASS="FUNCTION"
+>HAL_THREAD_SWITCH_CONTEXT()</TT
+>.
+The arguments are:</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>sp</DT
+><DD
+><P
+> 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.
+ </P
+></DD
+><DT
+>arg</DT
+><DD
+><P
+> A value that is passed as the first argument to the entry
+ point function.
+ </P
+></DD
+><DT
+>entry</DT
+><DD
+><P
+> The address of an entry point function. This will be called
+ according the C calling conventions, and the value of
+ <TT
+CLASS="PARAMETER"
+><I
+>arg</I
+></TT
+> will be passed as the first
+ argument. This function should have the following type signature
+ <TT
+CLASS="FUNCTION"
+>void entry(CYG_ADDRWORD arg)</TT
+>.
+ </P
+></DD
+><DT
+>id</DT
+><DD
+><P
+> 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.
+ </P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="HAL-CONTEXT-SWITCH">Thread Context Switching</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_THREAD_LOAD_CONTEXT( to )
+HAL_THREAD_SWITCH_CONTEXT( from, to )</PRE
+></TD
+></TR
+></TABLE
+><P
+>These macros implement the thread switch code. The arguments are:</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>from</DT
+><DD
+><P
+> A pointer to a location where the stack pointer of the current
+ thread will be stored.
+ </P
+></DD
+><DT
+>to</DT
+><DD
+><P
+> A pointer to a location from where the stack pointer of the next
+ thread will be read.
+ </P
+></DD
+></DL
+></DIV
+><P
+>For <TT
+CLASS="FUNCTION"
+>HAL_THREAD_LOAD_CONTEXT()</TT
+> 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.</P
+><P
+>For <TT
+CLASS="FUNCTION"
+>HAL_THREAD_SWITCH_CONTEXT()</TT
+> 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
+<TT
+CLASS="PARAMETER"
+><I
+>*from</I
+></TT
+>. The value in
+<TT
+CLASS="PARAMETER"
+><I
+>*to</I
+></TT
+> is then read and the state of the new
+thread is loaded from it.</P
+><P
+>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.</P
+><P
+>The implementation of <TT
+CLASS="FUNCTION"
+>HAL_THREAD_SWITCH_CONTEXT()</TT
+>
+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
+<TT
+CLASS="LITERAL"
+>CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM</TT
+> controls
+how many registers are saved.</P
+><P
+>The implementation of <TT
+CLASS="FUNCTION"
+>HAL_THREAD_LOAD_CONTEXT()</TT
+>
+loads a thread context, destroying the current context. With a little
+care this can be implemented by sharing code with
+<TT
+CLASS="FUNCTION"
+>HAL_THREAD_SWITCH_CONTEXT()</TT
+>. 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.</P
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7842">Bit indexing</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_LSBIT_INDEX( index, mask )
+HAL_MSBIT_INDEX( index, mask )</PRE
+></TD
+></TR
+></TABLE
+><P
+>These macros place in <TT
+CLASS="PARAMETER"
+><I
+>index</I
+></TT
+> the bit index of
+the least significant bit in <TT
+CLASS="PARAMETER"
+><I
+>mask</I
+></TT
+>. 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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7848">Idle thread activity</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_IDLE_THREAD_ACTION( count )</PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7852">Reorder barrier</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_REORDER_BARRIER()</PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7856">Breakpoint support</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_BREAKPOINT( label )
+HAL_BREAKINST
+HAL_BREAKINST_SIZE</PRE
+></TD
+></TR
+></TABLE
+><P
+>These macros provide support for breakpoints.</P
+><P
+><TT
+CLASS="FUNCTION"
+>HAL_BREAKPOINT()</TT
+> executes a breakpoint
+instruction. The label is defined at the breakpoint instruction so
+that exception code can detect which breakpoint was executed.</P
+><P
+><TT
+CLASS="LITERAL"
+>HAL_BREAKINST</TT
+> contains the breakpoint instruction
+code as an integer value. <TT
+CLASS="LITERAL"
+>HAL_BREAKINST_SIZE</TT
+> is
+the size of that breakpoint instruction in bytes. Together these
+may be used to place a breakpoint in any code.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7865">GDB support</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>HAL_THREAD_GET_SAVED_REGISTERS( sp, regs )
+HAL_GET_GDB_REGISTERS( regval, regs )
+HAL_SET_GDB_REGISTERS( regs, regval )</PRE
+></TD
+></TR
+></TABLE
+><P
+>These macros provide support for interfacing GDB to the HAL.</P
+><P
+><TT
+CLASS="FUNCTION"
+>HAL_THREAD_GET_SAVED_REGISTERS()</TT
+> extracts a
+pointer to a <SPAN
+CLASS="STRUCTNAME"
+>HAL_SavedRegisters</SPAN
+> 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 <SPAN
+CLASS="STRUCTNAME"
+>HAL_SavedRegisters</SPAN
+> structure
+to the variable passed as the second argument.</P
+><P
+><TT
+CLASS="FUNCTION"
+>HAL_GET_GDB_REGISTERS()</TT
+> 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
+<SPAN
+CLASS="STRUCTNAME"
+>HAL_SavedRegisters</SPAN
+> structure in the
+<TT
+CLASS="PARAMETER"
+><I
+>regs</I
+></TT
+> argument and a pointer to the memory to
+contain the GDB register dump in the <TT
+CLASS="PARAMETER"
+><I
+>regval</I
+></TT
+>
+argument.</P
+><P
+><TT
+CLASS="FUNCTION"
+>HAL_SET_GDB_REGISTERS()</TT
+> 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
+<TT
+CLASS="PARAMETER"
+><I
+>regval</I
+></TT
+> argument and a pointer to a
+<SPAN
+CLASS="STRUCTNAME"
+>HAL_SavedRegisters</SPAN
+> structure
+in the <TT
+CLASS="PARAMETER"
+><I
+>regs</I
+></TT
+> argument.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7883">Setjmp and longjmp support</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="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 )</PRE
+></TD
+></TR
+></TABLE
+><P
+>These functions provide support for the C
+<TT
+CLASS="FUNCTION"
+>setjmp()</TT
+> and <TT
+CLASS="FUNCTION"
+>longjmp()</TT
+>
+functions. Refer to the C library for further information.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7889">Stack Sizes</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>CYGNUM_HAL_STACK_SIZE_MINIMUM
+CYGNUM_HAL_STACK_SIZE_TYPICAL</PRE
+></TD
+></TR
+></TABLE
+><P
+>The values of these macros define the minimum and typical sizes of
+thread stacks.</P
+><P
+><TT
+CLASS="LITERAL"
+>CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
+> 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
+<TT
+CLASS="LITERAL"
+>CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
+>.</P
+><P
+><TT
+CLASS="LITERAL"
+>CYGNUM_HAL_STACK_SIZE_TYPICAL</TT
+> is a reasonable increment over
+<TT
+CLASS="LITERAL"
+>CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
+>, 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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7899">Address Translation</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>CYGARC_CACHED_ADDRESS(addr)
+CYGARC_UNCACHED_ADDRESS(addr)
+CYGARC_PHYSICAL_ADDRESS(addr)</PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+><P
+><TT
+CLASS="FUNCTION"
+>CYGARC_CACHED_ADDRESS()</TT
+> translates the given
+address to its location in cached memory. This is typically where the
+application will access the memory.</P
+><P
+><TT
+CLASS="FUNCTION"
+>CYGARC_UNCACHED_ADDRESS()</TT
+> 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.</P
+><P
+><TT
+CLASS="FUNCTION"
+>CYGARC_PHYSICAL_ADDRESS()</TT
+> 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.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN7909">Global Pointer</H2
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>CYGARC_HAL_SAVE_GP()
+CYGARC_HAL_RESTORE_GP()</PRE
+></TD
+></TR
+></TABLE
+><P
+>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.</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="hal-interfaces.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="hal-interrupt-handling.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>HAL Interfaces</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="hal-interfaces.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Interrupt Handling</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff