OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [hal-porting-platform.html] - Blame information for rev 314

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 
>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 
>

powered by: WebSVN 2.1.0

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