source: trunk/libs/newlib/src/libgloss/doc/porting.texi @ 643

Last change on this file since 643 was 444, checked in by satin@…, 6 years ago

add newlib,libalmos-mkh, restructure shared_syscalls.h and mini-libc

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