1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE=" Porting Guide"
23 HREF="hal-porting-guide.html"><LINK
25 TITLE=" Porting Guide"
26 HREF="hal-porting-guide.html"><LINK
28 TITLE="Virtual Vectors (eCos/ROM Monitor Calling Interface)"
29 HREF="hal-calling-if.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="hal-porting-guide.html"
65 >Chapter 11. Porting Guide</TD
71 HREF="hal-calling-if.html"
85 NAME="HAL-PORTING-STRUCTURE">HAL Structure</H1
87 >In order to write an eCos HAL it's a good idea to have at least a
88 passing understanding of how the HAL interacts with the rest of the
95 NAME="AEN8659">HAL Classes</H2
97 >The eCos HAL consists of four HAL sub-classes. This table gives a
98 brief description of each class and partly reiterates the description
100 HREF="hal-architecture-variant-and-platform.html"
103 refer to the on-line CVS tree (specifically to the sub-HALs used by
104 the PowerPC MBX target).</P
106 CLASS="INFORMALTABLE"
126 >Functionality Overview</TH
135 HREF="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/common/current?cvsroot=ecos"
142 >Configuration options and functionality shared by all HALs.</TD
146 >Generic debugging functionality, driver API, eCos/ROM monitor
147 calling interface, and tests.</TD
154 HREF="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/arch/current?cvsroot=ecos"
156 >(hal/<architecture>/arch)</A
161 >Functionality specific to the given architecture. Also default
162 implementations of some functionality which can be overridden by
163 variant or platform HALs.</TD
167 >Architecture specific debugger functionality (handles single
168 stepping, exception-to-signal conversion, etc.),
169 exception/interrupt vector definitions and handlers, cache
170 definition and control macros, context switching code, assembler
171 functions for early system initialization, configuration options,
172 and possibly tests. </TD
179 HREF="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/mpc8xx/current?cvsroot=ecos"
181 >(hal/<architecture>/<variant>)</A
186 >Some CPU architectures consist of a number variants, for example
187 MIPS CPUs come in both 32 and 64 bit versions, and some variants
188 have embedded features additional to the CPU core.</TD
192 >Variant extensions to the architecture code (cache,
193 exception/interrupt), configuration options, possibly drivers for
194 variant on-core devices, and possibly tests.</TD
201 HREF="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/mbx/current?cvsroot=ecos"
203 >(hal/<architecture>/<platform>)</A
208 >Contains functionality and configuration options specific to the
213 >Early platform initialization code, platform memory layout
214 specification, configuration options (processor speed, compiler
215 options), diagnostic IO functions, debugger IO functions,
216 platform specific extensions to architecture or variant code
217 (off-core interrupt controller), and possibly tests.</TD
224 HREF="http://sourceware.cygnus.com/cgi-bin/cvsweb.cgi/ecos/packages/hal/powerpc/quicc/current?cvsroot=ecos"
226 >(hal/<architecture>/<module>)</A
231 >Some variants share common modules on the core. Motorola's PowerPC
232 QUICC is an example of such a module.</TD
236 >Module specific functionality (interrupt controller, simple
237 device drivers), possibly tests.</TD
250 NAME="AEN8696">File Descriptions</H2
252 >Listed below are the files found in various HALs, with a short
253 description of what each file contains. When looking in existing HALs
254 beware that they do not necessarily follow this naming scheme.
255 If you are writing a new HAL, please try to follow it as
256 closely as possible. Still, no two targets are the same, so sometimes
257 it makes sense to use additional files.</P
263 NAME="AEN8699">Common HAL</H3
265 CLASS="INFORMALTABLE"
291 >include/dbg-thread-syscall.h</TT
296 >Defines the thread debugging syscall function. This is used by
297 the ROM monitor to access the thread debugging API in the RAM
306 >include/dbg-threads-api.h</TT
311 >Defines the thread debugging API. .</TD
319 >include/drv_api.h</TT
324 >Defines the driver API.</TD
332 >include/generic-stub.h</TT
337 >Defines the generic stub features.</TD
345 >include/hal_if.h</TT
350 >Defines the ROM/RAM calling interface API.</TD
358 >include/hal_misc.h</TT
363 >Defines miscellaneous helper functions shared by all HALs.</TD
371 >include/hal_stub.h</TT
376 >Defines eCos mappings of GDB stub features.</TD
384 >src/dbg-threads-syscall.c</TT
389 >Thread debugging implementation.</TD
402 >Driver API implementation. Depending on configuration this
403 provides either wrappers for the kernel API, or a minimal
404 implementation of these features. This allows drivers to be written
405 relying only on HAL features.</TD
418 >Empty dummy file ensuring creation of libtarget.a.</TD
426 >src/generic-stub.c</TT
431 >Generic GDB stub implementation. This provides the
432 communication protocol used to communicate with GDB over a serial
433 device or via the network.</TD
446 >ROM/RAM calling interface implementation. Provides wrappers from
447 the calling interface API to the eCos features used for the
461 >Various helper functions shared by all platforms and
475 >Wrappers from eCos HAL features to the features required by the
476 generic GDB stub.</TD
484 >src/stubrom/stubrom.c</TT
489 >The file used to build eCos GDB stub images. Basically a
490 cyg_start function with a hard coded breakpoint.</TD
498 >src/thread-packets.c</TT
503 >More thread debugging related functions.</TD
511 >src/thread-pkts.h</TT
516 >Defines more thread debugging related function.</TD
529 NAME="AEN8776">Architecture HAL</H3
531 >Some architecture HALs may add extra files for architecture
532 specific serial drivers, or for handling interrupts and exceptions if it
535 >Note that many of the definitions in these files are only
536 conditionally defined - if the equivalent variant or platform headers
537 provide the definitions, those override the generic architecture
540 CLASS="INFORMALTABLE"
566 >include/arch.inc</TT
571 >Various assembly macros used during system initialization.</TD
579 >include/basetype.h</TT
584 >Endian, label, alignment, and type size definitions. These
585 override common defaults in CYGPKG_INFRA.</TD
593 >include/hal_arch.h</TT
598 >Saved register frame format, various thread, register and stack
607 >include/hal_cache.h</TT
612 >Cache definitions and cache control macros.</TD
620 >include/hal_intr.h</TT
625 >Exception and interrupt definitions. Macros for configuring and
626 controlling interrupts. eCos real-time clock control macros.</TD
634 >include/hal_io.h</TT
639 >Macros for accessing IO devices.</TD
647 >include/<arch>_regs.h</TT
652 >Architecture register definitions.</TD
660 >include/<arch>_stub.h</TT
665 >Architecture stub definitions. In particular the register frame
666 layout used by GDB. This may differ from the one used by eCos.</TD
674 >include/<arch>.inc</TT
679 >Architecture convenience assembly macros.</TD
687 >src/<arch>.ld</TT
705 >Functions handling context switching and setjmp/longjmp.</TD
718 >Exception and interrupt handlers in C. Various other utility
727 >src/hal_mk_defs.c</TT
732 >Used to export definitions from C header files to assembler
746 >Any necessary interrupt handling functions.</TD
754 >src/<arch>stub.c</TT
759 >Architecture stub code. Contains functions for translating eCos
760 exceptions to UNIX signals and functions for single-stepping.</TD
773 >Exception, interrupt and early initialization code.</TD
786 NAME="AEN8851">Variant HAL</H3
788 >Some variant HALs may add extra files for variant specific serial
789 drivers, or for handling interrupts/exceptions if it makes sense.</P
791 >Note that these files may be mostly empty if the CPU variant can be
792 controlled by the generic architecture macros. The definitions present
793 are only conditionally defined - if the equivalent platform headers
794 provide the definitions, those override the variant definitions.</P
796 CLASS="INFORMALTABLE"
822 >include/var_arch.h</TT
827 >Saved register frame format, various thread, register and stack
836 >include/var_cache.h</TT
841 >Cache related macros.</TD
849 >include/var_intr.h</TT
854 >Interrupt related macros.</TD
862 >include/var_regs.h</TT
867 >Extra register definitions for the CPU variant.</TD
875 >include/variant.inc</TT
880 >Various assembly macros used during system initialization.</TD
893 >Interrupt functions if necessary.</TD
906 >hal_variant_init function and any necessary extra functions.</TD
919 >Interrupt handler table definition.</TD
927 >src/<arch>_<variant>.ld</TT
945 NAME="AEN8898">Platform HAL</H3
947 >Extras files may be added for platform specific serial
948 drivers. Extra files for handling interrupts and exceptions will be
949 present if it makes sense.</P
951 CLASS="INFORMALTABLE"
977 >include/hal_diag.h</TT
982 >Defines functions used for HAL diagnostics output. This would
983 normally be the ROM calling interface wrappers, but may also be the
984 low-level IO functions themselves, saving a little overhead.</TD
992 >include/platform.inc</TT
997 >Platform initialization code. This includes memory controller,
998 vectors, and monitor initialization. Depending on the architecture,
999 other things may need defining here as well: interrupt decoding,
1000 status register initialization value, etc.</TD
1008 >include/plf_cache.h</TT
1013 >Platform specific cache handling.</TD
1021 >include/plf_intr.h</TT
1026 >Platform specific interrupt handling.</TD
1034 >include/plf_io.h</TT
1039 >PCI IO definitions and macros. May also be used to override
1040 generic HAL IO macros if the platform endianness differs from that of
1049 >include/plf_stub.h</TT
1054 >Defines stub initializer and board reset details.</TD
1067 >May contain the low-level device drivers. But these may also
1068 reside in plf_stub.c</TD
1081 >Memory controller setup macro, and if necessary interrupt
1082 springboard code.</TD
1095 >Platform initialization code.</TD
1103 >src/plf_mk_defs.c</TT
1108 >Used to export definitions from C header files to assembler
1122 >Platform specific stub initialization and possibly the low-level
1131 >The platform HAL also contains files specifying the platform's
1132 memory layout. These files are located in
1135 >include/pkgconf</TT
1143 NAME="AEN8954">Auxiliary HAL</H3
1145 >Auxiliary HALs contain whatever files are necessary to provide the
1146 required functionality. There are no predefined set of files required
1147 in an auxiliary HAL.</P
1156 SUMMARY="Footer navigation table"
1167 HREF="hal-porting-guide.html"
1176 HREF="ecos-ref.html"
1185 HREF="hal-calling-if.html"
1201 HREF="hal-porting-guide.html"
1209 >Virtual Vectors (eCos/ROM Monitor Calling Interface)</TD