source: SVN/cambria/redboot/packages/hal/common/current/doc/hal.sgml @ 1

Last change on this file since 1 was 1, checked in by Tim Harvey, 2 years ago

restored latest version of files from server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 98.1 KB
Line 
1<!-- {{{ Banner                         -->
2
3<!-- =============================================================== -->
4<!--                                                                 -->
5<!--     HAL.sgml                                                    -->
6<!--                                                                 -->
7<!--     eCos common HAL documentation                               -->
8<!--                                                                 -->
9<!-- =============================================================== -->
10<!-- ####COPYRIGHTBEGIN####                                          -->
11<!--                                                                 -->
12<!-- =============================================================== -->
13<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
14<!-- This material may be distributed only subject to the terms      -->
15<!-- and conditions set forth in the Open Publication License, v1.0  -->
16<!-- or later (the latest version is presently available at          -->
17<!-- http://www.opencontent.org/openpub/)                            -->
18<!-- Distribution of the work or derivative of the work in any       -->
19<!-- standard (paper) book form is prohibited unless prior           -->
20<!-- permission obtained from the copyright holder                   -->
21<!-- =============================================================== -->
22<!--                                                                 -->     
23<!-- ####COPYRIGHTEND####                                            -->
24<!-- =============================================================== -->
25<!-- #####DESCRIPTIONBEGIN####                                       -->
26<!--                                                                 -->
27<!-- ####DESCRIPTIONEND####                                          -->
28<!-- =============================================================== -->
29
30<!-- }}} -->
31
32<part id="the-ecos-hardware-abstraction-layer">
33<title>The eCos Hardware Abstraction Layer (HAL)</title>
34
35<!-- {{{ Intro -->
36
37<chapter id=hal-introduction>
38<title>Introduction</title>
39<PARA>
40This is an initial specification of the <EMPHASIS>eCos</EMPHASIS> <!--
41<index></index> -->Hardware Abstraction Layer (HAL). The HAL abstracts
42the underlying hardware of a processor architecture and/or the
43platform to a level sufficient for the eCos kernel to be ported onto
44that platform.
45</PARA>
46
47<note>
48<title>Caveat</title>
49<PARA>
50This document is an informal description of the HAL capabilities and
51is not intended to be full documentation, although it may be used as a
52source for such. It also describes the HAL as it is currently
53implemented for the architectures targeted in this release. It most
54closely describes the HALs for the MIPS, I386 and PowerPC HALs. Other
55architectures are similar but may not be organized precisely as
56described here.
57</PARA>
58</note>
59
60</chapter>
61
62<!-- }}} -->
63<!-- {{{ Architecture, Variant and Platform  -->
64
65<CHAPTER id="hal-architecture-variant-and-platform">
66<TITLE>Architecture, Variant and Platform</TITLE>
67
68<para>
69We have identified three levels at which the HAL must operate.
70</para>
71
72<itemizedlist>
73  <listitem>
74    <para>
75    The <!-- <index></index> --><firstterm>architecture
76    HAL</firstterm> abstracts the basic CPU architecture and includes
77    things like interrupt delivery, context switching, CPU startup
78    etc.
79    </para>
80  </listitem>
81
82  <listitem>
83    <para>
84    The <!-- <index></index> --> <firstterm>variant HAL</firstterm>
85    encapsulates features of the CPU variant such as caches, MMU and
86    FPU features. It also deals with any on-chip peripherals such as
87    memory and interrupt controllers. For architectural variations,
88    the actual implementation of the variation is often in the
89    architectural HAL, and the variant HAL simply provides the correct
90    configuration definitions.
91    </para>
92  </listitem>
93
94    <listitem>
95    <para>
96    The <!-- <index></index> --><firstterm>platform HAL</firstterm>
97    abstracts the properties of the current platform and includes
98    things like platform startup, timer devices, I/O register access
99    and interrupt controllers.
100    </para>
101  </listitem>
102
103</itemizedlist>
104
105<para>
106The boundaries between these three HAL levels are necessarily blurred
107since functionality shifts between levels on a target-by-target basis.
108For example caches and MMU may be either an architecture feature or a
109variant feature. Similarly, memory and interrupt controllers may be
110on-chip and in the variant HAL, or off-chip and in the platform HAL.
111</para>
112<para>
113Generally there is a separate package for each of the architecture,
114variant and package HALs for a target. For some of the older targets,
115or where it would be essentially empty, the variant HAL is omitted.
116</para>
117</CHAPTER>
118
119<!-- }}} -->
120<!-- {{{ General Principles -->
121
122<CHAPTER id="hal-general-principles">
123<TITLE>General principles</TITLE>
124
125<PARA>
126The HAL has been implemented according to the following general
127principles:
128</PARA>
129<ORDEREDLIST>
130<LISTITEM>
131<PARA>        The HAL is implemented in C and assembler, although the
132              eCos kernel is largely implemented in C&plus;&plus;.
133              This is to permit the HAL the widest possible
134              applicability.</PARA>
135</LISTITEM>
136<LISTITEM>
137<PARA>All interfaces to the HAL are implemented by
138              CPP macros. This allows them to be implemented as inline
139              C code, inline assembler or function calls to external C
140              or assembler code. This allows the most efficient
141              implementation to be selected without affecting the
142              interface. It also allows them to be redefined if the
143              platform or variant HAL needs to replace or enhance a definition
144              from the architecture HAL.</PARA>
145</LISTITEM>
146<LISTITEM>
147<PARA>The HAL provides simple, portable mechanisms for dealing
148with the hardware of a wide range of architectures and platforms.
149It is always possible to bypass the HAL and program the hardware
150directly, but this may lead to a loss of portability. </PARA>
151</LISTITEM>
152</ORDEREDLIST>
153</CHAPTER>
154
155<!-- }}} -->
156<!-- {{{ HAL Interfaces -->
157
158<CHAPTER id="hal-interfaces">
159<TITLE><!-- <index></index> --><!-- <xref> -->HAL Interfaces</TITLE>
160
161<para>
162This section describes the main HAL interfaces.
163</para>
164
165<!-- {{{ Base Definitions -->
166
167<SECTION id="hal-base-definitions">
168<TITLE>Base Definitions</TITLE>
169
170<para>
171These are definitions that characterize the properties of the base
172architecture that are used to compile the portable parts of the
173kernel. They are concerned with such things a portable type
174definitions, endianness, and labeling.
175</para>
176
177<PARA>
178These definitions are supplied by the
179<filename>cyg/hal/basetype.h</filename> header file which is supplied
180by the architecture HAL. It is included automatically by
181<FILENAME>cyg/infra/cyg_type.h</FILENAME>.
182</PARA>
183
184<!-- =================================================================== -->
185
186<SECTION>
187<TITLE>Byte order</TITLE>
188<VARIABLELIST>
189  <VARLISTENTRY>
190    <TERM><VARNAME>CYG_BYTEORDER</VARNAME></TERM>
191    <LISTITEM>
192      <PARA>
193      This defines the byte order of the target and must be set to either
194      <varname>CYG_LSBFIRST</varname> or <varname>CYG_MSBFIRST</varname>.
195      </PARA>
196    </LISTITEM>
197  </VARLISTENTRY>
198</VARIABLELIST>
199</SECTION>
200
201<!-- =================================================================== -->
202
203<SECTION>
204<TITLE>Label Translation</TITLE>
205
206<VARIABLELIST>
207  <VARLISTENTRY>
208    <TERM><FUNCTION>CYG_LABEL_NAME(name)</FUNCTION></TERM>
209    <LISTITEM>
210
211      <PARA>
212      This is a wrapper used in some C and C&plus;&plus; files which
213      use labels defined in assembly code or the linker script.
214      It need only be defined if the default implementation in
215      <filename>cyg/infra/cyg_type.h</filename>, which passes the name
216      argument unaltered, is inadequate. It should be paired with
217      <function>CYG_LABEL_DEFN()</function>.
218      </PARA>
219    </LISTITEM>
220  </VARLISTENTRY>
221  <VARLISTENTRY>
222    <TERM><FUNCTION>CYG_LABEL_DEFN(name)</FUNCTION></TERM>
223    <LISTITEM>
224
225      <PARA>
226      This is a wrapper used in assembler sources and linker scripts
227      which define labels.  It need only be defined if the default
228      implementation in
229      <filename>cyg/infra/cyg_type.h</filename>, which passes the name
230      argument unaltered, is inadequate. The most usual alternative
231      definition of this macro prepends an underscore to the label
232      name.
233      </PARA>
234    </LISTITEM>
235  </VARLISTENTRY>
236</VARIABLELIST>
237</SECTION>
238
239
240<!-- =================================================================== -->
241
242<SECTION>
243<TITLE>Base types</TITLE>
244<PROGRAMLISTING>
245        cyg_halint8
246        cyg_halint16
247        cyg_halint32
248        cyg_halint64
249        cyg_halcount8
250        cyg_halcount16
251        cyg_halcount32
252        cyg_halcount64
253        cyg_halbool
254</PROGRAMLISTING>
255<PARA>
256These macros define the C base types that should be used to define
257variables of the given size. They only need to be defined if the
258default types specified in <filename>cyg/infra/cyg_type.h</filename>
259cannot be used. Note that these are only the base types, they will be
260composed with <literal>signed</literal> and
261<literal>unsigned</literal> to form full type specifications.
262</PARA>
263</SECTION>
264
265<!-- =================================================================== -->
266
267<SECTION>
268<TITLE>Atomic types</TITLE>
269<PROGRAMLISTING>
270        cyg_halatomic CYG_ATOMIC
271</PROGRAMLISTING>
272<PARA>
273These types are guaranteed to be read or written in a single
274uninterruptible operation. It is architecture defined what size this
275type is, but it will be at least a byte.
276</PARA>
277</SECTION>
278
279</SECTION>
280
281<!-- }}} -->
282<!-- {{{ Architecture Characterization  -->
283
284<SECTION id="hal-architecture-characterization">
285<TITLE>Architecture Characterization</TITLE>
286
287<para>
288These are definition that are related to the basic architecture of the
289CPU. These include the CPU context save format, context switching, bit
290twiddling, breakpoints, stack sizes and address translation.
291</para>
292
293<PARA>
294Most of these definition are found in
295<filename>cyg/hal/hal_arch.h</filename>.  This file is supplied by the
296architecture HAL. If there are variant or platform specific
297definitions then these will be found in
298<filename>cyg/hal/var_arch.h</filename> or
299<filename>cyg/hal/plf_arch.h</filename>. These files are include
300automatically by this header, so need not be included explicitly.
301</PARA>
302
303<!-- =================================================================== -->
304
305<SECTION>
306<TITLE>Register Save Format</TITLE>
307<PROGRAMLISTING>
308typedef struct HAL_SavedRegisters
309{
310    /* architecture-dependent list of registers to be saved */
311} HAL_SavedRegisters;
312</PROGRAMLISTING>
313<PARA>
314This structure describes the layout of a saved machine state on the
315stack. Such states are saved during thread context switches,
316interrupts and exceptions. Different quantities of state may be saved
317during each of these, but usually a thread context state is a subset
318of the interrupt state which is itself a subset of an exception state.
319For debugging purposes, the same structure is used for all three
320purposes, but where these states are significantly different, this
321structure may contain a union of the three states.
322</PARA>
323</SECTION>
324
325
326<!-- =================================================================== -->
327
328<SECTION>
329<TITLE>Thread Context Initialization</TITLE>
330
331<PROGRAMLISTING>
332HAL_THREAD_INIT_CONTEXT( sp, arg, entry, id )
333</PROGRAMLISTING>
334
335<PARA>
336This macro initializes a thread's context so that
337it may be switched to by <FUNCTION>HAL_THREAD_SWITCH_CONTEXT()</FUNCTION>.
338The arguments are:
339</PARA>
340<VARIABLELIST>
341  <VARLISTENTRY>
342    <TERM>sp</TERM>
343    <LISTITEM>
344      <PARA>
345      A location containing the current value of the thread's stack
346      pointer. This should be a variable or a structure field. The SP
347      value will be read out of here and an adjusted value written
348      back.
349      </PARA>
350    </LISTITEM>
351  </VARLISTENTRY>
352 
353  <VARLISTENTRY>
354    <TERM>arg</TERM>
355    <LISTITEM>
356      <PARA>
357      A value that is passed as the first argument to the entry
358      point function.
359      </PARA>
360    </LISTITEM>
361  </VARLISTENTRY>
362  <VARLISTENTRY>
363    <TERM>entry</TERM>
364    <LISTITEM>
365      <PARA>
366      The address of an entry point function. This will be called
367      according the C calling conventions, and the value of
368      <parameter>arg</parameter> will be passed as the first
369      argument. This function should have the following type signature
370      <function>void entry(CYG_ADDRWORD arg)</function>.
371      </PARA>
372    </LISTITEM>
373  </VARLISTENTRY>
374  <VARLISTENTRY>
375    <TERM>id</TERM>
376    <LISTITEM>
377      <PARA>
378      A thread id value. This is only used for debugging purposes,
379      it is ORed into the initialization pattern for unused registers
380      and may be used to help identify the thread from its register dump.
381      The least significant 16 bits of this value should be zero to allow
382      space for a register identifier.
383      </PARA>
384    </LISTITEM>
385  </VARLISTENTRY>
386</VARIABLELIST>
387</SECTION>
388
389<!-- =================================================================== -->
390
391<SECTION id="hal-context-switch">
392<TITLE>Thread Context Switching</TITLE>
393
394<PROGRAMLISTING>
395HAL_THREAD_LOAD_CONTEXT( to )
396HAL_THREAD_SWITCH_CONTEXT( from, to )
397</PROGRAMLISTING>
398<PARA>
399These macros implement the thread switch code. The arguments are:
400</PARA>
401
402<VARIABLELIST>
403  <VARLISTENTRY>
404    <TERM>from</TERM>
405    <LISTITEM>
406      <PARA>
407      A pointer to a location where the stack pointer of the current
408      thread will be stored.
409      </PARA>
410    </LISTITEM>
411  </VARLISTENTRY>
412  <VARLISTENTRY>
413    <TERM>to</TERM>
414    <LISTITEM>
415      <PARA>
416      A pointer to a location from where the stack pointer of the next
417      thread will be read.
418      </PARA>
419    </LISTITEM>
420  </VARLISTENTRY>
421</VARIABLELIST>
422
423<para>
424For <function>HAL_THREAD_LOAD_CONTEXT()</function> the current CPU
425state is discarded and the state of the destination thread is
426loaded. This is only used once, to load the first thread when the
427scheduler is started.
428</para>
429
430<PARA>
431For <function>HAL_THREAD_SWITCH_CONTEXT()</function> the state of the
432current thread is saved onto its stack, using the current value of the
433stack pointer, and the address of the saved state placed in
434<parameter>*from</parameter>.  The value in
435<parameter>*to</parameter> is then read and the state of the new
436thread is loaded from it.
437</PARA>
438
439<para>
440While these two operations may be implemented with inline assembler,
441they are normally implemented as calls to assembly code functions in
442the HAL. There are two advantages to doing it this way. First, the
443return link of the call provides a convenient PC value to be used in
444the saved context. Second, the calling conventions mean that the
445compiler will have already saved the caller-saved registers before the
446call, so the HAL need only save the callee-saved registers.
447</para>
448
449<para>
450The implementation of <function>HAL_THREAD_SWITCH_CONTEXT()</function>
451saves the current CPU state on the stack, including the current
452interrupt state (or at least the register that contains it). For
453debugging purposes it is useful to save the entire register set, but
454for performance only the ABI-defined callee-saved registers need be
455saved. If it is implemented, the option
456<literal>CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM</literal> controls
457how many registers are saved.
458</para>
459
460<para>
461The implementation of <function>HAL_THREAD_LOAD_CONTEXT()</function>
462loads a thread context, destroying the current context. With a little
463care this can be implemented by sharing code with
464<function>HAL_THREAD_SWITCH_CONTEXT()</function>. To load a thread
465context simply requires the saved registers to be restored from the
466stack and a jump or return made back to the saved PC.
467</para>
468
469<PARA>
470Note that interrupts are not disabled during this process, any
471interrupts that occur will be delivered onto the stack to which the
472current CPU stack pointer points. Hence the stack pointer
473should never be invalid, or loaded with a value that might cause the
474saved state to become corrupted by an interrupt. However, the current
475interrupt state is saved and restored as part of the thread
476context. If a thread disables interrupts and does something to cause a
477context switch, interrupts may be re-enabled on switching to another
478thread. Interrupts will be disabled again when the original thread
479regains control.
480</PARA>
481
482</SECTION>
483
484<!-- =================================================================== -->
485
486<SECTION>
487<TITLE>Bit indexing</TITLE>
488
489<PROGRAMLISTING>
490HAL_LSBIT_INDEX( index, mask )
491HAL_MSBIT_INDEX( index, mask )
492</PROGRAMLISTING>
493
494<PARA>
495These macros place in <parameter>index</parameter> the bit index of
496the least significant bit in <parameter>mask</parameter>. Some
497architectures have instruction level support for one or other of these
498operations. If no architectural support is available, then these
499macros may call C functions to do the job.
500</PARA>
501</SECTION>
502
503<!-- =================================================================== -->
504
505<SECTION>
506<TITLE>Idle thread activity</TITLE>
507
508<PROGRAMLISTING>
509HAL_IDLE_THREAD_ACTION( count )
510</PROGRAMLISTING>
511
512<PARA>
513It may be necessary under some circumstances for the HAL to execute
514code in the kernel idle thread's loop. An example might be to execute
515a processor halt instruction. This macro provides a portable way of
516doing this. The argument is a copy of the idle thread's loop counter,
517and may be used to trigger actions at longer intervals than every
518loop.
519</PARA>
520</SECTION>
521
522<!-- =================================================================== -->
523
524<SECTION>
525<TITLE>Reorder barrier</TITLE>
526
527<PROGRAMLISTING>
528HAL_REORDER_BARRIER()
529</PROGRAMLISTING>
530
531<PARA>
532When optimizing the compiler can reorder code. In some parts of
533multi-threaded systems, where the order of actions is vital, this can
534sometimes cause problems. This macro may be inserted into places where
535reordering should not happen and prevents code being migrated across
536it by the compiler optimizer. It should be placed between statements
537that must be executed in the order written in the code.
538</PARA>
539</SECTION>
540
541<!-- =================================================================== -->
542
543<SECTION>
544<TITLE>Breakpoint support</TITLE>
545
546<PROGRAMLISTING>
547HAL_BREAKPOINT( label )
548HAL_BREAKINST
549HAL_BREAKINST_SIZE
550</PROGRAMLISTING>
551
552<PARA>
553These macros provide support for breakpoints.
554</PARA>
555
556<PARA>
557<FUNCTION>HAL_BREAKPOINT()</FUNCTION> executes a breakpoint
558instruction. The label is defined at the breakpoint instruction so
559that exception code can detect which breakpoint was executed.
560</PARA>
561
562<PARA>
563<literal>HAL_BREAKINST</literal> contains the breakpoint instruction
564code as an integer value. <literal>HAL_BREAKINST_SIZE</literal> is
565the size of that breakpoint instruction in bytes. Together these
566may be used to place a breakpoint in any code.
567</PARA>
568</SECTION>
569
570<!-- =================================================================== -->
571
572<SECTION>
573<TITLE>GDB support</TITLE>
574
575<PROGRAMLISTING>
576HAL_THREAD_GET_SAVED_REGISTERS( sp, regs )
577HAL_GET_GDB_REGISTERS( regval, regs )
578HAL_SET_GDB_REGISTERS( regs, regval )
579</PROGRAMLISTING>
580
581<PARA>
582These macros provide support for interfacing GDB to the HAL.
583</PARA>
584
585<PARA>
586<FUNCTION>HAL_THREAD_GET_SAVED_REGISTERS()</FUNCTION> extracts a
587pointer to a <STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
588from a stack pointer value. The stack pointer passed in should be the
589value saved by the thread context macros. The macro will assign a
590pointer to the <STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
591to the variable passed as the second argument.
592</PARA>
593
594<PARA>
595<FUNCTION>HAL_GET_GDB_REGISTERS()</FUNCTION> translates a register
596state as saved by the HAL and into a register dump in the format
597expected by GDB. It takes a pointer to a
598<STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure in the
599<parameter>regs</parameter> argument and a pointer to the memory to
600contain the GDB register dump in the <parameter>regval</parameter>
601argument.
602</PARA>
603
604<PARA>
605<FUNCTION>HAL_SET_GDB_REGISTERS()</FUNCTION> translates a GDB format
606register dump into a the format expected by the HAL.  It takes a
607pointer to the memory containing the GDB register dump in the
608<parameter>regval</parameter> argument and a pointer to a
609<STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
610in the <parameter>regs</parameter> argument.
611</PARA>
612</SECTION>
613
614<!-- =================================================================== -->
615
616<SECTION>
617<TITLE>Setjmp and longjmp support</TITLE>
618
619<PROGRAMLISTING>
620CYGARC_JMP_BUF_SIZE
621hal_jmp_buf[CYGARC_JMP_BUF_SIZE]
622hal_setjmp( hal_jmp_buf env )
623hal_longjmp( hal_jmp_buf env, int val )
624</PROGRAMLISTING>
625
626<PARA>
627These functions provide support for the C
628<FUNCTION>setjmp()</FUNCTION> and <FUNCTION>longjmp()</FUNCTION>
629functions.  Refer to the C library for further information.
630</PARA>
631
632</SECTION>
633
634<!-- =================================================================== -->
635
636<section>
637<title>Stack Sizes</title>
638<programlisting>
639CYGNUM_HAL_STACK_SIZE_MINIMUM
640CYGNUM_HAL_STACK_SIZE_TYPICAL
641</programlisting>
642
643<para>
644The values of these macros define the minimum and typical sizes of
645thread stacks.
646</para>
647
648<para>
649<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal> defines the minimum
650size of a thread stack. This is enough for the thread to function
651correctly within eCos and allows it to take interrupts and context
652switches. There should also be enough space for a simple thread entry
653function to execute and call basic kernel operations on objects like
654mutexes and semaphores. However there will not be enough room for much
655more than this. When creating stacks for their own threads,
656applications should determine the stack usage needed for application
657purposes and then add
658<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal>.
659</para>
660
661<para>
662<literal>CYGNUM_HAL_STACK_SIZE_TYPICAL</literal> is a reasonable increment over
663<literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal>, usually about 1kB. This should be
664adequate for most modest thread needs. Only threads that need to
665define significant amounts of local data, or have very deep call trees
666should need to use a larger stack size.
667</para>
668
669</section>
670
671
672<!-- =================================================================== -->
673
674<section>
675<title>Address Translation</title>
676
677<programlisting>
678CYGARC_CACHED_ADDRESS(addr)
679CYGARC_UNCACHED_ADDRESS(addr)
680CYGARC_PHYSICAL_ADDRESS(addr)
681</programlisting>
682
683<para>
684These macros provide address translation between different views of
685memory. In many architectures a given memory location may be visible
686at different addresses in both cached and uncached forms. It is also
687possible that the MMU or some other address translation unit in the
688CPU presents memory to the program at a different virtual address to
689its physical address on the bus.
690</para>
691
692<para>
693<function>CYGARC_CACHED_ADDRESS()</function> translates the given
694address to its location in cached memory. This is typically where the
695application will access the memory.
696</para>
697
698<para>
699<function>CYGARC_UNCACHED_ADDRESS()</function> translates the given
700address to its location in uncached memory. This is typically where
701device drivers will access the memory to avoid cache problems. It may
702additionally be necessary for the cache to be flushed before the
703contents of this location is fully valid.
704</para>
705
706<para>
707<function>CYGARC_PHYSICAL_ADDRESS()</function> translates the given
708address to its location in the physical address space. This is
709typically the address that needs to be passed to device hardware such
710as a DMA engine, ethernet device or PCI bus bridge. The physical
711address may not be directly accessible to the program, it may be
712re-mapped by address translation.
713</para>
714
715</section>
716
717
718<!-- =================================================================== -->
719
720<section>
721<title>Global Pointer</title>
722
723<programlisting>
724CYGARC_HAL_SAVE_GP()
725CYGARC_HAL_RESTORE_GP()
726</programlisting>
727
728<para>
729These macros insert code to save and restore any global data pointer
730that the ABI uses. These are necessary when switching context between
731two eCos instances - for example between an eCos application and
732RedBoot.
733</para>
734
735</section>
736
737</SECTION>
738
739<!-- }}} -->
740<!-- {{{ Interrupt Handling -->
741
742<SECTION id="hal-interrupt-handling">
743<TITLE>Interrupt Handling</TITLE>
744
745<para>
746These interfaces contain definitions related to interrupt
747handling. They include definitions of exception and interrupt numbers,
748interrupt enabling and masking.
749</para>
750
751<PARA>
752These definitions are normally found in
753<FILENAME>cyg/hal/hal_intr.h</FILENAME>.  This file is supplied by the
754architecture HAL.  Any variant or platform specific definitions will
755be found in <filename>cyg/hal/var_intr.h</filename>,
756<filename>cyg/hal/plf_intr.h</filename> or
757<filename>cyg/hal/hal_platform_ints.h</filename> in the variant or platform
758HAL, depending on the exact target. These files are include
759automatically by this header, so need not be included explicitly.
760</PARA>
761
762<!-- =================================================================== -->
763
764<SECTION>
765<TITLE>Vector numbers</TITLE>
766
767<PROGRAMLISTING>
768CYGNUM_HAL_VECTOR_XXXX
769CYGNUM_HAL_VSR_MIN
770CYGNUM_HAL_VSR_MAX
771CYGNUM_HAL_VSR_COUNT
772
773CYGNUM_HAL_INTERRUPT_XXXX
774CYGNUM_HAL_ISR_MIN
775CYGNUM_HAL_ISR_MAX
776CYGNUM_HAL_ISR_COUNT
777
778CYGNUM_HAL_EXCEPTION_XXXX
779CYGNUM_HAL_EXCEPTION_MIN
780CYGNUM_HAL_EXCEPTION_MAX
781CYGNUM_HAL_EXCEPTION_COUNT
782</PROGRAMLISTING>
783
784<PARA>
785All possible VSR, interrupt and exception vectors are specified here,
786together with maximum and minimum values for range checking. While the
787VSR and exception numbers will be defined in this file, the interrupt
788numbers will normally be defined in the variant or platform HAL file
789that is included by this header.
790</PARA>
791
792<PARA>
793There are two ranges of numbers, those for the vector service
794routines and those for the interrupt service routines. The relationship
795between these two ranges is undefined, and no equivalence should
796be assumed if vectors from the two ranges coincide.
797</PARA>
798
799<PARA>
800The VSR vectors correspond to the set of exception vectors that can be
801delivered by the CPU architecture, many of these will be internal
802exception traps. The ISR vectors correspond to the set of external
803interrupts that can be delivered and are usually determined by extra
804decoding of the interrupt controller by the interrupt VSR.
805</PARA>
806
807<PARA>
808Where a CPU supports synchronous exceptions, the range of such
809exceptions allowed are defined by <literal>CYGNUM_HAL_EXCEPTION_MIN</literal> and
810<literal>CYGNUM_HAL_EXCEPTION_MAX</literal>. The
811<literal>CYGNUM_HAL_EXCEPTION_XXXX</literal> definitions are
812standard names used by target independent code to test for the
813presence of particular exceptions in the architecture. The actual
814exception numbers will normally correspond to the VSR exception
815range. In future other exceptions generated by the system software
816(such as stack overflow) may be added.
817</PARA>
818
819<PARA>
820<literal>CYGNUM_HAL_ISR_COUNT</literal>, <literal>CYGNUM_HAL_VSR_COUNT</literal> and
821<literal>CYGNUM_HAL_EXCEPTION_COUNT</literal> define the number of
822ISRs, VSRs and EXCEPTIONs respectively for the purposes of defining
823arrays etc. There might be a translation from the supplied vector
824numbers into array offsets. Hence
825<literal>CYGNUM_HAL_XXX_COUNT</literal> may not simply be
826<literal>CYGNUM_HAL_XXX_MAX</literal> - <literal>CYGNUM_HAL_XXX_MIN</literal> or <literal>CYGNUM_HAL_XXX_MAX</literal>&plus;1.
827</PARA>
828
829</SECTION>
830
831
832<!-- =================================================================== -->
833
834<SECTION>
835<TITLE>Interrupt state control</TITLE>
836
837<PROGRAMLISTING>
838CYG_INTERRUPT_STATE
839HAL_DISABLE_INTERRUPTS( old )
840HAL_RESTORE_INTERRUPTS( old )
841HAL_ENABLE_INTERRUPTS()
842HAL_QUERY_INTERRUPTS( state )
843</PROGRAMLISTING>
844
845<PARA>
846These macros provide control over the state of the CPUs interrupt mask
847mechanism. They should normally manipulate a CPU status register to
848enable and disable interrupt delivery. They should not access an
849interrupt controller.
850</PARA>
851
852
853<para>
854<literal>CYG_INTERRUPT_STATE</literal> is a data type that should be
855used to store the interrupt state returned by
856<function>HAL_DISABLE_INTERRUPTS()</function> and
857<function>HAL_QUERY_INTERRUPTS()</function> and passed to
858<function>HAL_RESTORE_INTERRUPTS()</function>.
859</para>
860
861<PARA>
862<FUNCTION>HAL_DISABLE_INTERRUPTS()</FUNCTION> disables the delivery of
863interrupts and stores the original state of the interrupt mask in the
864variable passed in the <parameter>old</parameter> argument.
865</PARA>
866
867<PARA>
868<FUNCTION>HAL_RESTORE_INTERRUPTS()</FUNCTION> restores the state of
869the interrupt mask to that recorded in <parameter>old</parameter>.
870</PARA>
871
872<PARA>
873<FUNCTION>HAL_ENABLE_INTERRUPTS()</FUNCTION> simply enables interrupts
874regardless of the current state of the mask.
875</PARA>
876
877<PARA>
878<FUNCTION>HAL_QUERY_INTERRUPTS()</FUNCTION> stores the state of the
879interrupt mask in the variable passed in the <parameter>
880state</parameter> argument. The state stored here should also be
881capable of being passed to
882<function>HAL_RESTORE_INTERRUPTS()</function> at a later point.
883</PARA>
884
885<PARA>
886It is at the HAL implementer&rsquo;s discretion exactly
887which interrupts are masked by this mechanism. Where a CPU has more
888than one interrupt type that may be masked separately (e.g. the
889ARM's IRQ and FIQ) only those that can raise DSRs need
890to be masked here. A separate architecture specific mechanism may
891then be used to control the other interrupt types.
892</PARA>
893
894</SECTION>
895
896<!-- =================================================================== -->
897
898<SECTION>
899<TITLE>ISR and VSR management</TITLE>
900
901<PROGRAMLISTING>
902HAL_INTERRUPT_IN_USE( vector, state )
903HAL_INTERRUPT_ATTACH( vector, isr, data, object )
904HAL_INTERRUPT_DETACH( vector, isr )
905HAL_VSR_SET( vector, vsr, poldvsr )
906HAL_VSR_GET( vector, pvsr )
907HAL_VSR_SET_TO_ECOS_HANDLER( vector, poldvsr )
908</PROGRAMLISTING>
909
910<PARA>
911These macros manage the attachment of interrupt and vector service
912routines to interrupt and exception vectors respectively.
913</PARA>
914
915<para>
916<function>HAL_INTERRUPT_IN_USE()</function> tests the state of the
917supplied interrupt vector and sets the value of the state parameter to
918either 1 or 0 depending on whether there is already an ISR attached to
919the vector. The HAL will only allow one ISR to be attached to each
920vector, so it is a good idea to use this function before using
921<function>HAL_INTERRUPT_ATTACH()</function>.
922</para>
923
924<PARA>
925<FUNCTION>HAL_INTERRUPT_ATTACH()</FUNCTION> attaches
926the ISR, data pointer and object pointer to the given
927<parameter>vector</parameter>. When an interrupt occurs on this
928vector the ISR is called using the C calling convention and the vector
929number and data pointer are passed to it as the first and second
930arguments respectively.
931</PARA>
932
933<PARA>
934<FUNCTION>HAL_INTERRUPT_DETACH()</FUNCTION> detaches the ISR from the
935vector.
936</PARA>
937
938<PARA>
939<FUNCTION>HAL_VSR_SET()</FUNCTION> replaces the VSR attached to the
940<parameter>vector</parameter> with the replacement supplied in
941<parameter>vsr</parameter>. The old VSR is returned in the location
942pointed to by <parameter>pvsr</parameter>.
943</PARA>
944
945<PARA>
946<FUNCTION>HAL_VSR_GET()</FUNCTION> assigns
947a copy of the VSR to the location pointed to by <parameter>pvsr</parameter>.
948</PARA>
949
950<para>
951<function>HAL_VSR_SET_TO_ECOS_HANDLER()</function> ensures that the
952VSR for a specific exception is pointing at the eCos exception VSR and
953not one for RedBoot or some other ROM monitor. The default when
954running under RedBoot is for exceptions to be handled by RedBoot and
955passed to GDB. This macro diverts the exception to eCos so that it may
956be handled by application code. The arguments are the VSR vector to be
957replaces, and a location in which to store the old VSR pointer, so
958that it may be replaced at a later point.
959</para>
960
961</SECTION>
962
963<!-- =================================================================== -->
964
965<SECTION>
966<TITLE>Interrupt controller management</TITLE>
967
968<PROGRAMLISTING>
969HAL_INTERRUPT_MASK( vector )
970HAL_INTERRUPT_UNMASK( vector )
971HAL_INTERRUPT_ACKNOWLEDGE( vector )
972HAL_INTERRUPT_CONFIGURE( vector, level, up )
973HAL_INTERRUPT_SET_LEVEL( vector, level )
974</PROGRAMLISTING>
975
976<PARA>
977These macros exert control over any prioritized interrupt
978controller that is present. If no priority controller exists, then
979these macros should be empty.
980</para>
981
982<note>
983  <para>
984  These macros may not be reentrant, so care should be taken to
985  prevent them being called while interrupts are enabled. This means
986  that they can be safely used in initialization code before
987  interrupts are enabled, and in ISRs. In DSRs, ASRs and thread code,
988  however, interrupts must be disabled before these macros are
989  called. Here is an example for use in a DSR where the interrupt
990  source is unmasked after data processing:
991  </para>
992<PROGRAMLISTING>
993 ...
994 HAL_DISABLE_INTERRUPTS(old);
995 HAL_INTERRUPT_UNMASK(CYGNUM_HAL_INTERRUPT_ETH);
996 HAL_RESTORE_INTERRUPTS(old);
997 ...
998</PROGRAMLISTING>
999</note>
1000
1001<PARA>
1002<FUNCTION>HAL_INTERRUPT_MASK()</FUNCTION> causes the interrupt
1003associated with the given vector to be blocked.
1004</PARA>
1005
1006<PARA>
1007<FUNCTION>HAL_INTERRUPT_UNMASK()</FUNCTION> causes the interrupt
1008associated with the given vector to be unblocked.
1009</PARA>
1010
1011<PARA>
1012<FUNCTION>HAL_INTERRUPT_ACKNOWLEDGE()</FUNCTION> acknowledges the
1013current interrupt from the given vector. This is usually executed from
1014the ISR for this vector when it is prepared to allow further
1015interrupts.  Most interrupt controllers need some form of acknowledge
1016action before the next interrupt is allowed through. Executing this
1017macro may cause another interrupt to be delivered. Whether this
1018interrupts the current code depends on the state of the CPU interrupt
1019mask.
1020</PARA>
1021
1022<PARA>
1023<FUNCTION>HAL_INTERRUPT_CONFIGURE()</FUNCTION> provides
1024control over how an interrupt signal is detected. The arguments
1025are:
1026</PARA>
1027<VARIABLELIST>
1028  <VARLISTENTRY>
1029    <TERM>vector</TERM>
1030    <LISTITEM>
1031      <PARA>The interrupt vector to be configured.</PARA>
1032    </LISTITEM>
1033  </VARLISTENTRY>
1034 
1035  <VARLISTENTRY>
1036    <TERM>level</TERM>
1037    <LISTITEM>
1038      <PARA>
1039      Set to <varname>true</varname> if the interrupt is detected by
1040      level, and <varname>false</varname> if it is edge triggered.
1041      </PARA>
1042    </LISTITEM>
1043  </VARLISTENTRY>
1044 
1045  <VARLISTENTRY>
1046    <TERM>up</TERM>
1047    <LISTITEM>
1048      <PARA>
1049      If the interrupt is set to level detect, then if this is
1050      <VARNAME>true</VARNAME> it is detected by a high signal level,
1051      and if <VARNAME>false</VARNAME> by a low signal level. If the
1052      interrupt is set to edge triggered, then if this is
1053      <VARNAME>true</VARNAME> it is triggered by a rising edge and if
1054      <VARNAME>false</VARNAME> by a falling edge.
1055      </PARA>
1056    </LISTITEM>
1057  </VARLISTENTRY>
1058</VARIABLELIST>
1059
1060<PARA>
1061<FUNCTION>HAL_INTERRUPT_SET_LEVEL()</FUNCTION> provides control over
1062the hardware priority of the interrupt. The arguments are:
1063</PARA>
1064
1065<VARIABLELIST>
1066  <VARLISTENTRY>
1067    <TERM>vector</TERM>
1068    <LISTITEM>
1069      <PARA>The interrupt whose level is to be set.</PARA>
1070    </LISTITEM>
1071  </VARLISTENTRY>
1072 
1073  <VARLISTENTRY>
1074    <TERM>level</TERM>
1075    <LISTITEM>
1076      <PARA>
1077      The priority level to which the interrupt is to set. In some
1078      architectures the masking of an interrupt is achieved by
1079      changing its priority level. Hence this function,
1080      <FUNCTION>HAL_INTERRUPT_MASK()</FUNCTION> and
1081      <FUNCTION>HAL_INTERRUPT_UNMASK()</FUNCTION> may interfere with
1082      each other.
1083      </PARA>
1084    </LISTITEM>
1085  </VARLISTENTRY>
1086</VARIABLELIST>
1087
1088</SECTION>
1089
1090</SECTION>
1091
1092<!-- }}} -->
1093<!-- {{{ Clocks and Timers -->
1094
1095<SECTION id="hal-clocks-and-timers">
1096<TITLE>Clocks and Timers</TITLE>
1097
1098<para>
1099These interfaces contain definitions related to clock and timer
1100handling. They include interfaces to initialize and read a clock for
1101generating regular interrupts, definitions for setting the frequency of
1102the clock, and support for short timed delays.
1103</para>
1104
1105<!-- =================================================================== -->
1106
1107<SECTION>
1108<TITLE>Clock Control</TITLE>
1109
1110<PROGRAMLISTING>
1111HAL_CLOCK_INITIALIZE( period )
1112HAL_CLOCK_RESET( vector, period )
1113HAL_CLOCK_READ( pvalue )
1114</PROGRAMLISTING>
1115
1116<PARA>
1117These macros provide control over a clock or timer device that may be
1118used by the kernel to provide time-out, delay and scheduling
1119services. The clock is assumed to be implemented by some form of
1120counter that is incremented or decremented by some external source and
1121which raises an interrupt when it reaches a predetermined value.
1122</PARA>
1123
1124<PARA>
1125<FUNCTION>HAL_CLOCK_INITIALIZE()</FUNCTION> initializes the timer
1126device to interrupt at the given period. The period is essentially the
1127value used to initialize the timer counter and must be calculated from
1128the timer frequency and the desired interrupt rate. The timer device
1129should generate an interrupt every <varname>period</varname> cycles.
1130</PARA>
1131
1132<PARA>
1133<FUNCTION>HAL_CLOCK_RESET()</FUNCTION> re-initializes the timer to
1134provoke the next interrupt. This macro is only really necessary when
1135the timer device needs to be reset in some way after each interrupt.
1136</PARA>
1137
1138<PARA>
1139<FUNCTION>HAL_CLOCK_READ()</FUNCTION> reads the current value of the
1140timer counter and puts the value in the location pointed to by
1141<parameter>pvalue</parameter>. The value stored will always be the
1142number of timer cycles since the last interrupt, and hence ranges
1143between zero and the initial period value. If this is a count-down
1144cyclic timer, some arithmetic may be necessary to generate this value.
1145</PARA>
1146
1147</SECTION>
1148
1149<!-- =================================================================== -->
1150
1151<section>
1152<title>Microsecond Delay</title>
1153
1154<programlisting width=72>
1155HAL_DELAY_US(us)
1156</programlisting>
1157
1158<para>
1159This is an optional definition. If defined the macro implements a busy
1160loop delay for the given number of microseconds. This is usually
1161implemented by waiting for the required number of hardware timer ticks
1162to pass.
1163</para>
1164
1165<para>
1166This operation should normally be used when a very short delay is
1167needed when controlling hardware, programming FLASH devices and similar
1168situations where a wait/timeout loop would otherwise be used. Since it
1169may disable interrupts, and is implemented by busy waiting, it should
1170not be used in code that is sensitive to interrupt or context switch
1171latencies.
1172</para>
1173
1174</section>
1175
1176<!-- =================================================================== -->
1177
1178<section>
1179<title>Clock Frequency Definition</title>
1180
1181<programlisting width=72>
1182CYGNUM_HAL_RTC_NUMERATOR
1183CYGNUM_HAL_RTC_DENOMINATOR
1184CYGNUM_HAL_RTC_PERIOD
1185</programlisting>
1186
1187<para>
1188These macros are defined in the CDL for each platform and supply the
1189necessary parameters to specify the frequency at which the clock
1190interrupts. These parameters are usually found in the CDL definitions
1191for the target platform, or in some cases the CPU variant.
1192</para>
1193
1194<para>
1195<literal>CYGNUM_HAL_RTC_NUMERATOR</literal> and
1196<literal>CYGNUM_HAL_RTC_DENOMINATOR</literal> specify the resolution
1197of the clock interrupt.  This resolution involves two separate values,
1198the numerator and the denominator. The result of dividing the
1199numerator by the denominator should correspond to the number of
1200nanoseconds between clock interrupts. For example a numerator of
12011000000000 and a denominator of 100 means that there are 10000000
1202nanoseconds (or 10 milliseconds) between clock interrupts. Expressing
1203the resolution as a fraction minimizes clock drift even for
1204frequencies that cannot be expressed as a simple integer. For example
1205a frequency of 60Hz corresponds to a clock resolution of
120616666666.66...  nanoseconds. This can be expressed accurately as
12071000000000 over 60.
1208</para>
1209
1210<para>
1211<literal>CYGNUM_HAL_RTC_PERIOD</literal> specifies the exact value
1212used to initialize the clock hardware, it is the value passed as a
1213parameter to <literal>HAL_CLOCK_INITIALIZE()</literal> and
1214<literal>HAL_CLOCK_RESET()</literal>. The exact meaning of the value
1215and the range of legal values therefore depends on the target
1216hardware, and the hardware documentation should be consulted for
1217further details.
1218</para>
1219
1220<para>
1221The default values for these macros in all HALs are calculated to give
1222a clock interrupt frequency of 100Hz, or 10ms between interrupts. To
1223change the clock frequency, the period needs to be changed, and the
1224resolution needs to be adjusted accordingly. As an example consider
1225the i386 PC target. The default values for these macros are:
1226</para>
1227
1228<programlisting width=72>
1229CYGNUM_HAL_RTC_NUMERATOR     1000000000
1230CYGNUM_HAL_RTC_DENOMINATOR   100
1231CYGNUM_HAL_RTC_PERIOD        11932
1232</programlisting>
1233
1234<para>
1235To change to, say, a 200Hz clock the period needs to be halved to
12365966, and to compensate the denominator needs to be doubled to 200. To
1237change to a 1KHz interrupt rate change the period to 1193 and the
1238denominator to 1000.
1239</para>
1240
1241<para>
1242Some HALs make this process a little easier by deriving the period
1243arithmetically from the denominator. This calculation may also involve
1244the CPU clock frequency and possibly other factors. For example in the
1245ARM AT91 variant HAL the period is defined by the following
1246expression:
1247</para>
1248
1249<programlisting width=72>
1250((CYGNUM_HAL_ARM_AT91_CLOCK_SPEED/32) / CYGNUM_HAL_RTC_DENOMINATOR)
1251</programlisting>
1252
1253<para>
1254In this case it is not necessary to change the period at all, just
1255change the denominator to select the desired clock frequency. However,
1256note that for certain choices of frequency, rounding errors in this
1257calculation may result in a small clock drift over time. This is
1258usually negligible, but if perfect accuracy is required, it may be
1259necessary to adjust the frequency or period by hand.
1260</para>
1261
1262</section>
1263
1264
1265</section>
1266
1267<!-- }}} -->
1268<!-- {{{ Input and Output -->
1269
1270<SECTION id="hal-input-and-output">
1271<TITLE>HAL I/O</TITLE>
1272
1273<PARA>
1274This section contains definitions for supporting access
1275to device control registers in an architecture neutral
1276fashion.
1277</PARA>
1278
1279<para>
1280These definitions are normally found in the header file
1281<FILENAME>cyg/hal/hal_io.h</FILENAME>.  This file itself contains
1282macros that are generic to the architecture. If there are variant or
1283platform specific IO access macros then these will be found in
1284<filename>cyg/hal/var_io.h</filename> and
1285<filename>cyg/hal/plf_io.h</filename> in the variant or platform HALs
1286respectively. These files are include automatically by this header, so
1287need not be included explicitly.
1288</para>
1289
1290<para>
1291This header (or more likely <filename>cyg/hal/plf_io.h</filename>) also
1292defines the PCI access macros. For more information on these see <xref
1293linkend="pci-library-reference">.
1294</para>
1295
1296<!-- =================================================================== -->
1297
1298<SECTION>
1299<TITLE>Register address</TITLE>
1300
1301<PROGRAMLISTING>
1302HAL_IO_REGISTER
1303</PROGRAMLISTING>
1304
1305<PARA>
1306This type is used to store the address of an I/O register. It will
1307normally be a memory address, an integer port address or an offset
1308into an I/O space. More complex architectures may need to code an
1309address space plus offset pair into a single word, or may represent it
1310as a structure.
1311</PARA>
1312
1313<PARA>
1314Values of variables and constants of this type will usually be
1315supplied by configuration mechanisms or in target specific headers.
1316</PARA>
1317
1318</SECTION>
1319
1320<!-- =================================================================== -->
1321
1322<SECTION>
1323<TITLE>Register read</TITLE>
1324
1325<PROGRAMLISTING>
1326HAL_READ_XXX( register, value )
1327HAL_READ_XXX_VECTOR( register, buffer, count, stride )
1328</PROGRAMLISTING>
1329
1330<PARA>
1331These macros support the reading of I/O registers in various
1332sizes. The <replaceable>XXX</replaceable> component of the name may be
1333<literal>UINT8</literal>, <literal>UINT16</literal>,
1334<literal>UINT32</literal>.
1335</PARA>
1336
1337<PARA>
1338<FUNCTION>HAL_READ_XXX()</FUNCTION> reads the appropriately sized
1339value from the register and stores it in the variable passed as the
1340second argument.
1341</PARA>
1342
1343<PARA>
1344<FUNCTION>HAL_READ_XXX_VECTOR()</FUNCTION> reads
1345<parameter>count</parameter> values of the appropriate size into
1346<parameter>buffer</parameter>. The <parameter>stride</parameter>
1347controls how the pointer advances through the register space. A stride
1348of zero will read the same register repeatedly, and a stride of one
1349will read adjacent registers of the given size. Greater strides will
1350step by larger amounts, to allow for sparsely mapped registers for
1351example.</PARA>
1352</SECTION>
1353
1354<!-- =================================================================== -->
1355
1356<SECTION>
1357<TITLE>Register write</TITLE>
1358
1359<PROGRAMLISTING>
1360HAL_WRITE_XXX( register, value )
1361HAL_WRITE_XXX_VECTOR( register, buffer,count, stride )
1362</PROGRAMLISTING>
1363
1364<PARA>
1365These macros support the writing of I/O registers in various
1366sizes. The <replaceable>XXX</replaceable> component of the name may be
1367<LITERAL>UINT8</LITERAL>, <LITERAL>UINT16</LITERAL>,
1368<LITERAL>UINT32</LITERAL>.
1369</PARA>
1370
1371<PARA>
1372<FUNCTION>HAL_WRITE_XXX()</FUNCTION> writes
1373the appropriately sized value from the variable passed as the second argument
1374stored it in the register.</PARA>
1375<PARA><FUNCTION>HAL_WRITE_XXX_VECTOR()</FUNCTION> writes
1376<parameter>count</parameter> values of the appropriate size from <parameter>
1377buffer</parameter>. The <parameter>stride</parameter> controls
1378how the pointer advances through the register space. A stride of
1379zero will write the same register repeatedly, and a stride of one
1380will write adjacent registers of the given size. Greater strides
1381will step by larger amounts, to allow for sparsely mapped registers
1382for example.</PARA>
1383</SECTION>
1384</SECTION>
1385
1386<!-- }}} -->
1387<!-- {{{ Cache Control -->
1388
1389<SECTION id="hal-cache-control">
1390<TITLE>Cache Control</TITLE>
1391
1392<PARA>This section contains definitions for supporting control
1393of the caches on the CPU.
1394</PARA>
1395
1396<para>
1397These definitions are usually found in the header file
1398<FILENAME>cyg/hal/hal_cache.h</FILENAME>.  This file may be defined in
1399the architecture, variant or platform HAL, depending on where the
1400caches are implemented for the target. Often there will be a generic
1401implementation of the cache control macros in the architecture HAL
1402with the ability to override or undefine them in the variant or
1403platform HAL. Even when the implementation of the cache macros is in
1404the architecture HAL, the cache dimensions will be defined in the
1405variant or platform HAL. As with other files, the variant or platform
1406specific definitions are usually found in
1407<filename>cyg/hal/var_cache.h</filename> and
1408<filename>cyg/hal/plf_cache.h</filename> respectively.  These files
1409are include automatically by this header, so need not be included
1410explicitly.
1411</para>
1412
1413<PARA>
1414There are versions of the macros defined here for both the Data and
1415Instruction caches. these are distinguished by the use of either
1416<literal>DCACHE</literal> or <literal>ICACHE</literal> in the macro
1417names. Some architectures have a unified cache, where both data and
1418instruction share the same cache. In these cases the control macros
1419use <literal>UCACHE</literal> and the <literal>DCACHE</literal> and
1420<literal>ICACHE</literal> macros will just be calls to the
1421<literal>UCACHE</literal> version. In the following descriptions,
1422<literal>XCACHE</literal> is used to stand for any of these. Where
1423there are issues specific to a particular cache, this will be
1424explained in the text.
1425</PARA>
1426
1427<PARA>
1428There might be target specific restrictions on the use of some of the
1429macros which it is the user's responsibility to comply with. Such
1430restrictions are documented in the header file with the macro
1431definition.
1432</PARA>
1433
1434<PARA>
1435Note that destructive cache macros should be used with caution.
1436Preceding a cache invalidation with a cache synchronization is not
1437safe in itself since an interrupt may happen after the synchronization
1438but before the invalidation. This might cause the state of dirty data
1439lines created during the interrupt to be lost.
1440</PARA>
1441
1442<PARA>
1443Depending on the architecture's capabilities, it may be possible to
1444temporarily disable the cache while doing the synchronization and
1445invalidation which solves the problem (no new data would be cached
1446during an interrupt). Otherwise it is necessary to disable interrupts
1447while manipulating the cache which may take a long time.
1448</PARA>
1449
1450<PARA>
1451Some platform HALs now support a pair of cache state query
1452macros: <function>HAL_ICACHE_IS_ENABLED( x )</function> and
1453<function>HAL_DCACHE_IS_ENABLED( x )</function> which set the argument
1454to true if the instruction or data cache is enabled,
1455respectively. Like most cache control macros, these are optional,
1456because the capabilities of different targets and boards can vary
1457considerably. Code which uses them, if it is to be considered
1458portable, should test for their existence first by means of
1459<literal>#ifdef</literal>.  Be sure to include
1460<filename>&lt;cyg/hal/hal_cache.h&gt;</filename> in order to do this
1461test and (maybe) use the macros.
1462</PARA>
1463
1464<!-- =================================================================== -->
1465
1466<SECTION>
1467<TITLE>Cache Dimensions</TITLE>
1468
1469<PROGRAMLISTING>
1470HAL_XCACHE_SIZE
1471HAL_XCACHE_LINE_SIZE
1472HAL_XCACHE_WAYS
1473HAL_XCACHE_SETS
1474</PROGRAMLISTING>
1475<PARA>
1476These macros define the size and dimensions of the Instruction
1477and Data caches.
1478</PARA>
1479
1480<VARIABLELIST>
1481  <VARLISTENTRY>
1482    <TERM>HAL_XCACHE_SIZE       </TERM>
1483    <LISTITEM>
1484      <PARA>Defines the total size of the cache in bytes.</PARA>
1485    </LISTITEM>
1486  </VARLISTENTRY>
1487
1488  <VARLISTENTRY>
1489    <TERM>HAL_XCACHE_LINE_SIZE  </TERM>
1490    <LISTITEM>
1491      <PARA>Defines the cache line size in bytes.</PARA>
1492    </LISTITEM>
1493  </VARLISTENTRY>
1494 
1495  <VARLISTENTRY>
1496    <TERM>HAL_XCACHE_WAYS       </TERM>
1497    <LISTITEM>
1498      <PARA>
1499      Defines the number of ways in each set and defines its level
1500      of associativity. This would be 1 for a direct mapped
1501      cache, 2 for a 2-way cache, 4 for 4-way and so on.
1502      </PARA>
1503    </LISTITEM>
1504  </VARLISTENTRY>
1505 
1506  <VARLISTENTRY>
1507    <TERM>HAL_XCACHE_SETS       </TERM>
1508    <LISTITEM>
1509      <PARA>
1510      Defines the number of sets in the cache, and is calculated from
1511      the previous values.
1512      </PARA>
1513    </LISTITEM>
1514  </VARLISTENTRY>
1515</VARIABLELIST>
1516
1517</SECTION>
1518
1519<!-- =================================================================== -->
1520
1521<SECTION>
1522<TITLE>Global Cache Control</TITLE>
1523
1524<PROGRAMLISTING>
1525HAL_XCACHE_ENABLE()
1526HAL_XCACHE_DISABLE()
1527HAL_XCACHE_INVALIDATE_ALL()
1528HAL_XCACHE_SYNC()
1529HAL_XCACHE_BURST_SIZE( size )
1530HAL_DCACHE_WRITE_MODE( mode )
1531HAL_XCACHE_LOCK( base, size )
1532HAL_XCACHE_UNLOCK( base, size )
1533HAL_XCACHE_UNLOCK_ALL()
1534</PROGRAMLISTING>
1535
1536<PARA>
1537These macros affect the state of the entire cache, or a large part of
1538it.
1539</PARA>
1540
1541<VARIABLELIST>
1542  <VARLISTENTRY>
1543    <TERM>HAL_XCACHE_ENABLE() and HAL_XCACHE_DISABLE()</TERM>
1544    <LISTITEM>
1545      <PARA>Enable and disable the cache.</PARA>
1546    </LISTITEM>
1547  </VARLISTENTRY>
1548
1549  <VARLISTENTRY>
1550    <TERM>HAL_XCACHE_INVALIDATE_ALL()</TERM>
1551    <LISTITEM>
1552      <PARA>
1553      Causes the entire contents of the cache to be invalidated.
1554      Depending on the hardware, this may require the cache to be disabled
1555      during the invalidation process. If so, the implementation must
1556      use <function>HAL_XCACHE_IS_ENABLED()</function> to save and
1557      restore the previous state.
1558      </PARA>
1559      <note>
1560        <para>
1561        If this macro is called after
1562        <function>HAL_XCACHE_SYNC()</function> with the intention of clearing
1563        the cache (invalidating the cache after writing dirty data back to
1564        memory), you must prevent interrupts from happening between the two
1565        calls:
1566        </para>
1567<PROGRAMLISTING>
1568 ...
1569 HAL_DISABLE_INTERRUPTS(old);
1570 HAL_XCACHE_SYNC();
1571 HAL_XCACHE_INVALIDATE_ALL();
1572 HAL_RESTORE_INTERRUPTS(old);
1573 ...
1574</PROGRAMLISTING>
1575        <para>
1576        Since the operation may take a very long time, real-time
1577        responsiveness could be affected, so only do this when it is
1578        absolutely required and you know the delay will not interfere
1579        with the operation of drivers or the application.
1580        </para>
1581      </note>
1582    </LISTITEM>
1583  </VARLISTENTRY>
1584
1585  <VARLISTENTRY>
1586    <TERM>HAL_XCACHE_SYNC()</TERM>
1587    <LISTITEM>
1588      <PARA>
1589      Causes the contents of the cache to be brought into synchronization
1590      with the contents of memory. In some implementations this may be
1591      equivalent to <function>HAL_XCACHE_INVALIDATE_ALL()</function>.
1592      </PARA>
1593    </LISTITEM>
1594  </VARLISTENTRY>
1595
1596  <VARLISTENTRY>
1597    <TERM>HAL_XCACHE_BURST_SIZE()</TERM>
1598    <LISTITEM>
1599      <PARA>
1600      Allows the size of cache to/from memory bursts to
1601      be controlled. This macro will only be defined if this functionality
1602      is available.
1603      </PARA>
1604    </LISTITEM>
1605  </VARLISTENTRY>
1606 
1607  <VARLISTENTRY>
1608    <TERM>HAL_DCACHE_WRITE_MODE()</TERM>
1609    <LISTITEM>
1610      <PARA>
1611      Controls the way in which data cache lines are written back to
1612      memory. There will be definitions for the possible
1613      modes. Typical definitions are
1614      <literal>HAL_DCACHE_WRITEBACK_MODE</literal> and
1615      <literal>HAL_DCACHE_WRITETHRU_MODE</literal>. This macro will
1616      only be defined if this functionality is available.
1617      </PARA>
1618    </LISTITEM>
1619  </VARLISTENTRY>
1620
1621  <VARLISTENTRY>
1622    <TERM>HAL_XCACHE_LOCK()</TERM>
1623    <LISTITEM>
1624      <PARA>
1625      Causes data to be locked into the cache. The base and size
1626      arguments define the memory region that will be locked into the
1627      cache. It is architecture dependent whether more than one locked
1628      region is allowed at any one time, and whether this operation
1629      causes the cache to cease acting as a cache for addresses
1630      outside the region during the duration of the lock. This macro
1631      will only be defined if this functionality is available.
1632      </PARA>
1633    </LISTITEM>
1634  </VARLISTENTRY>
1635
1636  <VARLISTENTRY>
1637    <TERM>HAL_XCACHE_UNLOCK()</TERM>
1638    <LISTITEM>
1639      <PARA>
1640      Cancels the locking of the memory region given. This should
1641      normally correspond to a region supplied in a matching lock
1642      call.  This macro will only be defined if this functionality is
1643      available.
1644      </PARA>
1645    </LISTITEM>
1646  </VARLISTENTRY>
1647
1648  <VARLISTENTRY>
1649    <TERM>HAL_XCACHE_UNLOCK_ALL()</TERM>
1650    <LISTITEM>
1651      <PARA>
1652      Cancels all existing locked memory regions. This may be required
1653      as part of the cache initialization on some architectures. This
1654      macro will only be defined if this functionality is available.
1655      </PARA>
1656    </LISTITEM>
1657  </VARLISTENTRY>
1658</VARIABLELIST>
1659
1660</SECTION>
1661
1662<!-- =================================================================== -->
1663
1664<SECTION>
1665<TITLE>Cache Line Control</TITLE>
1666
1667<PROGRAMLISTING>
1668HAL_DCACHE_ALLOCATE( base , size )
1669HAL_DCACHE_FLUSH( base , size )
1670HAL_XCACHE_INVALIDATE( base , size )
1671HAL_DCACHE_STORE( base , size )
1672HAL_DCACHE_READ_HINT( base , size )
1673HAL_DCACHE_WRITE_HINT( base , size )
1674HAL_DCACHE_ZERO( base , size )
1675</PROGRAMLISTING>
1676
1677<PARA>
1678All of these macros apply a cache operation to all cache lines that
1679match the memory address region defined by the base and size
1680arguments. These macros will only be defined if the described
1681functionality is available. Also, it is not guaranteed that the cache
1682function will only be applied to just the described regions, in some
1683architectures it may be applied to the whole cache.
1684</PARA>
1685
1686<VARIABLELIST>
1687  <VARLISTENTRY>
1688    <TERM>HAL_DCACHE_ALLOCATE()</TERM>
1689    <LISTITEM>
1690      <PARA>
1691      Allocates lines in the cache for the given region without
1692      reading their contents from memory, hence the contents of the lines
1693      is undefined. This is useful for preallocating lines which are to
1694      be completely overwritten, for example in a block copy
1695      operation.
1696      </PARA>
1697    </LISTITEM>
1698  </VARLISTENTRY>
1699 
1700  <VARLISTENTRY>
1701    <TERM>HAL_DCACHE_FLUSH()</TERM>
1702    <LISTITEM>
1703      <PARA>
1704      Invalidates all cache lines in the region after writing any
1705      dirty lines to memory.
1706      </PARA>
1707    </LISTITEM>
1708  </VARLISTENTRY>
1709 
1710  <VARLISTENTRY>
1711    <TERM>HAL_XCACHE_INVALIDATE() </TERM>
1712    <LISTITEM>
1713      <PARA>
1714      Invalidates all cache lines in the region. Any dirty lines
1715      are invalidated without being written to memory.
1716      </PARA>
1717    </LISTITEM>
1718  </VARLISTENTRY>
1719 
1720  <VARLISTENTRY>
1721    <TERM>HAL_DCACHE_STORE() </TERM>
1722    <LISTITEM>
1723      <PARA>
1724      Writes all dirty lines in the region to memory, but does not
1725      invalidate any lines.
1726      </PARA>
1727    </LISTITEM>
1728  </VARLISTENTRY>
1729 
1730  <VARLISTENTRY>
1731    <TERM>HAL_DCACHE_READ_HINT() </TERM>
1732    <LISTITEM>
1733      <PARA>
1734      Hints to the cache that the region is going to be read from
1735      in the near future. This may cause the region to be speculatively
1736      read into the cache.
1737      </PARA>
1738    </LISTITEM>
1739  </VARLISTENTRY>
1740 
1741  <VARLISTENTRY>
1742    <TERM>HAL_DCACHE_WRITE_HINT() </TERM>
1743    <LISTITEM>
1744      <PARA>
1745      Hints to the cache that the region is going to be written
1746      to in the near future. This may have the identical behavior to
1747      HAL_DCACHE_READ_HINT().
1748      </PARA>
1749    </LISTITEM>
1750  </VARLISTENTRY>
1751
1752  <VARLISTENTRY>
1753    <TERM>HAL_DCACHE_ZERO()</TERM>
1754    <LISTITEM>
1755      <PARA>
1756      Allocates and zeroes lines in the cache for the given
1757      region without reading memory. This is useful if a large area of
1758      memory is to be cleared.
1759      </PARA>
1760    </LISTITEM>
1761  </VARLISTENTRY>
1762</VARIABLELIST>
1763
1764</SECTION>
1765</SECTION>
1766
1767<!-- }}} -->
1768<!-- {{{ Linker Scripts -->
1769
1770<SECTION id="hal-linker-scripts">
1771<TITLE><!-- <xref> -->Linker Scripts</TITLE>
1772
1773<para>
1774When an eCos application is linked it must be done under the control
1775of a linker script. This script defines the memory areas, addresses
1776and sized, into which the code and data are to be put, and allocates
1777the various sections generated by the compiler to these.
1778</para>
1779
1780<para>
1781The linker script actually used is in
1782<filename>lib/target.ld</filename> in the install directory. This is
1783actually manufactured out of two other files: a base linker script and
1784an <literal>.ldi</literal> file that was generated by the memory
1785layout tool.
1786</para>
1787
1788<para>
1789The base linker script is usually supplied either by the architecture
1790HAL or the variant HAL. It consists of a set of linker script
1791fragments, in the form of C preprocessor macros, that define the major
1792output sections to be generated by the link operation. The
1793<literal>.ldi</literal> file, which is <literal>#include'ed</literal>
1794by the base linker script, uses these macro definitions to assign the
1795output sections to the required memory areas and link addresses.
1796</para>
1797
1798<para>
1799The <literal>.ldi</literal> file is supplied by the platform HAL, and
1800contains knowledge of the memory layout of the target platform. These
1801files generally conform to a standard naming convention, each file
1802being of the form:
1803</para>
1804<para>
1805<filename>pkgconf/mlt_&lt;architecture&gt;_&lt;variant&gt;_&lt;platform&gt;_&lt;startup&gt;.ldi</filename>
1806</para>
1807<para>
1808where <literal>&lt;architecture&gt;</literal>,
1809<literal>&lt;variant&gt;</literal> and
1810<literal>&lt;platform&gt;</literal> are the respective HAL package
1811names and <literal>&lt;startup&gt;</literal> is the startup type which
1812is usually one of <literal>ROM</literal>, <literal>RAM</literal> or
1813<literal>ROMRAM</literal>.
1814</para>
1815
1816<para>
1817In addition to the <literal>.ldi</literal> file, there is also a
1818congruously name <literal>.h</literal> file. This may be used by the
1819application to access information defined in the
1820<literal>.ldi</literal> file. Specifically it contains the memory
1821layout defined there, together with any additional section names
1822defined by the user. Examples of the latter are heap areas or PCI bus
1823memory access windows.
1824</para>
1825
1826<para>
1827The <literal>.ldi</literal> is manufactured by the <application>Memory
1828Layout Tool</application> (MLT). The <application>MLT</application> saves the memory
1829configuration into a file named
1830</para>
1831<para>
1832<filename>include/pkgconf/mlt_&lt;architecture&gt;_&lt;variant&gt;_&lt;platform&gt;_&lt;startup&gt;.mlt</filename>
1833</para>
1834<para>
1835in the platform HAL. This file is used by the
1836<application>MLT</application> to manufacture both the
1837<literal>.ldi</literal> and <literal>.h</literal> files. Users should
1838beware that direct edits the either of these files may be overwritten
1839if the <application>MLT</application> is run and regenerates them from the
1840<literal>.mlt</literal> file.
1841</para>
1842
1843<para>
1844The names of the <literal>.ldi</literal> and <literal>.h</literal>
1845files are defined by macro definitions in
1846<FILENAME>pkgconf/system.h</FILENAME>. These are
1847<literal>CYGHWR_MEMORY_LAYOUT_LDI</literal> and
1848<literal>CYGHWR_MEMORY_LAYOUT_H</literal> respectively. While there
1849will be little need for the application to refer to the
1850<literal>.ldi</literal> file directly, it may include the
1851<literal>.h</literal> file as follows:
1852</para>
1853
1854<programlisting>
1855#include CYGHWR_MEMORY_LAYOUT_H
1856</programlisting>
1857
1858</SECTION>
1859
1860<!-- }}} -->
1861<!-- {{{ Diagnostic Support -->
1862
1863<SECTION id="hal-diagnostic-support">
1864<TITLE>Diagnostic Support</TITLE>
1865
1866<para>
1867The HAL provides support for low level diagnostic IO. This is
1868particularly useful during early development as an aid to bringing up
1869a new platform. Usually this diagnostic channel is a UART or some
1870other serial IO device, but it may equally be a a memory
1871buffer, a simulator supported output channel, a ROM emulator virtual
1872UART, and LCD panel, a memory mapped video buffer or any other output
1873device.
1874</para>
1875
1876<PARA>
1877<FUNCTION>HAL_DIAG_INIT()</FUNCTION> performs any initialization
1878required on the device being used to generate diagnostic output. This
1879may include, for a UART, setting baud rate, and stop, parity and
1880character bits. For other devices it may include initializing a
1881controller or establishing contact with a remote device.
1882</PARA>
1883
1884<PARA>
1885<FUNCTION>HAL_DIAG_WRITE_CHAR(c)</FUNCTION> writes
1886the character supplied to the diagnostic output device.
1887</PARA>
1888
1889<PARA>
1890<FUNCTION>HAL_DIAG_READ_CHAR(c)</FUNCTION> reads a character from the
1891diagnostic device into the supplied variable. This is not supported
1892for all diagnostic devices.
1893</PARA>
1894
1895<para>
1896These macros are defined in the header file
1897<filename>cyg/hal/hal_diag.h</filename>. This file is usually supplied
1898by the variant or platform HAL, depending on where the IO device being
1899used is located. For example for on-chip UARTs it would be in the
1900variant HAL, but for a board-level LCD panel it would be in the
1901platform HAL.
1902</para>
1903
1904</section>
1905
1906<!-- }}} -->
1907<!-- {{{ SMP Support -->
1908
1909<section id="hal-smp-support">
1910<TITLE>SMP Support</TITLE>
1911
1912<para>
1913eCos contains support for limited Symmetric Multi-Processing
1914(SMP). This is only available on selected architectures and platforms.
1915</para>
1916
1917<section>
1918<title>Target Hardware Limitations</title>
1919
1920<para>
1921To allow a reasonable implementation of SMP, and to reduce the
1922disruption to the existing source base, a number of assumptions have
1923been made about the features of the target hardware.
1924</para>
1925
1926<itemizedlist>
1927<listitem>
1928<para>
1929Modest multiprocessing. The typical number of CPUs supported is two
1930to four, with an upper limit around eight. While there are no
1931inherent limits in the code, hardware and algorithmic limitations
1932will probably become significant beyond this point.
1933</para>
1934</listitem>
1935
1936<listitem>
1937<para>
1938SMP synchronization support. The hardware must supply a mechanism to
1939allow software on two CPUs to synchronize. This is normally provided
1940as part of the instruction set in the form of test-and-set,
1941compare-and-swap or load-link/store-conditional instructions. An
1942alternative approach is the provision of hardware semaphore
1943registers which can be used to serialize implementations of these
1944operations. Whatever hardware facilities are available, they are
1945used in eCos to implement spinlocks.
1946</para>
1947</listitem>
1948
1949<listitem>
1950<para>
1951Coherent caches. It is assumed that no extra effort will be required
1952to access shared memory from any processor. This means that either
1953there are no caches, they are shared by all processors, or are
1954maintained in a coherent state by the hardware. It would be too
1955disruptive to the eCos sources if every memory access had to be
1956bracketed by cache load/flush operations. Any hardware that requires
1957this is not supported.
1958</para>
1959</listitem>
1960
1961<listitem>
1962<para>
1963Uniform addressing. It is assumed that all memory that is
1964shared between CPUs is addressed at the same location from all
1965CPUs. Like non-coherent caches, dealing with CPU-specific address
1966translation is considered too disruptive to the eCos source
1967base. This does not, however, preclude systems with non-uniform
1968access costs for different CPUs.
1969</para>
1970</listitem>
1971
1972<listitem>
1973<para>
1974Uniform device addressing. As with access to memory, it is assumed
1975that all devices are equally accessible to all CPUs. Since device
1976access is often made from thread contexts, it is not possible to
1977restrict access to device control registers to certain CPUs, since
1978there is currently no support for binding or migrating threads to CPUs.
1979</para>
1980</listitem>
1981
1982<listitem>
1983<para>
1984Interrupt routing. The target hardware must have an interrupt
1985controller that can route interrupts to specific CPUs. It is
1986acceptable for all interrupts to be delivered to just one CPU, or
1987for some interrupts to be bound to specific CPUs, or for some
1988interrupts to be local to each CPU. At present dynamic routing,
1989where a different CPU may be chosen each time an interrupt is
1990delivered, is not supported. ECos cannot support hardware where all
1991interrupts are delivered to all CPUs simultaneously with the
1992expectation that software will resolve any conflicts.
1993</para>
1994</listitem>
1995
1996<listitem>
1997<para>
1998Inter-CPU interrupts. A mechanism to allow one CPU to interrupt
1999another is needed. This is necessary so that events on one CPU can
2000cause rescheduling on other CPUs.
2001</para>
2002</listitem>
2003
2004<listitem>
2005<para>
2006CPU Identifiers. Code running on a CPU must be able to determine
2007which CPU it is running on. The CPU Id is usually provided either in
2008a CPU status register, or in a register associated with the
2009inter-CPU interrupt delivery subsystem. ECos expects CPU Ids to be
2010small positive integers, although alternative representations, such
2011as bitmaps, can be converted relatively easily. Complex mechanisms
2012for getting the CPU Id cannot be supported. Getting the CPU Id must
2013be a cheap operation, since it is done often, and in performance
2014critical places such as interrupt handlers and the scheduler.
2015</para>
2016</listitem>
2017</itemizedlist>
2018
2019</section> 
2020
2021<section>
2022<title>HAL Support</title>
2023
2024<para>
2025SMP support in any platform depends on the HAL supplying the
2026appropriate operations. All HAL SMP support is defined in the
2027<filename>cyg/hal/hal_smp.h</filename> header. Variant and platform
2028specific definitions will be in <filename>cyg/hal/var_smp.h</filename>
2029and <filename>cyg/hal/plf_smp.h</filename> respectively. These files
2030are include automatically by this header, so need not be included
2031explicitly.
2032</para>
2033
2034<para>
2035SMP support falls into a number of functional groups.
2036</para>
2037
2038<section>
2039<title>CPU Control</title>
2040
2041<para>
2042This group consists of descriptive and control macros for managing the
2043CPUs in an SMP system.
2044</para>
2045
2046<variablelist>
2047<varlistentry>
2048<term><literal>HAL_SMP_CPU_TYPE</literal></term>
2049<listitem>
2050<para>
2051A type that can contain a CPU id. A CPU id is
2052usually a small integer that is used to index
2053arrays of variables that are managed on an
2054per-CPU basis.
2055</para>
2056</listitem>
2057</varlistentry>
2058
2059<varlistentry>
2060<term><literal>HAL_SMP_CPU_MAX</literal></term>
2061<listitem>
2062<para>
2063The maximum number of CPUs that can be
2064supported. This is used to provide the size of
2065any arrays that have an element per CPU.
2066</para>
2067</listitem>
2068</varlistentry>
2069
2070<varlistentry>
2071<term><literal>HAL_SMP_CPU_COUNT()</literal></term>
2072<listitem>
2073<para>
2074Returns the number of CPUs currently
2075operational. This may differ from
2076HAL_SMP_CPU_MAX depending on the runtime
2077environment.
2078</para>
2079</listitem>
2080</varlistentry>
2081
2082<varlistentry>
2083<term><literal>HAL_SMP_CPU_THIS()</literal></term>
2084<listitem>
2085<para>
2086Returns the CPU id of the current CPU.
2087</para>
2088</listitem>
2089</varlistentry>
2090
2091<varlistentry>
2092<term><literal>HAL_SMP_CPU_NONE</literal></term>
2093<listitem>
2094<para>
2095A value that does not match any real CPU
2096id. This is uses where a CPU type variable
2097must be set to a null value.
2098</para>
2099</listitem>
2100</varlistentry>
2101
2102<varlistentry>
2103<term><literal>HAL_SMP_CPU_START( cpu )</literal></term>
2104<listitem>
2105<para>
2106Starts the given CPU executing at a defined
2107HAL entry point. After performing any HAL
2108level initialization, the CPU calls up into
2109the kernel at <function>cyg_kernel_cpu_startup()</function>.
2110</para>
2111</listitem>
2112</varlistentry>
2113
2114<varlistentry>
2115<term><literal>HAL_SMP_CPU_RESCHEDULE_INTERRUPT( cpu, wait )</literal></term>
2116<listitem>
2117<para>
2118Sends the CPU a reschedule interrupt, and if
2119<parameter>wait</parameter> is non-zero, waits for an
2120acknowledgment. The interrupted CPU should call
2121<function>cyg_scheduler_set_need_reschedule()</function> in its DSR to
2122cause the reschedule to occur.
2123</para>
2124</listitem>
2125</varlistentry>
2126
2127<varlistentry>
2128<term><literal>HAL_SMP_CPU_TIMESLICE_INTERRUPT( cpu, wait )</literal></term>
2129<listitem>
2130<para>
2131Sends the CPU a timeslice interrupt, and if
2132<parameter>wait</parameter> is non-zero, waits for an
2133acknowledgment. The interrupted CPU should call
2134<function>cyg_scheduler_timeslice_cpu()</function> to cause the
2135timeslice event to be processed.
2136</para>
2137</listitem>
2138</varlistentry>
2139</variablelist>
2140</section>
2141
2142
2143<section>
2144<title>Test-and-set Support</title>
2145
2146<para>
2147Test-and-set is the foundation of the SMP synchronization
2148mechanisms.
2149</para>
2150
2151<variablelist>
2152<varlistentry>
2153<term><literal>HAL_TAS_TYPE</literal></term>
2154<listitem>
2155<para>
2156The type for all test-and-set variables. The
2157test-and-set macros only support operations on
2158a single bit (usually the least significant
2159bit) of this location. This allows for maximum
2160flexibility in the implementation.
2161</para>
2162</listitem>
2163</varlistentry>
2164
2165<varlistentry>
2166<term><literal>HAL_TAS_SET( tas, oldb )</literal></term>
2167<listitem>
2168<para>
2169Performs a test and set operation on the
2170location <parameter>tas</parameter>. <parameter>oldb</parameter> will contain <literal>true</literal> if
2171the location was already set, and <literal>false</literal> if
2172it was clear.
2173</para>
2174</listitem>
2175</varlistentry>
2176
2177<varlistentry>
2178<term><literal>HAL_TAS_CLEAR( tas, oldb )</literal></term>
2179<listitem>
2180<para>
2181Performs a test and clear operation on the
2182location <parameter>tas</parameter>. <parameter>oldb</parameter> will contain <literal>true</literal> if
2183the location was already set, and <literal>false</literal> if
2184it was clear.
2185</para>
2186</listitem>
2187</varlistentry>
2188</variablelist>
2189</section>
2190<section>
2191
2192<title>Spinlocks</title>
2193
2194<para>
2195Spinlocks provide inter-CPU locking. Normally they will be implemented
2196on top of the test-and-set mechanism above, but may also be
2197implemented by other means if, for example, the hardware has more
2198direct support for spinlocks.
2199</para>
2200
2201<variablelist>
2202<varlistentry>
2203<term><literal>HAL_SPINLOCK_TYPE</literal></term>
2204<listitem>
2205<para>
2206The type for all spinlock variables.
2207</para>
2208</listitem>
2209</varlistentry>
2210
2211<varlistentry>
2212<term><literal>HAL_SPINLOCK_INIT_CLEAR</literal></term>
2213<listitem>
2214<para>
2215A value that may be assigned to a spinlock
2216variable to initialize it to clear.
2217</para>
2218</listitem>
2219</varlistentry>
2220
2221<varlistentry>
2222<term><literal>HAL_SPINLOCK_INIT_SET</literal></term>
2223<listitem>
2224<para>
2225A value that may be assigned to a spinlock
2226variable to initialize it to set.
2227</para>
2228</listitem>
2229</varlistentry>
2230
2231<varlistentry>
2232<term><literal>HAL_SPINLOCK_SPIN( lock )</literal></term>
2233<listitem>
2234<para>
2235The caller spins in a busy loop waiting for
2236the lock to become clear. It then sets it and
2237continues. This is all handled atomically, so
2238that there are no race conditions between CPUs.
2239</para>
2240</listitem>
2241</varlistentry>
2242
2243<varlistentry>
2244<term><literal>HAL_SPINLOCK_CLEAR( lock )</literal></term>
2245<listitem>
2246<para>
2247The caller clears the lock. One of any waiting
2248spinners will then be able to proceed.
2249</para>
2250</listitem>
2251</varlistentry>
2252
2253<varlistentry>
2254<term><literal>HAL_SPINLOCK_TRY( lock, val )</literal></term>
2255<listitem>
2256<para>
2257Attempts to set the lock. The value put in
2258<parameter>val</parameter> will be <literal>true</literal> if the lock was
2259claimed successfully, and <literal>false</literal> if it was
2260not.
2261</para>
2262</listitem>
2263</varlistentry>
2264
2265<varlistentry>
2266<term><literal>HAL_SPINLOCK_TEST( lock, val )</literal></term>
2267<listitem>
2268<para>
2269Tests the current value of the lock. The value
2270put in <parameter>val</parameter> will be <literal>true</literal> if the lock is
2271claimed and <literal>false</literal> of it is clear.
2272</para>
2273</listitem>
2274</varlistentry>
2275</variablelist>
2276</section>
2277<section>
2278
2279<title>Scheduler Lock</title>
2280
2281<para>
2282The scheduler lock is the main protection for all kernel data
2283structures. By default the kernel implements the scheduler lock itself
2284using a spinlock. However, if spinlocks cannot be supported by the
2285hardware, or there is a more efficient implementation available, the
2286HAL may provide macros to implement the scheduler lock.
2287</para>
2288
2289<variablelist>
2290<varlistentry>
2291<term><literal>HAL_SMP_SCHEDLOCK_DATA_TYPE</literal></term>
2292<listitem>
2293<para>
2294A data type, possibly a structure, that
2295contains any data items needed by the
2296scheduler lock implementation. A variable of
2297this type will be instantiated as a static
2298member of the Cyg_Scheduler_SchedLock class
2299and passed to all the following macros.
2300</para>
2301</listitem>
2302</varlistentry>
2303
2304<varlistentry>
2305<term><literal>HAL_SMP_SCHEDLOCK_INIT( lock, data )</literal></term>
2306<listitem>
2307<para>
2308Initialize the scheduler lock. The <parameter>lock</parameter>
2309argument is the scheduler lock counter and the
2310<parameter>data</parameter> argument is a variable of
2311HAL_SMP_SCHEDLOCK_DATA_TYPE type.
2312</para>
2313</listitem>
2314</varlistentry>
2315
2316<varlistentry>
2317<term><literal>HAL_SMP_SCHEDLOCK_INC( lock, data )</literal></term>
2318<listitem>
2319<para>
2320Increment the scheduler lock. The first
2321increment of the lock from zero to one for any
2322CPU may cause it to wait until the lock is
2323zeroed by another CPU. Subsequent increments
2324should be less expensive since this CPU
2325already holds the lock.
2326</para>
2327</listitem>
2328</varlistentry>
2329
2330<varlistentry>
2331<term><literal>HAL_SMP_SCHEDLOCK_ZERO( lock, data )</literal></term>
2332<listitem>
2333<para>
2334Zero the scheduler lock. This operation will
2335also clear the lock so that other CPUs may
2336claim it.
2337</para>
2338</listitem>
2339</varlistentry>
2340
2341<varlistentry>
2342<term><literal>HAL_SMP_SCHEDLOCK_SET( lock, data, new )</literal></term>
2343<listitem>
2344<para>
2345Set the lock to a different value, in
2346<parameter>new</parameter>. This is only called when the lock is
2347already known to be owned by the current CPU. It is never called to
2348zero the lock, or to increment it from zero.
2349</para>
2350</listitem>
2351</varlistentry>
2352
2353</variablelist>
2354</section>
2355<section>
2356
2357<title>Interrupt Routing</title>
2358
2359<para>
2360The routing of interrupts to different CPUs is supported by two new
2361interfaces in hal_intr.h.
2362</para>
2363
2364<para>
2365Once an interrupt has been routed to a new CPU, the existing vector
2366masking and configuration operations should take account of the CPU
2367routing. For example, if the operation is not invoked on the
2368destination CPU itself, then the HAL may need to arrange to transfer
2369the operation to the destination CPU for correct application.
2370</para>
2371
2372<variablelist>
2373<varlistentry>
2374<term><literal>HAL_INTERRUPT_SET_CPU( vector, cpu )</literal></term>
2375<listitem>
2376<para>
2377Route the interrupt for the given <parameter>vector</parameter> to
2378the given <parameter>cpu</parameter>.
2379</para>
2380</listitem>
2381</varlistentry>
2382
2383<varlistentry>
2384<term><literal>HAL_INTERRUPT_GET_CPU( vector, cpu )</literal></term>
2385<listitem>
2386<para>
2387Set <parameter>cpu</parameter> to the id of the CPU to which this
2388vector is routed.
2389</para>
2390</listitem>
2391</varlistentry>
2392</variablelist>
2393
2394</section>
2395
2396</section>
2397
2398
2399</section>
2400
2401<!-- }}} -->
2402
2403</CHAPTER>
2404
2405<!-- }}} -->
2406<!-- {{{ Exception Handling -->
2407
2408<CHAPTER id="hal-exception-handling">
2409<TITLE>Exception Handling</TITLE>
2410
2411<!-- {{{ Intro -->
2412
2413<para>
2414Most of the HAL consists of simple macros or functions that are
2415called via the interfaces described in the previous section. These
2416just perform whatever operation is required by accessing the hardware
2417and then return. The exception to this is the handling of exceptions:
2418either synchronous hardware traps or asynchronous device
2419interrupts. Here control is passed first to the HAL, which then passed
2420it on to eCos or the application. After eCos has finished with it,
2421control is then passed back to the HAL for it to tidy up the CPU state
2422and resume processing from the point at which the exception occurred.
2423</para>
2424
2425<PARA>
2426The HAL exceptions handling code is usually found in the file
2427<FILENAME>vectors.S</FILENAME> in the architecture HAL.  Since the
2428reset entry point is usually implemented as one of these it also deals
2429with system startup.
2430</PARA>
2431
2432<PARA>
2433The exact implementation of this code is under the control of the HAL
2434implementer. So long as it interacts correctly with the interfaces
2435defined previously it may take any form.  However, all current
2436implementation follow the same pattern, and there should be a very
2437good reason to break with this. The rest of this section describes
2438these operate.
2439</PARA>
2440
2441<para>
2442Exception handling normally deals with the following broad areas of
2443functionality:
2444</para>
2445
2446<ITEMIZEDLIST>
2447  <LISTITEM>
2448    <PARA>Startup and initialization.</PARA>
2449  </LISTITEM>
2450
2451  <LISTITEM>
2452    <PARA>Hardware exception delivery.</PARA>
2453  </LISTITEM>
2454 
2455  <LISTITEM>
2456    <PARA>Default handling of synchronous exceptions.</PARA>
2457  </LISTITEM>
2458 
2459  <LISTITEM>
2460    <PARA>Default handling of asynchronous interrupts.</PARA>
2461  </LISTITEM>
2462</ITEMIZEDLIST>
2463
2464<!-- }}} -->
2465<!-- {{{ HAL Startup -->
2466
2467<SECTION id="hal-startup">
2468<TITLE><!-- <index></index> --><!-- <xref> -->HAL Startup</TITLE>
2469
2470<PARA>
2471Execution normally begins at the reset vector with
2472the machine in a minimal startup state. From here the HAL needs to get
2473the machine running, set up the execution environment for the
2474application, and finally invoke its entry point.
2475</PARA>
2476
2477<PARA>
2478The following is a list of the jobs that need to be done in
2479approximately the order in which they should be accomplished. Many
2480of these will not be needed in some configurations.
2481</PARA>
2482
2483<ITEMIZEDLIST>
2484  <listitem>
2485  <para>
2486  Initialize the hardware. This may involve initializing several
2487  subsystems in both the architecture, variant and platform
2488  HALs. These include:
2489  </para>
2490    <itemizedlist>
2491      <LISTITEM>
2492        <PARA>
2493        Initialize various CPU status registers. Most importantly, the CPU
2494        interrupt mask should be set to disable interrupts.
2495        </PARA>
2496      </LISTITEM>
2497
2498      <LISTITEM>
2499        <PARA>
2500        Initialize the MMU, if it is used. On many platforms it is
2501        only possible to control the cacheability of address ranges
2502        via the MMU. Also, it may be necessary to remap RAM and device
2503        registers to locations other than their defaults. However, for
2504        simplicity, the mapping should be kept as close to one-to-one
2505        physical-to-virtual as possible.
2506        </PARA>
2507      </LISTITEM>
2508
2509      <LISTITEM>
2510        <PARA>
2511        Set up the memory controller to access RAM, ROM and I/O devices
2512        correctly. Until this is done it may not be possible to access
2513        RAM. If this is a ROMRAM startup then the program code can
2514        now be copied to its RAM address and control transferred to it.
2515        </PARA>
2516      </LISTITEM>
2517
2518      <LISTITEM>
2519        <PARA>
2520        Set up any bus bridges and support chips. Often access to
2521        device registers needs to go through various bus bridges and
2522        other intermediary devices. In many systems these are combined
2523        with the memory controller, so it makes sense to set these up
2524        together. This is particularly important if early diagnostic
2525        output needs to go through one of these devices.
2526        </PARA>
2527      </LISTITEM>
2528
2529      <LISTITEM>
2530        <PARA>
2531        Set up diagnostic mechanisms. If the platform includes an LED or
2532        LCD output device, it often makes sense to output progress
2533        indications on this during startup. This helps with diagnosing
2534        hardware and software errors.
2535        </PARA>
2536      </LISTITEM>
2537
2538      <LISTITEM>
2539        <PARA>
2540        Initialize floating point and other extensions such as SIMD
2541        and multimedia engines. It is usually necessary to enable
2542        these and maybe initialize control and exception registers for
2543        these extensions.
2544        </PARA>
2545      </LISTITEM>
2546
2547
2548      <LISTITEM>
2549        <PARA>
2550        Initialize interrupt controller. At the very least, it should
2551        be configured to mask all interrupts. It may also be necessary
2552        to set up the mapping from the interrupt controller's vector
2553        number space to the CPU's exception number space. Similar
2554        mappings may need to be set up between primary and secondary
2555        interrupt controllers.
2556        </PARA>
2557      </LISTITEM>
2558     
2559      <LISTITEM>
2560        <PARA>
2561        Disable and initialize the caches. The caches should not
2562        normally be enabled at this point, but it may be necessary to
2563        clear or initialize them so that they can be enabled
2564        later. Some architectures require that the caches be
2565        explicitly reinitialized after a power-on reset.
2566        </PARA>
2567      </LISTITEM>
2568
2569
2570      <LISTITEM>
2571        <PARA>
2572        Initialize the timer, clock etc. While the timer used for RTC
2573        interrupts will be initialized later, it may be necessary to
2574        set up the clocks that drive it here.
2575        </PARA>
2576      </LISTITEM>
2577     
2578    </itemizedlist>
2579    <para>
2580    The exact order in which these initializations is done is
2581    architecture or variant specific. It is also often not necessary
2582    to do anything at all for some of these options. These fragments
2583    of code should concentrate on getting the target up and running so
2584    that C function calls can be made and code can be run. More
2585    complex initializations that cannot be done in assembly code may
2586    be postponed until calls to
2587    <function>hal_variant_init()</function> or
2588    <function>hal_platform_init()</function> are made.
2589    </para>
2590
2591    <para>
2592    Not all of these initializations need to be done for all startup
2593    types. In particular, RAM startups can reasonably assume that the
2594    ROM monitor or loader has already done most of this work.
2595    </para>
2596   
2597  </listitem>
2598 
2599  <LISTITEM>
2600    <PARA>
2601    Set up the stack pointer, this allows subsequent initialization
2602    code to make proper procedure calls. Usually the interrupt stack
2603    is used for this purpose since it is available, large enough, and
2604    will be reused for other purposes later.
2605    </PARA>
2606  </LISTITEM>
2607 
2608  <LISTITEM>
2609    <PARA>
2610    Initialize any global pointer register needed for access to
2611    globally defined variables. This allows subsequent initialization
2612    code to access global variables.
2613    </PARA>
2614  </LISTITEM>
2615
2616  <LISTITEM>
2617    <PARA>
2618    If the system is starting from ROM, copy the ROM template of the
2619    <filename>.data</filename> section out to its correct position in
2620    RAM. (<xref linkend="hal-linker-scripts">).
2621    </PARA>
2622  </LISTITEM>
2623
2624  <LISTITEM>
2625    <PARA>
2626    Zero the <filename>.bss</filename> section.
2627    </PARA>
2628  </LISTITEM>
2629     
2630  <LISTITEM>
2631    <PARA>
2632    Create a suitable C call stack frame. This may involve making
2633    stack space for call frames, and arguments, and initializing the
2634    back pointers to halt a GDB backtrace operation.
2635    </PARA>
2636  </LISTITEM>
2637
2638  <LISTITEM>
2639    <PARA>
2640    Call <function>hal_variant_init()</function> and
2641    <function>hal_platform_init()</function>. These will perform any
2642    additional initialization needed by the variant and platform. This
2643    typically includes further initialization of the interrupt
2644    controller, PCI bus bridges, basic IO devices and enabling the
2645    caches.
2646    </PARA>
2647  </LISTITEM>
2648 
2649  <LISTITEM>
2650    <PARA>
2651    Call <FUNCTION>cyg_hal_invoke_constructors()</FUNCTION> to run any
2652    static constructors.
2653    </PARA>
2654  </LISTITEM>
2655 
2656  <LISTITEM>
2657    <PARA>
2658    Call <FUNCTION>cyg_start()</FUNCTION>. If
2659    <FUNCTION>cyg_start()</FUNCTION> returns, drop into an infinite
2660    loop.
2661    </PARA>
2662  </LISTITEM>
2663</ITEMIZEDLIST>
2664
2665</SECTION>
2666
2667<!-- }}} -->
2668<!-- {{{ Vectors and VSRs -->
2669
2670<SECTION id="hal-vectors-and-vsrs"><!-- <index></index> -->
2671<TITLE>Vectors and VSRs</TITLE>
2672
2673<PARA>
2674The CPU delivers all <!-- <index></index> --> exceptions, whether
2675synchronous faults or asynchronous interrupts, to a set of hardware
2676defined vectors. Depending on the architecture, these may be
2677implemented in a number of different ways. Examples of existing
2678mechanisms are:
2679</PARA>
2680
2681<VARIABLELIST>
2682  <VARLISTENTRY>
2683    <TERM>PowerPC</TERM>
2684    <LISTITEM>
2685      <PARA>
2686      Exceptions are vectored to locations 256 bytes apart starting at
2687      either zero or <literal>0xFFF00000</literal>. There are 16 such
2688      vectors defined by the basic architecture and extra vectors may
2689      be defined by specific variants. One of the base vectors is for
2690      all external interrupts, and another is for the architecture
2691      defined timer.
2692      </PARA>
2693    </LISTITEM>
2694  </VARLISTENTRY>
2695 
2696  <VARLISTENTRY>
2697    <TERM>MIPS</TERM>
2698    <LISTITEM>
2699      <PARA>
2700      Most exceptions and all interrupts are vectored to a single
2701      address at either <literal>0x80000000</literal> or
2702      <literal>0xBFC00180</literal>. Software is responsible for
2703      reading the exception code from the CPU <literal>cause</literal>
2704      register to discover its true source. Some TLB and debug
2705      exceptions are delivered to different vector addresses, but
2706      these are not used currently by eCos. One of the exception codes
2707      in the <literal>cause</literal> register indicates an external
2708      interrupt. Additional bits in the <literal>cause</literal>
2709      register provide a first-level decode for the interrupt source,
2710      one of which represents an architecture defined timer.
2711      </PARA>
2712    </LISTITEM>
2713  </VARLISTENTRY>
2714
2715  <VARLISTENTRY>
2716    <TERM>IA32</TERM>
2717    <LISTITEM>
2718      <PARA>
2719      Exceptions are delivered via an Interrupt Descriptor Table (IDT)
2720      which is essentially an indirection table indexed by exception
2721      number. The IDT may be placed anywhere in memory. In PC hardware
2722      the standard interrupt controller can be programmed to deliver
2723      the external interrupts to a block of 16 vectors at any offset
2724      in the IDT. There is no hardware supplied mechanism for
2725      determining the vector taken, other than from the address jumped
2726      to.
2727      </PARA>
2728    </LISTITEM>
2729  </VARLISTENTRY>
2730 
2731  <VARLISTENTRY>
2732    <TERM>ARM</TERM>
2733    <LISTITEM>
2734      <PARA>
2735      All exceptions, including the FIQ and IRQ interrupts, are
2736      vectored to locations four bytes apart starting at zero. There
2737      is only room for one instruction here, which must immediately
2738      jump out to handling code higher in memory. Interrupt sources
2739      have to be decoded entirely from the interrupt controller.
2740      </PARA>
2741    </LISTITEM>
2742  </VARLISTENTRY>
2743</VARIABLELIST>
2744
2745
2746<para>
2747With such a wide variety of hardware approaches, it is not possible to
2748provide a generic mechanism for the substitution of exception vectors
2749directly. Therefore, eCos translates all of these mechanisms in to a
2750common approach that can be used by portable code on all platforms.
2751</para>
2752
2753<para>
2754The mechanism implemented is to attach to each hardware vector a short
2755piece of trampoline code that makes an indirect jump via a table to
2756the actual handler for the exception. This handler is called the
2757Vector Service Routine (VSR) and the table is called the VSR table.
2758</para>
2759
2760<para>
2761The trampoline code performs the absolute minimum processing necessary
2762to identify the exception source, and jump to the VSR. The VSR is then
2763responsible for saving the CPU state and taking the necessary actions
2764to handle the exception or interrupt. The entry conditions for the VSR
2765are as close to the raw hardware exception entry state as possible -
2766although on some platforms the trampoline will have had to move or
2767reorganize some registers to do its job.
2768</para>
2769
2770<para>
2771To make this more concrete, consider how the trampoline code operates
2772in each of the architectures described above:
2773</para>
2774
2775
2776<VARIABLELIST>
2777  <VARLISTENTRY>
2778    <TERM>PowerPC</TERM>
2779    <LISTITEM>
2780      <PARA>
2781      A separate trampoline is contained in each of the vector
2782      locations. This code saves a few work registers away to the
2783      special purposes registers available, loads the exception number
2784      into a register and then uses that to index the VSR table and
2785      jump to the VSR. The VSR is entered with some registers move to
2786      the SPRs, and one of the data register containing the number of
2787      the vector taken.
2788      </PARA>
2789    </LISTITEM>
2790  </VARLISTENTRY>
2791 
2792  <VARLISTENTRY>
2793    <TERM>MIPS</TERM>
2794    <LISTITEM>
2795      <PARA>
2796      A single trampoline routine attached to the common vector reads
2797      the exception code out of the <literal>cause</literal> register
2798      and uses that value to index the VSR table and jump to the VSR.
2799      The trampoline uses the two registers defined in the ABI for
2800      kernel use to do this, one of these will contain the exception
2801      vector number for the VSR.
2802      </PARA>
2803    </LISTITEM>
2804  </VARLISTENTRY>
2805
2806  <VARLISTENTRY>
2807    <TERM>IA32</TERM>
2808    <LISTITEM>
2809      <PARA>
2810      There is a separate 3 or 4 instruction trampoline pointed to by
2811      each active IDT table entry. The trampoline for exceptions that
2812      also have an error code pop it from the stack and put it into a
2813      memory location. Trampolines for non-error-code exceptions just
2814      zero the memory location. Then all trampolines push an
2815      interrupt/exception number onto the stack, and take an indirect
2816      jump through a precalculated offset in the VSR table. This is
2817      all done without saving any registers, using memory-only
2818      operations. The VSR is entered with the vector number pushed
2819      onto the stack on top of the standard hardware saved state.
2820      </PARA>
2821    </LISTITEM>
2822  </VARLISTENTRY>
2823   
2824  <VARLISTENTRY>
2825    <TERM>ARM</TERM>
2826    <LISTITEM>
2827      <PARA>
2828      The trampoline consists solely of the single instruction at the
2829      exception entry point. This is an indirect jump via a location
2830      32 bytes higher in memory. These locations, from
2831      <literal>0x20</literal> up, form the VSR table. Since each VSR
2832      is entered in a different CPU mode
2833      (<literal>SVC,UNDEF,ABORT,IRQ or FIQ</literal>) there has to be a
2834      different VSR for each exception that knows how to save the CPU
2835      state correctly.
2836      </PARA>
2837    </LISTITEM>
2838  </VARLISTENTRY>
2839</VARIABLELIST>
2840
2841</section>
2842
2843<!-- }}} -->
2844<!-- {{{ Synchronous Exception Handling -->
2845
2846<SECTION id="hal-default-synchronous-exception-handling">
2847<TITLE><!-- <index></index> -->Default Synchronous Exception Handling</TITLE>
2848
2849<PARA>
2850Most synchronous exception VSR table entries will point to a default
2851exception VSR which is responsible for handling all exceptions in a
2852generic manner. The default VSR simply saves the CPU state, makes any
2853adjustments to the CPU state that is necessary, and calls
2854<function>cyg_hal_exception_handler()</function>.
2855</PARA>
2856
2857<PARA>
2858<function>cyg_hal_exception_handler()</function> needs to pass the
2859exception on to some handling code.  There are two basic destinations:
2860enter GDB or pass the exception up to eCos. Exactly which
2861destination is taken depends on the configuration. When the GDB stubs are
2862included then the exception is passed to them, otherwise it is passed
2863to eCos.
2864</PARA>
2865
2866<para>
2867If an eCos application has been loaded by RedBoot then the VSR table
2868entries will all point into RedBoot's exception VSR, and will
2869therefore enter GDB if an exception occurs. If the eCos application
2870wants to handle an exception itself, it needs to replace the the VSR
2871table entry with one pointing to its own VSR. It can do this with the
2872<function>HAL_VSR_SET_TO_ECOS_HANDLER()</function> macro.
2873</para>
2874
2875</SECTION>
2876
2877<!-- }}} -->
2878<!-- {{{ Interrupt Handling -->
2879
2880<SECTION id="hal-default-interrupt-handling">
2881<TITLE><!-- <index></index> -->Default Interrupt Handling</TITLE>
2882
2883<PARA>
2884Most asynchronous external interrupt vectors will point to a default
2885interrupt VSR which decodes the actual interrupt being delivered from
2886the interrupt controller and invokes the appropriate ISR.
2887</PARA>
2888
2889<PARA>
2890The default interrupt VSR has a number of responsibilities if it is
2891going to interact with the Kernel cleanly and allow interrupts to
2892cause thread preemption.
2893</PARA>
2894
2895<PARA>
2896To support this VSR an ISR vector table is needed. For each valid
2897vector three pointers need to be stored: the ISR, its data pointer and
2898an opaque (to the HAL) interrupt object pointer needed by the
2899kernel. It is implementation defined whether these are stored in a
2900single table of triples, or in three separate tables.
2901</PARA>
2902
2903<PARA>
2904The VSR follows the following approximate plan:
2905</PARA>
2906
2907<ORDEREDLIST>
2908  <LISTITEM>
2909    <PARA>
2910    Save the CPU state. In non-debug configurations, it may be
2911    possible to get away with saving less than the entire machine
2912    state. The option
2913    <literal>CYGDBG_HAL_COMMON_INTERRUPTS_SAVE_MINIMUM_CONTEXT</literal>
2914    is supported in some targets to do this.
2915    </PARA>
2916  </LISTITEM>
2917 
2918  <LISTITEM>
2919    <PARA>
2920    Increment the kernel scheduler lock. This is a static member of
2921    the Cyg_Scheduler class, however it has also been aliased to
2922    <literal>cyg_scheduler_sched_lock</literal> so that it can be
2923    accessed from assembly code.
2924    </PARA>
2925  </LISTITEM>
2926 
2927  <LISTITEM>
2928    <PARA>
2929    (Optional) Switch to an interrupt stack if not already running on
2930    it. This allows nested interrupts to be delivered without needing
2931    every thread to have a stack large enough to take the maximum
2932    possible nesting. It is implementation defined how to detect
2933    whether this is a nested interrupt but there are two basic
2934    techniques. The first is to inspect the stack pointer and switch
2935    only if it is not currently within the interrupt stack range; the
2936    second is to maintain a counter of the interrupt nesting level and
2937    switch only if it is zero. The option
2938    <literal>CYGIMP_HAL_COMMON_INTERRUPTS_USE_INTERRUPT_STACK</literal>
2939    controls whether this happens.
2940    </PARA>
2941  </LISTITEM>
2942 
2943  <LISTITEM>
2944    <PARA>
2945    Decode the actual external interrupt being delivered from
2946    the interrupt controller. This will yield the ISR vector
2947    number. The code to do this usually needs to come from the
2948    variant or platform HAL, so is usually present in the form of a
2949    macro or procedure callout.
2950    </PARA>
2951  </LISTITEM>
2952 
2953  <LISTITEM>
2954    <PARA>
2955    (Optional) Re-enable interrupts to permit nesting. At this point
2956    we can potentially allow higher priority interrupts to occur. It
2957    depends on the interrupt architecture of the CPU and platform
2958    whether more interrupts will occur at this point, or whether they
2959    will only be delivered after the current interrupt has been
2960    acknowledged (by a call to
2961    <function>HAL_INTERRUPT_ACKNOWLEDGE()</function> in the ISR).
2962    </PARA>
2963  </LISTITEM>
2964 
2965  <LISTITEM>
2966    <PARA>
2967    Using the ISR vector number as an index, retrieve the
2968    ISR pointer and its data pointer from the ISR vector table.
2969    </PARA>
2970  </LISTITEM>
2971 
2972  <LISTITEM>
2973    <PARA>
2974    Construct a C call stack frame. This may involve making stack
2975    space for call frames, and arguments, and initializing the back
2976    pointers to halt a GDB backtrace operation.
2977    </PARA>
2978  </LISTITEM>
2979 
2980  <LISTITEM>
2981    <PARA>
2982    Call the ISR, passing the vector number and data pointer.  The
2983    vector number and a pointer to the saved state should be preserved
2984    across this call, preferably by storing them in registers that are
2985    defined to be callee-saved by the calling conventions.
2986    </PARA>
2987  </LISTITEM>
2988 
2989  <LISTITEM>
2990    <PARA>
2991    If this is an un-nested interrupt and a separate interrupt
2992    stack is being used, switch back to the interrupted thread's
2993    own stack.
2994    </PARA>
2995  </LISTITEM>
2996 
2997  <LISTITEM>
2998    <PARA>
2999    Use the saved ISR vector number to get the interrupt object
3000    pointer from the ISR vector table.
3001    </PARA>
3002  </LISTITEM>
3003 
3004  <LISTITEM>
3005    <PARA>
3006    Call <FUNCTION>interrupt_end()</FUNCTION> passing it the return
3007    value from the ISR, the interrupt object pointer and a pointer to
3008    the saved CPU state. This function is implemented by the Kernel
3009    and is responsible for finishing off the interrupt
3010    handling. Specifically, it may post a DSR depending on the ISR
3011    return value, and will decrement the scheduler lock. If the lock
3012    is zeroed by this operation then any posted DSRs may be called and
3013    may in turn result in a thread context switch.
3014    </PARA>
3015  </LISTITEM>
3016 
3017  <LISTITEM>
3018    <PARA>
3019    The return from <FUNCTION>interrupt_end()</FUNCTION> may occur
3020    some time after the call. Many other threads may have executed in
3021    the meantime. So here all we may do is restore the machine state
3022    and resume execution of the interrupted thread. Depending on the
3023    architecture, it may be necessary to disable interrupts again for
3024    part of this.
3025    </PARA>
3026  </LISTITEM>
3027 
3028</ORDEREDLIST>
3029
3030<PARA>
3031The detailed order of these steps may vary slightly depending on the
3032architecture, in particular where interrupts are enabled and disabled.
3033</PARA>
3034
3035</SECTION>
3036
3037<!-- }}} -->
3038
3039</CHAPTER>
3040
3041<!-- }}} -->
3042<!-- {{{ Porting Guide -->
3043
3044&hal-common-porting-sgml;
3045
3046<!-- }}} -->
3047<!-- {{{ Future Developments -->
3048
3049<CHAPTER id="hal-future-developments">
3050<TITLE><!-- <index></index> --><!-- <xref> -->Future developments</TITLE>
3051
3052<PARA>
3053The HAL is not complete, and will evolve and increase over
3054time. Among the intended developments are:
3055</PARA>
3056<ITEMIZEDLIST>
3057<LISTITEM>
3058<PARA>Common macros for interpreting the contents of a saved
3059machine context. These would allow portable code, such as debug
3060stubs, to extract such values as the program counter and stack pointer
3061from a state without having to interpret a <STRUCTNAME>HAL_SavedRegisters</STRUCTNAME> structure
3062directly.</PARA>
3063</LISTITEM>
3064<LISTITEM>
3065<PARA>Debugging support. Macros to set and clear hardware and
3066software breakpoints. Access to other areas of machine state may
3067also be supported.</PARA>
3068</LISTITEM>
3069<LISTITEM>
3070<PARA>Static initialization support. The current HAL provides a
3071dynamic interface to things like thread context initialization and ISR
3072attachment. We also need to be able to define the system entirely
3073statically so that it is ready to go on restart, without needing to
3074run code. This will require extra macros to define these
3075initializations.  Such support may have a consequential effect on the
3076current HAL specification.</PARA>
3077</LISTITEM>
3078<LISTITEM>
3079<PARA>CPU state control. Many CPUs have both kernel and user
3080states. Although it is not intended to run any code in user state
3081for the foreseeable future, it is possible that this may happen
3082eventually. If this is the case, then some minor changes may be needed
3083to the current HAL API to accommodate this. These should mostly
3084be extensions, but minor changes in semantics may also be required.</PARA>
3085</LISTITEM>
3086<LISTITEM>
3087<PARA>Physical memory management. Many embedded systems have
3088multiple memory areas with varying properties such as base address,
3089size, speed, bus width, cacheability and persistence. An API is
3090needed to support the discovery of this information about the machine's
3091physical memory map.</PARA>
3092</LISTITEM>
3093<LISTITEM>
3094<PARA>Memory management control. Some embedded processors have
3095a memory management unit. In some cases this must be enabled to
3096allow the cache to be controlled, particularly if different regions
3097of memory must have different caching properties. For some purposes,
3098in some systems, it will be useful to manipulate the MMU settings
3099dynamically.</PARA>
3100</LISTITEM>
3101<LISTITEM>
3102<PARA>Power management. Macros to access and control any power
3103management mechanisms available on the CPU implementation. These
3104would provide a substrate for a more general power management system
3105that also involved device drivers and other hardware components.</PARA>
3106</LISTITEM>
3107<LISTITEM>
3108<PARA>Generic serial line macros. Most serial line devices operate
3109in the same way, the only real differences being exactly which bits
3110in which registers perform the standard functions. It should be
3111possible to develop a set of HAL macros that provide basic serial
3112line services such as baud rate setting, enabling interrupts, polling
3113for transmit or receive ready, transmitting and receiving data etc.
3114Given these it should be possible to create a generic serial line
3115device driver that will allow rapid bootstrapping on any new platform.
3116It may be possible to extend this mechanism to other device types.</PARA>
3117</LISTITEM>
3118</ITEMIZEDLIST>
3119</CHAPTER>
3120
3121<!-- }}} -->
3122
3123</part>
Note: See TracBrowser for help on using the repository browser.