OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [hal-calling-if.html] - Blame information for rev 842

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.