--- /dev/null
+<!-- Copyright (C) 2003 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/). -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>Variant HAL Porting</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE=" Porting Guide"
+HREF="hal-porting-guide.html"><LINK
+REL="PREVIOUS"
+TITLE="Platform HAL Porting"
+HREF="hal-porting-platform.html"><LINK
+REL="NEXT"
+TITLE="Architecture HAL Porting"
+HREF="hal-porting-architecture.html"></HEAD
+><BODY
+CLASS="SECTION"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="hal-porting-platform.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 11. Porting Guide</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="hal-porting-architecture.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="HAL-PORTING-VARIANT">Variant HAL Porting</H1
+><P
+>A variant port can be a fairly limited job, but can also
+require quite a lot of work. A variant HAL describes how a specific
+CPU variant differs from the generic CPU architecture. The variant HAL
+can re-define cache, MMU, interrupt, and other features which override
+the default implementation provided by the architecture HAL.</P
+><P
+>Doing a variant port requires a preexisting architecture HAL port. It
+is also likely that a platform port will have to be done at the same
+time if it is to be tested.</P
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN9745">HAL Variant Porting Process</H2
+><P
+>The easiest way to make a new variant HAL is simply to copy an
+existing variant HAL and change all the files to match the new
+variant. If this is the first variant for an architecture, it may be
+hard to decide which parts should be put in the variant - knowledge of
+other variants of the architecture is required.</P
+><P
+>Looking at existing variant HALs (e.g., MIPS tx39, tx49) may be a
+help - usually things such as caching, interrupt and exception
+handling differ between variants. Initialization code, and code for
+handling various core components (FPU, DSP, MMU, etc.) may also differ
+or be missing altogether on some variants. Linker scripts may also require
+specific variant versions.</P
+><DIV
+CLASS="NOTE"
+><BLOCKQUOTE
+CLASS="NOTE"
+><P
+><B
+>Note: </B
+>Some CPU variants may require specific compiler
+support. That support must be in place before you can undertake the
+eCos variant port.</P
+></BLOCKQUOTE
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN9752">HAL Variant CDL</H2
+><P
+>The CDL in a variant HAL tends to depend on the exact functionality
+supported by the variant. If it implements some of the devices
+described in the platform HAL, then the CDL for those will be here
+rather than there (for example the real-time clock).</P
+><P
+>There may also be CDL to select options in the architecture HAL to
+configure it to a particular architectural variant.</P
+><P
+>Each variant needs an entry in the <TT
+CLASS="FILENAME"
+>ecos.db</TT
+>
+file. This is the one for the SH3:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>package CYGPKG_HAL_SH_SH3 {
+ alias { "SH3 architecture" hal_sh_sh3 }
+ directory hal/sh/sh3
+ script hal_sh_sh3.cdl
+ hardware
+ description "
+ The SH3 (SuperH 3) variant HAL package provides generic
+ support for SH3 variant CPUs."
+}</PRE
+></TD
+></TR
+></TABLE
+><P
+>As you can see, it is very similar to the platform entry.</P
+><P
+>The variant CDL file will contain a package entry named for the
+architecture and variant, matching the package name in the
+<TT
+CLASS="FILENAME"
+>ecos.db</TT
+> file. Here is the initial part of the
+MIPS VR4300 CDL file:</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>cdl_package CYGPKG_HAL_MIPS_VR4300 {
+ display "VR4300 variant"
+ parent CYGPKG_HAL_MIPS
+ implements CYGINT_HAL_MIPS_VARIANT
+ hardware
+ include_dir cyg/hal
+ define_header hal_mips_vr4300.h
+ description "
+ The VR4300 variant HAL package provides generic support
+ for this processor architecture. It is also necessary to
+ select a specific target platform HAL package."</PRE
+></TD
+></TR
+></TABLE
+><P
+>This defines the package, placing it under the MIPS architecture
+package in the hierarchy. The <TT
+CLASS="LITERAL"
+>implements</TT
+> line
+indicates that this is a MIPS variant. The architecture package uses
+this to check that exactly one variant is configured in.</P
+><P
+>The variant defines some options that cause the architecture HAL to
+configure itself to support this variant.</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+> cdl_option CYGHWR_HAL_MIPS_64BIT {
+ display "Variant 64 bit architecture support"
+ calculated 1
+ }
+
+ cdl_option CYGHWR_HAL_MIPS_FPU {
+ display "Variant FPU support"
+ calculated 1
+ }
+
+ cdl_option CYGHWR_HAL_MIPS_FPU_64BIT {
+ display "Variant 64 bit FPU support"
+ calculated 1
+ }</PRE
+></TD
+></TR
+></TABLE
+><P
+>These tell the architecture that this is a 64 bit MIPS architecture,
+that it has a floating point unit, and that we are going to use it in
+64 bit mode rather than 32 bit mode.</P
+><P
+>The CDL file finishes off with some build options.</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+> define_proc {
+ puts $::cdl_header "#include <pkgconf/hal_mips.h>"
+ }
+
+ compile var_misc.c
+
+ make {
+ <PREFIX>/lib/target.ld: <PACKAGE>/src/mips_vr4300.ld
+ $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) $(CFLAGS) -o $@ $<
+ @echo $@ ": \\" > $(notdir $@).deps
+ @tail +2 target.tmp >> $(notdir $@).deps
+ @echo >> $(notdir $@).deps
+ @rm target.tmp
+ }
+
+ cdl_option CYGBLD_LINKER_SCRIPT {
+ display "Linker script"
+ flavor data
+ no_define
+ calculated { "src/mips_vr4300.ld" }
+ }
+
+}</PRE
+></TD
+></TR
+></TABLE
+><P
+>The <TT
+CLASS="LITERAL"
+>define_proc</TT
+> causes the architecture
+configuration file to be included into the configuration file for the
+variant. The <TT
+CLASS="LITERAL"
+>compile</TT
+> causes the single source file
+for this variant, <TT
+CLASS="FILENAME"
+>var_misc.c</TT
+> to be compiled. The
+<TT
+CLASS="LITERAL"
+>make</TT
+> command emits makefile rules to combine the
+linker script with the <TT
+CLASS="FILENAME"
+>.ldi</TT
+> file to generate
+<TT
+CLASS="LITERAL"
+>target.ld</TT
+>. Finally, in the MIPS HALs, the main
+linker script is defined in the variant, rather than the architecture,
+so <TT
+CLASS="LITERAL"
+>CYGBLD_LINKER_SCRIPT</TT
+> is defined here.</P
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN9778">Cache Support</H2
+><P
+>The main area where the variant is likely to be involved is in cache
+support. Often the only thing that distinguishes one CPU variant from
+another is the size of its caches.</P
+><P
+>In architectures such as the MIPS and PowerPC where cache instructions
+are part of the ISA, most of the actual cache operations are
+implemented in the architecture HAL. In this case the variant HAL only
+needs to define the cache dimensions. The following are the cache
+dimensions defined in the MIPS VR4300 variant
+<TT
+CLASS="FILENAME"
+>var_cache.h</TT
+>.</P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>// Data cache
+#define HAL_DCACHE_SIZE (8*1024) // Size of data cache in bytes
+#define HAL_DCACHE_LINE_SIZE 16 // Size of a data cache line
+#define HAL_DCACHE_WAYS 1 // Associativity of the cache
+
+// Instruction cache
+#define HAL_ICACHE_SIZE (16*1024) // Size of cache in bytes
+#define HAL_ICACHE_LINE_SIZE 32 // Size of a cache line
+#define HAL_ICACHE_WAYS 1 // Associativity of the cache
+
+#define HAL_DCACHE_SETS (HAL_DCACHE_SIZE/(HAL_DCACHE_LINE_SIZE*HAL_DCACHE_WAYS))
+#define HAL_ICACHE_SETS (HAL_ICACHE_SIZE/(HAL_ICACHE_LINE_SIZE*HAL_ICACHE_WAYS))</PRE
+></TD
+></TR
+></TABLE
+><P
+>Additional cache macros, or overrides for the defaults, may also
+appear in here. While some architectures have instructions for
+managing cache lines, overall enable/disable operations may be handled
+via variant specific registers. If so then
+<TT
+CLASS="FILENAME"
+>var_cache.h</TT
+> should also define the
+<TT
+CLASS="LITERAL"
+>HAL_XCACHE_ENABLE()</TT
+> and
+<TT
+CLASS="LITERAL"
+>HAL_XCACHE_DISABLE()</TT
+> macros.</P
+><P
+>If there are any generic features that the variant does not support
+(cache locking is a typical example) then
+<TT
+CLASS="LITERAL"
+>var_cache.h</TT
+> may need to disable definitions of
+certain operations. It is architecture dependent exactly how this is
+done.</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="hal-porting-platform.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="hal-porting-architecture.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Platform HAL Porting</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="hal-porting-guide.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Architecture HAL Porting</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff