1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Architecture Characterization</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="HAL Interfaces"
23 HREF="hal-interfaces.html"><LINK
25 TITLE="HAL Interfaces"
26 HREF="hal-interfaces.html"><LINK
28 TITLE="Interrupt Handling"
29 HREF="hal-interrupt-handling.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="hal-interfaces.html"
65 >Chapter 9. HAL Interfaces</TD
71 HREF="hal-interrupt-handling.html"
85 NAME="HAL-ARCHITECTURE-CHARACTERIZATION">Architecture Characterization</H1
87 >These are definition that are related to the basic architecture of the
88 CPU. These include the CPU context save format, context switching, bit
89 twiddling, breakpoints, stack sizes and address translation.</P
91 >Most of these definition are found in
94 >cyg/hal/hal_arch.h</TT
95 >. This file is supplied by the
96 architecture HAL. If there are variant or platform specific
97 definitions then these will be found in
100 >cyg/hal/var_arch.h</TT
104 >cyg/hal/plf_arch.h</TT
105 >. These files are include
106 automatically by this header, so need not be included explicitly.</P
112 NAME="AEN7787">Register Save Format</H2
120 CLASS="PROGRAMLISTING"
121 >typedef struct HAL_SavedRegisters
123 /* architecture-dependent list of registers to be saved */
124 } HAL_SavedRegisters;</PRE
129 >This structure describes the layout of a saved machine state on the
130 stack. Such states are saved during thread context switches,
131 interrupts and exceptions. Different quantities of state may be saved
132 during each of these, but usually a thread context state is a subset
133 of the interrupt state which is itself a subset of an exception state.
134 For debugging purposes, the same structure is used for all three
135 purposes, but where these states are significantly different, this
136 structure may contain a union of the three states.</P
143 NAME="AEN7791">Thread Context Initialization</H2
151 CLASS="PROGRAMLISTING"
152 >HAL_THREAD_INIT_CONTEXT( sp, arg, entry, id )</PRE
157 >This macro initializes a thread's context so that
158 it may be switched to by <TT
160 >HAL_THREAD_SWITCH_CONTEXT()</TT
162 The arguments are:</P
172 > A location containing the current value of the thread's stack
173 pointer. This should be a variable or a structure field. The SP
174 value will be read out of here and an adjusted value written
182 > A value that is passed as the first argument to the entry
190 > The address of an entry point function. This will be called
191 according the C calling conventions, and the value of
197 > will be passed as the first
198 argument. This function should have the following type signature
201 >void entry(CYG_ADDRWORD arg)</TT
209 > A thread id value. This is only used for debugging purposes,
210 it is ORed into the initialization pattern for unused registers
211 and may be used to help identify the thread from its register dump.
212 The least significant 16 bits of this value should be zero to allow
213 space for a register identifier.
224 NAME="HAL-CONTEXT-SWITCH">Thread Context Switching</H2
232 CLASS="PROGRAMLISTING"
233 >HAL_THREAD_LOAD_CONTEXT( to )
234 HAL_THREAD_SWITCH_CONTEXT( from, to )</PRE
239 >These macros implement the thread switch code. The arguments are:</P
249 > A pointer to a location where the stack pointer of the current
250 thread will be stored.
257 > A pointer to a location from where the stack pointer of the next
266 >HAL_THREAD_LOAD_CONTEXT()</TT
268 state is discarded and the state of the destination thread is
269 loaded. This is only used once, to load the first thread when the
270 scheduler is started.</P
274 >HAL_THREAD_SWITCH_CONTEXT()</TT
276 current thread is saved onto its stack, using the current value of the
277 stack pointer, and the address of the saved state placed in
289 > is then read and the state of the new
290 thread is loaded from it.</P
292 >While these two operations may be implemented with inline assembler,
293 they are normally implemented as calls to assembly code functions in
294 the HAL. There are two advantages to doing it this way. First, the
295 return link of the call provides a convenient PC value to be used in
296 the saved context. Second, the calling conventions mean that the
297 compiler will have already saved the caller-saved registers before the
298 call, so the HAL need only save the callee-saved registers.</P
300 >The implementation of <TT
302 >HAL_THREAD_SWITCH_CONTEXT()</TT
304 saves the current CPU state on the stack, including the current
305 interrupt state (or at least the register that contains it). For
306 debugging purposes it is useful to save the entire register set, but
307 for performance only the ABI-defined callee-saved registers need be
308 saved. If it is implemented, the option
311 >CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM</TT
313 how many registers are saved.</P
315 >The implementation of <TT
317 >HAL_THREAD_LOAD_CONTEXT()</TT
319 loads a thread context, destroying the current context. With a little
320 care this can be implemented by sharing code with
323 >HAL_THREAD_SWITCH_CONTEXT()</TT
325 context simply requires the saved registers to be restored from the
326 stack and a jump or return made back to the saved PC.</P
328 >Note that interrupts are not disabled during this process, any
329 interrupts that occur will be delivered onto the stack to which the
330 current CPU stack pointer points. Hence the stack pointer
331 should never be invalid, or loaded with a value that might cause the
332 saved state to become corrupted by an interrupt. However, the current
333 interrupt state is saved and restored as part of the thread
334 context. If a thread disables interrupts and does something to cause a
335 context switch, interrupts may be re-enabled on switching to another
336 thread. Interrupts will be disabled again when the original thread
344 NAME="AEN7842">Bit indexing</H2
352 CLASS="PROGRAMLISTING"
353 >HAL_LSBIT_INDEX( index, mask )
354 HAL_MSBIT_INDEX( index, mask )</PRE
359 >These macros place in <TT
365 the least significant bit in <TT
371 architectures have instruction level support for one or other of these
372 operations. If no architectural support is available, then these
373 macros may call C functions to do the job.</P
380 NAME="AEN7848">Idle thread activity</H2
388 CLASS="PROGRAMLISTING"
389 >HAL_IDLE_THREAD_ACTION( count )</PRE
394 >It may be necessary under some circumstances for the HAL to execute
395 code in the kernel idle thread's loop. An example might be to execute
396 a processor halt instruction. This macro provides a portable way of
397 doing this. The argument is a copy of the idle thread's loop counter,
398 and may be used to trigger actions at longer intervals than every
406 NAME="AEN7852">Reorder barrier</H2
414 CLASS="PROGRAMLISTING"
415 >HAL_REORDER_BARRIER()</PRE
420 >When optimizing the compiler can reorder code. In some parts of
421 multi-threaded systems, where the order of actions is vital, this can
422 sometimes cause problems. This macro may be inserted into places where
423 reordering should not happen and prevents code being migrated across
424 it by the compiler optimizer. It should be placed between statements
425 that must be executed in the order written in the code.</P
432 NAME="AEN7856">Breakpoint support</H2
440 CLASS="PROGRAMLISTING"
441 >HAL_BREAKPOINT( label )
443 HAL_BREAKINST_SIZE</PRE
448 >These macros provide support for breakpoints.</P
452 >HAL_BREAKPOINT()</TT
453 > executes a breakpoint
454 instruction. The label is defined at the breakpoint instruction so
455 that exception code can detect which breakpoint was executed.</P
460 > contains the breakpoint instruction
461 code as an integer value. <TT
463 >HAL_BREAKINST_SIZE</TT
465 the size of that breakpoint instruction in bytes. Together these
466 may be used to place a breakpoint in any code.</P
473 NAME="AEN7865">GDB support</H2
481 CLASS="PROGRAMLISTING"
482 >HAL_THREAD_GET_SAVED_REGISTERS( sp, regs )
483 HAL_GET_GDB_REGISTERS( regval, regs )
484 HAL_SET_GDB_REGISTERS( regs, regval )</PRE
489 >These macros provide support for interfacing GDB to the HAL.</P
493 >HAL_THREAD_GET_SAVED_REGISTERS()</TT
497 >HAL_SavedRegisters</SPAN
499 from a stack pointer value. The stack pointer passed in should be the
500 value saved by the thread context macros. The macro will assign a
503 >HAL_SavedRegisters</SPAN
505 to the variable passed as the second argument.</P
509 >HAL_GET_GDB_REGISTERS()</TT
510 > translates a register
511 state as saved by the HAL and into a register dump in the format
512 expected by GDB. It takes a pointer to a
515 >HAL_SavedRegisters</SPAN
522 > argument and a pointer to the memory to
523 contain the GDB register dump in the <TT
533 >HAL_SET_GDB_REGISTERS()</TT
534 > translates a GDB format
535 register dump into a the format expected by the HAL. It takes a
536 pointer to the memory containing the GDB register dump in the
542 > argument and a pointer to a
545 >HAL_SavedRegisters</SPAN
559 NAME="AEN7883">Setjmp and longjmp support</H2
567 CLASS="PROGRAMLISTING"
569 hal_jmp_buf[CYGARC_JMP_BUF_SIZE]
570 hal_setjmp( hal_jmp_buf env )
571 hal_longjmp( hal_jmp_buf env, int val )</PRE
576 >These functions provide support for the C
584 functions. Refer to the C library for further information.</P
591 NAME="AEN7889">Stack Sizes</H2
599 CLASS="PROGRAMLISTING"
600 >CYGNUM_HAL_STACK_SIZE_MINIMUM
601 CYGNUM_HAL_STACK_SIZE_TYPICAL</PRE
606 >The values of these macros define the minimum and typical sizes of
611 >CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
612 > defines the minimum
613 size of a thread stack. This is enough for the thread to function
614 correctly within eCos and allows it to take interrupts and context
615 switches. There should also be enough space for a simple thread entry
616 function to execute and call basic kernel operations on objects like
617 mutexes and semaphores. However there will not be enough room for much
618 more than this. When creating stacks for their own threads,
619 applications should determine the stack usage needed for application
620 purposes and then add
623 >CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
628 >CYGNUM_HAL_STACK_SIZE_TYPICAL</TT
629 > is a reasonable increment over
632 >CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
633 >, usually about 1kB. This should be
634 adequate for most modest thread needs. Only threads that need to
635 define significant amounts of local data, or have very deep call trees
636 should need to use a larger stack size.</P
643 NAME="AEN7899">Address Translation</H2
651 CLASS="PROGRAMLISTING"
652 >CYGARC_CACHED_ADDRESS(addr)
653 CYGARC_UNCACHED_ADDRESS(addr)
654 CYGARC_PHYSICAL_ADDRESS(addr)</PRE
659 >These macros provide address translation between different views of
660 memory. In many architectures a given memory location may be visible
661 at different addresses in both cached and uncached forms. It is also
662 possible that the MMU or some other address translation unit in the
663 CPU presents memory to the program at a different virtual address to
664 its physical address on the bus.</P
668 >CYGARC_CACHED_ADDRESS()</TT
669 > translates the given
670 address to its location in cached memory. This is typically where the
671 application will access the memory.</P
675 >CYGARC_UNCACHED_ADDRESS()</TT
676 > translates the given
677 address to its location in uncached memory. This is typically where
678 device drivers will access the memory to avoid cache problems. It may
679 additionally be necessary for the cache to be flushed before the
680 contents of this location is fully valid.</P
684 >CYGARC_PHYSICAL_ADDRESS()</TT
685 > translates the given
686 address to its location in the physical address space. This is
687 typically the address that needs to be passed to device hardware such
688 as a DMA engine, ethernet device or PCI bus bridge. The physical
689 address may not be directly accessible to the program, it may be
690 re-mapped by address translation.</P
697 NAME="AEN7909">Global Pointer</H2
705 CLASS="PROGRAMLISTING"
706 >CYGARC_HAL_SAVE_GP()
707 CYGARC_HAL_RESTORE_GP()</PRE
712 >These macros insert code to save and restore any global data pointer
713 that the ABI uses. These are necessary when switching context between
714 two eCos instances - for example between an eCos application and
723 SUMMARY="Footer navigation table"
734 HREF="hal-interfaces.html"
752 HREF="hal-interrupt-handling.html"
768 HREF="hal-interfaces.html"
776 >Interrupt Handling</TD