doc/html/ref/hal-porting-variant.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Variant HAL Porting</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE=" Porting Guide"
  23 HREF="hal-porting-guide.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Platform HAL Porting"
  26 HREF="hal-porting-platform.html"><LINK
  27 REL="NEXT"
  28 TITLE="Architecture HAL Porting"
  29 HREF="hal-porting-architecture.html"></HEAD
  30 ><BODY
  31 CLASS="SECTION"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="hal-porting-platform.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 11. Porting Guide</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="hal-porting-architecture.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECTION"
  82 ><H1
  83 CLASS="SECTION"
  84 ><A
  85 NAME="HAL-PORTING-VARIANT">Variant HAL Porting</H1
  86 ><P
  87 >A variant port can be a fairly limited job, but can also
  88 require quite a lot of work. A variant HAL describes how a specific
  89 CPU variant differs from the generic CPU architecture. The variant HAL
  90 can re-define cache, MMU, interrupt, and other features which override
  91 the default implementation provided by the architecture HAL.</P
  92 ><P
  93 >Doing a variant port requires a preexisting architecture HAL port. It
  94 is also likely that a platform port will have to be done at the same
  95 time if it is to be tested.</P
  96 ><DIV
  97 CLASS="SECTION"
  98 ><H2
  99 CLASS="SECTION"
 100 ><A
 101 NAME="AEN9745">HAL Variant Porting Process</H2
 102 ><P
 103 >The easiest way to make a new variant HAL is simply to copy an
 104 existing variant HAL and change all the files to match the new
 105 variant. If this is the first variant for an architecture, it may be
 106 hard to decide which parts should be put in the variant - knowledge of
 107 other variants of the architecture is required.</P
 108 ><P
 109 >Looking at existing variant HALs (e.g., MIPS tx39, tx49) may be a
 110 help - usually things such as caching, interrupt and exception
 111 handling differ between variants. Initialization code, and code for
 112 handling various core components (FPU, DSP, MMU, etc.) may also differ
 113 or be missing altogether on some variants. Linker scripts may also require
 114 specific variant versions.</P
 115 ><DIV
 116 CLASS="NOTE"
 117 ><BLOCKQUOTE
 118 CLASS="NOTE"
 119 ><P
 120 ><B
 121 >Note: </B
 122 >Some CPU variants may require specific compiler
 123 support. That support must be in place before you can undertake the
 124 eCos variant port.</P
 125 ></BLOCKQUOTE
 126 ></DIV
 127 ></DIV
 128 ><DIV
 129 CLASS="SECTION"
 130 ><H2
 131 CLASS="SECTION"
 132 ><A
 133 NAME="AEN9752">HAL Variant CDL</H2
 134 ><P
 135 >The CDL in a variant HAL tends to depend on the exact functionality
 136 supported by the variant. If it implements some of the devices
 137 described in the platform HAL, then the CDL for those will be here
 138 rather than there (for example the real-time clock).</P
 139 ><P
 140 >There may also be CDL to select options in the architecture HAL to
 141 configure it to a particular architectural variant.</P
 142 ><P
 143 >Each variant needs an entry in the <TT
 144 CLASS="FILENAME"
 145 >ecos.db</TT
 146 >
 147 file. This is the one for the SH3:</P
 148 ><TABLE
 149 BORDER="5"
 150 BGCOLOR="#E0E0F0"
 151 WIDTH="70%"
 152 ><TR
 153 ><TD
 154 ><PRE
 155 CLASS="PROGRAMLISTING"
 156 >package CYGPKG_HAL_SH_SH3 {
 157     alias         { "SH3 architecture" hal_sh_sh3 }
 158     directory     hal/sh/sh3
 159     script        hal_sh_sh3.cdl
 160     hardware
 161     description   "
 162         The SH3 (SuperH 3) variant HAL package provides generic
 163         support for SH3 variant CPUs."
 164 }</PRE
 165 ></TD
 166 ></TR
 167 ></TABLE
 168 ><P
 169 >As you can see, it is very similar to the platform entry.</P
 170 ><P
 171 >The variant CDL file will contain a package entry named for the
 172 architecture and variant, matching the package name in the
 173 <TT
 174 CLASS="FILENAME"
 175 >ecos.db</TT
 176 > file. Here is the initial part of the
 177 MIPS VR4300 CDL file:</P
 178 ><TABLE
 179 BORDER="5"
 180 BGCOLOR="#E0E0F0"
 181 WIDTH="70%"
 182 ><TR
 183 ><TD
 184 ><PRE
 185 CLASS="PROGRAMLISTING"
 186 >cdl_package CYGPKG_HAL_MIPS_VR4300 {
 187     display       "VR4300 variant"
 188     parent        CYGPKG_HAL_MIPS
 189     implements    CYGINT_HAL_MIPS_VARIANT
 190     hardware
 191     include_dir   cyg/hal
 192     define_header hal_mips_vr4300.h
 193     description   "
 194            The VR4300 variant HAL package provides generic support
 195            for this processor architecture. It is also necessary to
 196            select a specific target platform HAL package."</PRE
 197 ></TD
 198 ></TR
 199 ></TABLE
 200 ><P
 201 >This defines the package, placing it under the MIPS architecture
 202 package in the hierarchy. The <TT
 203 CLASS="LITERAL"
 204 >implements</TT
 205 > line
 206 indicates that this is a MIPS variant. The architecture package uses
 207 this to check that exactly one variant is configured in.</P
 208 ><P
 209 >The variant defines some options that cause the architecture HAL to
 210 configure itself to support this variant.</P
 211 ><TABLE
 212 BORDER="5"
 213 BGCOLOR="#E0E0F0"
 214 WIDTH="70%"
 215 ><TR
 216 ><TD
 217 ><PRE
 218 CLASS="PROGRAMLISTING"
 219 >    cdl_option CYGHWR_HAL_MIPS_64BIT {
 220         display    "Variant 64 bit architecture support"
 221         calculated 1
 222     }
 223
 224     cdl_option CYGHWR_HAL_MIPS_FPU {
 225         display    "Variant FPU support"
 226         calculated 1
 227     }
 228
 229     cdl_option CYGHWR_HAL_MIPS_FPU_64BIT {
 230         display    "Variant 64 bit FPU support"
 231         calculated 1
 232     }</PRE
 233 ></TD
 234 ></TR
 235 ></TABLE
 236 ><P
 237 >These tell the architecture that this is a 64 bit MIPS architecture,
 238 that it has a floating point unit, and that we are going to use it in
 239 64 bit mode rather than 32 bit mode.</P
 240 ><P
 241 >The CDL file finishes off with some build options.</P
 242 ><TABLE
 243 BORDER="5"
 244 BGCOLOR="#E0E0F0"
 245 WIDTH="70%"
 246 ><TR
 247 ><TD
 248 ><PRE
 249 CLASS="PROGRAMLISTING"
 250 >    define_proc {
 251         puts $::cdl_header "#include &lt;pkgconf/hal_mips.h&gt;"
 252     }
 253
 254     compile       var_misc.c
 255
 256     make {
 257         &lt;PREFIX&gt;/lib/target.ld: &lt;PACKAGE&gt;/src/mips_vr4300.ld
 258         $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) $(CFLAGS) -o $@ $&lt;
 259         @echo $@ ": \\" &gt; $(notdir $@).deps
 260         @tail +2 target.tmp &gt;&gt; $(notdir $@).deps
 261         @echo &gt;&gt; $(notdir $@).deps
 262         @rm target.tmp
 263     }
 264
 265     cdl_option CYGBLD_LINKER_SCRIPT {
 266         display "Linker script"
 267         flavor data
 268         no_define
 269         calculated  { "src/mips_vr4300.ld" }
 270     }
 271
 272 }</PRE
 273 ></TD
 274 ></TR
 275 ></TABLE
 276 ><P
 277 >The <TT
 278 CLASS="LITERAL"
 279 >define_proc</TT
 280 > causes the architecture
 281 configuration file to be included into the configuration file for the
 282 variant. The <TT
 283 CLASS="LITERAL"
 284 >compile</TT
 285 > causes the single source file
 286 for this variant, <TT
 287 CLASS="FILENAME"
 288 >var_misc.c</TT
 289 > to be compiled. The
 290 <TT
 291 CLASS="LITERAL"
 292 >make</TT
 293 > command emits makefile rules to combine the
 294 linker script with the <TT
 295 CLASS="FILENAME"
 296 >.ldi</TT
 297 > file to generate
 298 <TT
 299 CLASS="LITERAL"
 300 >target.ld</TT
 301 >. Finally, in the MIPS HALs, the main
 302 linker script is defined in the variant, rather than the architecture,
 303 so <TT
 304 CLASS="LITERAL"
 305 >CYGBLD_LINKER_SCRIPT</TT
 306 > is defined here.</P
 307 ></DIV
 308 ><DIV
 309 CLASS="SECTION"
 310 ><H2
 311 CLASS="SECTION"
 312 ><A
 313 NAME="AEN9778">Cache Support</H2
 314 ><P
 315 >The main area where the variant is likely to be involved is in cache
 316 support. Often the only thing that distinguishes one CPU variant from
 317 another is the size of its caches.</P
 318 ><P
 319 >In architectures such as the MIPS and PowerPC where cache instructions
 320 are part of the ISA, most of the actual cache operations are
 321 implemented in the architecture HAL. In this case the variant HAL only
 322 needs to define the cache dimensions. The following are the cache
 323 dimensions defined in the MIPS VR4300 variant
 324 <TT
 325 CLASS="FILENAME"
 326 >var_cache.h</TT
 327 >.</P
 328 ><TABLE
 329 BORDER="5"
 330 BGCOLOR="#E0E0F0"
 331 WIDTH="70%"
 332 ><TR
 333 ><TD
 334 ><PRE
 335 CLASS="PROGRAMLISTING"
 336 >// Data cache
 337 #define HAL_DCACHE_SIZE                 (8*1024)        // Size of data cache in bytes
 338 #define HAL_DCACHE_LINE_SIZE            16              // Size of a data cache line
 339 #define HAL_DCACHE_WAYS                 1               // Associativity of the cache
 340
 341 // Instruction cache
 342 #define HAL_ICACHE_SIZE                 (16*1024)       // Size of cache in bytes
 343 #define HAL_ICACHE_LINE_SIZE            32              // Size of a cache line
 344 #define HAL_ICACHE_WAYS                 1               // Associativity of the cache
 345
 346 #define HAL_DCACHE_SETS (HAL_DCACHE_SIZE/(HAL_DCACHE_LINE_SIZE*HAL_DCACHE_WAYS))
 347 #define HAL_ICACHE_SETS (HAL_ICACHE_SIZE/(HAL_ICACHE_LINE_SIZE*HAL_ICACHE_WAYS))</PRE
 348 ></TD
 349 ></TR
 350 ></TABLE
 351 ><P
 352 >Additional cache macros, or overrides for the defaults, may also
 353 appear in here. While some architectures have instructions for
 354 managing cache lines, overall enable/disable operations may be handled
 355 via variant specific registers. If so then
 356 <TT
 357 CLASS="FILENAME"
 358 >var_cache.h</TT
 359 > should also define the
 360 <TT
 361 CLASS="LITERAL"
 362 >HAL_XCACHE_ENABLE()</TT
 363 > and
 364 <TT
 365 CLASS="LITERAL"
 366 >HAL_XCACHE_DISABLE()</TT
 367 > macros.</P
 368 ><P
 369 >If there are any generic features that the variant does not support
 370 (cache locking is a typical example) then
 371 <TT
 372 CLASS="LITERAL"
 373 >var_cache.h</TT
 374 > may need to disable definitions of
 375 certain operations. It is architecture dependent exactly how this is
 376 done.</P
 377 ></DIV
 378 ></DIV
 379 ><DIV
 380 CLASS="NAVFOOTER"
 381 ><HR
 382 ALIGN="LEFT"
 383 WIDTH="100%"><TABLE
 384 SUMMARY="Footer navigation table"
 385 WIDTH="100%"
 386 BORDER="0"
 387 CELLPADDING="0"
 388 CELLSPACING="0"
 389 ><TR
 390 ><TD
 391 WIDTH="33%"
 392 ALIGN="left"
 393 VALIGN="top"
 394 ><A
 395 HREF="hal-porting-platform.html"
 396 ACCESSKEY="P"
 397 >Prev</A
 398 ></TD
 399 ><TD
 400 WIDTH="34%"
 401 ALIGN="center"
 402 VALIGN="top"
 403 ><A
 404 HREF="ecos-ref.html"
 405 ACCESSKEY="H"
 406 >Home</A
 407 ></TD
 408 ><TD
 409 WIDTH="33%"
 410 ALIGN="right"
 411 VALIGN="top"
 412 ><A
 413 HREF="hal-porting-architecture.html"
 414 ACCESSKEY="N"
 415 >Next</A
 416 ></TD
 417 ></TR
 418 ><TR
 419 ><TD
 420 WIDTH="33%"
 421 ALIGN="left"
 422 VALIGN="top"
 423 >Platform HAL Porting</TD
 424 ><TD
 425 WIDTH="34%"
 426 ALIGN="center"
 427 VALIGN="top"
 428 ><A
 429 HREF="hal-porting-guide.html"
 430 ACCESSKEY="U"
 431 >Up</A
 432 ></TD
 433 ><TD
 434 WIDTH="33%"
 435 ALIGN="right"
 436 VALIGN="top"
 437 >Architecture HAL Porting</TD
 438 ></TR
 439 ></TABLE
 440 ></DIV
 441 ></BODY
 442 ></HTML
 443 >