Go to the first, previous, next, last section, table of contents.

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

Supported Targets

Currently libgloss is being used for the following targets:

Sparclite Targets Supported

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.

Motorola CPU32 Targets supported

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.

Mips core Targets Supported

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.

PA-RISC Targets Supported

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.

Configuring and building libgloss.

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.