@raggedbottom @global@parindent=0pt
Copyright (C) 1993, 1994, 1995 Cygnus Support
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.
Rough Draft
The goal of this document is to gather all the information needed to port the GNU tools to a new embedded target in one place. This will duplicate some info found in the other manual for the GNU tools, but this should be all you'll need.
Libgloss is a library for all the details that usually get glossed over.
This library refers to things like startup code, and usually I/O support
for gcc and C library. The C library used through out
this manual is newlib. Newlib is a ANSI conforming C library
developed by Cygnus Support. Libgloss could easily be made to
support other C libraries, and it can be used standalone as well. The
standalone configuration is typically used when bringing up new
hardware, or on small systems.
For a long time, these details were part of newlib. This approach worked well when a complete tool chain only had to support one system. A tool chain refers to the series of compiler passes required to produce a binary file that will run on an embedded system. For C, the passes are cpp, gcc, gas, ld. Cpp is the preprocessor, which process all the header files and macros. Gcc is the compiler, which produces assembler from the processed C files. Gas assembles the code into object files, and then ld combines the object files and binds the code to addresses and produces the final executable image.
Most of the time a tool chain does only have to support one target
execution environment. An example of this would be a tool chain for the
AMD 29k processor family. All of the execution environments for this
processor are have the same interface, the same memory map, and the same
I/O code. In this case all of the support code is in newlib/sys/FIXME.
Libgloss's creation was forced initially be the cpu32 processor
family. There are many different execution environments for this line,
and they vary wildly. newlib itself has only has a few dependencies that
it needs for each target. These are explained later in this doc. The
hardware dependent part of newlib was reorganized into a separate
directory structure within newlib called the stub dirs. It was initially
called this because most of the routines newlib needs for a target were
simple stubs that do nothing, but return a value to the application. They
only exist so the linker can produce a final executable image. This work
was done during the early part of 1993.
After a while it became apparent that this approach of isolating the hardware and systems files together made sense. Around this same time the stub dirs were made to run standalone, mostly so it could also be used to support GDB's remote debugging needs. At this time it was decided to move the stub dirs out of newlib and into it's own separate library so it could be used standalone, and be included in various other GNU tools without having to bring in all of newlib, which is large. The new library is called Libgloss, for Gnu Low-level OS support.
Currently libgloss is being used for the following targets:
This is for the Fujitsu Sparclite family of processors. Currently this covers the ex930, ex931, ex932, ex933, and the ex934. In addition to the I/O code a startup file, this has a GDB debug-stub that gets linked into your application. This is an exception handler style debug stub. For more info, see the section on Porting GDB. section Writing a new GDB backend.
The Fujitsu eval boards use a host based terminal program to load and
execute programs on the target. This program, pciuh is relatively
new (in 1994) and it replaced the previous ROM monitor which had the
shell in the ROM. GDB uses the the GDB remote protocol, the relevant
source files from the gdb sources are remote-sparcl.c. The debug stub is
part of libgloss and is called sparcl-stub.c.
This refers to Motorola's m68k based CPU32 processor family. The crt0.S
startup file should be usable with any target environment, and it's
mostly just the I/O code and linker scripts that vary. Currently there
is support for the Motorola MVME line of 6U VME boards and IDP
line of eval boards. All of the
Motorola VME boards run Bug, a ROM based debug monitor.
This monitor has the feature of using user level traps to do I/O, so
this code should be portable to other MVME boards with little if any
change. The startup file also can remain unchanged. About the only thing
that varies is the address for where the text section begins. This can
be accomplished either in the linker script, or on the command line
using the `-Ttext [address]'.
There is also support for the rom68k monitor as shipped on
Motorola's IDP eval board line. This code should be portable across the
range of CPU's the board supports. There is also GDB support for this
target environment in the GDB source tree. The relevant files are
gdb/monitor.c, monitor.h, and rom58k-rom.c. The usage of these files is
discussed in the GDB section.
The Crt0 startup file should run on any mips target that doesn't require
additional hardware initialization. The I/O code so far only supports a
custom LSI33k based RAID disk controller board. It should easy to
change to support the IDT line of eval boards. Currently the two
debugging protocols supported by GDB for mips targets is IDT's mips
debug protocol, and a customized hybrid of the standard GDB remote
protocol and GDB's standard ROM monitor support. Included here is the
debug stub for the hybrid monitor. This supports the LSI33k processor,
and only has support for the GDB protocol commands g, G,
m, M, which basically only supports the register and
memory reading and writing commands. This is part of libgloss and is
called lsi33k-stub.c.
The crt0.S should also work on the IDT line of eval boards, but has only
been run on the LSI33k for now. There is no I/O support for the IDT eval
board at this time. The current I/O code is for a customized version of
LSI's pmon ROM monitor. This uses entry points into the monitor,
and should easily port to other versions of the pmon monitor. Pmon is
distributed in source by LSI.
This supports the various boards manufactured by the HP-PRO consortium. This is a group of companies all making variations on the PA-RISC processor. Currently supported are ports to the WinBond `Cougar' board based around their w89k version of the PA. Also supported is the Oki op50n processor.
There is also included, but never built an unfinished port to the HP 743 board. This board is the main CPU board for the HP700 line of industrial computers. This target isn't exactly an embedded system, in fact it's really only designed to load and run HP-UX. Still, the crt0.S and I/O code are fully working. It is included mostly because their is a barely functioning exception handler GDB debug stub, and I hope somebody could use it. The other PRO targets all use GDB's ability to talk to ROM monitors directly, so it doesn't need a debug stub. There is also a utility that will produce a bootable file by HP's ROM monitor. This is all included in the hopes somebody else will finish it. :-)
Both the WinBond board and the Oki board download srecords. The WinBond board also has support for loading the SOM files as produced by the native compiler on HP-UX. WinBond supplies a set of DOS programs that will allow the loading of files via a bidirectional parallel port. This has never been tested with the output of GNU SOM, as this manual is mostly for Unix based systems.
Libgloss uses an autoconf based script to configure. Autoconf scripts are portable shell scripts that are generated from a configure.in file. Configure input scripts are based themselves on m4. Most configure scripts run a series of tests to determine features the various supported features of the target. For features that can't be determined by a feature test, a makefile fragment is merged in. The configure process leaves creates a Makefile in the build directory. For libgloss, there are only a few configure options of importance. These are --target and --srcdir.
Typically libgloss is built in a separate tree just for objects. In this manner, it's possible to have a single source tree, and multiple object trees. If you only need to configure for a single target environment, then you can configure in the source tree. The argument for --target is a config string. It's usually safest to use the full canonical opposed to the target alias. So, to configure for a CPU32 (m68k) with a separate source tree, use:
../src/libgloss/configure --verbose --target m68k-coff
The configure script is in the source tree. When configure is invoked it will determine it's own source tree, so the --srcdir is would be redundant here.
Once libgloss is configured, make is sufficient to build it. The
default values for Makefiles are typically correct for all
supported systems. The test cases in the testsuite will also built
automatically as opposed to a make check, where test binaries
aren't built till test time. This is mostly cause the libgloss
testsuites are the last thing built when building the entire GNU source
tree, so it's a good test of all the other compilation passes.
The default values for the Makefiles are set in the Makefile fragment merged in during configuration. This fragment typically has rules like
CC_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`
Basically this is a runtime test to determine whether there are freshly
built executables for the other main passes of the GNU tools. If there
isn't an executable built in the same object tree, then
transformedthe generic tool name (like gcc) is transformed to the
name typically used in GNU cross compilers. The names are
typically based on the target's canonical name, so if you've configured
for m68k-coff the transformed name is m68k-coff-gcc in
this case. If you install with aliases or rename the tools, this won't
work, and it will always look for tools in the path. You can force the a
different name to work by reconfiguring with the
--program-transform-name option to configure. This option takes a
sed script like this -e s,^,m68k-coff-, which produces tools
using 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 -msoft-float
support are used. The Makefile fragments set the MUTILIB
variable, and if it is set, the search path is modified. If the linking
is done with an installed cross compiler, then none of this needs to be
used. This is done so libgloss will build automatically with a fresh,
and uninstalled object tree. It also makes it easier to debug the other
tools using libgloss's test suites.
Go to the first, previous, next, last section, table of contents.