doc/html/ref/hal-calling-if.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 >Virtual Vectors (eCos/ROM Monitor Calling Interface)</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 Structure"
  26 HREF="hal-porting-structure.html"><LINK
  27 REL="NEXT"
  28 TITLE="HAL Coding Conventions"
  29 HREF="hal-porting-coding-conventions.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-structure.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-coding-conventions.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-CALLING-IF">Virtual Vectors (eCos/ROM Monitor Calling Interface)</H1
  86 ><P
  87 >Some eCos platforms have supported full debugging capabilities via
  88 CygMon since day one. Platforms of the architectures PowerPC, ARM, and
  89 SH do not provide those features unless a GDB stub is included in the
  90 application.</P
  91 ><P
  92 >This is going to change. All platforms will (eventually) support
  93 all the debugging features by relying on a ROM/RAM calling interface
  94 (also referred to as virtual vector table) provided by the ROM
  95 monitor. This calling interface is based on the tables used by libbsp
  96 and is thus backwards compatible with the existing CygMon supported
  97 platforms.</P
  98 ><DIV
  99 CLASS="SECTION"
 100 ><H2
 101 CLASS="SECTION"
 102 ><A
 103 NAME="HAL-PORTING-VIRTUAL-VECTORS">Virtual Vectors</H2
 104 ><P
 105 >What are virtual vectors, what do they do, and why are they
 106 needed?</P
 107 ><P
 108 >"Virtual vectors" is the name of a table located at a static
 109 location in the target address space. This table contains 64 vectors
 110 that point to <SPAN
 111 CLASS="emphasis"
 112 ><I
 113 CLASS="EMPHASIS"
 114 >service</I
 115 ></SPAN
 116 > functions or data.</P
 117 ><P
 118 >The fact that the vectors are always placed at the same location in
 119 the address space means that both ROM and RAM startup configurations
 120 can access these and thus the services pointed to.</P
 121 ><P
 122 >The primary goal is to allow services to be provided by ROM
 123 configurations (ROM monitors such as RedBoot in particular) with
 124 <SPAN
 125 CLASS="emphasis"
 126 ><I
 127 CLASS="EMPHASIS"
 128 >clients</I
 129 ></SPAN
 130 > in RAM configurations being able to use these
 131 services.</P
 132 ><P
 133 >Without the table of pointers this would be impossible since the
 134 ROM and RAM applications would be linked separately - in effect having
 135 separate name spaces - preventing direct references from one to the
 136 other.</P
 137 ><P
 138 >This decoupling of service from client is needed by RedBoot,
 139 allowing among other things debugging of applications which do not
 140 contain debugging client code (stubs).</P
 141 ><DIV
 142 CLASS="SECTION"
 143 ><H3
 144 CLASS="SECTION"
 145 ><A
 146 NAME="AEN8971">Initialization (or Mechanism vs. Policy)</H3
 147 ><P
 148 >Virtual vectors are a <SPAN
 149 CLASS="emphasis"
 150 ><I
 151 CLASS="EMPHASIS"
 152 >mechanism</I
 153 ></SPAN
 154 > for decoupling services
 155 from clients in the address space.</P
 156 ><P
 157 >The mechanism allows services to be implemented by a ROM
 158 monitor, a RAM application, to be switched out at run-time, to be
 159 disabled by installing pointers to dummy functions, etc.</P
 160 ><P
 161 >The appropriate use of the mechanism is specified loosely by a
 162 <SPAN
 163 CLASS="emphasis"
 164 ><I
 165 CLASS="EMPHASIS"
 166 >policy</I
 167 ></SPAN
 168 >. The general policy dictates that the vectors are
 169 initialized in whole by ROM monitors (built for ROM or RAM), or by
 170 stand-alone applications.</P
 171 ><P
 172 >For configurations relying on a ROM monitor environment, the policy
 173 is to allow initialization on a service by service basis. The default
 174 is to initialize all services, except COMMS services since these are
 175 presumed to already be carrying a communication session to the
 176 debugger / console which was used for launching the application.  This
 177 means that the bulk of the code gets tested in normal builds, and not
 178 just once in a blue moon when building new stubs or a ROM
 179 configuration.</P
 180 ><P
 181 >The configuration options are written to comply with this policy by
 182 default, but can be overridden by the user if desired. Defaults
 183 are:</P
 184 ><P
 185 ></P
 186 ><UL
 187 ><LI
 188 ><P
 189 >For application development: the ROM monitor provides
 190 debugging and diagnostic IO services, the RAM application relies
 191 on these by default.</P
 192 ></LI
 193 ><LI
 194 ><P
 195 >For production systems: the application contains all the
 196 necessary services.</P
 197 ></LI
 198 ></UL
 199 ></DIV
 200 ><DIV
 201 CLASS="SECTION"
 202 ><H3
 203 CLASS="SECTION"
 204 ><A
 205 NAME="AEN8985">Pros and Cons of Virtual Vectors</H3
 206 ><P
 207 >There are pros and cons associated with the use of virtual
 208 vectors. We do believe that the pros generally outweigh the cons by a
 209 great margin, but there may be situations where the opposite is
 210 true.</P
 211 ><P
 212 >The use of the services are implemented by way of macros, meaning
 213 that it is possible to circumvent the virtual vectors if
 214 desired. There is (as yet) no implementation for doing this, but it is
 215 possible.</P
 216 ><P
 217 >Here is a list of pros and cons:</P
 218 ><P
 219 ></P
 220 ><DIV
 221 CLASS="VARIABLELIST"
 222 ><DL
 223 ><DT
 224 >Pro: Allows debugging without including stubs</DT
 225 ><DD
 226 ><P
 227 >This is the primary reason for using virtual vectors. It
 228           allows the ROM monitor to provide most of the debugging
 229           infrastructure, requiring only the application to provide
 230           hooks for asynchronous debugger interrupts and for accessing
 231           kernel thread information.</P
 232 ></DD
 233 ><DT
 234 >Pro: Allows debugging to be initiated from arbitrary
 235        channel</DT
 236 ><DD
 237 ><P
 238 > While this is only true where the application does not
 239            actively override the debugging channel setup, it is a very
 240            nice feature during development. In particular it makes it
 241            possible to launch (and/or debug) applications via Ethernet
 242            even though the application configuration does not contain
 243            networking support.</P
 244 ></DD
 245 ><DT
 246 >Pro: Image smaller due to services being provided by ROM
 247        monitor</DT
 248 ><DD
 249 ><P
 250 >All service functions except HAL IO are included in the
 251            default configuration. But if these are all disabled the
 252            image for download will be a little smaller. Probably
 253            doesn't matter much for regular development, but it is a
 254            worthwhile saving for the 20000 daily tests run in the Red
 255            Hat eCos test farm.</P
 256 ></DD
 257 ><DT
 258 >Con: The vectors add a layer of indirection, increasing application
 259        size and reducing performance.</DT
 260 ><DD
 261 ><P
 262 >The size increase is a fraction of what is required to
 263            implement the services. So for RAM configurations there is
 264            a net saving, while for ROM configurations there is a small
 265            overhead.</P
 266 ><P
 267 >The performance loss means little for most of the
 268            services (of which the most commonly used is diagnostic IO
 269            which happens via polled routines
 270            anyway).</P
 271 ></DD
 272 ><DT
 273 >Con: The layer of indirection is another point of
 274        failure.</DT
 275 ><DD
 276 ><P
 277 > The concern primarily being that of vectors being
 278            trashed by rogue writes from bad code, causing a complete
 279            loss of the service and possibly a crash.  But this does
 280            not differ much from a rogue write to anywhere else in the
 281            address space which could cause the same amount of
 282            mayhem. But it is arguably an additional point of failure
 283            for the service in question.</P
 284 ></DD
 285 ><DT
 286 >Con: All the indirection stuff makes it harder to bring a HAL
 287        up</DT
 288 ><DD
 289 ><P
 290 > This is a valid concern. However, seeing as most of the
 291            code in question is shared between all HALs and should
 292            remain unchanged over time, the risk of it being broken
 293            when a new HAL is being worked on should be
 294            minimal.</P
 295 ><P
 296 > When starting a new port, be sure to implement the HAL
 297            IO drivers according to the scheme used in other drivers,
 298            and there should be no problem.</P
 299 ><P
 300 > However, it is still possible to circumvent the vectors
 301            if they are suspect of causing problems: simply change the
 302            HAL_DIAG_INIT and HAL_DIAG_WRITE_CHAR macros to use the raw
 303            IO functions.</P
 304 ></DD
 305 ></DL
 306 ></DIV
 307 ></DIV
 308 ><DIV
 309 CLASS="SECTION"
 310 ><H3
 311 CLASS="SECTION"
 312 ><A
 313 NAME="AEN9018">Available services</H3
 314 ><P
 315 >The <TT
 316 CLASS="FILENAME"
 317 >hal_if.h</TT
 318 > file in the common HAL defines the
 319 complete list of available services. A few worth mentioning in
 320 particular:</P
 321 ><P
 322 ></P
 323 ><UL
 324 ><LI
 325 ><P
 326 >COMMS services. All HAL IO happens via the communication
 327         channels.</P
 328 ></LI
 329 ><LI
 330 ><P
 331 >uS delay. Fine granularity (busy wait) delay function.</P
 332 ></LI
 333 ><LI
 334 ><P
 335 >Reset. Allows a software initiated reset of the board.</P
 336 ></LI
 337 ></UL
 338 ></DIV
 339 ></DIV
 340 ><DIV
 341 CLASS="SECTION"
 342 ><H2
 343 CLASS="SECTION"
 344 ><A
 345 NAME="AEN9029">The COMMS channels</H2
 346 ><P
 347 >As all HAL IO happens via the COMMS channels these deserve to be
 348 described in a little more detail. In particular the controls of where
 349 diagnostic output is routed and how it is treated to allow for display
 350 in debuggers.</P
 351 ><DIV
 352 CLASS="SECTION"
 353 ><H3
 354 CLASS="SECTION"
 355 ><A
 356 NAME="AEN9032">Console and Debugging Channels</H3
 357 ><P
 358 >There are two COMMS channels - one for console IO and one for
 359 debugging IO. They can be individually configured to use any of the
 360 actual IO ports (serial or Ethernet) available on the platform.</P
 361 ><P
 362 >The console channel is used for any IO initiated by calling the
 363 <TT
 364 CLASS="FUNCTION"
 365 >diag_*()</TT
 366 > functions. Note that these should only be used during
 367 development for debugging, assertion and possibly tracing
 368 messages. All proper IO should happen via proper devices. This means
 369 it should be possible to remove the HAL device drivers from production
 370 configurations where assertions are disabled.</P
 371 ><P
 372 >The debugging channel is used for communication between the
 373 debugger and the stub which remotely controls the target for the
 374 debugger (the stub runs on the target). This usually happens via some
 375 protocol, encoding commands and replies in some suitable form.</P
 376 ><P
 377 >Having two separate channels allows, e.g., for simple logging
 378 without conflicts with the debugger or interactive IO which some
 379 debuggers do not allow.</P
 380 ></DIV
 381 ><DIV
 382 CLASS="SECTION"
 383 ><H3
 384 CLASS="SECTION"
 385 ><A
 386 NAME="AEN9039">Mangling</H3
 387 ><P
 388 >As debuggers usually have a protocol using specialized commands
 389 when communicating with the stub on the target, sending out text as
 390 raw ASCII from the target on the same channel will either result in
 391 protocol errors (with loss of control over the target) or the text may
 392 just be ignored as junk by the debugger.</P
 393 ><P
 394 >To get around this, some debuggers have a special command for text
 395 output. Mangling is the process of encoding diagnostic ASCII text
 396 output in the form specified by the debugger protocol.</P
 397 ><P
 398 >When it is necessary to use mangling, i.e. when writing console
 399 output to the same port used for debugging, a mangler function is
 400 installed on the console channel which mangles the text and passes it
 401 on to the debugger channel.</P
 402 ></DIV
 403 ><DIV
 404 CLASS="SECTION"
 405 ><H3
 406 CLASS="SECTION"
 407 ><A
 408 NAME="AEN9044">Controlling the Console Channel</H3
 409 ><P
 410 >Console output configuration is either inherited from the ROM
 411 monitor launching the application, or it is specified by the
 412 application. This is controlled by the new option
 413 <TT
 414 CLASS="LITERAL"
 415 >CYGSEM_HAL_VIRTUAL_VECTOR_INHERIT_CONSOLE</TT
 416 > which
 417 defaults to enabled when the configuration is set to use a ROM
 418 monitor.</P
 419 ><P
 420 >If the user wants to specify the console configuration in the
 421 application image, there are two new options that are used for
 422 this.</P
 423 ><P
 424 >Defaults are to direct diagnostic output via a mangler to the
 425 debugging channel (<TT
 426 CLASS="LITERAL"
 427 >CYGDBG_HAL_DIAG_TO_DEBUG_CHAN</TT
 428 >
 429 enabled). The mangler type is controlled by the option
 430 <TT
 431 CLASS="LITERAL"
 432 >CYGSEM_HAL_DIAG_MANGLER</TT
 433 >. At present there are only
 434 two mangler types:</P
 435 ><P
 436 ></P
 437 ><DIV
 438 CLASS="VARIABLELIST"
 439 ><DL
 440 ><DT
 441 ><SPAN
 442 CLASS="ACRONYM"
 443 >GDB</SPAN
 444 ></DT
 445 ><DD
 446 ><P
 447 > This causes a mangler appropriate for debugging with GDB to be
 448        installed on the console channel.</P
 449 ></DD
 450 ><DT
 451 >None</DT
 452 ><DD
 453 ><P
 454 > This causes a NULL mangler to be installed on the console
 455         channel.  It will redirect the IO to/from the debug channel
 456         without mangling of the data. This option differs from setting
 457         the console channel to the same IO port as the debugging
 458         channel in that it will keep redirecting data to the debugging
 459         channel even if that is changed to some other port.</P
 460 ></DD
 461 ></DL
 462 ></DIV
 463 ><P
 464 >Finally, by disabling <TT
 465 CLASS="LITERAL"
 466 >CYGDBG_HAL_DIAG_TO_DEBUG_CHAN</TT
 467 >, the diagnostic
 468 output is directed in raw form to the specified console IO port.</P
 469 ><P
 470 >In summary this results in the following common configuration
 471 scenarios for RAM startup configurations:</P
 472 ><P
 473 ></P
 474 ><UL
 475 ><LI
 476 ><P
 477 > For regular debugging with diagnostic output appearing in the
 478      debugger, mangling is enabled and stubs disabled.</P
 479 ><P
 480 >Diagnostic output appears via the debugging channel as
 481      initiated by the ROM monitor, allowing for correct behavior
 482      whether the application was launched via serial or Ethernet, from
 483      the RedBoot command line or from a debugger.</P
 484 ></LI
 485 ><LI
 486 ><P
 487 > For debugging with raw diagnostic output, mangling is
 488      disabled.</P
 489 ><P
 490 > Debugging session continues as initiated by the ROM monitor,
 491      whether the application was launched via serial or
 492      Ethernet. Diagnostic output is directed at the IO port configured
 493      in the application configuration.</P
 494 ><DIV
 495 CLASS="NOTE"
 496 ><BLOCKQUOTE
 497 CLASS="NOTE"
 498 ><P
 499 ><B
 500 >Note:: </B
 501 > There is one caveat to be aware of. If the
 502        application uses proper devices (be it serial or Ethernet) on
 503        the same ports as those used by the ROM monitor, the
 504        connections initiated by the ROM monitor will be
 505        terminated.</P
 506 ></BLOCKQUOTE
 507 ></DIV
 508 ></LI
 509 ></UL
 510 ><P
 511 >And for ROM startup configurations:</P
 512 ><P
 513 ></P
 514 ><UL
 515 ><LI
 516 ><P
 517 > Production configuration with raw output and no debugging
 518      features (configured for RAM or ROM), mangling is disabled, no
 519      stubs are included.</P
 520 ><P
 521 >Diagnostic output appears (in unmangled form) on the specified
 522      IO port.</P
 523 ></LI
 524 ><LI
 525 ><P
 526 > RedBoot configuration, includes debugging features and necessary
 527      mangling.</P
 528 ><P
 529 >Diagnostic and debugging output port is auto-selected by the
 530      first connection to any of the supported IO ports. Can change
 531      from interactive mode to debugging mode when a debugger is
 532      detected - when this happens a mangler will be installed as
 533      required.</P
 534 ></LI
 535 ><LI
 536 ><P
 537 > GDB stubs configuration (obsoleted by RedBoot configuration),
 538      includes debugging features, mangling is hardwired to GDB
 539      protocol.</P
 540 ><P
 541 >Diagnostic and debugging output is hardwired to configured IO
 542      ports, mangling is hardwired.</P
 543 ></LI
 544 ></UL
 545 ></DIV
 546 ><DIV
 547 CLASS="SECTION"
 548 ><H3
 549 CLASS="SECTION"
 550 ><A
 551 NAME="AEN9086">Footnote: Design Reasoning for Control of Console Channel</H3
 552 ><P
 553 >The current code for controlling the console channel is a
 554 replacement for an older implementation which had some shortcomings
 555 which addressed by the new implementation.</P
 556 ><P
 557 >This is what the old implementation did: on initialization it would
 558 check if the CDL configured console channel differed from the active
 559 debug channel - and if so, set the console channel, thereby disabling
 560 mangling.</P
 561 ><P
 562 >The idea was that whatever channel was configured to be used for
 563 console (i.e., diagnostic output) in the application was what should
 564 be used. Also, it meant that if debug and console channels were
 565 normally the same, a changed console channel would imply a request for
 566 unmangled output.</P
 567 ><P
 568 >But this prevented at least two things:</P
 569 ><P
 570 ></P
 571 ><UL
 572 ><LI
 573 ><P
 574 > It was impossible to inherit the existing connection by which
 575      the application was launched (either by RedBoot commands via
 576      telnet, or by via a debugger).</P
 577 ><P
 578 >This was mostly a problem on targets supporting Ethernet
 579      access since the diagnostic output would not be returned via the
 580      Ethernet connection, but on the configured serial port.</P
 581 ><P
 582 >The problem also occurred on any targets with multiple serial
 583      ports where the ROM monitor was configured to use a different
 584      port than the CDL defaults.</P
 585 ></LI
 586 ><LI
 587 ><P
 588 > Proper control of when to mangle or just write out raw ASCII
 589         text.</P
 590 ><P
 591 >Sometimes it's desirable to disable mangling, even if the
 592      channel specified is the same as that used for debugging. This
 593      usually happens if GDB is used to download the application, but
 594      direct interaction with the application on the same channel is
 595      desired (GDB protocol only allows output from the target, no
 596      input).</P
 597 ></LI
 598 ></UL
 599 ></DIV
 600 ></DIV
 601 ><DIV
 602 CLASS="SECTION"
 603 ><H2
 604 CLASS="SECTION"
 605 ><A
 606 NAME="AEN9100">The calling Interface API</H2
 607 ><P
 608 >The calling interface API is defined by hal_if.h and hal_if.c in
 609 hal/common.</P
 610 ><P
 611 >The API provides a set of services. Different platforms, or
 612 different versions of the ROM monitor for a single platform, may
 613 implement fewer or extra service. The table has room for growth, and
 614 any entries which are not supported map to a NOP-service (when called
 615 it returns 0 (<TT
 616 CLASS="LITERAL"
 617 >false</TT
 618 >)).</P
 619 ><P
 620 >A client of a service should either be selected by configuration,
 621 or have suitable fall back alternatives in case the feature is not
 622 implemented by the ROM monitor.</P
 623 ><DIV
 624 CLASS="NOTE"
 625 ><BLOCKQUOTE
 626 CLASS="NOTE"
 627 ><P
 628 ><B
 629 >Note:: </B
 630 >Checking for unimplemented service when this may be a data
 631 field/pointer instead of a function: suggest reserving the last entry
 632 in the table as the NOP-service pointer. Then clients can compare a
 633 service entry with this pointer to determine whether it's initialized
 634 or not.</P
 635 ></BLOCKQUOTE
 636 ></DIV
 637 ><P
 638 >The header file <TT
 639 CLASS="FILENAME"
 640 >cyg/hal/hal_if.h</TT
 641 > defines
 642  the table layout and accessor macros (allowing primitive type
 643  checking and alternative implementations should it become necessary).</P
 644 ><P
 645 >The source file <TT
 646 CLASS="FILENAME"
 647 >hal_if.c</TT
 648 > defines the table
 649  initialization function. All HALs should call this during platform
 650  initialization - the table will get initialized according to
 651  configuration.  Also defined here are wrapper functions which map
 652  between the calling interface API and the API of the used eCos
 653  functions.</P
 654 ><DIV
 655 CLASS="SECTION"
 656 ><H3
 657 CLASS="SECTION"
 658 ><A
 659 NAME="AEN9113">Implemented Services</H3
 660 ><P
 661 >This is a brief description of the services, some of which are
 662 described in further detail below.</P
 663 ><P
 664 ></P
 665 ><DIV
 666 CLASS="VARIABLELIST"
 667 ><DL
 668 ><DT
 669 ><TT
 670 CLASS="LITERAL"
 671 >VERSION</TT
 672 ></DT
 673 ><DD
 674 ><P
 675 >Version of table. Serves as a way to check for how many
 676         features are available in the table. This is the index of the
 677         last service in the table.</P
 678 ></DD
 679 ><DT
 680 ><TT
 681 CLASS="LITERAL"
 682 >KILL_VECTOR</TT
 683 ></DT
 684 ><DD
 685 ><P
 686 >[Presently unused by the stub code, but initialized] This
 687         vector defines a function to execute when the system receives
 688         a kill signal from the debugger. It is initialized with the
 689         reset function (see below), but the application (or eCos) can
 690         override it if necessary.</P
 691 ></DD
 692 ><DT
 693 ><TT
 694 CLASS="LITERAL"
 695 >CONSOLE_PROCS</TT
 696 ></DT
 697 ><DD
 698 ><P
 699 >The communication procedure table used for console IO
 700         (see <A
 701 HREF="hal-calling-if.html#HAL-PORTING-IO-CHANNELS"
 702 >the Section called <I
 703 >IO channels</I
 704 ></A
 705 >.</P
 706 ></DD
 707 ><DT
 708 ><TT
 709 CLASS="LITERAL"
 710 >DEBUG_PROCS</TT
 711 ></DT
 712 ><DD
 713 ><P
 714 >The communication procedure table used for debugger IO
 715         (see <A
 716 HREF="hal-calling-if.html#HAL-PORTING-IO-CHANNELS"
 717 >the Section called <I
 718 >IO channels</I
 719 ></A
 720 >).</P
 721 ></DD
 722 ><DT
 723 ><TT
 724 CLASS="LITERAL"
 725 >FLUSH_DCACHE</TT
 726 ></DT
 727 ><DD
 728 ><P
 729 >Flushes the data cache for the specified
 730         region. Some implementations may flush the entire data cache.</P
 731 ></DD
 732 ><DT
 733 ><TT
 734 CLASS="LITERAL"
 735 >FLUSH_ICACHE</TT
 736 ></DT
 737 ><DD
 738 ><P
 739 >Flushes (invalidates) the instruction cache
 740         for the specified region. Some implementations may flush the
 741         entire instruction cache.</P
 742 ></DD
 743 ><DT
 744 ><TT
 745 CLASS="LITERAL"
 746 >SET_DEBUG_COMM</TT
 747 ></DT
 748 ><DD
 749 ><P
 750 >Change debugging communication channel.</P
 751 ></DD
 752 ><DT
 753 ><TT
 754 CLASS="LITERAL"
 755 >SET_CONSOLE_COMM</TT
 756 ></DT
 757 ><DD
 758 ><P
 759 >Change console communication channel.</P
 760 ></DD
 761 ><DT
 762 ><TT
 763 CLASS="LITERAL"
 764 >DBG_SYSCALL</TT
 765 ></DT
 766 ><DD
 767 ><P
 768 >Vector used to communication between debugger functions in
 769         ROM and in RAM. RAM eCos configurations may install a function
 770         pointer here which the ROM monitor uses to get thread
 771         information from the kernel running in RAM.</P
 772 ></DD
 773 ><DT
 774 ><TT
 775 CLASS="LITERAL"
 776 >RESET</TT
 777 ></DT
 778 ><DD
 779 ><P
 780 >Resets the board on call. If it is not possible to reset
 781         the board from software, it will jump to the ROM entry point
 782         which will perform a "software" reset of the board.</P
 783 ></DD
 784 ><DT
 785 ><TT
 786 CLASS="LITERAL"
 787 >CONSOLE_INTERRUPT_FLAG</TT
 788 ></DT
 789 ><DD
 790 ><P
 791 >Set if a debugger interrupt request was detected while
 792         processing console IO. Allows the actual breakpoint action to
 793         be handled after return to RAM, ensuring proper backtraces
 794         etc.</P
 795 ></DD
 796 ><DT
 797 ><TT
 798 CLASS="LITERAL"
 799 >DELAY_US</TT
 800 ></DT
 801 ><DD
 802 ><P
 803 >Will delay the specified number of microseconds. The
 804         precision is platform dependent to some extend - a small value
 805         (&#60;100us) is likely to cause bigger delays than requested.</P
 806 ></DD
 807 ><DT
 808 ><TT
 809 CLASS="LITERAL"
 810 >FLASH_CFG_OP</TT
 811 ></DT
 812 ><DD
 813 ><P
 814 >For accessing configuration settings kept in flash memory.</P
 815 ></DD
 816 ><DT
 817 ><TT
 818 CLASS="LITERAL"
 819 >INSTALL_BPT_FN</TT
 820 ></DT
 821 ><DD
 822 ><P
 823 >Installs a breakpoint at the specified address. This is
 824         used by the asynchronous breakpoint support
 825         (see ).</P
 826 ></DD
 827 ></DL
 828 ></DIV
 829 ></DIV
 830 ><DIV
 831 CLASS="SECTION"
 832 ><H3
 833 CLASS="SECTION"
 834 ><A
 835 NAME="AEN9189">Compatibility</H3
 836 ><P
 837 >When a platform is changed to support the calling interface,
 838 applications will use it if so configured. That means that if an
 839 application is run on a platform with an older ROM monitor, the
 840 service is almost guaranteed to fail.</P
 841 ><P
 842 >For this reason, applications should only use Console Comm for HAL
 843 diagnostics output if explicitly configured to do so
 844 (<TT
 845 CLASS="LITERAL"
 846 >CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
 847 >).</P
 848 ><P
 849 >As for asynchronous GDB interrupts, the service will always be
 850 used. This is likely to cause a crash under older ROM monitors, but
 851 this crash may be caught by the debugger. The old workaround still
 852 applies: if you need asynchronous breakpoints or thread debugging
 853 under older ROM monitors, you may have to include the debugging
 854 support when configuring eCos.</P
 855 ></DIV
 856 ><DIV
 857 CLASS="SECTION"
 858 ><H3
 859 CLASS="SECTION"
 860 ><A
 861 NAME="AEN9195">Implementation details</H3
 862 ><P
 863 >During the startup of a ROM monitor, the calling table will be
 864 initialized. This also happens if eCos is configured <SPAN
 865 CLASS="emphasis"
 866 ><I
 867 CLASS="EMPHASIS"
 868 >not</I
 869 ></SPAN
 870 > to rely on
 871 a ROM monitor.</P
 872 ><DIV
 873 CLASS="NOTE"
 874 ><BLOCKQUOTE
 875 CLASS="NOTE"
 876 ><P
 877 ><B
 878 >Note:: </B
 879 > There is reserved space (256 bytes) for the vector
 880 table whether it gets used or not. This may be something that we want
 881 to change if we ever have to shave off every last byte for a given
 882 target.</P
 883 ></BLOCKQUOTE
 884 ></DIV
 885 ><P
 886 >If thread debugging features are enabled, the function for accessing
 887 the thread information gets registered in the table during startup of
 888 a RAM startup configuration.</P
 889 ><P
 890 >Further implementation details are described where the service itself
 891 is described.</P
 892 ></DIV
 893 ><DIV
 894 CLASS="SECTION"
 895 ><H3
 896 CLASS="SECTION"
 897 ><A
 898 NAME="AEN9204">New Platform Ports</H3
 899 ><P
 900 >The <TT
 901 CLASS="FUNCTION"
 902 >hal_platform_init()</TT
 903 > function must call
 904 <TT
 905 CLASS="FUNCTION"
 906 >hal_if_init()</TT
 907 >.</P
 908 ><P
 909 >The HAL serial driver must, when called via
 910 <TT
 911 CLASS="FUNCTION"
 912 >cyg_hal_plf_comms_init()</TT
 913 > must initialize the
 914 communication channels.</P
 915 ><P
 916 >The <TT
 917 CLASS="FUNCTION"
 918 >reset()</TT
 919 > function defined in
 920 <TT
 921 CLASS="FILENAME"
 922 >hal_if.c</TT
 923 > will attempt to do a hardware reset, but
 924 if this fails it will fall back to simply jumping to the reset
 925 entry-point. On most platforms the startup initialization will go a
 926 long way to reset the target to a sane state (there will be
 927 exceptions, of course). For this reason, make sure to define
 928 <TT
 929 CLASS="LITERAL"
 930 >HAL_STUB_PLATFORM_RESET_ENTRY</TT
 931 > in plf_stub.h.</P
 932 ><P
 933 >All debugging features must be in place in order for the debugging
 934 services to be functional. See general platform porting notes.</P
 935 ></DIV
 936 ><DIV
 937 CLASS="SECTION"
 938 ><H3
 939 CLASS="SECTION"
 940 ><A
 941 NAME="AEN9216">New architecture ports</H3
 942 ><P
 943 >There are no specific requirements for a new architecture port in
 944 order to support the calling interface, but the basic debugging
 945 features must be in place. See general architecture porting notes.</P
 946 ></DIV
 947 ></DIV
 948 ><DIV
 949 CLASS="SECTION"
 950 ><H2
 951 CLASS="SECTION"
 952 ><A
 953 NAME="HAL-PORTING-IO-CHANNELS">IO channels</H2
 954 ><P
 955 >The calling interface provides procedure tables for all IO channels on
 956 the platform. These are used for console (diagnostic) and debugger IO,
 957 allowing a ROM monitor to provided all the needed IO routines. At
 958 the same time, this makes it easy to switch console/debugger channels
 959 at run-time (the old implementation had hardwired drivers for console
 960 and debugger IO, preventing these to change at run-time).</P
 961 ><P
 962 >The hal_if provides wrappers which interface these services to the
 963 eCos infrastructure diagnostics routines. This is done in a way which
 964 ensures proper string mangling of the diagnostics output when required
 965 (e.g. O-packetization when using a GDB compatible ROM monitor).</P
 966 ><DIV
 967 CLASS="SECTION"
 968 ><H3
 969 CLASS="SECTION"
 970 ><A
 971 NAME="AEN9223">Available Procedures</H3
 972 ><P
 973 >This is a brief description of the procedures</P
 974 ><P
 975 ></P
 976 ><DIV
 977 CLASS="VARIABLELIST"
 978 ><DL
 979 ><DT
 980 ><TT
 981 CLASS="LITERAL"
 982 >CH_DATA</TT
 983 ></DT
 984 ><DD
 985 ><P
 986 >Pointer to the controller IO base (or a pointer to a per-device
 987     structure if more data than the IO base is required). All the
 988     procedures below are called with this data item as the first
 989     argument.</P
 990 ></DD
 991 ><DT
 992 ><TT
 993 CLASS="LITERAL"
 994 >WRITE</TT
 995 ></DT
 996 ><DD
 997 ><P
 998 >Writes the buffer to the device.</P
 999 ></DD
1000 ><DT
1001 ><TT
1002 CLASS="LITERAL"
1003 >READ</TT
1004 ></DT
1005 ><DD
1006 ><P
1007 >Fills a buffer from the device.</P
1008 ></DD
1009 ><DT
1010 ><TT
1011 CLASS="LITERAL"
1012 >PUTC</TT
1013 ></DT
1014 ><DD
1015 ><P
1016 >Write a character to the device.</P
1017 ></DD
1018 ><DT
1019 ><TT
1020 CLASS="LITERAL"
1021 >GETC</TT
1022 ></DT
1023 ><DD
1024 ><P
1025 >Read a character from the device.</P
1026 ></DD
1027 ><DT
1028 ><TT
1029 CLASS="LITERAL"
1030 >CONTROL</TT
1031 ></DT
1032 ><DD
1033 ><P
1034 >Device feature control. Second argument specifies function:</P
1035 ><P
1036 ></P
1037 ><DIV
1038 CLASS="VARIABLELIST"
1039 ><DL
1040 ><DT
1041 ><TT
1042 CLASS="LITERAL"
1043 >SETBAUD</TT
1044 ></DT
1045 ><DD
1046 ><P
1047 >Changes baud rate.</P
1048 ></DD
1049 ><DT
1050 ><TT
1051 CLASS="LITERAL"
1052 >GETBAUD</TT
1053 ></DT
1054 ><DD
1055 ><P
1056 >Returns the current baud rate.</P
1057 ></DD
1058 ><DT
1059 ><TT
1060 CLASS="LITERAL"
1061 >INSTALL_DBG_ISR</TT
1062 ></DT
1063 ><DD
1064 ><P
1065 >[Unused]</P
1066 ></DD
1067 ><DT
1068 ><TT
1069 CLASS="LITERAL"
1070 >REMOVE_DBG_ISR</TT
1071 ></DT
1072 ><DD
1073 ><P
1074 >[Unused]</P
1075 ></DD
1076 ><DT
1077 ><TT
1078 CLASS="LITERAL"
1079 >IRQ_DISABLE</TT
1080 ></DT
1081 ><DD
1082 ><P
1083 >Disable debugging receive interrupts on the device.</P
1084 ></DD
1085 ><DT
1086 ><TT
1087 CLASS="LITERAL"
1088 >IRQ_ENABLE</TT
1089 ></DT
1090 ><DD
1091 ><P
1092 >Enable debugging receive interrupts on the device.</P
1093 ></DD
1094 ><DT
1095 ><TT
1096 CLASS="LITERAL"
1097 >DBG_ISR_VECTOR</TT
1098 ></DT
1099 ><DD
1100 ><P
1101 >Returns the ISR vector used by the device for debugging
1102         receive interrupts.</P
1103 ></DD
1104 ><DT
1105 ><TT
1106 CLASS="LITERAL"
1107 >SET_TIMEOUT</TT
1108 ></DT
1109 ><DD
1110 ><P
1111 >Set GETC timeout in milliseconds.</P
1112 ></DD
1113 ><DT
1114 ><TT
1115 CLASS="LITERAL"
1116 >FLUSH_OUTPUT</TT
1117 ></DT
1118 ><DD
1119 ><P
1120 >Forces driver to flush data in its buffers. Note
1121             that this may not affect hardware buffers
1122         (e.g. FIFOs).</P
1123 ></DD
1124 ></DL
1125 ></DIV
1126 ></DD
1127 ><DT
1128 ><TT
1129 CLASS="LITERAL"
1130 >DBG_ISR</TT
1131 ></DT
1132 ><DD
1133 ><P
1134 >ISR used to handle receive interrupts from the
1135         device (see ).</P
1136 ></DD
1137 ><DT
1138 ><TT
1139 CLASS="LITERAL"
1140 >GETC_TIMEOUT</TT
1141 ></DT
1142 ><DD
1143 ><P
1144 >Read a character from the device with timeout.</P
1145 ></DD
1146 ></DL
1147 ></DIV
1148 ></DIV
1149 ><DIV
1150 CLASS="SECTION"
1151 ><H3
1152 CLASS="SECTION"
1153 ><A
1154 NAME="AEN9313">Usage</H3
1155 ><P
1156 >The standard eCos diagnostics IO functions use the channel
1157 procedure table when <TT
1158 CLASS="LITERAL"
1159 >CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
1160 > is enabled. That
1161 means that when you use diag_printf (or the libc printf function) the
1162 stream goes through the selected console procedure table. If you use
1163 the virtual vector function SET_CONSOLE_COMM you can change the device
1164 which the diagnostics output goes to at run-time.</P
1165 ><P
1166 >You can also use the table functions directly if desired
1167 (regardless of the <TT
1168 CLASS="LITERAL"
1169 >CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
1170 > setting - assuming
1171 the ROM monitor provides the services). Here is a small example which
1172 changes the console to use channel 2, fetches the comm procs pointer
1173 and calls the write function from that table, then restores the
1174 console to the original channel:</P
1175 ><TABLE
1176 BORDER="5"
1177 BGCOLOR="#E0E0F0"
1178 WIDTH="70%"
1179 ><TR
1180 ><TD
1181 ><PRE
1182 CLASS="PROGRAMLISTING"
1183 >#define T "Hello World!\n"
1184
1185 int
1186 main(void)
1187 {
1188     hal_virtual_comm_table_t* comm;
1189     int cur = CYGACC_CALL_IF_SET_CONSOLE_COMM(CYGNUM_CALL_IF_SET_COMM_ID_QUERY_CURRENT);
1190
1191     CYGACC_CALL_IF_SET_CONSOLE_COMM(2);
1192
1193     comm = CYGACC_CALL_IF_CONSOLE_PROCS();
1194     CYGACC_COMM_IF_WRITE(*comm, T, strlen(T));
1195
1196     CYGACC_CALL_IF_SET_CONSOLE_COMM(cur);
1197 }</PRE
1198 ></TD
1199 ></TR
1200 ></TABLE
1201 ><P
1202 >Beware that if doing something like the above, you should only do
1203 it to a channel which does not have GDB at the other end: GDB ignores
1204 raw data, so you would not see the output.</P
1205 ></DIV
1206 ><DIV
1207 CLASS="SECTION"
1208 ><H3
1209 CLASS="SECTION"
1210 ><A
1211 NAME="AEN9321">Compatibility</H3
1212 ><P
1213 >The use of this service is controlled by the option
1214 <TT
1215 CLASS="LITERAL"
1216 >CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
1217 > which is disabled per default on most
1218 older platforms (thus preserving backwards compatibility with older
1219 stubs). On newer ports, this option should always be set.</P
1220 ></DIV
1221 ><DIV
1222 CLASS="SECTION"
1223 ><H3
1224 CLASS="SECTION"
1225 ><A
1226 NAME="AEN9325">Implementation Details</H3
1227 ><P
1228 >There is an array of procedure tables (raw comm channels) for each
1229 IO device of the platform which get initialized by the ROM monitor, or
1230 optionally by a RAM startup configuration (allowing the RAM
1231 configuration to take full control of the target).  In addition to
1232 this, there's a special table which is used to hold mangler
1233 procedures.</P
1234 ><P
1235 >The vector table defines which of these channels are selected for
1236 console and debugging IO respectively: console entry can be empty,
1237 point to mangler channel, or point to a raw channel. The debugger
1238 entry should always point to a raw channel.</P
1239 ><P
1240 >During normal console output (i.e., diagnostic output) the console
1241 table will be used to handle IO if defined. If not defined, the debug
1242 table will be used.</P
1243 ><P
1244 >This means that debuggers (such as GDB) which require text streams
1245 to be mangled (O-packetized in the case of GDB), can rely on the ROM
1246 monitor install mangling IO routines in the special mangler table and
1247 select this for console output. The mangler will pass the mangled data
1248 on to the selected debugging channel.</P
1249 ><P
1250 >If the eCos configuration specifies a different console channel
1251 from that used by the debugger, the console entry will point to the
1252 selected raw channel, thus overriding any mangler provided by the ROM
1253 monitor.</P
1254 ><P
1255 >See hal_if_diag_* routines in hal_if.c for more details of the stream
1256 path of diagnostic output. See <TT
1257 CLASS="FUNCTION"
1258 >cyg_hal_gdb_diag_*()</TT
1259 > routines in
1260 <TT
1261 CLASS="FILENAME"
1262 >hal_stub.c</TT
1263 > for the mangler used for GDB communication.</P
1264 ></DIV
1265 ><DIV
1266 CLASS="SECTION"
1267 ><H3
1268 CLASS="SECTION"
1269 ><A
1270 NAME="AEN9335">New Platform Ports</H3
1271 ><P
1272 >Define CDL options <TT
1273 CLASS="LITERAL"
1274 >CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS</TT
1275 >,
1276 <TT
1277 CLASS="LITERAL"
1278 >CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL</TT
1279 >, and
1280 <TT
1281 CLASS="LITERAL"
1282 >CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</TT
1283 >.</P
1284 ><P
1285 >If <TT
1286 CLASS="LITERAL"
1287 >CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
1288 > is set, make sure the infra diag
1289 code uses the hal_if diag functions:</P
1290 ><TABLE
1291 BORDER="5"
1292 BGCOLOR="#E0E0F0"
1293 WIDTH="70%"
1294 ><TR
1295 ><TD
1296 ><PRE
1297 CLASS="PROGRAMLISTING"
1298 > #define HAL_DIAG_INIT() hal_if_diag_init()
1299  #define HAL_DIAG_WRITE_CHAR(_c_) hal_if_diag_write_char(_c_)
1300  #define HAL_DIAG_READ_CHAR(_c_) hal_if_diag_read_char(&#38;_c_)</PRE
1301 ></TD
1302 ></TR
1303 ></TABLE
1304 ><P
1305 >In addition to the above functions, the platform HAL must also
1306 provide a function cyg_hal_plf_comms_init which initializes the
1307 drivers and the channel procedure tables.</P
1308 ><P
1309 >Most of the other functionality in the table is more or less
1310 possible to copy unchanged from existing ports. Some care is necessary
1311 though to ensure the proper handling of interrupt vectors and timeouts
1312 for various devices handled by the same driver. See PowerPC/Cogent
1313 platform HAL for an example implementation.</P
1314 ><DIV
1315 CLASS="NOTE"
1316 ><BLOCKQUOTE
1317 CLASS="NOTE"
1318 ><P
1319 ><B
1320 >Note:: </B
1321 > When vector table console code is <SPAN
1322 CLASS="emphasis"
1323 ><I
1324 CLASS="EMPHASIS"
1325 >not</I
1326 ></SPAN
1327 > used,
1328 the platform HAL must map the HAL_DIAG_INIT, HAL_DIAG_WRITE_CHAR and
1329 HAL_DIAG_READ_CHAR macros directly to the low-level IO functions,
1330 hardwired to use a compile-time configured channel.</P
1331 ></BLOCKQUOTE
1332 ></DIV
1333 ><DIV
1334 CLASS="NOTE"
1335 ><BLOCKQUOTE
1336 CLASS="NOTE"
1337 ><P
1338 ><B
1339 >Note:: </B
1340 > On old ports the hardwired <TT
1341 CLASS="LITERAL"
1342 >HAL_DIAG_INIT</TT
1343 >,
1344 <TT
1345 CLASS="LITERAL"
1346 >HAL_DIAG_WRITE_CHAR</TT
1347 > and
1348 <TT
1349 CLASS="LITERAL"
1350 >HAL_DIAG_READ_CHAR</TT
1351 > implementations will also
1352 contain code to O-packetize the output for GDB. This should
1353 <SPAN
1354 CLASS="emphasis"
1355 ><I
1356 CLASS="EMPHASIS"
1357 >not</I
1358 ></SPAN
1359 > be adopted for new ports! On new ports the
1360 ROM monitor is guaranteed to provide the necessary mangling via the
1361 vector table. The hardwired configuration should be reserved for ROM
1362 startups where achieving minimal image size is crucial.</P
1363 ></BLOCKQUOTE
1364 ></DIV
1365 ></DIV
1366 ></DIV
1367 ></DIV
1368 ><DIV
1369 CLASS="NAVFOOTER"
1370 ><HR
1371 ALIGN="LEFT"
1372 WIDTH="100%"><TABLE
1373 SUMMARY="Footer navigation table"
1374 WIDTH="100%"
1375 BORDER="0"
1376 CELLPADDING="0"
1377 CELLSPACING="0"
1378 ><TR
1379 ><TD
1380 WIDTH="33%"
1381 ALIGN="left"
1382 VALIGN="top"
1383 ><A
1384 HREF="hal-porting-structure.html"
1385 ACCESSKEY="P"
1386 >Prev</A
1387 ></TD
1388 ><TD
1389 WIDTH="34%"
1390 ALIGN="center"
1391 VALIGN="top"
1392 ><A
1393 HREF="ecos-ref.html"
1394 ACCESSKEY="H"
1395 >Home</A
1396 ></TD
1397 ><TD
1398 WIDTH="33%"
1399 ALIGN="right"
1400 VALIGN="top"
1401 ><A
1402 HREF="hal-porting-coding-conventions.html"
1403 ACCESSKEY="N"
1404 >Next</A
1405 ></TD
1406 ></TR
1407 ><TR
1408 ><TD
1409 WIDTH="33%"
1410 ALIGN="left"
1411 VALIGN="top"
1412 >HAL Structure</TD
1413 ><TD
1414 WIDTH="34%"
1415 ALIGN="center"
1416 VALIGN="top"
1417 ><A
1418 HREF="hal-porting-guide.html"
1419 ACCESSKEY="U"
1420 >Up</A
1421 ></TD
1422 ><TD
1423 WIDTH="33%"
1424 ALIGN="right"
1425 VALIGN="top"
1426 >HAL Coding Conventions</TD
1427 ></TR
1428 ></TABLE
1429 ></DIV
1430 ></BODY
1431 ></HTML
1432 >