| blob | babc22eea0376e61e80ec00a0601a58fc9417166 |
1 \input texinfo @c -*- Texinfo -*-
2 @setfilename porting.info
3 @settitle Embed with GNU
5 @c
6 @c This file documents the process of porting the GNU tools to an
7 @c embedded environment.
8 @c
10 @finalout
11 @setchapternewpage off
12 @iftex
13 @raggedbottom
14 @global@parindent=0pt
15 @end iftex
17 @titlepage
18 @title Embed With GNU
19 @subtitle Porting The GNU Tools To Embedded Systems
20 @sp 4
21 @subtitle Spring 1995
22 @subtitle Very *Rough* Draft
23 @author Rob Savoye - Cygnus Support
24 @page
26 @vskip 0pt plus 1filll
27 Copyright @copyright{} 1993, 1994, 1995 Cygnus Support
29 Permission is granted to make and distribute verbatim copies of
30 this manual provided the copyright notice and this permission notice
31 are preserved on all copies.
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided also that
35 the entire resulting derived work is distributed under the terms of a
36 permission notice identical to this one.
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions.
40 @end titlepage
42 @ifinfo
43 @format
44 START-INFO-DIR-ENTRY
45 * Embed with GNU: (porting-). Embed with GNU
46 END-INFO-DIR-ENTRY
47 @end format
48 Copyright (c) 1993, 1994, 1995 Cygnus Support
50 Permission is granted to make and distribute verbatim copies of
51 this manual provided the copyright notice and this permission notice
52 are preserved on all copies.
54 Permission is granted to copy and distribute modified versions of this
55 manual under the conditions for verbatim copying, provided also that
56 the entire resulting derived work is distributed under the terms of a
57 permission notice identical to this one.
59 Permission is granted to copy and distribute translations of this manual
60 into another language, under the above conditions for modified versions.
62 @node Top
63 @top Embed with GNU
65 @end ifinfo
66 @strong{Rough Draft}
68 The goal of this document is to gather all the information needed to
69 port the GNU tools to a new embedded target in one place. This will
70 duplicate some info found in the other manual for the GNU tools, but
71 this should be all you'll need.
73 @menu
74 * Libgloss:: Libgloss, a library of board support packages.
75 * GCC:: Porting GCC/G++ to a new embedded target.
76 * Libraries:: Making Newlib run on an new embedded target.
77 * GDB:: Making GDB understand a new back end.
78 * Binutils:: Using the GNU binary utilities.
79 * Code Listings:: Listings of the commented source code from the
80 text.
81 @end menu
83 @node Libgloss, GCC, Top, Top
84 @chapter Libgloss
85 Libgloss is a library for all the details that usually get glossed over.
86 This library refers to things like startup code, and usually I/O support
87 for @code{gcc} and @code{C library}. The C library used through out
88 this manual is @code{newlib}. Newlib is a ANSI conforming C library
89 developed by Cygnus Support. Libgloss could easily be made to
90 support other C libraries, and it can be used standalone as well. The
91 standalone configuration is typically used when bringing up new
92 hardware, or on small systems.
94 For a long time, these details were part of newlib. This approach worked
95 well when a complete tool chain only had to support one system. A tool
96 chain refers to the series of compiler passes required to produce a
97 binary file that will run on an embedded system. For C, the passes are
98 cpp, gcc, gas, ld. Cpp is the preprocessor, which process all the header
99 files and macros. Gcc is the compiler, which produces assembler from the
100 processed C files. Gas assembles the code into object files, and then ld
101 combines the object files and binds the code to addresses and produces
102 the final executable image.
104 Most of the time a tool chain does only have to support one target
105 execution environment. An example of this would be a tool chain for the
106 AMD 29k processor family. All of the execution environments for this
107 processor are have the same interface, the same memory map, and the same
108 I/O code. In this case all of the support code is in newlib/sys/FIXME.
109 Libgloss's creation was forced initially be the @code{cpu32} processor
110 family. There are many different execution environments for this line,
111 and they vary wildly. newlib itself has only has a few dependencies that
112 it needs for each target. These are explained later in this doc. The
113 hardware dependent part of newlib was reorganized into a separate
114 directory structure within newlib called the stub dirs. It was initially
115 called this because most of the routines newlib needs for a target were
116 simple stubs that do nothing, but return a value to the application. They
117 only exist so the linker can produce a final executable image. This work
118 was done during the early part of 1993.
120 After a while it became apparent that this approach of isolating the
121 hardware and systems files together made sense. Around this same time
122 the stub dirs were made to run standalone, mostly so it could also be
123 used to support GDB's remote debugging needs. At this time it was
124 decided to move the stub dirs out of newlib and into it's own separate
125 library so it could be used standalone, and be included in various other
126 GNU tools without having to bring in all of newlib, which is large. The
127 new library is called Libgloss, for Gnu Low-level OS support.
129 @menu
130 * Supported targets:: What targets libgloss currently
131 supports.
132 * Building libgloss:: How to configure and built libgloss
133 for a target.
134 @end menu
136 @node Supported targets, Building libgloss, Libgloss, Libgloss
137 @subsection Supported Targets
138 Currently libgloss is being used for the following targets:
140 @menu
141 * Sparclite:: Fujitsu's sparclite.
142 * CPU32:: Various m68k based targets.
143 * Mips:: Mips code based targets.
144 * PA-RISC:: Precision Risc Organization..
145 @end menu
147 @node Sparclite, CPU32, , Supported targets
148 @subsection Sparclite Targets Supported
149 @c FIXME: put links to the docs in etc/targetdoc
150 This is for the Fujitsu Sparclite family of processors. Currently this
151 covers the ex930, ex931, ex932, ex933, and the ex934. In addition to the
152 I/O code a startup file, this has a GDB debug-stub that gets linked into
153 your application. This is an exception handler style debug stub. For
154 more info, see the section on Porting GDB. @ref{GDB,,Porting GDB}.
156 The Fujitsu eval boards use a host based terminal program to load and
157 execute programs on the target. This program, @code{pciuh} is relatively
158 new (in 1994) and it replaced the previous ROM monitor which had the
159 shell in the ROM. GDB uses the the GDB remote protocol, the relevant
160 source files from the gdb sources are remote-sparcl.c. The debug stub is
161 part of libgloss and is called sparcl-stub.c.
163 @node CPU32, Mips, Sparclite, Supported targets
164 @subsection Motorola CPU32 Targets supported
165 This refers to Motorola's m68k based CPU32 processor family. The crt0.S
166 startup file should be usable with any target environment, and it's
167 mostly just the I/O code and linker scripts that vary. Currently there
168 is support for the Motorola MVME line of 6U VME boards and IDP
169 line of eval boards. All of the
170 Motorola VME boards run @code{Bug}, a ROM based debug monitor.
171 This monitor has the feature of using user level traps to do I/O, so
172 this code should be portable to other MVME boards with little if any
173 change. The startup file also can remain unchanged. About the only thing
174 that varies is the address for where the text section begins. This can
175 be accomplished either in the linker script, or on the command line
176 using the @samp{-Ttext [address]}.
178 @c FIXME: Intermetrics or ISI wrote rom68k ?
179 There is also support for the @code{rom68k} monitor as shipped on
180 Motorola's IDP eval board line. This code should be portable across the
181 range of CPU's the board supports. There is also GDB support for this
182 target environment in the GDB source tree. The relevant files are
183 gdb/monitor.c, monitor.h, and rom58k-rom.c. The usage of these files is
184 discussed in the GDB section.
186 @node Mips, PA-RISC, CPU32, Supported targets
187 @subsection Mips core Targets Supported
188 The Crt0 startup file should run on any mips target that doesn't require
189 additional hardware initialization. The I/O code so far only supports a
190 custom LSI33k based RAID disk controller board. It should easy to
191 change to support the IDT line of eval boards. Currently the two
192 debugging protocols supported by GDB for mips targets is IDT's mips
193 debug protocol, and a customized hybrid of the standard GDB remote
194 protocol and GDB's standard ROM monitor support. Included here is the
195 debug stub for the hybrid monitor. This supports the LSI33k processor,
196 and only has support for the GDB protocol commands @code{g}, @code{G},
197 @code{m}, @code{M}, which basically only supports the register and
198 memory reading and writing commands. This is part of libgloss and is
199 called lsi33k-stub.c.
201 The crt0.S should also work on the IDT line of eval boards, but has only
202 been run on the LSI33k for now. There is no I/O support for the IDT eval
203 board at this time. The current I/O code is for a customized version of
204 LSI's @code{pmon} ROM monitor. This uses entry points into the monitor,
205 and should easily port to other versions of the pmon monitor. Pmon is
206 distributed in source by LSI.
208 @node PA-RISC, , Mips, Supported targets
209 @subsection PA-RISC Targets Supported
210 This supports the various boards manufactured by the HP-PRO consortium.
211 This is a group of companies all making variations on the PA-RISC
212 processor. Currently supported are ports to the WinBond @samp{Cougar}
213 board based around their w89k version of the PA. Also supported is the
214 Oki op50n processor.
216 There is also included, but never built an unfinished port to the HP 743
217 board. This board is the main CPU board for the HP700 line of industrial
218 computers. This target isn't exactly an embedded system, in fact it's
219 really only designed to load and run HP-UX. Still, the crt0.S and I/O
220 code are fully working. It is included mostly because their is a barely
221 functioning exception handler GDB debug stub, and I hope somebody could
222 use it. The other PRO targets all use GDB's ability to talk to ROM
223 monitors directly, so it doesn't need a debug stub. There is also a
224 utility that will produce a bootable file by HP's ROM monitor. This is
225 all included in the hopes somebody else will finish it. :-)
227 Both the WinBond board and the Oki board download srecords. The WinBond
228 board also has support for loading the SOM files as produced by the
229 native compiler on HP-UX. WinBond supplies a set of DOS programs that
230 will allow the loading of files via a bidirectional parallel port. This
231 has never been tested with the output of GNU SOM, as this manual is
232 mostly for Unix based systems.
234 @node Building libgloss, , Supported targets, Libgloss
235 @subsection Configuring and building libgloss.
237 Libgloss uses an autoconf based script to configure. Autoconf scripts
238 are portable shell scripts that are generated from a configure.in file.
239 Configure input scripts are based themselves on m4. Most configure
240 scripts run a series of tests to determine features the various
241 supported features of the target. For features that can't be determined
242 by a feature test, a makefile fragment is merged in. The configure
243 process leaves creates a Makefile in the build directory. For libgloss,
244 there are only a few configure options of importance. These are --target
245 and --srcdir.
247 Typically libgloss is built in a separate tree just for objects. In this
248 manner, it's possible to have a single source tree, and multiple object
249 trees. If you only need to configure for a single target environment,
250 then you can configure in the source tree. The argument for --target is
251 a config string. It's usually safest to use the full canonical opposed
252 to the target alias. So, to configure for a CPU32 (m68k) with a separate
253 source tree, use:
255 @smallexample
256 ../src/libgloss/configure --verbose --target m68k-coff
257 @end smallexample
259 The configure script is in the source tree. When configure is invoked
260 it will determine it's own source tree, so the --srcdir is would be
261 redundant here.
263 Once libgloss is configured, @code{make} is sufficient to build it. The
264 default values for @code{Makefiles} are typically correct for all
265 supported systems. The test cases in the testsuite will also built
266 automatically as opposed to a @code{make check}, where test binaries
267 aren't built till test time. This is mostly cause the libgloss
268 testsuites are the last thing built when building the entire GNU source
269 tree, so it's a good test of all the other compilation passes.
271 The default values for the Makefiles are set in the Makefile fragment
272 merged in during configuration. This fragment typically has rules like
274 @smallexample
275 CC_FOR_TARGET = `if [ -f $$@{OBJROOT@}/gcc/xgcc ] ; \
276 then echo $@{OBJROOT@}/gcc/xgcc -B$@{OBJROOT@}/gcc/ ; \
277 else t='$@{program_transform_name@}'; echo gcc | sed -e '' $$t ; fi`
278 @end smallexample
280 Basically this is a runtime test to determine whether there are freshly
281 built executables for the other main passes of the GNU tools. If there
282 isn't an executable built in the same object tree, then
283 @emph{transformed}the generic tool name (like gcc) is transformed to the
284 name typically used in GNU cross compilers. The names are
285 typically based on the target's canonical name, so if you've configured
286 for @code{m68k-coff} the transformed name is @code{m68k-coff-gcc} in
287 this case. If you install with aliases or rename the tools, this won't
288 work, and it will always look for tools in the path. You can force the a
289 different name to work by reconfiguring with the
290 @code{--program-transform-name} option to configure. This option takes a
291 sed script like this @code{-e s,^,m68k-coff-,} which produces tools
292 using the standard names (at least here at Cygnus).
294 The search for the other GNU development tools is exactly the same idea.
295 This technique gets messier when build options like @code{-msoft-float}
296 support are used. The Makefile fragments set the @code{MUTILIB}
297 variable, and if it is set, the search path is modified. If the linking
298 is done with an installed cross compiler, then none of this needs to be
299 used. This is done so libgloss will build automatically with a fresh,
300 and uninstalled object tree. It also makes it easier to debug the other
301 tools using libgloss's test suites.
303 @node GCC, Libraries, Libgloss, Top
304 @chapter Porting GCC
306 Porting GCC requires two things, neither of which has anything to do
307 with GCC. If GCC already supports a processor type, then all the work in
308 porting GCC is really a linker issue. All GCC has to do is produce
309 assembler output in the proper syntax. Most of the work is done by the
310 linker, which is described elsewhere.
312 Mostly all GCC does is format the command line for the linker pass. The
313 command line for GCC is set in the various config subdirectories of gcc.
314 The options of interest to us are @code{CPP_SPEC} and
315 @code{STARTFILE_SPEC}. CPP_SPEC sets the builtin defines for your
316 environment. If you support multiple environments with the same
317 processor, then OS specific defines will need to be elsewhere.
318 @c FIXME: Check these names
320 @code{STARTFILE_SPEC}
322 Once you have linker support, GCC will be able to produce a fully linked
323 executable image. The only @emph{part} of GCC that the linker wants is a
324 crt0.o, and a memory map. If you plan on running any programs that do
325 I/O of any kind, you'll need to write support for the C library, which
326 is described elsewhere.
328 @menu
329 * Overview:: An overview as to the compilation passes.
330 * Options:: Useful GCC options for embedded systems.
331 @end menu
333 @node Overview, Options, , GCC
334 @subsection Compilation passes
336 GCC by itself only compiles the C or C++ code into assembler. Typically
337 GCC invokes all the passes required for you. These passes are cpp, cc1,
338 gas, ld. @code{cpp} is the C preprocessor. This will merge in the
339 include files, expand all macros definitions, and process all the
340 @code{#ifdef} sections. To see the output of ccp, invoke gcc with the
341 @code{-E} option, and the preprocessed file will be printed on the
342 stdout. cc1 is the actual compiler pass that produces the assembler for
343 the processed file. GCC is actually only a driver program for all the
344 compiler passes. It will format command line options for the other passes.
345 The usual command line GCC uses for the final link phase will have LD
346 link in the startup code and additional libraries by default.
348 GNU AS started it's life to only function as a compiler pass, but
349 these days it can also be used as a source level assembler. When used as
350 a source level assembler, it has a companion assembler preprocessor
351 called @code{gasp}. This has a syntax similar to most other assembler
352 macros packages. GAS emits a relocatable object file from the assembler
353 source. The object file contains the executable part of the application,
354 and debug symbols.
356 LD is responsible for resolving the addresses and symbols to something
357 that will be fully self-contained. Some RTOS's use relocatable object
358 file formats like @code{a.out}, but more commonly the final image will
359 only use absolute addresses for symbols. This enables code to be burned
360 into PROMS as well. Although LD can produce an executable image, there
361 is usually a hidden object file called @code{crt0.o} that is required as
362 startup code. With this startup code and a memory map, the executable
363 image will actually run on the target environment. @ref{Crt0,,Startup
364 Files}.
366 The startup code usually defines a special symbol like @code{_start}
367 that is the default base address for the application, and the first
368 symbol in the executable image. If you plan to use any routines from the
369 standard C library, you'll also need to implement the functions that
370 this library is dependent on. @ref{Libraries,,Porting Newlib}.
372 @node Options, , Overview, GCC
373 @c FIXME: Need stuff here about -fpic, -Ttext, etc...
375 Options for the various development tools are covered in more detail
376 elsewhere. Still, the amount of options can be an overwhelming amount of
377 stuff, so the options most suited to embedded systems are summarized
378 here. If you use GCC as the main driver for all the passes, most of the
379 linker options can be passed directly to the compiler. There are also
380 GCC options that control how the GCC driver formats the command line
381 arguments for the linker.
383 @menu
384 * GCC Options:: Options for the compiler.
385 * GAS Options:: Options for the assembler.
386 * LD Options:: Options for the linker.
387 @end menu
389 @node GCC Options, GAS Options, , Options
390 Most of the GCC options that we're interested control how the GCC driver
391 formats the options for the linker pass.
393 @c FIXME: this section is still under work.
394 @table @code
395 @item -nostartfiles
396 @item -nostdlib
397 @item -Xlinker
398 Pass the next option directly to the linker.
400 @item -v
401 @item -fpic
402 @end table
404 @node GAS Options, LD Options, GCC Options, Options
405 @c FIXME: Needs stuff here
407 @node LD Options, , GAS Options, Options
408 @c FIXME: Needs stuff here
411 @node Libraries, GDB, GCC, Top
412 @chapter Porting newlib
414 @menu
415 * Crt0:: Crt0.S.
416 * Linker Scripts:: Linker scripts for memory management.
417 * What to do now:: Tricks for manipulating formats.
418 * Libc:: Making libc work.
419 @end menu
421 @node Crt0, Linker Scripts, , Libraries
422 @section Crt0, the main startup file
424 To make a program that has been compiled with GCC to run, you
425 need to write some startup code. The initial piece of startup code is
426 called a crt0. (C RunTime 0) This is usually written in assembler, and
427 it's object gets linked in first, and bootstraps the rest of the
428 application when executed. This file needs to do the following things.
430 @enumerate
431 @item
432 Initialize anything that needs it. This init section varies. If you are
433 developing an application that gets download to a ROM monitor, then
434 there is usually no need for any special initialization. The ROM monitor
435 handles it for you.
437 If you plan to burn your code in a ROM, then the crt0 typically has to
438 do all the hardware initialization that is required to run an
439 application. This can include things like initializing serial ports or
440 run a memory check. It all depends on the hardware.
442 @item
443 Zero the BSS section. This is for uninitialized data. All the addresses in
444 this section need to be initialized to zero so that programs that forget
445 to check new variables default value will get unpredictable results.
447 @item
448 Call main()
449 This is what basically starts things running. If your ROM monitor
450 supports it, then first setup argc and argv for command line arguments
451 and an environment pointer. Then branch to main(). For G++ the the main
452 routine gets a branch to __main inserted by the code generator at the
453 very top. __main() is used by G++ to initialize it's internal tables.
454 __main() then returns back to your original main() and your code gets
455 executed.
457 @item
458 Call exit()
459 After main() has returned, you need to cleanup things and return control
460 of the hardware from the application. On some hardware, there is nothing
461 to return to, especially if your program is in ROM. Sometimes the best
462 thing to do in this case is do a hardware reset, or branch back to the
463 start address all over again.
465 When there is a ROM monitor present, usually a user trap can be called
466 and then the ROM takes over. Pick a safe vector with no side
467 effects. Some ROMs have a builtin trap handler just for this case.
468 @end enumerate
469 portable between all the m68k based boards we have here.
470 @ref{crt0.S,,Example Crt0.S}.
473 @smallexample
474 /* ANSI concatenation macros. */
476 #define CONCAT1(a, b) CONCAT2(a, b)
477 #define CONCAT2(a, b) a ## b
478 @end smallexample
479 These we'll use later.
481 @smallexample
482 /* These are predefined by new versions of GNU cpp. */
484 #ifndef __USER_LABEL_PREFIX__
485 #define __USER_LABEL_PREFIX__ _
486 #endif
488 /* Use the right prefix for global labels. */
489 #define SYM(x) CONCAT1 (__USER_LABEL_PREFIX__, x)
491 @end smallexample
493 These macros are to make this code portable between both @emph{COFF} and
494 @emph{a.out}. @emph{COFF} always has an @var{_ (underline)} prepended on
495 the front of all global symbol names. @emph{a.out} has none.
497 @smallexample
498 #ifndef __REGISTER_PREFIX__
499 #define __REGISTER_PREFIX__
500 #endif
502 /* Use the right prefix for registers. */
503 #define REG(x) CONCAT1 (__REGISTER_PREFIX__, x)
505 #define d0 REG (d0)
506 #define d1 REG (d1)
507 #define d2 REG (d2)
508 #define d3 REG (d3)
509 #define d4 REG (d4)
510 #define d5 REG (d5)
511 #define d6 REG (d6)
512 #define d7 REG (d7)
513 #define a0 REG (a0)
514 #define a1 REG (a1)
515 #define a2 REG (a2)
516 #define a3 REG (a3)
517 #define a4 REG (a4)
518 #define a5 REG (a5)
519 #define a6 REG (a6)
520 #define fp REG (fp)
521 #define sp REG (sp)
522 @end smallexample
524 This is for portability between assemblers. Some register names have a
525 @var{%} or @var{$} prepended to the register name.
527 @smallexample
528 /*
529 * Set up some room for a stack. We just grab a chunk of memory.
530 */
531 .set stack_size, 0x2000
532 .comm SYM (stack), stack_size
533 @end smallexample
535 Set up space for the stack. This can also be done in the linker script,
536 but it typically gets done here.
538 @smallexample
539 /*
540 * Define an empty environment.
541 */
542 .data
543 .align 2
544 SYM (environ):
545 .long 0
546 @end smallexample
548 Set up an empty space for the environment. This is bogus on any most ROM
549 monitor, but we setup a valid address for it, and pass it to main. At
550 least that way if an application checks for it, it won't crash.
552 @smallexample
553 .align 2
554 .text
555 .global SYM (stack)
557 .global SYM (main)
558 .global SYM (exit)
559 /*
560 * This really should be __bss_start, not SYM (__bss_start).
561 */
562 .global __bss_start
563 @end smallexample
565 Setup a few global symbols that get used elsewhere. @var{__bss_start}
566 needs to be unchanged, as it's setup by the linker script.
568 @smallexample
569 /*
570 * start -- set things up so the application will run.
571 */
572 SYM (start):
573 link a6, #-8
574 moveal #SYM (stack) + stack_size, sp
576 /*
577 * zerobss -- zero out the bss section
578 */
579 moveal #__bss_start, a0
580 moveal #SYM (end), a1
581 1:
582 movel #0, (a0)
583 leal 4(a0), a0
584 cmpal a0, a1
585 bne 1b
586 @end smallexample
588 The global symbol @code{start} is used by the linker as the default
589 address to use for the @code{.text} section. then it zeros the
590 @code{.bss} section so the uninitialized data will all be cleared. Some
591 programs have wild side effects from having the .bss section let
592 uncleared. Particularly it causes problems with some implementations of
593 @code{malloc}.
595 @smallexample
596 /*
597 * Call the main routine from the application to get it going.
598 * main (argc, argv, environ)
599 * We pass argv as a pointer to NULL.
600 */
601 pea 0
602 pea SYM (environ)
603 pea sp@@(4)
604 pea 0
605 jsr SYM (main)
606 movel d0, sp@@-
607 @end smallexample
609 Setup the environment pointer and jump to @code{main()}. When
610 @code{main()} returns, it drops down to the @code{exit} routine below.
612 @smallexample
613 /*
614 * _exit -- Exit from the application. Normally we cause a user trap
615 * to return to the ROM monitor for another run.
616 */
617 SYM (exit):
618 trap #0
619 @end smallexample
621 Implementing @code{exit} here is easy. Both the @code{rom68k} and @code{bug}
622 can handle a user caused exception of @code{zero} with no side effects.
623 Although the @code{bug} monitor has a user caused trap that will return
624 control to the ROM monitor, this solution has been more portable.
626 @node Linker Scripts, What to do now, Crt0, Libraries
627 @section Linker scripts for memory management
629 The linker script sets up the memory map of an application. It also
630 sets up default values for variables used elsewhere by sbrk() and the
631 crt0. These default variables are typically called @code{_bss_start} and
632 @code{_end}.
634 For G++, the constructor and destructor tables must also be setup here.
635 The actual section names vary depending on the object file format. For
636 @code{a.out} and @code{coff}, the three main sections are @code{.text},
637 @code{.data}, and @code{.bss}.
639 Now that you have an image, you can test to make sure it got the
640 memory map right. You can do this by having the linker create a memory
641 map (by using the @code{-Map} option), or afterwards by using @code{nm} to
642 check a few critical addresses like @code{start}, @code{bss_end}, and
643 @code{_etext}.
645 Here's a breakdown of a linker script for a m68k based target board.
646 See the file @code{libgloss/m68k/idp.ld}, or go to the appendixes in
647 the end of the manual. @ref{idp.ld,,Example Linker Script}.
649 @smallexample
650 STARTUP(crt0.o)
651 OUTPUT_ARCH(m68k)
652 INPUT(idp.o)
653 SEARCH_DIR(.)
654 __DYNAMIC = 0;
655 @end smallexample
657 The @code{STARTUP} command loads the file specified so that it's
658 first. In this case it also doubles to load the file as well, because
659 the m68k-coff configuration defaults to not linking in the crt0.o by
660 default. It assumes that the developer probably has their own crt0.o.
661 This behavior is controlled in the config file for each architecture.
662 It's a macro called @code{STARTFILE_SPEC}, and if it's set to
663 @code{null}, then when @code{gcc} formats it's command line, it doesn't
664 add @code{crto.o}. Any file name can be specified here, but the default
665 is always @code{crt0.o}.
667 Course if you only use @code{ld} to link, then the control of whether or
668 not to link in @code{crt0.o} is done on the command line. If you have
669 multiple crto files, then you can leave this out all together, and link
670 in the @code{crt0.o} in the makefile, or by having different linker
671 scripts. Sometimes this is done for initializing floating point
672 optionally, or to add device support.
674 The @code{OUTPUT_ARCH} sets architecture the output file is for.
676 @code{INPUT} loads in the file specified. In this case, it's a relocated
677 library that contains the definitions for the low-level functions need
678 by libc.a. This could have also been specified on the command line, but
679 as it's always needed, it might as well be here as a default.
680 @code{SEARCH_DIR} specifies the path to look for files, and
681 @code{_DYNAMIC} means in this case there are no shared libraries.
683 @c FIXME: Check the linker manual to make sure this is accurate.
684 @smallexample
685 /*
686 * Setup the memory map of the MC68ec0x0 Board (IDP)
687 * stack grows up towards high memory. This works for
688 * both the rom68k and the mon68k monitors.
689 */
690 MEMORY
691 @{
692 ram : ORIGIN = 0x10000, LENGTH = 2M
693 @}
694 @end smallexample
696 This specifies a name for a section that can be referred to later in the
697 script. In this case, it's only a pointer to the beginning of free RAM
698 space, with an upper limit at 2M. If the output file exceeds the upper
699 limit, it will produce an error message.
701 @smallexample
702 /*
703 * stick everything in ram (of course)
704 */
705 SECTIONS
706 @{
707 .text :
708 @{
709 CREATE_OBJECT_SYMBOLS
710 *(.text)
711 etext = .;
712 __CTOR_LIST__ = .;
713 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
714 *(.ctors)
715 LONG(0)
716 __CTOR_END__ = .;
717 __DTOR_LIST__ = .;
718 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
719 *(.dtors)
720 LONG(0)
721 __DTOR_END__ = .;
722 *(.lit)
723 *(.shdata)
724 @} > ram
725 .shbss SIZEOF(.text) + ADDR(.text) : @{
726 *(.shbss)
727 @}
728 @end smallexample
730 Set up the @code{.text} section. In a @code{COFF} file, .text is where
731 all the actual instructions are. This also sets up the @emph{CONTRUCTOR}
732 and the @emph{DESTRUCTOR} tables for @code{G++}. Notice that the section
733 description redirects itself to the @emph{ram} variable setup earlier.
735 @smallexample
736 .talias : @{ @} > ram
737 .data : @{
738 *(.data)
739 CONSTRUCTORS
740 _edata = .;
741 @} > ram
742 @end smallexample
744 Setup the @code{.data} section. In a @code{coff} file, this is where all
745 he initialized data goes. @code{CONSTRUCTORS} is a special command used
746 by @code{ld}.
748 @smallexample
749 .bss SIZEOF(.data) + ADDR(.data) :
750 @{
751 __bss_start = ALIGN(0x8);
752 *(.bss)
753 *(COMMON)
754 end = ALIGN(0x8);
755 _end = ALIGN(0x8);
756 __end = ALIGN(0x8);
757 @}
758 .mstack : @{ @} > ram
759 .rstack : @{ @} > ram
760 .stab . (NOLOAD) :
761 @{
762 [ .stab ]
763 @}
764 .stabstr . (NOLOAD) :
765 @{
766 [ .stabstr ]
767 @}
768 @}
769 @end smallexample
771 Setup the @code{.bss} section. In a @code{COFF} file, this is where
772 unitialized data goes. The symbols @code{_bss_start} and @code{_end}
773 are setup here for use by the @code{crt0.o} when it zero's the
774 @code{.bss} section.
777 @node What to do now, Libc, Linker Scripts, Libraries
778 @section What to do when you have a binary image
780 A few ROM monitors load binary images, typically @code{a.out}, but most all
781 will load an @code{srecord}. An srecord is an ASCII representation of a binary
782 image. At it's simplest, an srecord is an address, followed by a byte
783 count, followed by the bytes, and a 2's compliment checksum. A whole
784 srecord file has an optional @emph{start} record, and a required @emph{end}
785 record. To make an srecord from a binary image, the GNU @code{objcopy} program
786 is used. This will read the image and make an srecord from it. To do
787 this, invoke objcopy like this: @code{objcopy -O srec infile outfile}. Most
788 PROM burners also read srecords or a similar format. Use @code{objdump -i} to
789 get a list of support object files types for your architecture.
791 @node Libc, , What to do now, Libraries
792 @section Libraries
794 This describes @code{newlib}, a freely available libc replacement. Most
795 applications use calls in the standard C library. When initially linking
796 in libc.a, several I/O functions are undefined. If you don't plan on
797 doing any I/O, then you're OK, otherwise they need to be created. These
798 routines are read, write, open, close. sbrk, and kill. Open & close
799 don't need to be fully supported unless you have a filesystems, so
800 typically they are stubbed out. Kill is also a stub, since you can't do
801 process control on an embedded system.
803 Sbrk() is only needed by applications that do dynamic memory
804 allocation. It's uses the symbol @code{_end} that is setup in the linker
805 script. It also requires a compile time option to set the upper size
806 limit on the heap space. This leaves us with read and write, which are
807 required for serial I/O. Usually these two routines are written in C,
808 and call a lower level function for the actual I/O operation. These two
809 lowest level I/O primitives are inbyte() and outbyte(), and are also
810 used by GDB back ends if you've written an exception handler. Some
811 systems also implement a havebyte() for input as well.
813 Other commonly included functions are routines for manipulating
814 LED's on the target (if they exist) or low level debug help. Typically a
815 putnum() for printing words and bytes as a hex number is helpful, as
816 well as a low-level print() to output simple strings.
818 As libg++ uses the I/O routines in libc.a, if read and write work,
819 then libg++ will also work with no additional changes.
821 @menu
822 * I/O Support:: Functions that make serial I/O work.
823 * Memory Support:: Memory support.
824 * Misc Support:: Other needed functions.
825 * Debugging:: Useful Debugging Functions
826 @end menu
828 @node I/O Support, Memory Support, , Libc
829 @subsection Making I/O work
831 @node Memory Support, Misc Support, I/O Support, Libc
832 @subsection Routines for dynamic memory allocation
833 To support using any of the memory functions, you need to implement
834 sbrk(). @code{malloc()}, @code{calloc()}, and @code{realloc()} all call
835 @code{sbrk()} at there lowest level. @code{caddr_t} is defined elsewhere
836 as @code{char *}. @code{RAMSIZE} is presently a compile time option. All
837 this does is move a pointer to heap memory and check for the upper
838 limit. @ref{glue.c,,Example libc support code}. @code{sbrk()} returns a
839 pointer to the previous value before more memory was allocated.
841 @smallexample
842 /* _end is set in the linker command file *
843 extern caddr_t _end;/
845 /* just in case, most boards have at least some memory */
846 #ifndef RAMSIZE
847 # define RAMSIZE (caddr_t)0x100000
848 #endif
850 /*
851 * sbrk -- changes heap size size. Get nbytes more
852 * RAM. We just increment a pointer in what's
853 * left of memory on the board.
854 */
855 caddr_t
856 sbrk(nbytes)
857 int nbytes;
858 @{
859 static caddr_t heap_ptr = NULL;
860 caddr_t base;
862 if (heap_ptr == NULL) @{
863 heap_ptr = (caddr_t)&_end;
864 @}
866 if ((RAMSIZE - heap_ptr) >= 0) @{
867 base = heap_ptr;
868 heap_ptr += nbytes;
869 return (base);
870 @} else @{
871 errno = ENOMEM;
872 return ((caddr_t)-1);
873 @}
874 @}
875 @end smallexample
877 @node Misc Support, Debugging, Memory Support, Libc
878 @subsection Misc support routines
880 These are called by @code{newlib} but don't apply to the embedded
881 environment. @code{isatty()} is self explanatory. @code{kill()} doesn't
882 apply either in an environment withno process control, so it justs
883 exits, which is a similar enough behavior. @code{getpid()} can safely
884 return any value greater than 1. The value doesn't effect anything in
885 @code{newlib} because once again there is no process control.
887 @smallexample
888 /*
889 * isatty -- returns 1 if connected to a terminal device,
890 * returns 0 if not. Since we're hooked up to a
891 * serial port, we'll say yes and return a 1.
892 */
893 int
894 isatty(fd)
895 int fd;
896 @{
897 return (1);
898 @}
900 /*
901 * getpid -- only one process, so just return 1.
902 */
903 #define __MYPID 1
904 int
905 getpid()
906 @{
907 return __MYPID;
908 @}
910 /*
911 * kill -- go out via exit...
912 */
913 int
914 kill(pid, sig)
915 int pid;
916 int sig;
917 @{
918 if(pid == __MYPID)
919 _exit(sig);
920 return 0;
921 @}
922 @end smallexample
924 @node Debugging, , Misc Support, Libc
925 @subsection Useful debugging functions
927 There are always a few useful functions for debugging your project in
928 progress. I typically implement a simple @code{print()} routine that
929 runs standalone in liblgoss, with no @code{newlib} support. The I/O
930 function @code{outbyte()} can also be used for low level debugging. Many
931 times print will work when there are problems that cause @code{printf()} to
932 cause an exception. @code{putnum()} is just to print out values in hex
933 so they are easier to read.
935 @smallexample
936 /*
937 * print -- do a raw print of a string
938 */
939 int
940 print(ptr)
941 char *ptr;
942 @{
943 while (*ptr) @{
944 outbyte (*ptr++);
945 @}
946 @}
948 /*
949 * putnum -- print a 32 bit number in hex
950 */
951 int
952 putnum (num)
953 unsigned int num;
954 @{
955 char buffer[9];
956 int count;
957 char *bufptr = buffer;
958 int digit;
960 for (count = 7 ; count >= 0 ; count--) @{
961 digit = (num >> (count * 4)) & 0xf;
963 if (digit <= 9)
964 *bufptr++ = (char) ('0' + digit);
965 else
966 *bufptr++ = (char) ('a' - 10 + digit);
967 @}
969 *bufptr = (char) 0;
970 print (buffer);
971 return;
972 @}
973 @end smallexample
975 If there are LEDs on the board, they can also be put to use for
976 debugging when the serial I/O code is being written. I usually implement
977 a @code{zylons()} function, which strobes the LEDS (if there is more
978 than one) in sequence, creating a rotating effect. This is convenient
979 between I/O to see if the target is still alive. Another useful LED
980 function is @code{led_putnum()}, which takes a digit and displays it as
981 a bit pattern or number. These usually have to be written in assembler
982 for each target board. Here are a number of C based routines that may be
983 useful.
985 @code{led_putnum()} puts a number on a single digit segmented
986 LED display. This LED is set by setting a bit mask to an address, where
987 1 turns the segment off, and 0 turns it on. There is also a little
988 decimal point on the LED display, so it gets the leftmost bit. The other
989 bits specify the segment location. The bits look like:
991 @smallexample
992 [d.p | g | f | e | d | c | b | a ] is the byte.
993 @end smallexample
995 The locations are set up as:
997 @smallexample
998 a
999 -----
1000 f | | b
1001 | g |
1002 -----
1003 | |
1004 e | | c
1005 -----
1006 d
1007 @end smallexample
1009 This takes a number that's already been converted to a string, and
1010 prints it.
1012 @smallexample
1013 #define LED_ADDR 0xd00003
1015 void
1016 led_putnum ( num )
1017 char num;
1018 @{
1019 static unsigned char *leds = (unsigned char *)LED_ADDR;
1020 static unsigned char num_bits [18] = @{
1021 0xff, /* clear all */
1022 0xc0, 0xf9, 0xa4, 0xb0, 0x99, 0x92, 0x82, 0xf8, 0x80, 0x98, /* numbers 0-9 */
1023 0x98, 0x20, 0x3, 0x27, 0x21, 0x4, 0xe /* letters a-f */
1024 @};
1026 if (num >= '0' && num <= '9')
1027 num = (num - '0') + 1;
1029 if (num >= 'a' && num <= 'f')
1030 num = (num - 'a') + 12;
1032 if (num == ' ')
1033 num = 0;
1035 *leds = num_bits[num];
1036 @}
1038 /*
1039 * zylons -- draw a rotating pattern. NOTE: this function never returns.
1040 */
1041 void
1042 zylons()
1043 @{
1044 unsigned char *leds = (unsigned char *)LED_ADDR;
1045 unsigned char curled = 0xfe;
1047 while (1)
1048 @{
1049 *leds = curled;
1050 curled = (curled >> 1) | (curled << 7);
1051 delay ( 200 );
1052 @}
1053 @}
1054 @end smallexample
1057 @node GDB, Binutils, Libraries, Top
1058 @chapter Writing a new GDB backend
1060 Typically, either the low-level I/O routines are used for debugging, or
1061 LEDs, if present. It is much easier to use GDb for debugging an
1062 application. There are several different techniques used to have GDB work
1063 remotely. Commonly more than one kind of GDB interface is used to cober
1064 a wide variety of development needs.
1066 The most common style of GDB backend is an exception handler for
1067 breakpoints. This is also called a @emph{gdb stub}, and is requires the
1068 two additional lines of init code in your @code{main()} routine. The GDB
1069 stubs all use the GDB @emph{remote protocol}. When the application gets a
1070 breakpoint exception, it communicates to GDB on the host.
1072 Another common style of interfacing GDB to a target is by using an
1073 existing ROM monitor. These break down into two main kinds, a similar
1074 protocol to the GDB remote protocol, and an interface that uses the ROM
1075 monitor directly. This kind has GDB simulating a human operator, and all
1076 GDB does is work as a command formatter and parser.
1078 @menu
1079 * GNU remote protocol:: The standard remote protocol.
1080 * Exception handler:: A linked in exception handler.
1081 * ROM monitors:: Using a ROM monitor as a backend.
1082 * Other remote protocols:: Adding support for new protocols.
1083 @end menu
1085 @node GNU remote protocol, Exception handler, ,GDB
1086 @section The standard remote protocol
1088 The standard remote protocol is a simple, packet based scheme. A debug
1089 packet whose contents are @emph{<data>} is encapsulated for transmission
1090 in the form:
1092 @smallexample
1093 $ <data> # CSUM1 CSUM2
1094 @end smallexample
1096 @emph{<data>} must be ASCII alphanumeric and cannot include characters
1097 @code{$} or @code{#}. If @emph{<data>} starts with two characters
1098 followed by @code{:}, then the existing stubs interpret this as a
1099 sequence number. For example, the command @code{g} is used to read the
1100 values of the registers. So, a packet to do this would look like
1102 @smallexample
1103 $g#67
1104 @end smallexample
1106 @emph{CSUM1} and @emph{CSUM2} are an ascii representation in hex of an
1107 8-bit checksum of @emph{<data>}, the most significant nibble is sent first.
1108 the hex digits 0-9,a-f are used.
1110 A simple protocol is used when communicating with the target. This is
1111 mainly to give a degree of error handling over the serial cable. For
1112 each packet transmitted successfully, the target responds with a
1113 @code{+} (@code{ACK}). If there was a transmission error, then the target
1114 responds with a @code{-} (@code{NAK}). An error is determined when the
1115 checksum doesn't match the calculated checksum for that data record.
1116 Upon reciept of the @code{ACK}, @code{GDB} can then transmit the next
1117 packet.
1119 Here is a list of the main functions that need to be supported. Each data
1120 packet is a command with a set number of bytes in the command packet.
1121 Most commands either return data, or respond with a @code{NAK}. Commands
1122 that don't return data respond with an @code{ACK}. All data values are
1123 ascii hex digits. Every byte needs two hex digits to represent t. This
1124 means that a byte with the value @samp{7} becomes @samp{07}. On a 32 bit
1125 machine this works out to 8 characters per word. All of the bytes in a
1126 word are stored in the target byte order. When writing the host side of
1127 the GDB protocol, be careful of byte order, and make sure that the code
1128 will run on both big and little endian hosts and produce the same answers.
1130 These functions are the minimum required to make a GDB backend work. All
1131 other commands are optional, and not supported by all GDB backends.
1133 @table @samp
1134 @item read registers @code{g}
1136 returns @code{XXXXXXXX...}
1138 Registers are in the internal order for GDB, and the bytes in a register
1139 are in the same order the machine uses. All values are in sequence
1140 starting with register 0. All registers are listed in the same packet. A
1141 sample packet would look like @code{$g#}.
1143 @item write registers @code{GXXXXXXXX...}
1144 @code{XXXXXXXX} is the value to set the register to. Registers are in
1145 the internal order for GDB, and the bytes in a register are in the same
1146 order the machine uses. All values are in sequence starting with
1147 register 0. All registers values are listed in the same packet. A sample
1148 packet would look like @code{$G000000001111111122222222...#}
1150 returns @code{ACK} or @code{NAK}
1152 @item read memory @code{mAAAAAAAA,LLLL}
1153 @code{AAAAAAAA} is address, @code{LLLL} is length. A sample packet would
1154 look like @code{$m00005556,0024#}. This would request 24 bytes starting
1155 at address @emph{00005556}
1157 returns @code{XXXXXXXX...}
1158 @code{XXXXXXXX} is the memory contents. Fewer bytes than requested will
1159 be returned if only part of the data can be read. This can be determined
1160 by counting the values till the end of packet @code{#} is seen and
1161 comparing that with the total count of bytes that was requested.
1163 @item write memory @code{MAAAAAAAA,LLLL:XXXXXXXX}
1164 @code{AAAAAAAA} is the starting address, @code{LLLL} is the number of
1165 bytes to be written, and @code{XXXXXXXX} is value to be written. A
1166 sample packet would look like
1167 @code{$M00005556,0024:101010101111111100000000...#}
1169 returns @code{ACK} or @code{NAK} for an error. @code{NAK} is also
1170 returned when only part of the data is written.
1172 @item continue @code{cAAAAAAAAA}
1173 @code{AAAAAAAA} is address to resume execution at. If @code{AAAAAAAA} is
1174 omitted, resume at the curent address of the @code{pc} register.
1176 returns the same replay as @code{last signal}. There is no immediate
1177 replay to @code{cont} until the next breakpoint is reached, and the
1178 program stops executing.
1180 @item step sAA..AA
1181 @code{AA..AA} is address to resume
1182 If @code{AA..AA} is omitted, resume at same address.
1184 returns the same replay as @code{last signal}. There is no immediate
1185 replay to @code{step} until the next breakpoint is reached, and the
1186 program stops executing.
1188 @item last signal @code{?}
1190 This returns one of the following:
1192 @itemize @bullet
1193 @item @code{SAA}
1194 Where @code{AA} is the number of the last signal.
1195 Exceptions on the target are converted to the most similar Unix style
1196 signal number, like @code{SIGSEGV}. A sample response of this type would
1197 look like @code{$S05#}.
1199 @item TAAnn:XXXXXXXX;nn:XXXXXXXX;nn:XXXXXXXX;
1200 @code{AA} is the signal number.
1201 @code{nn} is the register number.
1202 @code{XXXXXXXX} is the register value.
1204 @item WAA
1205 The process exited, and @code{AA} is the exit status. This is only
1206 applicable for certains sorts of targets.
1208 @end itemize
1210 These are used in some GDB backends, but not all.
1212 @item write reg @code{Pnn=XXXXXXXX}
1213 Write register @code{nn} with value @code{XXXXXXXX}.
1215 returns @code{ACK} or @code{NAK}
1217 @item kill request k
1219 @item toggle debug d
1220 toggle debug flag (see 386 & 68k stubs)
1222 @item reset r
1223 reset -- see sparc stub.
1225 @item reserved @code{other}
1226 On other requests, the stub should ignore the request and send an empty
1227 response @code{$#<checksum>}. This way we can extend the protocol and GDB
1228 can tell whether the stub it is talking to uses the old or the new.
1230 @item search @code{tAA:PP,MM}
1231 Search backwards starting at address @code{AA} for a match with pattern
1232 PP and mask @code{MM}. @code{PP} and @code{MM} are 4 bytes.
1234 @item general query @code{qXXXX}
1235 Request info about XXXX.
1237 @item general set @code{QXXXX=yyyy}
1238 Set value of @code{XXXX} to @code{yyyy}.
1240 @item query sect offs @code{qOffsets}
1241 Get section offsets. Reply is @code{Text=xxx;Data=yyy;Bss=zzz}
1243 @item console output Otext
1244 Send text to stdout. The text gets display from the target side of the
1245 serial connection.
1247 @end table
1249 Responses can be run-length encoded to save space. A @code{*}means that
1250 the next character is an ASCII encoding giving a repeat count which
1251 stands for that many repetitions of the character preceding the @code{*}.
1252 The encoding is n+29, yielding a printable character where n >=3
1253 (which is where run length encoding starts to win). You can't use a
1254 value of where n >126 because it's only a two byte value. An example
1255 would be a @code{0*03} means the same thing as @code{0000}.
1257 @node Exception handler, ROM monitors, GNU remote protocol, GDB
1258 @section A linked in exception handler
1260 A @emph{GDB stub} consists of two parts, support for the exception
1261 handler, and the exception handler itself. The exception handler needs
1262 to communicate to GDB on the host whenever there is a breakpoint
1263 exception. When GDB starts a program running on the target, it's polling
1264 the serial port during execution looking for any debug packets. So when
1265 a breakpoint occurs, the exception handler needs to save state, and send
1266 a GDB remote protocol packet to GDB on the host. GDB takes any output
1267 that isn't a debug command packet and displays it in the command window.
1269 Support for the exception handler varies between processors, but the
1270 minimum supported functions are those needed by GDB. These are functions
1271 to support the reading and writing of registers, the reading and writing
1272 of memory, start execution at an address, single step, and last signal.
1273 Sometimes other functions for adjusting the baud rate, or resetting the
1274 hardware are implemented.
1276 Once GDB gets the command packet from the breakpoint, it will read a few
1277 registers and memory locations an then wait for the user. When the user
1278 types @code{run} or @code{continue} a @code{continue} command is issued
1279 to the backend, and control returns from the breakpoint routine to the
1280 application.
1282 @node ROM monitors, Other remote protocols, Exception handler, GDB
1283 @section Using a ROM monitor as a backend
1284 GDB also can mimic a human user and use a ROM monitors normal debug
1285 commands as a backend. This consists mostly of sending and parsing
1286 @code{ASCII} strings. All the ROM monitor interfaces share a common set
1287 of routines in @code{gdb/monitor.c}. This supports adding new ROM
1288 monitor interfaces by filling in a structure with the common commands
1289 GDB needs. GDb already supports several command ROM monitors, including
1290 Motorola's @code{Bug} monitor for their VME boards, and the Rom68k
1291 monitor by Integrated Systems, Inc. for various m68k based boards. GDB
1292 also supports the custom ROM monitors on the WinBond and Oki PA based
1293 targets. There is builtin support for loading files to ROM monitors
1294 specifically. GDB can convert a binary into an srecord and then load it
1295 as an ascii file, or using @code{xmodem}.
1297 @c FIXME: do I need trademark somethings here ? Is Integrated the right
1298 @c company?
1300 @node Other remote protocols, ,ROM monitors, GDB
1301 @section Adding support for new protocols
1302 @c FIXME: write something here
1304 @node Binutils, Code Listings, GDB, Top
1306 @node Code Listings, idp.ld, Binutils, Top
1307 @appendix Code Listings
1309 @menu
1310 * idp.ld:: A m68k linker script.
1311 * crt0.S:: Crt0.S for an m68k.
1312 * glue.c:: C based support for for Stdio functions.
1313 * mvme.S:: Rom monitor based I/O support in assembler.
1314 * io.c:: C based for memory mapped I/O.
1315 * leds.c:: C based LED routines.
1316 @end menu
1318 @node idp.ld, crt0.S, Code Listings, Code Listings
1319 @section Linker script for the IDP board
1321 This is the linker script script that is used on the Motorola IDP board.
1323 @example
1324 STARTUP(crt0.o)
1325 OUTPUT_ARCH(m68k)
1326 INPUT(idp.o)
1327 SEARCH_DIR(.)
1328 __DYNAMIC = 0;
1329 /*
1330 * Setup the memory map of the MC68ec0x0 Board (IDP)
1331 * stack grows up towards high memory. This works for
1332 * both the rom68k and the mon68k monitors.
1333 */
1334 MEMORY
1335 @{
1336 ram : ORIGIN = 0x10000, LENGTH = 2M
1337 @}
1338 /*
1339 * stick everything in ram (of course)
1340 */
1341 SECTIONS
1342 @{
1343 .text :
1344 @{
1345 CREATE_OBJECT_SYMBOLS
1346 *(.text)
1347 etext = .;
1348 __CTOR_LIST__ = .;
1349 LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
1350 *(.ctors)
1351 LONG(0)
1352 __CTOR_END__ = .;
1353 __DTOR_LIST__ = .;
1354 LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
1355 *(.dtors)
1356 LONG(0)
1357 __DTOR_END__ = .;
1358 *(.lit)
1359 *(.shdata)
1360 @} > ram
1361 .shbss SIZEOF(.text) + ADDR(.text) : @{
1362 *(.shbss)
1363 @}
1364 .talias : @{ @} > ram
1365 .data : @{
1366 *(.data)
1367 CONSTRUCTORS
1368 _edata = .;
1369 @} > ram
1371 .bss SIZEOF(.data) + ADDR(.data) :
1372 @{
1373 __bss_start = ALIGN(0x8);
1374 *(.bss)
1375 *(COMMON)
1376 end = ALIGN(0x8);
1377 _end = ALIGN(0x8);
1378 __end = ALIGN(0x8);
1379 @}
1380 .mstack : @{ @} > ram
1381 .rstack : @{ @} > ram
1382 .stab . (NOLOAD) :
1383 @{
1384 [ .stab ]
1385 @}
1386 .stabstr . (NOLOAD) :
1387 @{
1388 [ .stabstr ]
1389 @}
1390 @}
1391 @end example
1393 @node crt0.S, glue.c, idp.ld, Code Listings
1394 @section crt0.S - The startup file
1396 @example
1397 /*
1398 * crt0.S -- startup file for m68k-coff
1399 *
1400 */
1402 .title "crt0.S for m68k-coff"
1404 /* These are predefined by new versions of GNU cpp. */
1406 #ifndef __USER_LABEL_PREFIX__
1407 #define __USER_LABEL_PREFIX__ _
1408 #endif
1410 #ifndef __REGISTER_PREFIX__
1411 #define __REGISTER_PREFIX__
1412 #endif
1414 /* ANSI concatenation macros. */
1416 #define CONCAT1(a, b) CONCAT2(a, b)
1417 #define CONCAT2(a, b) a ## b
1419 /* Use the right prefix for global labels. */
1421 #define SYM(x) CONCAT1 (__USER_LABEL_PREFIX__, x)
1423 /* Use the right prefix for registers. */
1425 #define REG(x) CONCAT1 (__REGISTER_PREFIX__, x)
1427 #define d0 REG (d0)
1428 #define d1 REG (d1)
1429 #define d2 REG (d2)
1430 #define d3 REG (d3)
1431 #define d4 REG (d4)
1432 #define d5 REG (d5)
1433 #define d6 REG (d6)
1434 #define d7 REG (d7)
1435 #define a0 REG (a0)
1436 #define a1 REG (a1)
1437 #define a2 REG (a2)
1438 #define a3 REG (a3)
1439 #define a4 REG (a4)
1440 #define a5 REG (a5)
1441 #define a6 REG (a6)
1442 #define fp REG (fp)
1443 #define sp REG (sp)
1445 /*
1446 * Set up some room for a stack. We just grab a chunk of memory.
1447 */
1448 .set stack_size, 0x2000
1449 .comm SYM (stack), stack_size
1451 /*
1452 * Define an empty environment.
1453 */
1454 .data
1455 .align 2
1456 SYM (environ):
1457 .long 0
1459 .align 2
1460 .text
1461 .global SYM (stack)
1463 .global SYM (main)
1464 .global SYM (exit)
1465 /*
1466 * This really should be __bss_start, not SYM (__bss_start).
1467 */
1468 .global __bss_start
1470 /*
1471 * start -- set things up so the application will run.
1472 */
1473 SYM (start):
1474 link a6, #-8
1475 moveal #SYM (stack) + stack_size, sp
1477 /*
1478 * zerobss -- zero out the bss section
1479 */
1480 moveal #__bss_start, a0
1481 moveal #SYM (end), a1
1482 1:
1483 movel #0, (a0)
1484 leal 4(a0), a0
1485 cmpal a0, a1
1486 bne 1b
1488 /*
1489 * Call the main routine from the application to get it going.
1490 * main (argc, argv, environ)
1491 * We pass argv as a pointer to NULL.
1492 */
1493 pea 0
1494 pea SYM (environ)
1495 pea sp@@(4)
1496 pea 0
1497 jsr SYM (main)
1498 movel d0, sp@@-
1500 /*
1501 * _exit -- Exit from the application. Normally we cause a user trap
1502 * to return to the ROM monitor for another run.
1503 */
1504 SYM (exit):
1505 trap #0
1506 @end example
1508 @node glue.c, mvme.S, crt0.S, Code Listings
1509 @section C based "glue" code.
1511 @example
1513 /*
1514 * glue.c -- all the code to make GCC and the libraries run on
1515 * a bare target board. These should work with any
1516 * target if inbyte() and outbyte() exist.
1517 */
1519 #include <sys/types.h>
1520 #include <sys/stat.h>
1521 #include <errno.h>
1522 #ifndef NULL
1523 #define NULL 0
1524 #endif
1526 /* FIXME: this is a hack till libc builds */
1527 __main()
1528 @{
1529 return;
1530 @}
1532 #undef errno
1533 int errno;
1535 extern caddr_t _end; /* _end is set in the linker command file */
1536 extern int outbyte();
1537 extern unsigned char inbyte();
1538 extern int havebyte();
1540 /* just in case, most boards have at least some memory */
1541 #ifndef RAMSIZE
1542 # define RAMSIZE (caddr_t)0x100000
1543 #endif
1545 /*
1546 * read -- read bytes from the serial port. Ignore fd, since
1547 * we only have stdin.
1548 */
1549 int
1550 read(fd, buf, nbytes)
1551 int fd;
1552 char *buf;
1553 int nbytes;
1554 @{
1555 int i = 0;
1557 for (i = 0; i < nbytes; i++) @{
1558 *(buf + i) = inbyte();
1559 if ((*(buf + i) == '\n') || (*(buf + i) == '\r')) @{
1560 (*(buf + i)) = 0;
1561 break;
1562 @}
1563 @}
1564 return (i);
1565 @}
1567 /*
1568 * write -- write bytes to the serial port. Ignore fd, since
1569 * stdout and stderr are the same. Since we have no filesystem,
1570 * open will only return an error.
1571 */
1572 int
1573 write(fd, buf, nbytes)
1574 int fd;
1575 char *buf;
1576 int nbytes;
1577 @{
1578 int i;
1580 for (i = 0; i < nbytes; i++) @{
1581 if (*(buf + i) == '\n') @{
1582 outbyte ('\r');
1583 @}
1584 outbyte (*(buf + i));
1585 @}
1586 return (nbytes);
1587 @}
1589 /*
1590 * open -- open a file descriptor. We don't have a filesystem, so
1591 * we return an error.
1592 */
1593 int
1594 open(buf, flags, mode)
1595 char *buf;
1596 int flags;
1597 int mode;
1598 @{
1599 errno = EIO;
1600 return (-1);
1601 @}
1603 /*
1604 * close -- close a file descriptor. We don't need
1605 * to do anything, but pretend we did.
1606 */
1607 int
1608 close(fd)
1609 int fd;
1610 @{
1611 return (0);
1612 @}
1614 /*
1615 * sbrk -- changes heap size size. Get nbytes more
1616 * RAM. We just increment a pointer in what's
1617 * left of memory on the board.
1618 */
1619 caddr_t
1620 sbrk(nbytes)
1621 int nbytes;
1622 @{
1623 static caddr_t heap_ptr = NULL;
1624 caddr_t base;
1626 if (heap_ptr == NULL) @{
1627 heap_ptr = (caddr_t)&_end;
1628 @}
1630 if ((RAMSIZE - heap_ptr) >= 0) @{
1631 base = heap_ptr;
1632 heap_ptr += nbytes;
1633 return (base);
1634 @} else @{
1635 errno = ENOMEM;
1636 return ((caddr_t)-1);
1637 @}
1638 @}
1640 /*
1641 * isatty -- returns 1 if connected to a terminal device,
1642 * returns 0 if not. Since we're hooked up to a
1643 * serial port, we'll say yes and return a 1.
1644 */
1645 int
1646 isatty(fd)
1647 int fd;
1648 @{
1649 return (1);
1650 @}
1652 /*
1653 * lseek -- move read/write pointer. Since a serial port
1654 * is non-seekable, we return an error.
1655 */
1656 off_t
1657 lseek(fd, offset, whence)
1658 int fd;
1659 off_t offset;
1660 int whence;
1661 @{
1662 errno = ESPIPE;
1663 return ((off_t)-1);
1664 @}
1666 /*
1667 * fstat -- get status of a file. Since we have no file
1668 * system, we just return an error.
1669 */
1670 int
1671 fstat(fd, buf)
1672 int fd;
1673 struct stat *buf;
1674 @{
1675 errno = EIO;
1676 return (-1);
1677 @}
1679 /*
1680 * getpid -- only one process, so just return 1.
1681 */
1682 #define __MYPID 1
1683 int
1684 getpid()
1685 @{
1686 return __MYPID;
1687 @}
1689 /*
1690 * kill -- go out via exit...
1691 */
1692 int
1693 kill(pid, sig)
1694 int pid;
1695 int sig;
1696 @{
1697 if(pid == __MYPID)
1698 _exit(sig);
1699 return 0;
1700 @}
1702 /*
1703 * print -- do a raw print of a string
1704 */
1705 int
1706 print(ptr)
1707 char *ptr;
1708 @{
1709 while (*ptr) @{
1710 outbyte (*ptr++);
1711 @}
1712 @}
1714 /*
1715 * putnum -- print a 32 bit number in hex
1716 */
1717 int
1718 putnum (num)
1719 unsigned int num;
1720 @{
1721 char buffer[9];
1722 int count;
1723 char *bufptr = buffer;
1724 int digit;
1726 for (count = 7 ; count >= 0 ; count--) @{
1727 digit = (num >> (count * 4)) & 0xf;
1729 if (digit <= 9)
1730 *bufptr++ = (char) ('0' + digit);
1731 else
1732 *bufptr++ = (char) ('a' - 10 + digit);
1733 @}
1735 *bufptr = (char) 0;
1736 print (buffer);
1737 return;
1738 @}
1739 @end example
1741 @node mvme.S, io.c, glue.c, Code Listings
1742 @section I/O assembler code sample
1744 @example
1745 /*
1746 * mvme.S -- board support for m68k
1747 */
1749 .title "mvme.S for m68k-coff"
1751 /* These are predefined by new versions of GNU cpp. */
1753 #ifndef __USER_LABEL_PREFIX__
1754 #define __USER_LABEL_PREFIX__ _
1755 #endif
1757 #ifndef __REGISTER_PREFIX__
1758 #define __REGISTER_PREFIX__
1759 #endif
1761 /* ANSI concatenation macros. */
1763 #define CONCAT1(a, b) CONCAT2(a, b)
1764 #define CONCAT2(a, b) a ## b
1766 /* Use the right prefix for global labels. */
1768 #define SYM(x) CONCAT1 (__USER_LABEL_PREFIX__, x)
1770 /* Use the right prefix for registers. */
1772 #define REG(x) CONCAT1 (__REGISTER_PREFIX__, x)
1774 #define d0 REG (d0)
1775 #define d1 REG (d1)
1776 #define d2 REG (d2)
1777 #define d3 REG (d3)
1778 #define d4 REG (d4)
1779 #define d5 REG (d5)
1780 #define d6 REG (d6)
1781 #define d7 REG (d7)
1782 #define a0 REG (a0)
1783 #define a1 REG (a1)
1784 #define a2 REG (a2)
1785 #define a3 REG (a3)
1786 #define a4 REG (a4)
1787 #define a5 REG (a5)
1788 #define a6 REG (a6)
1789 #define fp REG (fp)
1790 #define sp REG (sp)
1791 #define vbr REG (vbr)
1793 .align 2
1794 .text
1795 .global SYM (_exit)
1796 .global SYM (outln)
1797 .global SYM (outbyte)
1798 .global SYM (putDebugChar)
1799 .global SYM (inbyte)
1800 .global SYM (getDebugChar)
1801 .global SYM (havebyte)
1802 .global SYM (exceptionHandler)
1804 .set vbr_size, 0x400
1805 .comm SYM (vbr_table), vbr_size
1807 /*
1808 * inbyte -- get a byte from the serial port
1809 * d0 - contains the byte read in
1810 */
1811 .align 2
1812 SYM (getDebugChar): /* symbol name used by m68k-stub */
1813 SYM (inbyte):
1814 link a6, #-8
1815 trap #15
1816 .word inchr
1817 moveb sp@@, d0
1818 extbl d0
1819 unlk a6
1820 rts
1822 /*
1823 * outbyte -- sends a byte out the serial port
1824 * d0 - contains the byte to be sent
1825 */
1826 .align 2
1827 SYM (putDebugChar): /* symbol name used by m68k-stub */
1828 SYM (outbyte):
1829 link fp, #-4
1830 moveb fp@@(11), sp@@
1831 trap #15
1832 .word outchr
1833 unlk fp
1834 rts
1836 /*
1837 * outln -- sends a string of bytes out the serial port with a CR/LF
1838 * a0 - contains the address of the string's first byte
1839 * a1 - contains the address of the string's last byte
1840 */
1841 .align 2
1842 SYM (outln):
1843 link a6, #-8
1844 moveml a0/a1, sp@@
1845 trap #15
1846 .word outln
1847 unlk a6
1848 rts
1850 /*
1851 * outstr -- sends a string of bytes out the serial port without a CR/LF
1852 * a0 - contains the address of the string's first byte
1853 * a1 - contains the address of the string's last byte
1854 */
1855 .align 2
1856 SYM (outstr):
1857 link a6, #-8
1858 moveml a0/a1, sp@@
1859 trap #15
1860 .word outstr
1861 unlk a6
1862 rts
1864 /*
1865 * havebyte -- checks to see if there is a byte in the serial port,
1866 * returns 1 if there is a byte, 0 otherwise.
1867 */
1868 SYM (havebyte):
1869 trap #15
1870 .word instat
1871 beqs empty
1872 movel #1, d0
1873 rts
1874 empty:
1875 movel #0, d0
1876 rts
1878 /*
1879 * These constants are for the MVME-135 board's boot monitor. They
1880 * are used with a TRAP #15 call to access the monitor's I/O routines.
1881 * they must be in the word following the trap call.
1882 */
1883 .set inchr, 0x0
1884 .set instat, 0x1
1885 .set inln, 0x2
1886 .set readstr, 0x3
1887 .set readln, 0x4
1888 .set chkbrk, 0x5
1890 .set outchr, 0x20
1891 .set outstr, 0x21
1892 .set outln, 0x22
1893 .set write, 0x23
1894 .set writeln, 0x24
1895 .set writdln, 0x25
1896 .set pcrlf, 0x26
1897 .set eraseln, 0x27
1898 .set writd, 0x28
1899 .set sndbrk, 0x29
1901 .set tm_ini, 0x40
1902 .set dt_ini, 0x42
1903 .set tm_disp, 0x43
1904 .set tm_rd, 0x44
1906 .set redir, 0x60
1907 .set redir_i, 0x61
1908 .set redir_o, 0x62
1909 .set return, 0x63
1910 .set bindec, 0x64
1912 .set changev, 0x67
1913 .set strcmp, 0x68
1914 .set mulu32, 0x69
1915 .set divu32, 0x6A
1916 .set chk_sum, 0x6B
1918 @end example
1920 @node io.c, leds.c, mvme.S, Code Listings
1921 @section I/O code sample
1923 @example
1924 #include "w89k.h"
1926 /*
1927 * outbyte -- shove a byte out the serial port. We wait till the byte
1928 */
1929 int
1930 outbyte(byte)
1931 unsigned char byte;
1932 @{
1933 while ((inp(RS232REG) & TRANSMIT) == 0x0) @{ @} ;
1934 return (outp(RS232PORT, byte));
1935 @}
1937 /*
1938 * inbyte -- get a byte from the serial port
1939 */
1940 unsigned char
1941 inbyte()
1942 @{
1943 while ((inp(RS232REG) & RECEIVE) == 0x0) @{ @};
1944 return (inp(RS232PORT));
1945 @}
1946 @end example
1948 @node leds.c, ,io.c, Code Listings
1949 @section Led control sample
1951 @example
1952 /*
1953 * leds.h -- control the led's on a Motorola mc68ec0x0 board.
1954 */
1956 #ifndef __LEDS_H__
1957 #define __LEDS_H__
1959 #define LED_ADDR 0xd00003
1960 #define LED_0 ~0x1
1961 #define LED_1 ~0x2
1962 #define LED_2 ~0x4
1963 #define LED_3 ~0x8
1964 #define LED_4 ~0x10
1965 #define LED_5 ~0x20
1966 #define LED_6 ~0x40
1967 #define LED_7 ~0x80
1968 #define LEDS_OFF 0xff
1969 #define LEDS_ON 0x0
1971 #define FUDGE(x) ((x >= 0xa && x <= 0xf) ? (x + 'a') & 0x7f : (x + '0') & 0x7f)
1973 extern void led_putnum( char );
1975 #endif /* __LEDS_H__ */
1977 /*
1978 * leds.c -- control the led's on a Motorola mc68ec0x0 (IDP)board.
1979 */
1980 #include "leds.h"
1982 void zylons();
1983 void led_putnum();
1985 /*
1986 * led_putnum -- print a hex number on the LED. the value of num must be a char with
1987 * the ascii value. ie... number 0 is '0', a is 'a', ' ' (null) clears
1988 * the led display.
1989 * Setting the bit to 0 turns it on, 1 turns it off.
1990 * the LED's are controlled by setting the right bit mask in the base
1991 * address.
1992 * The bits are:
1993 * [d.p | g | f | e | d | c | b | a ] is the byte.
1994 *
1995 * The locations are:
1996 *
1997 * a
1998 * -----
1999 * f | | b
2000 * | g |
2001 * -----
2002 * | |
2003 * e | | c
2004 * -----
2005 * d . d.p (decimal point)
2006 */
2007 void
2008 led_putnum ( num )
2009 char num;
2010 @{
2011 static unsigned char *leds = (unsigned char *)LED_ADDR;
2012 static unsigned char num_bits [18] = @{
2013 0xff, /* clear all */
2014 0xc0, 0xf9, 0xa4, 0xb0, 0x99, 0x92, 0x82, 0xf8, 0x80, 0x98, /* numbers 0-9 */
2015 0x98, 0x20, 0x3, 0x27, 0x21, 0x4, 0xe /* letters a-f */
2016 @};
2018 if (num >= '0' && num <= '9')
2019 num = (num - '0') + 1;
2021 if (num >= 'a' && num <= 'f')
2022 num = (num - 'a') + 12;
2024 if (num == ' ')
2025 num = 0;
2027 *leds = num_bits[num];
2028 @}
2030 /*
2031 * zylons -- draw a rotating pattern. NOTE: this function never returns.
2032 */
2033 void
2034 zylons()
2035 @{
2036 unsigned char *leds = (unsigned char *)LED_ADDR;
2037 unsigned char curled = 0xfe;
2039 while (1)
2040 @{
2041 *leds = curled;
2042 curled = (curled >> 1) | (curled << 7);
2043 delay ( 200 );
2044 @}
2045 @}
2046 @end example
2048 @page
2049 @contents
2050 @c second page break makes sure right-left page alignment works right
2051 @c with a one-page toc, even though we don't have setchapternewpage odd.
2052 @page
2053 @bye