\input texinfo        @c                    -*- Texinfo -*-@setfilename porting.info@settitle Embed with GNU@c@c This file documents the process of porting the GNU tools to an@c embedded environment.@c@finalout@setchapternewpage off@iftex@raggedbottom@global@parindent=0pt@end iftex@titlepage@title Embed With GNU@subtitle Porting The GNU Tools To Embedded Systems@sp 4@subtitle Spring 1995@subtitle Very *Rough* Draft@author Rob Savoye - Cygnus Support@page@vskip 0pt plus 1filllCopyright @copyright{} 1993, 1994, 1995 Cygnus SupportPermission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided also thatthe entire resulting derived work is distributed under the terms of apermission notice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions.@end titlepage@ifinfo@formatSTART-INFO-DIR-ENTRY* Embed with GNU: (porting-).         Embed with GNUEND-INFO-DIR-ENTRY@end formatCopyright (c) 1993, 1994, 1995 Cygnus SupportPermission is granted to make and distribute verbatim copies ofthis manual provided the copyright notice and this permission noticeare preserved on all copies.Permission is granted to copy and distribute modified versions of thismanual under the conditions for verbatim copying, provided also thatthe entire resulting derived work is distributed under the terms of apermission notice identical to this one.Permission is granted to copy and distribute translations of this manualinto another language, under the above conditions for modified versions.@node Top@top Embed with GNU@end ifinfo@strong{Rough Draft}The goal of this document is to gather all the information needed toport the GNU tools to a new embedded target in one place. This willduplicate some info found in the other manual for the GNU tools, butthis should be all you'll need. @menu* Libgloss::            Libgloss, a library of board support packages.* GCC::                 Porting GCC/G++ to a new embedded target.* Libraries::           Making Newlib run on an new embedded target.* GDB::                 Making GDB understand a new back end.* Binutils::            Using the GNU binary utilities.* Code Listings::       Listings of the commented source code from the                        text.@end menu@node Libgloss, GCC, Top, Top@chapter LibglossLibgloss is a library for all the details that usually get glossed over.This library refers to things like startup code, and usually I/O supportfor @code{gcc} and @code{C library}. The C library used through outthis manual is @code{newlib}. Newlib is a ANSI conforming C librarydeveloped by Cygnus Support. Libgloss could easily be made tosupport other C libraries, and it can be used standalone as well. Thestandalone configuration is typically used when bringing up newhardware, or on small systems. For a long time, these details were part of newlib. This approach workedwell when a complete tool chain only had to support one system. A toolchain refers to the series of compiler passes required to produce abinary file that will run on an embedded system. For C, the passes arecpp, gcc, gas, ld. Cpp is the preprocessor, which process all the headerfiles and macros. Gcc is the compiler, which produces assembler from theprocessed C files. Gas assembles the code into object files, and then ldcombines the object files and binds the code to addresses and producesthe final executable image. Most of the time a tool chain does only have to support one targetexecution environment. An example of this would be a tool chain for theAMD 29k processor family. All of the execution environments for thisprocessor are have the same interface, the same memory map, and the sameI/O code. In this case all of the support code is in newlib/sys/FIXME.Libgloss's creation was forced initially be the @code{cpu32} processorfamily. There are many different execution environments for this line,and they vary wildly. newlib itself has only has a few dependencies thatit needs for each target. These are explained later in this doc. Thehardware dependent part of newlib was reorganized into a separatedirectory structure within newlib called the stub dirs. It was initiallycalled this because most of the routines newlib needs for a target weresimple stubs that do nothing, but return a value to the application. Theyonly exist so the linker can produce a final executable image. This workwas done during the early part of 1993.After a while it became apparent that this approach of isolating thehardware and systems files together made sense. Around this same timethe stub dirs were made to run standalone, mostly so it could also beused to support GDB's remote debugging needs. At this time it wasdecided to move the stub dirs out of newlib and into it's own separatelibrary so it could be used standalone, and be included in various otherGNU tools without having to bring in all of newlib, which is large. Thenew library is called Libgloss, for Gnu Low-level OS support. @menu* Supported targets::           What targets libgloss currently                                supports.* Building libgloss::           How to configure and built libgloss                                for a target.@end menu@node Supported targets, Building libgloss, Libgloss, Libgloss@subsection Supported TargetsCurrently libgloss is being used for the following targets:@menu* Sparclite::                   Fujitsu's sparclite.* CPU32::                       Various m68k based targets.* Mips::                        Mips code based targets.* PA-RISC::                     Precision Risc Organization..@end menu@node Sparclite, CPU32, , Supported targets@subsection Sparclite Targets Supported@c FIXME: put links to the docs in etc/targetdocThis is for the Fujitsu Sparclite family of processors. Currently this covers the ex930, ex931, ex932, ex933, and the ex934. In addition to theI/O code a startup file, this has a GDB debug-stub that gets linked intoyour application. This is an exception handler style debug stub. Formore info, see the section on Porting GDB. @ref{GDB,,Porting GDB}.The Fujitsu eval boards use a host based terminal program to load andexecute programs on the target. This program, @code{pciuh} is relativelynew (in 1994) and it replaced the previous ROM monitor which had theshell in the ROM. GDB uses the the GDB remote protocol, the relevantsource files from the gdb sources are remote-sparcl.c. The debug stub ispart of libgloss and is called sparcl-stub.c.@node CPU32, Mips, Sparclite, Supported targets@subsection Motorola CPU32 Targets supportedThis refers to Motorola's m68k based CPU32 processor family. The crt0.Sstartup file should be usable with any target environment, and it'smostly just the I/O code and linker scripts that vary. Currently thereis support for the Motorola MVME line of 6U VME boards and IDPline of eval boards. All of theMotorola VME boards run @code{Bug}, a ROM based debug monitor.This monitor has the feature of using user level traps to do I/O, sothis code should be portable to other MVME boards with little if anychange. The startup file also can remain unchanged. About the only thingthat varies is the address for where the text section begins. This canbe accomplished either in the linker script, or on the command lineusing the @samp{-Ttext [address]}.@c FIXME: Intermetrics or ISI wrote rom68k ?There is also support for the @code{rom68k} monitor as shipped onMotorola's IDP eval board line. This code should be portable across therange of CPU's the board supports. There is also GDB support for thistarget environment in the GDB source tree. The relevant files aregdb/monitor.c, monitor.h, and rom58k-rom.c. The usage of these files isdiscussed in the GDB section.@node Mips, PA-RISC, CPU32, Supported targets@subsection Mips core Targets SupportedThe Crt0 startup file should run on any mips target that doesn't requireadditional hardware initialization. The I/O code so far only supports acustom LSI33k based RAID disk controller board. It should easy tochange to support the IDT line of eval boards. Currently the twodebugging protocols supported by GDB for mips targets is IDT's mipsdebug protocol, and a customized hybrid of the standard GDB remoteprotocol and GDB's standard ROM monitor support. Included here is thedebug stub for the hybrid monitor. This supports the LSI33k processor,and only has support for the GDB protocol commands @code{g}, @code{G},@code{m}, @code{M}, which basically only supports the register andmemory reading and writing commands. This is part of libgloss and iscalled lsi33k-stub.c.The crt0.S should also work on the IDT line of eval boards, but has onlybeen run on the LSI33k for now. There is no I/O support for the IDT evalboard at this time. The current I/O code is for a customized version ofLSI's @code{pmon} ROM monitor. This uses entry points into the monitor,and should easily port to other versions of the pmon monitor. Pmon isdistributed in source by LSI.@node PA-RISC, , Mips, Supported targets@subsection PA-RISC Targets SupportedThis supports the various boards manufactured by the HP-PRO consortium.This is a group of companies all making variations on the PA-RISCprocessor. Currently supported are ports to the WinBond @samp{Cougar}board based around their w89k version of the PA. Also supported is theOki op50n processor.There is also included, but never built an unfinished port to the HP 743board. This board is the main CPU board for the HP700 line of industrialcomputers. This target isn't exactly an embedded system, in fact it'sreally only designed to load and run HP-UX. Still, the crt0.S and I/Ocode are fully working. It is included mostly because their is a barelyfunctioning exception handler GDB debug stub, and I hope somebody coulduse it. The other PRO targets all use GDB's ability to talk to ROMmonitors directly, so it doesn't need a debug stub. There is also autility that will produce a bootable file by HP's ROM monitor. This isall included in the hopes somebody else will finish it. :-)Both the WinBond board and the Oki board download srecords. The WinBondboard also has support for loading the SOM files as produced by thenative compiler on HP-UX. WinBond supplies a set of DOS programs thatwill allow the loading of files via a bidirectional parallel port. Thishas never been tested with the output of GNU SOM, as this manual ismostly for Unix based systems. @node Building libgloss, , Supported targets, Libgloss@subsection Configuring and building libgloss.Libgloss uses an autoconf based script to configure. Autoconf scriptsare portable shell scripts that are generated from a configure.in file.Configure input scripts are based themselves on m4. Most configurescripts run a series of tests to determine features the varioussupported features of the target. For features that can't be determinedby a feature test, a makefile fragment is merged in. The configureprocess leaves creates a Makefile in the build directory. For libgloss,there are only a few configure options of importance. These are --targetand --srcdir. Typically libgloss is built in a separate tree just for objects. In thismanner, it's possible to have a single source tree, and multiple objecttrees. If you only need to configure for a single target environment,then you can configure in the source tree. The argument for --target isa config string. It's usually safest to use the full canonical opposedto the target alias. So, to configure for a CPU32 (m68k) with a separatesource tree, use:@smallexample../src/libgloss/configure --verbose --target m68k-coff@end smallexampleThe configure script is in the source tree. When configure is invokedit will determine it's own source tree, so the --srcdir is would beredundant here.Once libgloss is configured, @code{make} is sufficient to build it. Thedefault values for @code{Makefiles} are typically correct for allsupported systems. The test cases in the testsuite will also builtautomatically as opposed to a @code{make check}, where test binariesaren't built till test time. This is mostly cause the libglosstestsuites are the last thing built when building the entire GNU sourcetree, so it's a good test of all the other compilation passes.The default values for the Makefiles are set in the Makefile fragmentmerged in during configuration. This fragment typically has rules like@smallexampleCC_FOR_TARGET = `if [ -f $$@{OBJROOT@}/gcc/xgcc ] ; \	then echo $@{OBJROOT@}/gcc/xgcc -B$@{OBJROOT@}/gcc/ ; \	else t='$@{program_transform_name@}'; echo gcc | sed -e '' $$t ; fi`@end smallexampleBasically this is a runtime test to determine whether there are freshlybuilt executables for the other main passes of the GNU tools. If thereisn't an executable built in the same object tree, then@emph{transformed}the generic tool name (like gcc) is transformed to thename typically used in GNU cross compilers. The  names aretypically based on the target's canonical name, so if you've configuredfor @code{m68k-coff} the transformed name is @code{m68k-coff-gcc} inthis case. If you install with aliases or rename the tools, this won'twork, and it will always look for tools in the path. You can force the adifferent name to work by reconfiguring with the@code{--program-transform-name} option to configure. This option takes ased script like this @code{-e s,^,m68k-coff-,} which produces toolsusing the standard names (at least here at Cygnus). The search for the other GNU development tools is exactly the same idea. This technique gets messier when build options like @code{-msoft-float}support are used. The Makefile fragments set the @code{MUTILIB}variable, and if it is set, the search path is modified. If the linkingis done with an installed cross compiler, then none of this needs to beused. This is done so libgloss will build automatically with a fresh,and uninstalled object tree. It also makes it easier to debug the othertools using libgloss's test suites.@node GCC, Libraries, Libgloss, Top@chapter Porting GCCPorting GCC requires two things, neither of which has anything to dowith GCC. If GCC already supports a processor type, then all the work inporting GCC is really a linker issue. All GCC has to do is produceassembler output in the proper syntax. Most of the work is done by thelinker, which is described elsewhere.Mostly all GCC does is format the command line for the linker pass. Thecommand line for GCC is set in the various config subdirectories of gcc.The options of interest to us are @code{CPP_SPEC} and@code{STARTFILE_SPEC}. CPP_SPEC sets the builtin defines for yourenvironment. If you support multiple environments with the sameprocessor, then OS specific defines will need to be elsewhere. @c FIXME: Check these names@code{STARTFILE_SPEC}Once you have linker support, GCC will be able to produce a fully linkedexecutable image. The only @emph{part} of GCC that the linker wants is acrt0.o, and a memory map. If you plan on running any programs that doI/O of any kind, you'll need to write support for the C library, whichis described elsewhere. @menu* Overview::            An overview as to the compilation passes.* Options::             Useful GCC options for embedded systems.@end menu@node Overview, Options, , GCC@subsection Compilation passesGCC by itself only compiles the C or C++ code into assembler. TypicallyGCC invokes all the passes required for you. These passes are cpp, cc1,gas, ld. @code{cpp} is the C preprocessor. This will merge in theinclude files, expand all macros definitions, and process all the@code{#ifdef} sections. To see the output of ccp, invoke gcc with the@code{-E} option, and the preprocessed file will be printed on thestdout. cc1 is the actual compiler pass that produces the assembler forthe processed file. GCC is actually only a driver program for all thecompiler passes. It will format command line options for the other passes.The usual command line GCC uses for the final link phase will have LDlink in the startup code and additional libraries by default.GNU AS started it's life to only function as a compiler pass, butthese days it can also be used as a source level assembler. When used asa source level assembler, it has a companion assembler preprocessorcalled @code{gasp}. This has a syntax similar to most other assemblermacros packages. GAS emits a relocatable object file from the assemblersource. The object file contains the executable part of the application,and debug symbols.LD is responsible for resolving the addresses and symbols to somethingthat will be fully self-contained. Some RTOS's use relocatable objectfile formats like @code{a.out}, but more commonly the final image willonly use absolute addresses for symbols. This enables code to be burnedinto PROMS as well. Although LD can produce an executable image, thereis usually a hidden object file called @code{crt0.o} that is required asstartup code.  With this startup code and a memory map, the executableimage will actually run on the target environment. @ref{Crt0,,StartupFiles}.The startup code usually defines a special symbol like @code{_start}that is the default base address for the application, and the firstsymbol in the executable image. If you plan to use any routines from thestandard C library, you'll also need to implement the functions thatthis library is dependent on. @ref{Libraries,,Porting Newlib}.@node Options, , Overview, GCC@c FIXME: Need stuff here about -fpic, -Ttext, etc...Options for the various development tools are covered in more detailelsewhere. Still, the amount of options can be an overwhelming amount ofstuff, so the options most suited to embedded systems are summarizedhere. If you use GCC as the main driver for all the passes, most of thelinker options can be passed directly to the compiler. There are alsoGCC options that control how the GCC driver formats the command linearguments for the linker.@menu* GCC Options::         Options for the compiler.* GAS Options::         Options for the assembler.* LD Options::          Options for the linker.@end menu@node GCC Options, GAS Options, , OptionsMost of the GCC options that we're interested control how the GCC driverformats the options for the linker pass. @c FIXME: this section is still under work.@table @code@item -nostartfiles@item -nostdlib@item -XlinkerPass the next option directly to the linker.@item -v@item -fpic@end table@node GAS Options, LD Options, GCC Options, Options@c FIXME: Needs stuff here@node LD Options, , GAS Options, Options@c FIXME: Needs stuff here@node Libraries, GDB, GCC, Top