doc/html/ref/hal-porting-platform.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 >Platform 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="HAL Coding Conventions"
  26 HREF="hal-porting-coding-conventions.html"><LINK
  27 REL="NEXT"
  28 TITLE="Variant HAL Porting"
  29 HREF="hal-porting-variant.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-coding-conventions.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-variant.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-PLATFORM">Platform HAL Porting</H1
  86 ><P
  87 >This is the type of port that takes the least effort. It basically
  88 consists of describing the platform (board) for the HAL: memory
  89 layout, early platform initialization, interrupt controllers, and a
  90 simple serial device driver.</P
  91 ><P
  92 >Doing a platform port requires a preexisting architecture and
  93 possibly a variant HAL port.</P
  94 ><DIV
  95 CLASS="SECTION"
  96 ><H2
  97 CLASS="SECTION"
  98 ><A
  99 NAME="AEN9415">HAL Platform Porting Process</H2
 100 ><DIV
 101 CLASS="SECTION"
 102 ><H3
 103 CLASS="SECTION"
 104 ><A
 105 NAME="AEN9417">Brief overview</H3
 106 ><P
 107 >The easiest way to make a new platform HAL is simply to copy an
 108 existing platform HAL of the same architecture/variant and change all
 109 the files to match the new one. In case this is the first platform for
 110 the architecture/variant, a platform HAL from another architecture
 111 should be used as a template.</P
 112 ><P
 113 >The best way to start a platform port is to concentrate on getting
 114 RedBoot to run. RedBoot is a simpler environment than full eCos, it
 115 does not use interrupts or threads, but covers most of the
 116 basic startup requirements.</P
 117 ><P
 118 >RedBoot normally runs out of FLASH or ROM and provides program loading
 119 and debugging facilities.  This allows further HAL development to
 120 happen using RAM startup configurations, which is desirable for the
 121 simple reason that downloading an image which you need to test is
 122 often many times faster than either updating a flash part, or indeed,
 123 erasing and reprogramming an EPROM.</P
 124 ><P
 125 >There are two approaches to getting to this first goal:</P
 126 ><P
 127 ></P
 128 ><OL
 129 TYPE="1"
 130 ><LI
 131 ><P
 132 >The board is equipped with a ROM monitor which allows "load and go" of
 133 ELF, binary, S-record or some other image type which can be created
 134 using <SPAN
 135 CLASS="APPLICATION"
 136 >objcopy</SPAN
 137 >. This allows you to develop
 138 RedBoot by downloading and running the code (saving time).</P
 139 ><P
 140 >When the stub is running it is a good idea to examine the various
 141 hardware registers to help you write the platform initialization code.</P
 142 ><P
 143 >Then you may have to fiddle a bit going through step two (getting it
 144 to run from ROM startup). If at all possible, preserve the original
 145 ROM monitor so you can revert to it if necessary.</P
 146 ></LI
 147 ><LI
 148 ><P
 149 >The board has no ROM monitor. You need to get the platform
 150 initialization and stub working by repeatedly making changes, updating
 151 flash or EPROM and testing the changes. If you are lucky, you have a
 152 JTAG or similar CPU debugger to help you. If not, you will probably
 153 learn to appreciate LEDs. This approach may also be needed during the
 154 initial phase of moving RedBoot from RAM startup to ROM, since it is
 155 very unlikely to work first time.</P
 156 ></LI
 157 ></OL
 158 ></DIV
 159 ><DIV
 160 CLASS="SECTION"
 161 ><H3
 162 CLASS="SECTION"
 163 ><A
 164 NAME="AEN9431">Step-by-step</H3
 165 ><P
 166 >Given that no two platforms are exactly the same, you may have to
 167 deviate from the below. Also, you should expect a fair amount of
 168 fiddling - things almost never go right the first time. See the hints
 169 section below for some suggestions that might help debugging.</P
 170 ><P
 171 >The description below is based on the HAL layout used in the MIPS,
 172 PC and MN10300 HALs. Eventually all HALs should be converted to look like
 173 these - but in a transition period there will be other HALs which look
 174 substantially different. Please try to adhere to the following as much is
 175 possible without causing yourself too much grief integrating with a
 176 HAL which does not follow this layout.</P
 177 ><DIV
 178 CLASS="SECTION"
 179 ><H4
 180 CLASS="SECTION"
 181 ><A
 182 NAME="AEN9435">Minimal requirements</H4
 183 ><P
 184 >These are the changes you must make before you attempt to build
 185 RedBoot. You are advised to read all the sources though.</P
 186 ><P
 187 ></P
 188 ><OL
 189 TYPE="1"
 190 ><LI
 191 ><P
 192 >Copy an existing platform HAL from the same or another
 193     architecture. Rename the files as necessary to follow the
 194     standard: CDL and MLT related files should contain the
 195     &lt;arch&gt;_&lt;variant&gt;_&lt;platform&gt; triplet.</P
 196 ></LI
 197 ><LI
 198 ><P
 199 >Adjust CDL options. Primarily option naming, real-time
 200     clock/counter, and CYGHWR_MEMORY_LAYOUT variables, but also other
 201     options may need editing. Look through the architecture/variant
 202     CDL files to see if there are any requirements/features which
 203     where not used on the platform you copied. If so, add appropriate
 204     ones. See <A
 205 HREF="hal-porting-platform.html#HAL-PORTING-CDL-REQUIREMENTS"
 206 >the Section called <I
 207 >HAL Platform CDL</I
 208 ></A
 209 > for more
 210     details.</P
 211 ></LI
 212 ><LI
 213 ><P
 214 >Add the necessary packages and target descriptions to the
 215     top-level <TT
 216 CLASS="FILENAME"
 217 >ecos.db</TT
 218 > file. See <A
 219 HREF="hal-porting-platform.html#HAL-PORTING-ECOS-DATABASE"
 220 >the Section called <I
 221 >eCos Database</I
 222 ></A
 223 >. Initially, the target entry
 224     should only contain the HAL packages. Other hardware support
 225     packages will be added later.</P
 226 ></LI
 227 ><LI
 228 ><P
 229 >Adjust the MLT files in
 230     <TT
 231 CLASS="FILENAME"
 232 >include/pkgconf</TT
 233 > to match the memory layout on
 234     the platform. For initial testing it should be enough to just hand
 235     edit .h and .ldi files, but eventually you should generate all
 236     files using the memory layout editor in the configuration
 237     tool. See <A
 238 HREF="hal-porting-platform.html#HAL-PORTING-PLATFORM-MEMORY-LAYOUT"
 239 >the Section called <I
 240 >Platform Memory Layout</I
 241 ></A
 242 > for
 243     more details.</P
 244 ></LI
 245 ><LI
 246 ><P
 247 >    Edit the <TT
 248 CLASS="FILENAME"
 249 >misc/redboot_&lt;STARTUP&gt;.ecm</TT
 250 > for
 251     the startup type you have chosen to begin with. Rename any
 252     platform specific options and remove any that do not apply. In the
 253     <TT
 254 CLASS="LITERAL"
 255 >cdl_configuration</TT
 256 > section, comment out any
 257     extra packages that are added, particularly packages such as
 258     <TT
 259 CLASS="LITERAL"
 260 >CYGPKG_IO_FLASH</TT
 261 > and
 262     <TT
 263 CLASS="LITERAL"
 264 >CYGPKG_IO_ETH_DRIVERS</TT
 265 >. These are not needed for
 266     initial porting and will be added back later.
 267     </P
 268 ></LI
 269 ><LI
 270 ><P
 271 >If the default IO macros are not correct, override them in
 272     plf_io.h. This may be necessary if the platform uses a different
 273     endianness from the default for the CPU.</P
 274 ></LI
 275 ><LI
 276 ><P
 277 >Leave out/comment out code that enables caches and/or MMU if
 278     possible. Execution speed will not be a concern until the port is
 279     feature complete.</P
 280 ></LI
 281 ><LI
 282 ><P
 283 >Implement a simple serial driver (polled mode only). Make sure the
 284     initialization function properly hooks the procedures up in the
 285     virtual vector IO channel tables. RedBoot will call the serial
 286     driver via these tables.</P
 287 ><P
 288 >    By copying an existing platform HAL most of this code will be
 289     already done, and will only need the platform specific hardware
 290     access code to be written.
 291     </P
 292 ></LI
 293 ><LI
 294 ><P
 295 >Adjust/implement necessary platform
 296     initialization. This can be found in
 297     <TT
 298 CLASS="FILENAME"
 299 >platform.inc</TT
 300 > and
 301     <TT
 302 CLASS="FILENAME"
 303 >platform.S</TT
 304 > files (ARM:
 305     <TT
 306 CLASS="FILENAME"
 307 >hal_platform_setup.h</TT
 308 > and
 309     <TT
 310 CLASS="FILENAME"
 311 >&lt;platform&gt;_misc.c</TT
 312 >, PowerPC:
 313     <TT
 314 CLASS="FILENAME"
 315 >&lt;platform&gt;.S</TT
 316 >). This step can be
 317     postponed if you are doing a RAM startup RedBoot first and the
 318     existing ROM monitor handles board initialization.</P
 319 ></LI
 320 ><LI
 321 ><P
 322 >Define <TT
 323 CLASS="LITERAL"
 324 >HAL_STUB_PLATFORM_RESET</TT
 325 >
 326     (optionally empty) and
 327     <TT
 328 CLASS="LITERAL"
 329 >HAL_STUB_PLATFORM_RESET_ENTRY</TT
 330 > so that RedBoot
 331     can reset-on-detach - this is very handy, often removing the need
 332     for physically resetting the board between downloads.</P
 333 ></LI
 334 ></OL
 335 ><P
 336 >You should now be able to build RedBoot. For ROM startup:</P
 337 ><TABLE
 338 BORDER="5"
 339 BGCOLOR="#E0E0F0"
 340 WIDTH="70%"
 341 ><TR
 342 ><TD
 343 ><PRE
 344 CLASS="PROGRAMLISTING"
 345 >% ecosconfig new &lt;target_name&gt; redboot
 346 % ecosconfig import $(ECOS_REPOSITORY)/hal/&lt;architecture&gt;/&lt;platform&gt;/&lt;version&gt;/misc/redboot_ROM.ecm
 347 % ecosconfig tree
 348 % make</PRE
 349 ></TD
 350 ></TR
 351 ></TABLE
 352 ><P
 353 >You may have to make further changes than suggested above to get
 354 the make command to succeed. But when it does, you should find a
 355 RedBoot image in install/bin. To program this image into flash or
 356 EPROM, you may need to convert to some other file type, and possibly
 357 adjust the start address. When you have the correct
 358 <SPAN
 359 CLASS="APPLICATION"
 360 >objcopy</SPAN
 361 > command to do this, add it to the
 362 <TT
 363 CLASS="LITERAL"
 364 >CYGBLD_BUILD_GDB_STUBS</TT
 365 > custom build rule in the
 366 platform CDL file.</P
 367 ><P
 368 >Having updated the flash/EPROM on the board, you should see output
 369 on the serial port looking like this when powering on the board:</P
 370 ><TABLE
 371 BORDER="5"
 372 BGCOLOR="#E0E0F0"
 373 WIDTH="70%"
 374 ><TR
 375 ><TD
 376 ><PRE
 377 CLASS="PROGRAMLISTING"
 378 >RedBoot(tm) bootstrap and debug environment [ROMRAM]
 379 Non-certified release, version UNKNOWN - built 15:42:24, Mar 14 2002
 380
 381 Platform: &lt;PLATFORM&gt; (&lt;ARCHITECTURE&gt; &lt;VARIANT&gt;)
 382 Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
 383
 384 RAM: 0x00000000-0x01000000, 0x000293e8-0x00ed1000 available
 385 FLASH: 0x24000000 - 0x26000000, 256 blocks of 0x00020000 bytes each.
 386 RedBoot&#62; </PRE
 387 ></TD
 388 ></TR
 389 ></TABLE
 390 ><P
 391 >If you do not see this output, you need to go through all your
 392 changes and figure out what's wrong. If there's a user programmable
 393 LED or LCD on the board it may help you figure out how far RedBoot
 394 gets before it hangs. Unfortunately there's no good way to describe
 395 what to do in this situation - other than that you have to play with
 396 the code and the board.</P
 397 ></DIV
 398 ><DIV
 399 CLASS="SECTION"
 400 ><H4
 401 CLASS="SECTION"
 402 ><A
 403 NAME="AEN9484">Adding features</H4
 404 ><P
 405 >Now you should have a basic RedBoot running on the board. This
 406 means you have a the correct board initialization and a working serial
 407 driver. It's time to flesh out the remaining HAL features.</P
 408 ><P
 409 ></P
 410 ><OL
 411 TYPE="1"
 412 ><LI
 413 ><P
 414 >Reset. As mentioned above it is desirable to get the board to
 415 reset when GDB disconnects. When GDB disconnects it sends RedBoot
 416 a kill-packet, and RedBoot first calls <TT
 417 CLASS="LITERAL"
 418 >HAL_STUB_PLATFORM_RESET()</TT
 419 >,
 420 attempting to perform a software-invoked reset. Most embedded
 421 CPUs/boards have a watchdog which is capable of triggering a reset.
 422 If your target does not have a watchdog, leave
 423 <TT
 424 CLASS="LITERAL"
 425 >HAL_STUB_PLATFORM_RESET()</TT
 426 > empty and rely on the fallback approach.</P
 427 ><P
 428 >If <TT
 429 CLASS="LITERAL"
 430 >HAL_STUB_PLATFORM_RESET()</TT
 431 > did not cause a reset, RedBoot will
 432 jump to <TT
 433 CLASS="LITERAL"
 434 >HAL_STUB_PLATFORM_RESET_ENTRY</TT
 435 > - this should be the address
 436 where the CPU will start execution after a reset. Re-initializing the
 437 board and drivers will <SPAN
 438 CLASS="emphasis"
 439 ><I
 440 CLASS="EMPHASIS"
 441 >usually</I
 442 ></SPAN
 443 > be good enough to make a
 444 hardware reset unnecessary.</P
 445 ><P
 446 >After the reset caused by the kill-packet, the target will be ready
 447 for GDB to connect again. During a days work, this will save you from
 448 pressing the reset button many times.</P
 449 ><P
 450 >Note that it is possible to disconnect from the board without
 451 causing it to reset by using the GDB command &quot;detach&quot;.</P
 452 ></LI
 453 ><LI
 454 ><P
 455 >Single-stepping is necessary for both instruction-level debugging
 456 and for breakpoint support. Single-stepping support should already be
 457 in place as part of the architecture/variant HAL, but you want to give
 458 it a quick test since you will come to rely on it.</P
 459 ></LI
 460 ><LI
 461 ><P
 462 >Real-time clock interrupts drive the eCos scheduler clock. Many
 463 embedded CPUs have an on-core timer (e.g. SH) or decrementer
 464 (e.g. MIPS, PPC) that can be used, and in this case it will already be
 465 supported by the architecture/variant HAL. You only have to calculate
 466 and enter the proper <TT
 467 CLASS="LITERAL"
 468 >CYGNUM_HAL_RTC_CONSTANTS</TT
 469 >
 470 definitions in the platform CDL file.</P
 471 ><P
 472 >On some targets it may be necessary to use a platform-specific
 473 timer source for driving the real-time clock. In this case you also
 474 have to enter the proper CDL definitions, but must also define
 475 suitable versions of the <TT
 476 CLASS="LITERAL"
 477 >HAL_CLOCK_XXXX</TT
 478 > macros.</P
 479 ></LI
 480 ><LI
 481 ><P
 482 >Interrupt decoding usually differs between platforms because the
 483 number and type of devices on the board differ. In
 484 <TT
 485 CLASS="FILENAME"
 486 >plf_intr.h</TT
 487 > (ARM:
 488 <TT
 489 CLASS="FILENAME"
 490 >hal_platform_ints.h</TT
 491 >) you must either extend or
 492 replace the default vector definitions provided by the architecture
 493 or variant interrupt headers. You may also have to define
 494 <TT
 495 CLASS="LITERAL"
 496 >HAL_INTERRUPT_XXXX</TT
 497 > control macros.</P
 498 ></LI
 499 ><LI
 500 ><P
 501 >Caching may also differ from architecture/variant definitions.
 502 This maybe just the cache sizes, but there can also be bigger
 503 differences for example if the platform supports 2nd level caches.</P
 504 ><P
 505 >When cache definitions are in place, enable the caches on
 506 startup. First verify that the system is stable for RAM startups, then
 507 build a new RedBoot and install it. This will test if caching, and in
 508 particular the cache sync/flush operations, also work for ROM startup.</P
 509 ></LI
 510 ><LI
 511 ><P
 512 >Asynchronous breakpoints allow you to stop application execution
 513 and enter the debugger. Asynchronous breakpoint details are described
 514 in .</P
 515 ></LI
 516 ></OL
 517 ><P
 518 >You should now have a completed platform HAL port. Verify its
 519 stability and completeness by running all the eCos tests and fix any
 520 problems that show up (you have a working RedBoot now, remember! That
 521 means you can debug the code to see why it fails).</P
 522 ><P
 523 >Given the many configuration options in eCos, there may be hidden
 524 bugs or missing features that do not show up even if you run all the
 525 tests successfully with a default configuration. A comprehensive test
 526 of the entire system will take many configuration permutations and
 527 many many thousands of tests executed.</P
 528 ></DIV
 529 ></DIV
 530 ><DIV
 531 CLASS="SECTION"
 532 ><H3
 533 CLASS="SECTION"
 534 ><A
 535 NAME="AEN9517">Hints</H3
 536 ><P
 537 ></P
 538 ><UL
 539 ><LI
 540 ><P
 541 >JTAG or similar CPU debugging hardware can greatly reduce the time
 542     it takes to write a HAL port since you always have full visibility
 543     of what the CPU is doing.
 544     </P
 545 ></LI
 546 ><LI
 547 ><P
 548 >LEDs can be your friends if you don't have a JTAG
 549     device. Especially in the start of the porting effort if you don't
 550     already have a working ROM monitor on the target. Then you have to
 551     get a basic RedBoot working while basically being blindfolded. The
 552     LED can make it little easier, as you'll be able to do limited
 553     tracking of program flow and behavior by switching the LED on and
 554     off. If the board has multiple LEDs you can show a number (using
 555     binary notation with the LEDs) and sprinkle code which sets
 556     different numbers throughout the code.</P
 557 ></LI
 558 ><LI
 559 ><P
 560 >Debugging the interrupt processing is possible if you are
 561     careful with the way you program the very early interrupt entry
 562     handling. Write it so that as soon as possible in the interrupt
 563     path, taking a trap (exception) does not harm execution. See the
 564     SH vectors.S code for an example. Look for
 565     <TT
 566 CLASS="LITERAL"
 567 >cyg_hal_default_interrupt_vsr</TT
 568 > and the label
 569     <TT
 570 CLASS="LITERAL"
 571 >cyg_hal_default_interrupt_vsr_bp_safe</TT
 572 >, which
 573     marks the point after which traps/single-stepping is safe.
 574     </P
 575 ><P
 576 >Being able to display memory content, CPU registers,
 577     interrupt controller details at the time of an interrupt can save
 578     a lot of time.</P
 579 ></LI
 580 ><LI
 581 ><P
 582 >Using assertions is a good idea. They can sometimes reveal subtle
 583     bugs or missing features long before you would otherwise have
 584     found them, let alone notice them.
 585     </P
 586 ><P
 587 >The default eCos configuration does not use assertions, so you
 588     have to enable them by switching on the option <TT
 589 CLASS="LITERAL"
 590 >CYGPKG_INFRA_DEBUG</TT
 591 >
 592     in the infra package.</P
 593 ></LI
 594 ><LI
 595 ><P
 596 >The idle loop can be used to help debug the system.
 597     </P
 598 ><P
 599 >Triggering clock from the idle loop is a neat trick for
 600     examining system behavior either before interrupts are fully
 601     working, or to speed up &quot;the clock&quot;.
 602     </P
 603 ><P
 604 >Use the idle loop to monitor and/or print out variables or
 605     hardware registers.</P
 606 ></LI
 607 ><LI
 608 ><P
 609 ><SPAN
 610 CLASS="APPLICATION"
 611 >hal_mk_defs</SPAN
 612 > is used in some of the
 613 HALs (ARM, SH) as a way to generate assembler symbol definitions from
 614 C header files without imposing an assembler/C syntax separation in
 615 the C header files.</P
 616 ></LI
 617 ></UL
 618 ></DIV
 619 ></DIV
 620 ><DIV
 621 CLASS="SECTION"
 622 ><H2
 623 CLASS="SECTION"
 624 ><A
 625 NAME="HAL-PORTING-CDL-REQUIREMENTS">HAL Platform CDL</H2
 626 ><P
 627 >The platform CDL both contains details necessary for the building
 628 of eCos, and platform-specific configuration options. For this reason
 629 the options differ between platforms, and the below is just a brief
 630 description of the most common options.</P
 631 ><P
 632 > See  Components Writers Guide
 633 for more details on CDL. Also have a quick look around in
 634 existing platform CDL files to get an idea of what is possible and how
 635 various configuration issues can be represented with CDL.</P
 636 ><DIV
 637 CLASS="SECTION"
 638 ><H3
 639 CLASS="SECTION"
 640 ><A
 641 NAME="HAL-PORTING-ECOS-DATABASE">eCos Database</H3
 642 ><P
 643 >The eCos configuration system is made aware of a package by
 644 adding a package description in <TT
 645 CLASS="FILENAME"
 646 >ecos.db</TT
 647 >. As an
 648 example we use the <TT
 649 CLASS="LITERAL"
 650 >TX39/JMR3904</TT
 651 > platform:</P
 652 ><TABLE
 653 BORDER="5"
 654 BGCOLOR="#E0E0F0"
 655 WIDTH="70%"
 656 ><TR
 657 ><TD
 658 ><PRE
 659 CLASS="PROGRAMLISTING"
 660 >package CYGPKG_HAL_MIPS_TX39_JMR3904 {
 661         alias           { "Toshiba JMR-TX3904 board" hal_tx39_jmr3904 tx39_jmr3904_hal }
 662         directory       hal/mips/jmr3904
 663         script          hal_mips_tx39_jmr3904.cdl
 664         hardware
 665         description "
 666            The JMR3904 HAL package should be used when targeting the
 667            actual hardware. The same package can also be used when
 668            running on the full simulator, since this provides an
 669            accurate simulation of the hardware including I/O devices.
 670            To use the simulator in this mode the command
 671            `target sim --board=jmr3904' should be used from inside gdb."
 672 }</PRE
 673 ></TD
 674 ></TR
 675 ></TABLE
 676 ><P
 677 >This contains the title and description presented in the
 678 Configuration Tool when the package is selected. It also specifies
 679 where in the tree the package files can be found (<TT
 680 CLASS="LITERAL"
 681 >directory</TT
 682 >)
 683 and the name of the CDL file which contains the package details
 684 (<TT
 685 CLASS="LITERAL"
 686 >script</TT
 687 >).</P
 688 ><P
 689 >To be able to build and test a configuration for the new target, there
 690 also needs to be a <TT
 691 CLASS="LITERAL"
 692 >target</TT
 693 > entry in the
 694 <TT
 695 CLASS="FILENAME"
 696 >ecos.db</TT
 697 > file. </P
 698 ><TABLE
 699 BORDER="5"
 700 BGCOLOR="#E0E0F0"
 701 WIDTH="70%"
 702 ><TR
 703 ><TD
 704 ><PRE
 705 CLASS="PROGRAMLISTING"
 706 >target jmr3904 {
 707         alias           { "Toshiba JMR-TX3904 board" jmr tx39 }
 708         packages        { CYGPKG_HAL_MIPS
 709                           CYGPKG_HAL_MIPS_TX39
 710                           CYGPKG_HAL_MIPS_TX39_JMR3904
 711         }
 712         description "
 713            The jmr3904 target provides the packages needed to run
 714            eCos on a Toshiba JMR-TX3904 board. This target can also
 715            be used when running in the full simulator, since the simulator provides an
 716            accurate simulation of the hardware including I/O devices.
 717            To use the simulator in this mode the command
 718            `target sim --board=jmr3904' should be used from inside gdb."
 719 }</PRE
 720 ></TD
 721 ></TR
 722 ></TABLE
 723 ><P
 724 >The important part here is the <TT
 725 CLASS="LITERAL"
 726 >packages</TT
 727 > section
 728 which defines the various hardware specific packages that contribute
 729 to support for this target. In this case the MIPS architecture
 730 package, the TX39 variant package, and the JMR-TX3904 platform
 731 packages are selected. Other packages, for serial drivers, ethernet
 732 drivers and FLASH memory drivers may also appear here.</P
 733 ></DIV
 734 ><DIV
 735 CLASS="SECTION"
 736 ><H3
 737 CLASS="SECTION"
 738 ><A
 739 NAME="AEN9559">CDL File Layout</H3
 740 ><P
 741 >All the platform options are contained in a CDL package named
 742 <TT
 743 CLASS="LITERAL"
 744 >CYGPKG_HAL_&lt;architecture&gt;_&lt;variant&gt;_&lt;platform&gt;</TT
 745 >.
 746 They all share more or less the same <TT
 747 CLASS="LITERAL"
 748 >cdl_package</TT
 749 >
 750 details:</P
 751 ><TABLE
 752 BORDER="5"
 753 BGCOLOR="#E0E0F0"
 754 WIDTH="70%"
 755 ><TR
 756 ><TD
 757 ><PRE
 758 CLASS="PROGRAMLISTING"
 759 >cdl_package CYGPKG_HAL_MIPS_TX39_JMR3904 {
 760     display       "JMR3904 evaluation board"
 761     parent        CYGPKG_HAL_MIPS
 762     requires      CYGPKG_HAL_MIPS_TX39
 763     define_header hal_mips_tx39_jmr3904.h
 764     include_dir   cyg/hal
 765     description   "
 766            The JMR3904 HAL package should be used when targeting the
 767            actual hardware. The same package can also be used when
 768            running on the full simulator, since this provides an
 769            accurate simulation of the hardware including I/O devices.
 770            To use the simulator in this mode the command
 771            `target sim --board=jmr3904' should be used from inside gdb."
 772
 773     compile       platform.S plf_misc.c plf_stub.c
 774
 775     define_proc {
 776         puts $::cdl_system_header "#define CYGBLD_HAL_TARGET_H   &lt;pkgconf/hal_mips_tx39.h&gt;"
 777         puts $::cdl_system_header "#define CYGBLD_HAL_PLATFORM_H &lt;pkgconf/hal_mips_tx39_jmr3904.h&gt;"
 778     }
 779
 780     ...
 781 }</PRE
 782 ></TD
 783 ></TR
 784 ></TABLE
 785 ><P
 786 >This specifies that the platform package should be parented under
 787 the MIPS packages, requires the TX39 variant HAL and all configuration
 788 settings should be saved in
 789 <TT
 790 CLASS="FILENAME"
 791 >cyg/hal/hal_mips_tx39_jmt3904.h</TT
 792 >.</P
 793 ><P
 794 >The <TT
 795 CLASS="LITERAL"
 796 >compile</TT
 797 > line specifies which files should be built
 798 when this package is enabled, and the <TT
 799 CLASS="LITERAL"
 800 >define_proc</TT
 801 > defines
 802 some macros that are used to access the variant or architecture (the
 803 <TT
 804 CLASS="LITERAL"
 805 >_TARGET_</TT
 806 > name is a bit of a misnomer) and platform
 807 configuration options. </P
 808 ></DIV
 809 ><DIV
 810 CLASS="SECTION"
 811 ><H3
 812 CLASS="SECTION"
 813 ><A
 814 NAME="AEN9571">Startup Type</H3
 815 ><P
 816 >eCos uses an option to select between a set of valid startup
 817 configurations. These are normally RAM, ROM and possibly ROMRAM. This
 818 setting is used to select which linker map to use (i.e., where to link
 819 eCos and the application in the memory space), and how the startup
 820 code should behave.</P
 821 ><TABLE
 822 BORDER="5"
 823 BGCOLOR="#E0E0F0"
 824 WIDTH="70%"
 825 ><TR
 826 ><TD
 827 ><PRE
 828 CLASS="PROGRAMLISTING"
 829 >cdl_component CYG_HAL_STARTUP {
 830     display       "Startup type"
 831     flavor        data
 832     legal_values  {"RAM" "ROM"}
 833     default_value {"RAM"}
 834         no_define
 835         define -file system.h CYG_HAL_STARTUP
 836     description   "
 837        When targeting the JMR3904 board it is possible to build
 838        the system for either RAM bootstrap, ROM bootstrap, or STUB
 839        bootstrap. RAM bootstrap generally requires that the board
 840        is equipped with ROMs containing a suitable ROM monitor or
 841        equivalent software that allows GDB to download the eCos
 842        application on to the board. The ROM bootstrap typically
 843        requires that the eCos application be blown into EPROMs or
 844        equivalent technology."
 845 }</PRE
 846 ></TD
 847 ></TR
 848 ></TABLE
 849 ><P
 850 >The <TT
 851 CLASS="LITERAL"
 852 >no_define</TT
 853 > and <TT
 854 CLASS="LITERAL"
 855 >define</TT
 856 >
 857 pair is used to make the setting of this option appear in the file
 858 <TT
 859 CLASS="FILENAME"
 860 >system.h</TT
 861 > instead of the default specified in the
 862 header.</P
 863 ></DIV
 864 ><DIV
 865 CLASS="SECTION"
 866 ><H3
 867 CLASS="SECTION"
 868 ><A
 869 NAME="AEN9579">Build options</H3
 870 ><P
 871 >A set of options under the components
 872 <TT
 873 CLASS="LITERAL"
 874 >CYGBLD_GLOBAL_OPTIONS</TT
 875 > and
 876 <TT
 877 CLASS="LITERAL"
 878 >CYGHWR_MEMORY_LAYOUT</TT
 879 > specify how eCos should be
 880 built: what tools and compiler options should be used, and which
 881 linker fragments should be used.</P
 882 ><TABLE
 883 BORDER="5"
 884 BGCOLOR="#E0E0F0"
 885 WIDTH="70%"
 886 ><TR
 887 ><TD
 888 ><PRE
 889 CLASS="PROGRAMLISTING"
 890 >&#13;cdl_component CYGBLD_GLOBAL_OPTIONS {
 891     display "Global build options"
 892     flavor  none
 893     parent  CYGPKG_NONE
 894     description   "
 895             Global build options including control over
 896             compiler flags, linker flags and choice of toolchain."
 897
 898
 899     cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
 900         display "Global command prefix"
 901         flavor  data
 902         no_define
 903         default_value { "mips-tx39-elf" }
 904         description "
 905             This option specifies the command prefix used when
 906             invoking the build tools."
 907     }
 908
 909     cdl_option CYGBLD_GLOBAL_CFLAGS {
 910         display "Global compiler flags"
 911         flavor  data
 912         no_define
 913         default_value { "-Wall -Wpointer-arith -Wstrict-prototypes -Winline -Wundef -Woverloaded-virtual -g -O2 -ffunction-sections -fdata-sections -fno-rtti -fno-exceptions -fvtable-gc -finit-priority" }
 914         description   "
 915             This option controls the global compiler flags which
 916             are used to compile all packages by
 917             default. Individual packages may define
 918             options which override these global flags."
 919     }
 920
 921     cdl_option CYGBLD_GLOBAL_LDFLAGS {
 922         display "Global linker flags"
 923         flavor  data
 924         no_define
 925         default_value { "-g -nostdlib -Wl,--gc-sections -Wl,-static" }
 926         description   "
 927             This option controls the global linker flags. Individual
 928             packages may define options which override these global flags."
 929     }
 930 }
 931
 932 cdl_component CYGHWR_MEMORY_LAYOUT {
 933     display "Memory layout"
 934     flavor data
 935     no_define
 936     calculated { CYG_HAL_STARTUP == "RAM" ? "mips_tx39_jmr3904_ram" : \
 937                                             "mips_tx39_jmr3904_rom" }
 938
 939     cdl_option CYGHWR_MEMORY_LAYOUT_LDI {
 940         display "Memory layout linker script fragment"
 941         flavor data
 942         no_define
 943         define -file system.h CYGHWR_MEMORY_LAYOUT_LDI
 944         calculated { CYG_HAL_STARTUP == "RAM" ? "&lt;pkgconf/mlt_mips_tx39_jmr3904_ram.ldi&gt;" : \
 945                                                 "&lt;pkgconf/mlt_mips_tx39_jmr3904_rom.ldi&gt;" }
 946     }
 947
 948     cdl_option CYGHWR_MEMORY_LAYOUT_H {
 949         display "Memory layout header file"
 950         flavor data
 951         no_define
 952         define -file system.h CYGHWR_MEMORY_LAYOUT_H
 953         calculated { CYG_HAL_STARTUP == "RAM" ? "&lt;pkgconf/mlt_mips_tx39_jmr3904_ram.h&gt;" : \
 954                                                 "&lt;pkgconf/mlt_mips_tx39_jmr3904_rom.h&gt;" }
 955     }
 956 }&#13;</PRE
 957 ></TD
 958 ></TR
 959 ></TABLE
 960 ></DIV
 961 ><DIV
 962 CLASS="SECTION"
 963 ><H3
 964 CLASS="SECTION"
 965 ><A
 966 NAME="AEN9585">Common Target Options</H3
 967 ><P
 968 >All platforms also specify real-time clock details:</P
 969 ><TABLE
 970 BORDER="5"
 971 BGCOLOR="#E0E0F0"
 972 WIDTH="70%"
 973 ><TR
 974 ><TD
 975 ><PRE
 976 CLASS="PROGRAMLISTING"
 977 ># Real-time clock/counter specifics
 978 cdl_component CYGNUM_HAL_RTC_CONSTANTS {
 979     display       "Real-time clock constants."
 980     flavor        none
 981
 982     cdl_option CYGNUM_HAL_RTC_NUMERATOR {
 983         display       "Real-time clock numerator"
 984         flavor        data
 985         calculated    1000000000
 986     }
 987     cdl_option CYGNUM_HAL_RTC_DENOMINATOR {
 988         display       "Real-time clock denominator"
 989         flavor        data
 990         calculated    100
 991     }
 992     # Isn't a nice way to handle freq requirement!
 993     cdl_option CYGNUM_HAL_RTC_PERIOD {
 994         display       "Real-time clock period"
 995         flavor        data
 996         legal_values  { 15360 20736 }
 997         calculated     { CYGHWR_HAL_MIPS_CPU_FREQ == 50 ? 15360 : \
 998                          CYGHWR_HAL_MIPS_CPU_FREQ == 66 ? 20736 : 0 }
 999     }
1000 }</PRE
1001 ></TD
1002 ></TR
1003 ></TABLE
1004 ><P
1005 > The <TT
1006 CLASS="LITERAL"
1007 >NUMERATOR</TT
1008 > divided by the
1009 <TT
1010 CLASS="LITERAL"
1011 >DENOMINATOR</TT
1012 > gives the number of nanoseconds per
1013 tick. The <TT
1014 CLASS="LITERAL"
1015 >PERIOD</TT
1016 > is the divider to be programmed
1017 into a hardware timer that is driven from an appropriate hardware
1018 clock, such that the timer overflows once per tick (normally
1019 generating a CPU interrupt to mark the end of a tick). The tick
1020 default rate is typically 100Hz.</P
1021 ><P
1022 >Platforms that make use of the virtual vector
1023 ROM calling interface (see <A
1024 HREF="hal-calling-if.html"
1025 >the Section called <I
1026 >Virtual Vectors (eCos/ROM Monitor Calling Interface)</I
1027 ></A
1028 >) will also
1029 specify details necessary to define configuration channels (these
1030 options are from the SH/EDK7707 HAL) :</P
1031 ><TABLE
1032 BORDER="5"
1033 BGCOLOR="#E0E0F0"
1034 WIDTH="70%"
1035 ><TR
1036 ><TD
1037 ><PRE
1038 CLASS="PROGRAMLISTING"
1039 >cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS {
1040     display      "Number of communication channels on the board"
1041     flavor       data
1042     calculated   1
1043 }
1044
1045 cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL {
1046     display          "Debug serial port"
1047     flavor data
1048     legal_values     0 to CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS-1
1049     default_value    0
1050     description      "
1051        The EDK/7708 board has only one serial port. This option
1052        chooses which port will be used to connect to a host
1053        running GDB."
1054 }
1055
1056 cdl_option CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL {
1057     display          "Diagnostic serial port"
1058     flavor data
1059     legal_values     0 to CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS-1
1060     default_value    0
1061     description      "
1062        The EDK/7708 board has only one serial port.  This option
1063        chooses which port will be used for diagnostic output."
1064 }</PRE
1065 ></TD
1066 ></TR
1067 ></TABLE
1068 ><P
1069 >The platform usually also specify an option controlling the ability
1070  to co-exist with a ROM monitor:</P
1071 ><TABLE
1072 BORDER="5"
1073 BGCOLOR="#E0E0F0"
1074 WIDTH="70%"
1075 ><TR
1076 ><TD
1077 ><PRE
1078 CLASS="PROGRAMLISTING"
1079 >cdl_option CYGSEM_HAL_USE_ROM_MONITOR {
1080     display       "Work with a ROM monitor"
1081     flavor        booldata
1082     legal_values  { "Generic" "CygMon" "GDB_stubs" }
1083     default_value { CYG_HAL_STARTUP == "RAM" ? "CygMon" : 0 }
1084     parent        CYGPKG_HAL_ROM_MONITOR
1085     requires      { CYG_HAL_STARTUP == "RAM" }
1086     description   "
1087         Support can be enabled for three different varieties of ROM monitor.
1088         This support changes various eCos semantics such as the encoding
1089         of diagnostic output, or the overriding of hardware interrupt
1090         vectors.
1091         Firstly there is \"Generic\" support which prevents the HAL
1092         from overriding the hardware vectors that it does not use, to
1093         instead allow an installed ROM monitor to handle them. This is
1094         the most basic support which is likely to be common to most
1095         implementations of ROM monitor.
1096         \"CygMon\" provides support for the Cygnus ROM Monitor.
1097         And finally, \"GDB_stubs\" provides support when GDB stubs are
1098         included in the ROM monitor or boot ROM."
1099 }</PRE
1100 ></TD
1101 ></TR
1102 ></TABLE
1103 ><P
1104 >Or the ability to be configured as a ROM monitor:</P
1105 ><TABLE
1106 BORDER="5"
1107 BGCOLOR="#E0E0F0"
1108 WIDTH="70%"
1109 ><TR
1110 ><TD
1111 ><PRE
1112 CLASS="PROGRAMLISTING"
1113 >cdl_option CYGSEM_HAL_ROM_MONITOR {
1114     display       "Behave as a ROM monitor"
1115     flavor        bool
1116     default_value 0
1117     parent        CYGPKG_HAL_ROM_MONITOR
1118     requires      { CYG_HAL_STARTUP == "ROM" }
1119     description   "
1120         Enable this option if this program is to be used as a ROM monitor,
1121         i.e. applications will be loaded into RAM on the board, and this
1122         ROM monitor may process exceptions or interrupts generated from the
1123         application. This enables features such as utilizing a separate
1124         interrupt stack when exceptions are generated."
1125 }</PRE
1126 ></TD
1127 ></TR
1128 ></TABLE
1129 ><P
1130 >The latter option is accompanied by a special build rule that
1131 extends the generic ROM monitor build rule in the common HAL:</P
1132 ><TABLE
1133 BORDER="5"
1134 BGCOLOR="#E0E0F0"
1135 WIDTH="70%"
1136 ><TR
1137 ><TD
1138 ><PRE
1139 CLASS="PROGRAMLISTING"
1140 >cdl_option CYGBLD_BUILD_GDB_STUBS {
1141     display "Build GDB stub ROM image"
1142     default_value 0
1143     requires { CYG_HAL_STARTUP == "ROM" }
1144     requires CYGSEM_HAL_ROM_MONITOR
1145     requires CYGBLD_BUILD_COMMON_GDB_STUBS
1146     requires CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
1147     requires ! CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
1148     requires ! CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT
1149     requires ! CYGDBG_HAL_COMMON_INTERRUPTS_SAVE_MINIMUM_CONTEXT
1150     requires ! CYGDBG_HAL_COMMON_CONTEXT_SAVE_MINIMUM
1151     no_define
1152     description "
1153         This option enables the building of the GDB stubs for the
1154         board. The common HAL controls takes care of most of the
1155         build process, but the final conversion from ELF image to
1156         binary data is handled by the platform CDL, allowing
1157         relocation of the data if necessary."
1158
1159     make -priority 320 {
1160         &lt;PREFIX&gt;/bin/gdb_module.bin : &lt;PREFIX&gt;/bin/gdb_module.img
1161         $(OBJCOPY) -O binary $&#60; $@
1162     }
1163 }</PRE
1164 ></TD
1165 ></TR
1166 ></TABLE
1167 ><P
1168 >Most platforms support RedBoot, and some options are needed to
1169 configure for RedBoot.</P
1170 ><TABLE
1171 BORDER="5"
1172 BGCOLOR="#E0E0F0"
1173 WIDTH="70%"
1174 ><TR
1175 ><TD
1176 ><PRE
1177 CLASS="PROGRAMLISTING"
1178 >    cdl_component CYGPKG_REDBOOT_HAL_OPTIONS {
1179         display       "Redboot HAL options"
1180         flavor        none
1181         no_define
1182         parent        CYGPKG_REDBOOT
1183         active_if     CYGPKG_REDBOOT
1184         description   "
1185             This option lists the target's requirements for a valid Redboot
1186             configuration."
1187
1188         cdl_option CYGBLD_BUILD_REDBOOT_BIN {
1189             display       "Build Redboot ROM binary image"
1190             active_if     CYGBLD_BUILD_REDBOOT
1191             default_value 1
1192             no_define
1193             description "This option enables the conversion of the Redboot ELF
1194                          image to a binary image suitable for ROM programming."
1195
1196             make -priority 325 {
1197                 &lt;PREFIX&gt;/bin/redboot.bin : &lt;PREFIX&gt;/bin/redboot.elf
1198                 $(OBJCOPY) --strip-debug $&#60; $(@:.bin=.img)
1199                 $(OBJCOPY) -O srec $&#60; $(@:.bin=.srec)
1200                 $(OBJCOPY) -O binary $&#60; $@
1201             }
1202         }
1203     }</PRE
1204 ></TD
1205 ></TR
1206 ></TABLE
1207 ><P
1208 >The important part here is the <TT
1209 CLASS="LITERAL"
1210 >make</TT
1211 > command in the
1212 <TT
1213 CLASS="LITERAL"
1214 >CYGBLD_BUILD_REDBOOT_BIN</TT
1215 > option which emits
1216 makefile commands to translate the <TT
1217 CLASS="FILENAME"
1218 >.elf</TT
1219 > file
1220 generated by the link phase into both a binary file and an S-Record
1221 file. If a different format is required by a PROM programmer or ROM
1222 monitor, then different output formats would need to be generated here.</P
1223 ></DIV
1224 ></DIV
1225 ><DIV
1226 CLASS="SECTION"
1227 ><H2
1228 CLASS="SECTION"
1229 ><A
1230 NAME="HAL-PORTING-PLATFORM-MEMORY-LAYOUT">Platform Memory Layout</H2
1231 ><P
1232 >The platform memory layout is defined using the Memory
1233 Configuration Window  in the Configuration Tool.</P
1234 ><DIV
1235 CLASS="NOTE"
1236 ><BLOCKQUOTE
1237 CLASS="NOTE"
1238 ><P
1239 ><B
1240 >Note: </B
1241 >If you do not have access to a Windows machine, you can
1242 hand edit the <TT
1243 CLASS="FILENAME"
1244 >.h</TT
1245 > and <TT
1246 CLASS="FILENAME"
1247 >.ldi</TT
1248 > files to match the
1249 properties of your platform. If you want to contribute your port back
1250 to the eCos community, ask someone on the list to make proper memory
1251 map files for you.</P
1252 ></BLOCKQUOTE
1253 ></DIV
1254 ><DIV
1255 CLASS="SECTION"
1256 ><H3
1257 CLASS="SECTION"
1258 ><A
1259 NAME="AEN9615">Layout Files</H3
1260 ><P
1261 >The memory configuration details are saved in three files:</P
1262 ><P
1263 ></P
1264 ><DIV
1265 CLASS="VARIABLELIST"
1266 ><DL
1267 ><DT
1268 ><TT
1269 CLASS="FILENAME"
1270 >.mlt</TT
1271 ></DT
1272 ><DD
1273 ><P
1274 >This is the Configuration Tool save-file. It is only used
1275         by the Configuration Tool.</P
1276 ></DD
1277 ><DT
1278 ><TT
1279 CLASS="FILENAME"
1280 >.ldi</TT
1281 ></DT
1282 ><DD
1283 ><P
1284 >This is the linker script fragment. It defines the memory
1285         and location of sections by way of macros defined in the
1286         architecture or variant linker script.</P
1287 ></DD
1288 ><DT
1289 ><TT
1290 CLASS="FILENAME"
1291 >.h</TT
1292 ></DT
1293 ><DD
1294 ><P
1295 >This file describes some of the memory region details as C
1296         macros, allowing eCos or the application adapt the memory
1297         layout of a specific configuration.</P
1298 ></DD
1299 ></DL
1300 ></DIV
1301 ><P
1302 >These three files are generated for each startup-type, since the
1303 memory details usually differ.</P
1304 ></DIV
1305 ><DIV
1306 CLASS="SECTION"
1307 ><H3
1308 CLASS="SECTION"
1309 ><A
1310 NAME="AEN9635">Reserved Regions</H3
1311 ><P
1312 >Some areas of the memory space are reserved for specific
1313 purposes, making room for exception vectors and various tables. RAM
1314 startup configurations also need to reserve some space at the bottom
1315 of the memory map for the ROM monitor.</P
1316 ><P
1317 >These reserved areas are named with the prefix "reserved_" which is
1318 handled specially by the Configuration Tool: instead of referring to a
1319 linker macro, the start of the area is labeled and a gap left in the
1320 memory map.</P
1321 ></DIV
1322 ></DIV
1323 ><DIV
1324 CLASS="SECTION"
1325 ><H2
1326 CLASS="SECTION"
1327 ><A
1328 NAME="AEN9639">Platform Serial Device Support</H2
1329 ><P
1330 >The first step is to set up the CDL definitions. The configuration
1331 options that need to be set are the following:</P
1332 ><P
1333 ></P
1334 ><DIV
1335 CLASS="VARIABLELIST"
1336 ><DL
1337 ><DT
1338 ><TT
1339 CLASS="LITERAL"
1340 >CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS</TT
1341 ></DT
1342 ><DD
1343 ><P
1344 >The number of channels, usually 0, 1 or 2.</P
1345 ></DD
1346 ><DT
1347 ><TT
1348 CLASS="LITERAL"
1349 >CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL</TT
1350 ></DT
1351 ><DD
1352 ><P
1353 >The channel to use for GDB.</P
1354 ></DD
1355 ><DT
1356 ><TT
1357 CLASS="LITERAL"
1358 >CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL_BAUD</TT
1359 ></DT
1360 ><DD
1361 ><P
1362 >Initial baud rate for debug channel.</P
1363 ></DD
1364 ><DT
1365 ><TT
1366 CLASS="LITERAL"
1367 >CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</TT
1368 ></DT
1369 ><DD
1370 ><P
1371 >The channel to use for the
1372     console.</P
1373 ></DD
1374 ><DT
1375 ><TT
1376 CLASS="LITERAL"
1377 >CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL_BAUD</TT
1378 ></DT
1379 ><DD
1380 ><P
1381 >The initial baud rate for the console
1382     channel.</P
1383 ></DD
1384 ><DT
1385 ><TT
1386 CLASS="LITERAL"
1387 >CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL_DEFAULT</TT
1388 ></DT
1389 ><DD
1390 ><P
1391 >The default console channel.</P
1392 ></DD
1393 ></DL
1394 ></DIV
1395 ><P
1396 >The code in <TT
1397 CLASS="FILENAME"
1398 >hal_diag.c</TT
1399 > need to be converted to
1400 support the new serial device.
1401 If this the same as a device already supported, copy that.</P
1402 ><P
1403 >The following functions and types need to be rewritten to support a new serial
1404 device.</P
1405 ><P
1406 ></P
1407 ><DIV
1408 CLASS="VARIABLELIST"
1409 ><DL
1410 ><DT
1411 ><TT
1412 CLASS="LITERAL"
1413 >struct channel_data_t;</TT
1414 ></DT
1415 ><DD
1416 ><P
1417 >      Structure containing base address, timeout and ISR vector number
1418       for each serial device supported. Extra fields my be added if
1419       necessary for the device. For example some devices have
1420       write-only control registers, so keeping a shadow of the last
1421       value written here can be useful.
1422       </P
1423 ></DD
1424 ><DT
1425 ><TT
1426 CLASS="LITERAL"
1427 >xxxx_ser_channels[];</TT
1428 ></DT
1429 ><DD
1430 ><P
1431 >       Array of <TT
1432 CLASS="LITERAL"
1433 >channel_data_t</TT
1434 >, initialized with parameters of each
1435         channel. The index into this array is the channel number used
1436         in the CDL options above and is used by the virtual vector
1437         mechanism to refer to each channel.
1438         </P
1439 ></DD
1440 ><DT
1441 ><TT
1442 CLASS="LITERAL"
1443 >void cyg_hal_plf_serial_init_channel(void
1444            *__ch_data)</TT
1445 ></DT
1446 ><DD
1447 ><P
1448 >       Initialize the serial device. The parameter is actually a pointer to a
1449         <TT
1450 CLASS="LITERAL"
1451 >channel_data_t</TT
1452 > and should be cast back to
1453         this type before use. This function should use the CDL
1454         definition for the baud rate for the channel it is initializing.
1455         </P
1456 ></DD
1457 ><DT
1458 ><TT
1459 CLASS="LITERAL"
1460 >void cyg_hal_plf_serial_putc(void * __ch_data,
1461                     char *c)</TT
1462 ></DT
1463 ><DD
1464 ><P
1465 >        Send a character to the serial device. This function should
1466         poll for the device being ready to send and then write the character.
1467         Since this is intended to be a diagnostic/debug channel, it is
1468         often also a good idea to poll for end of transmission
1469         too. This ensures that as much data gets out of the system as
1470         possible.
1471         </P
1472 ></DD
1473 ><DT
1474 ><TT
1475 CLASS="LITERAL"
1476 >bool cyg_hal_plf_serial_getc_nonblock(void*
1477                     __ch_data, cyg_uint8* ch)</TT
1478 ></DT
1479 ><DD
1480 ><P
1481 >        This function tests the device and if a character is
1482         available, places it in <TT
1483 CLASS="PARAMETER"
1484 ><I
1485 >*ch</I
1486 ></TT
1487 > and returns
1488         <TT
1489 CLASS="LITERAL"
1490 >TRUE</TT
1491 >. If no character is available, then
1492         the function returns <TT
1493 CLASS="LITERAL"
1494 >FALSE</TT
1495 > immediately.
1496         </P
1497 ></DD
1498 ><DT
1499 ><TT
1500 CLASS="LITERAL"
1501 >int cyg_hal_plf_serial_control(void *__ch_data,
1502                     __comm_control_cmd_t __func,
1503                     ...)</TT
1504 ></DT
1505 ><DD
1506 ><P
1507 >        This is an IOCTL-like function for controlling various aspects
1508         of the serial device. The only part in which you may need to
1509         do some work initially is in the
1510         <TT
1511 CLASS="LITERAL"
1512 >__COMMCTL_IRQ_ENABLE</TT
1513 > and
1514         <TT
1515 CLASS="LITERAL"
1516 >__COMMCTL_IRQ_DISABLE</TT
1517 > cases to
1518         enable/disable interrupts.
1519         </P
1520 ></DD
1521 ><DT
1522 ><TT
1523 CLASS="LITERAL"
1524 >int cyg_hal_plf_serial_isr(void *__ch_data, int* __ctrlc,
1525                        CYG_ADDRWORD __vector, CYG_ADDRWORD
1526                        __data)</TT
1527 ></DT
1528 ><DD
1529 ><P
1530 >        This interrupt handler, called from the spurious interrupt
1531         vector, is specifically for dealing with
1532         <TT
1533 CLASS="LITERAL"
1534 >Ctrl-C</TT
1535 > interrupts from GDB. When called
1536         this function should do the following:
1537         <P
1538 ></P
1539 ><OL
1540 TYPE="1"
1541 ><LI
1542 ><P
1543 >Check for an incoming character. The code here is very
1544           similar to that in
1545           <TT
1546 CLASS="FUNCTION"
1547 >cyg_hal_plf_serial_getc_nonblock()</TT
1548 >.
1549           </P
1550 ></LI
1551 ><LI
1552 ><P
1553 >         Read the character and call
1554           <TT
1555 CLASS="FUNCTION"
1556 >cyg_hal_is_break()</TT
1557 >.
1558           </P
1559 ></LI
1560 ><LI
1561 ><P
1562 >         If result is true, set <TT
1563 CLASS="PARAMETER"
1564 ><I
1565 >*__ctrlc</I
1566 ></TT
1567 > to
1568           <TT
1569 CLASS="LITERAL"
1570 >1</TT
1571 >.
1572           </P
1573 ></LI
1574 ><LI
1575 ><P
1576 >         Return <TT
1577 CLASS="LITERAL"
1578 >CYG_ISR_HANDLED</TT
1579 >.
1580           </P
1581 ></LI
1582 ></OL
1583 >
1584       </P
1585 ></DD
1586 ><DT
1587 ><TT
1588 CLASS="LITERAL"
1589 >void cyg_hal_plf_serial_init()</TT
1590 ></DT
1591 ><DD
1592 ><P
1593 >        Initialize each of the serial channels.
1594         First call <TT
1595 CLASS="FUNCTION"
1596 >cyg_hal_plf_serial_init_channel()</TT
1597 > for each channel.
1598         Then call the <TT
1599 CLASS="LITERAL"
1600 >CYGACC_COMM_IF_*</TT
1601 > macros for
1602         each channel. This latter set of calls are identical for all
1603         channels, so the best way to do this is to copy and edit an
1604         existing example.
1605         </P
1606 ></DD
1607 ></DL
1608 ></DIV
1609 ></DIV
1610 ></DIV
1611 ><DIV
1612 CLASS="NAVFOOTER"
1613 ><HR
1614 ALIGN="LEFT"
1615 WIDTH="100%"><TABLE
1616 SUMMARY="Footer navigation table"
1617 WIDTH="100%"
1618 BORDER="0"
1619 CELLPADDING="0"
1620 CELLSPACING="0"
1621 ><TR
1622 ><TD
1623 WIDTH="33%"
1624 ALIGN="left"
1625 VALIGN="top"
1626 ><A
1627 HREF="hal-porting-coding-conventions.html"
1628 ACCESSKEY="P"
1629 >Prev</A
1630 ></TD
1631 ><TD
1632 WIDTH="34%"
1633 ALIGN="center"
1634 VALIGN="top"
1635 ><A
1636 HREF="ecos-ref.html"
1637 ACCESSKEY="H"
1638 >Home</A
1639 ></TD
1640 ><TD
1641 WIDTH="33%"
1642 ALIGN="right"
1643 VALIGN="top"
1644 ><A
1645 HREF="hal-porting-variant.html"
1646 ACCESSKEY="N"
1647 >Next</A
1648 ></TD
1649 ></TR
1650 ><TR
1651 ><TD
1652 WIDTH="33%"
1653 ALIGN="left"
1654 VALIGN="top"
1655 >HAL Coding Conventions</TD
1656 ><TD
1657 WIDTH="34%"
1658 ALIGN="center"
1659 VALIGN="top"
1660 ><A
1661 HREF="hal-porting-guide.html"
1662 ACCESSKEY="U"
1663 >Up</A
1664 ></TD
1665 ><TD
1666 WIDTH="33%"
1667 ALIGN="right"
1668 VALIGN="top"
1669 >Variant HAL Porting</TD
1670 ></TR
1671 ></TABLE
1672 ></DIV
1673 ></BODY
1674 ></HTML
1675 >