Subversion Repositories openrisc

\input texinfo        @c                    -*- Texinfo -*-

\input texinfo        @c                    -*- Texinfo -*-

@setfilename porting.info

@setfilename porting.info

@settitle Embed with GNU

@settitle Embed with GNU

@c

@c

@c This file documents the process of porting the GNU tools to an

@c This file documents the process of porting the GNU tools to an

@c embedded environment.

@c embedded environment.

@c

@c

@finalout

@finalout

@setchapternewpage off

@setchapternewpage off

@iftex

@iftex

@raggedbottom

@raggedbottom

@global@parindent=0pt

@global@parindent=0pt

@end iftex

@end iftex

@titlepage

@titlepage

@title Embed With GNU

@title Embed With GNU

@subtitle Porting The GNU Tools To Embedded Systems

@subtitle Porting The GNU Tools To Embedded Systems

@sp 4

@sp 4

@subtitle Spring 1995

@subtitle Spring 1995

@subtitle Very *Rough* Draft

@subtitle Very *Rough* Draft

@author Rob Savoye - Cygnus Support

@author Rob Savoye - Cygnus Support

@page

@page

@vskip 0pt plus 1filll

@vskip 0pt plus 1filll

Copyright @copyright{} 1993, 1994, 1995 Cygnus Support

Copyright @copyright{} 1993, 1994, 1995 Cygnus Support

Permission is granted to make and distribute verbatim copies of

Permission is granted to make and distribute verbatim copies of

this manual provided the copyright notice and this permission notice

this manual provided the copyright notice and this permission notice

are preserved on all copies.

are preserved on all copies.

Permission is granted to copy and distribute modified versions of this

Permission is granted to copy and distribute modified versions of this

manual under the conditions for verbatim copying, provided also that

manual under the conditions for verbatim copying, provided also that

the entire resulting derived work is distributed under the terms of a

the entire resulting derived work is distributed under the terms of a

permission notice identical to this one.

permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual

Permission is granted to copy and distribute translations of this manual

into another language, under the above conditions for modified versions.

into another language, under the above conditions for modified versions.

@end titlepage

@end titlepage

@ifinfo

@ifinfo

@format

@format

START-INFO-DIR-ENTRY

START-INFO-DIR-ENTRY

* Embed with GNU: (porting-).         Embed with GNU

* Embed with GNU: (porting-).         Embed with GNU

END-INFO-DIR-ENTRY

END-INFO-DIR-ENTRY

@end format

@end format

Copyright (c) 1993, 1994, 1995 Cygnus Support

Copyright (c) 1993, 1994, 1995 Cygnus Support

Permission is granted to make and distribute verbatim copies of

Permission is granted to make and distribute verbatim copies of

this manual provided the copyright notice and this permission notice

this manual provided the copyright notice and this permission notice

are preserved on all copies.

are preserved on all copies.

Permission is granted to copy and distribute modified versions of this

Permission is granted to copy and distribute modified versions of this

manual under the conditions for verbatim copying, provided also that

manual under the conditions for verbatim copying, provided also that

the entire resulting derived work is distributed under the terms of a

the entire resulting derived work is distributed under the terms of a

permission notice identical to this one.

permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual

Permission is granted to copy and distribute translations of this manual

into another language, under the above conditions for modified versions.

into another language, under the above conditions for modified versions.

@node Top

@node Top

@top Embed with GNU

@top Embed with GNU

@end ifinfo

@end ifinfo

@strong{Rough Draft}

@strong{Rough Draft}

The goal of this document is to gather all the information needed to

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

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

duplicate some info found in the other manual for the GNU tools, but

this should be all you'll need.

this should be all you'll need.

@menu

@menu

* Libgloss::            Libgloss, a library of board support packages.

* Libgloss::            Libgloss, a library of board support packages.

* GCC::                 Porting GCC/G++ to a new embedded target.

* GCC::                 Porting GCC/G++ to a new embedded target.

* Libraries::           Making Newlib run on an new embedded target.

* Libraries::           Making Newlib run on an new embedded target.

* GDB::                 Making GDB understand a new back end.

* GDB::                 Making GDB understand a new back end.

* Binutils::            Using the GNU binary utilities.

* Binutils::            Using the GNU binary utilities.

* Code Listings::       Listings of the commented source code from the

* Code Listings::       Listings of the commented source code from the

                        text.

                        text.

@end menu

@end menu

@node Libgloss, GCC, Top, Top

@node Libgloss, GCC, Top, Top

@chapter Libgloss

@chapter Libgloss

Libgloss is a library for all the details that usually get glossed over.

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

This library refers to things like startup code, and usually I/O support

for @code{gcc} and @code{C library}. The C library used through out

for @code{gcc} and @code{C library}. The C library used through out

this manual is @code{newlib}. Newlib is a ANSI conforming C library

this manual is @code{newlib}. Newlib is a ANSI conforming C library

developed by Cygnus Support. Libgloss could easily be made to

developed by Cygnus Support. Libgloss could easily be made to

support other C libraries, and it can be used standalone as well. The

support other C libraries, and it can be used standalone as well. The

standalone configuration is typically used when bringing up new

standalone configuration is typically used when bringing up new

hardware, or on small systems.

hardware, or on small systems.

For a long time, these details were part of newlib. This approach worked

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

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

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

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

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

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

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

combines the object files and binds the code to addresses and produces

the final executable image.

the final executable image.

Most of the time a tool chain does only have to support one target

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

execution environment. An example of this would be a tool chain for the

AMD 29k processor family. All of the execution environments for this

AMD 29k processor family. All of the execution environments for this

processor are have the same interface, the same memory map, and the same

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.

I/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} processor

Libgloss's creation was forced initially be the @code{cpu32} processor

family. There are many different execution environments for this line,

family. There are many different execution environments for this line,

and they vary wildly. newlib itself has only has a few dependencies that

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

it needs for each target. These are explained later in this doc. The

hardware dependent part of newlib was reorganized into a separate

hardware dependent part of newlib was reorganized into a separate

directory structure within newlib called the stub dirs. It was initially

directory structure within newlib called the stub dirs. It was initially

called this because most of the routines newlib needs for a target were

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

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

only exist so the linker can produce a final executable image. This work

was done during the early part of 1993.

was done during the early part of 1993.

After a while it became apparent that this approach of isolating the

After a while it became apparent that this approach of isolating the

hardware and systems files together made sense. Around this same time

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

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

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

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

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

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.

new library is called Libgloss, for Gnu Low-level OS support.

@menu

@menu

* Supported targets::           What targets libgloss currently

* Supported targets::           What targets libgloss currently

                                supports.

                                supports.

* Building libgloss::           How to configure and built libgloss

* Building libgloss::           How to configure and built libgloss

                                for a target.

                                for a target.

* Board support::               How to add support for a new board.

* Board support::               How to add support for a new board.

@end menu

@end menu

@node Supported targets, Building libgloss, Libgloss, Libgloss

@node Supported targets, Building libgloss, Libgloss, Libgloss

@subsection Supported Targets

@subsection Supported Targets

Currently libgloss is being used for the following targets:

Currently libgloss is being used for the following targets:

@menu

@menu

* Sparclite::                   Fujitsu's sparclite.

* Sparclite::                   Fujitsu's sparclite.

* CPU32::                       Various m68k based targets.

* CPU32::                       Various m68k based targets.

* Mips::                        Mips code based targets.

* Mips::                        Mips code based targets.

* PA-RISC::                     Precision Risc Organization..

* PA-RISC::                     Precision Risc Organization..

@end menu

@end menu

@node Sparclite, CPU32, , Supported targets

@node Sparclite, CPU32, , Supported targets

@subsection Sparclite Targets Supported

@subsection Sparclite Targets Supported

@c FIXME: put links to the docs in etc/targetdoc

@c FIXME: put links to the docs in etc/targetdoc

This is for the Fujitsu Sparclite family of processors. Currently this

This is for the Fujitsu Sparclite family of processors. Currently this

covers the ex930, ex931, ex932, ex933, and the ex934. In addition to the

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

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

your application. This is an exception handler style debug stub. For

more info, see the section on Porting GDB. @ref{GDB,,Porting GDB}.

more info, see the section on Porting GDB. @ref{GDB,,Porting GDB}.

The Fujitsu eval boards use a host based terminal program to load and

The Fujitsu eval boards use a host based terminal program to load and

execute programs on the target. This program, @code{pciuh} is relatively

execute programs on the target. This program, @code{pciuh} is relatively

new (in 1994) and it replaced the previous ROM monitor which had the

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

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

source files from the gdb sources are remote-sparcl.c. The debug stub is

part of libgloss and is called sparcl-stub.c.

part of libgloss and is called sparcl-stub.c.

@node CPU32, Mips, Sparclite, Supported targets

@node CPU32, Mips, Sparclite, Supported targets

@subsection Motorola CPU32 Targets supported

@subsection Motorola CPU32 Targets supported

This refers to Motorola's m68k based CPU32 processor family. The crt0.S

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

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

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

is support for the Motorola MVME line of 6U VME boards and IDP

line of eval boards. All of the

line of eval boards. All of the

Motorola VME boards run @code{Bug}, a ROM based debug monitor.

Motorola VME boards run @code{Bug}, a ROM based debug monitor.

This monitor has the feature of using user level traps to do I/O, so

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

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

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

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

be accomplished either in the linker script, or on the command line

using the @samp{-Ttext [address]}.

using the @samp{-Ttext [address]}.

@c FIXME: Intermetrics or ISI wrote rom68k ?

@c FIXME: Intermetrics or ISI wrote rom68k ?

There is also support for the @code{rom68k} monitor as shipped on

There is also support for the @code{rom68k} monitor as shipped on

Motorola's IDP eval board line. This code should be portable across the

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

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

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

gdb/monitor.c, monitor.h, and rom58k-rom.c. The usage of these files is

discussed in the GDB section.

discussed in the GDB section.

@node Mips, PA-RISC, CPU32, Supported targets

@node Mips, PA-RISC, CPU32, Supported targets

@subsection Mips core Targets Supported

@subsection Mips core Targets Supported

The Crt0 startup file should run on any mips target that doesn't require

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

additional hardware initialization. The I/O code so far only supports a

custom LSI33k based RAID disk controller board. It should easy to

custom LSI33k based RAID disk controller board. It should easy to

change to support the IDT line of eval boards. Currently the two

change to support the IDT line of eval boards. Currently the two

debugging protocols supported by GDB for mips targets is IDT's mips

debugging protocols supported by GDB for mips targets is IDT's mips

debug protocol, and a customized hybrid of the standard GDB remote

debug protocol, and a customized hybrid of the standard GDB remote

protocol and GDB's standard ROM monitor support. Included here is the

protocol and GDB's standard ROM monitor support. Included here is the

debug stub for the hybrid monitor. This supports the LSI33k processor,

debug stub for the hybrid monitor. This supports the LSI33k processor,

and only has support for the GDB protocol commands @code{g}, @code{G},

and only has support for the GDB protocol commands @code{g}, @code{G},

@code{m}, @code{M}, which basically only supports the register and

@code{m}, @code{M}, which basically only supports the register and

memory reading and writing commands. This is part of libgloss and is

memory reading and writing commands. This is part of libgloss and is

called lsi33k-stub.c.

called lsi33k-stub.c.

The crt0.S should also work on the IDT line of eval boards, but has only

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

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

board at this time. The current I/O code is for a customized version of

LSI's @code{pmon} ROM monitor. This uses entry points into the monitor,

LSI's @code{pmon} ROM monitor. This uses entry points into the monitor,

and should easily port to other versions of the pmon monitor. Pmon is

and should easily port to other versions of the pmon monitor. Pmon is

distributed in source by LSI.

distributed in source by LSI.

@node PA-RISC, , Mips, Supported targets

@node PA-RISC, , Mips, Supported targets

@subsection PA-RISC Targets Supported

@subsection PA-RISC Targets Supported

This supports the various boards manufactured by the HP-PRO consortium.

This supports the various boards manufactured by the HP-PRO consortium.

This is a group of companies all making variations on the PA-RISC

This is a group of companies all making variations on the PA-RISC

processor. Currently supported are ports to the WinBond @samp{Cougar}

processor. Currently supported are ports to the WinBond @samp{Cougar}

board based around their w89k version of the PA. Also supported is the

board based around their w89k version of the PA. Also supported is the

Oki op50n processor.

Oki op50n processor.

There is also included, but never built an unfinished port to the HP 743

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

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

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

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

code are fully working. It is included mostly because their is a barely

functioning exception handler GDB debug stub, and I hope somebody could

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

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

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

utility that will produce a bootable file by HP's ROM monitor. This is

all included in the hopes somebody else will finish it. :-)

all included in the hopes somebody else will finish it. :-)

Both the WinBond board and the Oki board download srecords. The WinBond

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

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

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

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

has never been tested with the output of GNU SOM, as this manual is

mostly for Unix based systems.

mostly for Unix based systems.

@node Building libgloss, Board support, Supported targets, Libgloss

@node Building libgloss, Board support, Supported targets, Libgloss

@subsection Configuring and building libgloss.

@subsection Configuring and building libgloss.

Libgloss uses an autoconf based script to configure. Autoconf scripts

Libgloss uses an autoconf based script to configure. Autoconf scripts

are portable shell scripts that are generated from a configure.in file.

are portable shell scripts that are generated from a configure.in file.

Configure input scripts are based themselves on m4. Most configure

Configure input scripts are based themselves on m4. Most configure

scripts run a series of tests to determine features the various

scripts run a series of tests to determine features the various

supported features of the target. For features that can't be determined

supported features of the target. For features that can't be determined

by a feature test, a makefile fragment is merged in. The configure

by a feature test, a makefile fragment is merged in. The configure

process leaves creates a Makefile in the build directory. For libgloss,

process leaves creates a Makefile in the build directory. For libgloss,

there are only a few configure options of importance. These are --target

there are only a few configure options of importance. These are --target

and --srcdir.

and --srcdir.

Typically libgloss is built in a separate tree just for objects. In this

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

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,

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

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

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

to the target alias. So, to configure for a CPU32 (m68k) with a separate

source tree, use:

source tree, use:

@smallexample

@smallexample

../src/libgloss/configure --verbose --target m68k-coff

../src/libgloss/configure --verbose --target m68k-coff

@end smallexample

@end smallexample

The configure script is in the source tree. When configure is invoked

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

it will determine it's own source tree, so the --srcdir is would be

redundant here.

redundant here.

Once libgloss is configured, @code{make} is sufficient to build it. The

Once libgloss is configured, @code{make} is sufficient to build it. The

default values for @code{Makefiles} are typically correct for all

default values for @code{Makefiles} are typically correct for all

supported systems. The test cases in the testsuite will also built

supported systems. The test cases in the testsuite will also built

automatically as opposed to a @code{make check}, where test binaries

automatically as opposed to a @code{make check}, where test binaries

aren't built till test time. This is mostly cause the libgloss

aren't built till test time. This is mostly cause the libgloss

testsuites are the last thing built when building the entire GNU source

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.

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

The default values for the Makefiles are set in the Makefile fragment

merged in during configuration. This fragment typically has rules like

merged in during configuration. This fragment typically has rules like

@smallexample

@smallexample

CC_FOR_TARGET = `if [ -f $$@{OBJROOT@}/gcc/xgcc ] ; \

CC_FOR_TARGET = `if [ -f $$@{OBJROOT@}/gcc/xgcc ] ; \

        then echo $@{OBJROOT@}/gcc/xgcc -B$@{OBJROOT@}/gcc/ ; \

        then echo $@{OBJROOT@}/gcc/xgcc -B$@{OBJROOT@}/gcc/ ; \

        else t='$@{program_transform_name@}'; echo gcc | sed -e '' $$t ; fi`

        else t='$@{program_transform_name@}'; echo gcc | sed -e '' $$t ; fi`

@end smallexample

@end smallexample

Basically this is a runtime test to determine whether there are freshly

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

built executables for the other main passes of the GNU tools. If there

isn't an executable built in the same object tree, then

isn't an executable built in the same object tree, then

@emph{transformed}the generic tool name (like gcc) is transformed to the

@emph{transformed}the generic tool name (like gcc) is transformed to the

name typically used in GNU cross compilers. The  names are

name typically used in GNU cross compilers. The  names are

typically based on the target's canonical name, so if you've configured

typically based on the target's canonical name, so if you've configured

for @code{m68k-coff} the transformed name is @code{m68k-coff-gcc} in

for @code{m68k-coff} the transformed name is @code{m68k-coff-gcc} in

this case. If you install with aliases or rename the tools, this won't

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

work, and it will always look for tools in the path. You can force the a

different name to work by reconfiguring with the

different name to work by reconfiguring with the

@code{--program-transform-name} option to configure. This option takes a

@code{--program-transform-name} option to configure. This option takes a

sed script like this @code{-e s,^,m68k-coff-,} which produces tools

sed script like this @code{-e s,^,m68k-coff-,} which produces tools

using the standard names (at least here at Cygnus).

using the standard names (at least here at Cygnus).

The search for the other GNU development tools is exactly the same idea.

The search for the other GNU development tools is exactly the same idea.

This technique gets messier when build options like @code{-msoft-float}

This technique gets messier when build options like @code{-msoft-float}

support are used. The Makefile fragments set the @code{MUTILIB}

support are used. The Makefile fragments set the @code{MUTILIB}

variable, and if it is set, the search path is modified. If the linking

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

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,

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

and uninstalled object tree. It also makes it easier to debug the other

tools using libgloss's test suites.

tools using libgloss's test suites.

@node Board support, , Building libgloss, Libgloss

@node Board support, , Building libgloss, Libgloss

@subsection Adding Support for a New Board

@subsection Adding Support for a New Board

This section explains how to add support for a new board to libgloss.

This section explains how to add support for a new board to libgloss.

In order to add support for a board, you must already have developed a

In order to add support for a board, you must already have developed a

toolchain for the target architecture.

toolchain for the target architecture.

All of the changes you will make will be in the subdirectory named

All of the changes you will make will be in the subdirectory named

after the architecture used by your board.  For example, if you are

after the architecture used by your board.  For example, if you are

developing support for a new ColdFire board, you will modify files in

developing support for a new ColdFire board, you will modify files in

the @file{m68k} subdirectory, as that subdirectory contains support

the @file{m68k} subdirectory, as that subdirectory contains support

for all 68K devices, including architecture variants like ColdFire.

for all 68K devices, including architecture variants like ColdFire.

In general, you will be adding three components: a @file{crt0.S} file

In general, you will be adding three components: a @file{crt0.S} file

(@pxref{Crt0}), a linker script (@pxref{Linker Scripts}), and a

(@pxref{Crt0}), a linker script (@pxref{Linker Scripts}), and a

hardware support library.  Each should be prefixed with the name of

hardware support library.  Each should be prefixed with the name of

your board.  For example, if you ard adding support for a new Surf

your board.  For example, if you ard adding support for a new Surf

board, then you will be adding the assembly @file{surf-crt0.S} (which

board, then you will be adding the assembly @file{surf-crt0.S} (which

will be assembled into @file{surf-crt0.o}), the linker script

will be assembled into @file{surf-crt0.o}), the linker script

@file{surf.ld}, and other C and assembly files which will be combined

@file{surf.ld}, and other C and assembly files which will be combined

into the hardware support library @file{libsurf.a}.

into the hardware support library @file{libsurf.a}.

You should modify @file{Makefile.in} to define new variables

You should modify @file{Makefile.in} to define new variables

corresponding to your board.  Although there is some variation between

corresponding to your board.  Although there is some variation between

architectures, the general convention is to use the following format:

architectures, the general convention is to use the following format:

@example

@example

# The name of the crt0.o file.

# The name of the crt0.o file.

SURF_CRT0    = surf-crt0.o

SURF_CRT0    = surf-crt0.o

# The name of the linker script.

# The name of the linker script.

SURF_SCRIPTS = surf.ld

SURF_SCRIPTS = surf.ld

# The name of the hardware support library.

# The name of the hardware support library.

SURF_BSP     = libsurf.a

SURF_BSP     = libsurf.a

# The object files that make up the hardware support library.

# The object files that make up the hardware support library.

SURF_OBJS    = surf-file1.o surf-file2.o

SURF_OBJS    = surf-file1.o surf-file2.o

# The name of the Makefile target to use for installation.

# The name of the Makefile target to use for installation.

SURF_INSTALL = install-surf

SURF_INSTALL = install-surf

@end example

@end example

Then, you should create the @code{$@{SURF_BSP@}} and

Then, you should create the @code{$@{SURF_BSP@}} and

@code{$@{SURF_INSTALL@}} make targets.  Add @code{$@{SURF_CRT0@}} to

@code{$@{SURF_INSTALL@}} make targets.  Add @code{$@{SURF_CRT0@}} to

the dependencies for the @code{all} target and add

the dependencies for the @code{all} target and add

@code{$@{SURF_INSTALL@}} to the dependencies for the @code{install}

@code{$@{SURF_INSTALL@}} to the dependencies for the @code{install}

target.  Now, when libgloss is built and installed, support for your

target.  Now, when libgloss is built and installed, support for your

BSP will be installed as well.

BSP will be installed as well.

@node GCC, Libraries, Libgloss, Top

@node GCC, Libraries, Libgloss, Top

@chapter Porting GCC

@chapter Porting GCC

Porting GCC requires two things, neither of which has anything to do

Porting GCC requires two things, neither of which has anything to do

with GCC. If GCC already supports a processor type, then all the work in

with GCC. If GCC already supports a processor type, then all the work in

porting GCC is really a linker issue. All GCC has to do is produce

porting GCC is really a linker issue. All GCC has to do is produce

assembler output in the proper syntax. Most of the work is done by the

assembler output in the proper syntax. Most of the work is done by the

linker, which is described elsewhere.

linker, which is described elsewhere.

Mostly all GCC does is format the command line for the linker pass. The

Mostly all GCC does is format the command line for the linker pass. The

command line for GCC is set in the various config subdirectories of gcc.

command line for GCC is set in the various config subdirectories of gcc.

The options of interest to us are @code{CPP_SPEC} and

The options of interest to us are @code{CPP_SPEC} and

@code{STARTFILE_SPEC}. CPP_SPEC sets the builtin defines for your

@code{STARTFILE_SPEC}. CPP_SPEC sets the builtin defines for your

environment. If you support multiple environments with the same

environment. If you support multiple environments with the same

processor, then OS specific defines will need to be elsewhere.

processor, then OS specific defines will need to be elsewhere.

@c FIXME: Check these names

@c FIXME: Check these names

@code{STARTFILE_SPEC}

@code{STARTFILE_SPEC}

Once you have linker support, GCC will be able to produce a fully linked

Once you have linker support, GCC will be able to produce a fully linked

executable image. The only @emph{part} of GCC that the linker wants is a

executable image. The only @emph{part} of GCC that the linker wants is a

crt0.o, and a memory map. If you plan on running any programs that do

crt0.o, and a memory map. If you plan on running any programs that do

I/O of any kind, you'll need to write support for the C library, which

I/O of any kind, you'll need to write support for the C library, which

is described elsewhere.

is described elsewhere.

@menu

@menu

* Overview::            An overview as to the compilation passes.

* Overview::            An overview as to the compilation passes.

* Options::             Useful GCC options for embedded systems.

* Options::             Useful GCC options for embedded systems.

@end menu

@end menu

@node Overview, Options, , GCC

@node Overview, Options, , GCC

@subsection Compilation passes

@subsection Compilation passes

GCC by itself only compiles the C or C++ code into assembler. Typically

GCC by itself only compiles the C or C++ code into assembler. Typically

GCC invokes all the passes required for you. These passes are cpp, cc1,

GCC invokes all the passes required for you. These passes are cpp, cc1,

gas, ld. @code{cpp} is the C preprocessor. This will merge in the

gas, ld. @code{cpp} is the C preprocessor. This will merge in the

include files, expand all macros definitions, and process all the

include files, expand all macros definitions, and process all the

@code{#ifdef} sections. To see the output of ccp, invoke gcc with 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 the

@code{-E} option, and the preprocessed file will be printed on the

stdout. cc1 is the actual compiler pass that produces the assembler for

stdout. cc1 is the actual compiler pass that produces the assembler for

the processed file. GCC is actually only a driver program for all the

the processed file. GCC is actually only a driver program for all the

compiler passes. It will format command line options for the other passes.

compiler passes. It will format command line options for the other passes.

The usual command line GCC uses for the final link phase will have LD

The usual command line GCC uses for the final link phase will have LD

link in the startup code and additional libraries by default.

link in the startup code and additional libraries by default.

GNU AS started it's life to only function as a compiler pass, but

GNU AS started it's life to only function as a compiler pass, but

these days it can also be used as a source level assembler. When used as

these days it can also be used as a source level assembler. When used as

a source level assembler, it has a companion assembler preprocessor

a source level assembler, it has a companion assembler preprocessor

called @code{gasp}. This has a syntax similar to most other assembler

called @code{gasp}. This has a syntax similar to most other assembler

macros packages. GAS emits a relocatable object file from the assembler

macros packages. GAS emits a relocatable object file from the assembler

source. The object file contains the executable part of the application,

source. The object file contains the executable part of the application,

and debug symbols.

and debug symbols.

LD is responsible for resolving the addresses and symbols to something

LD is responsible for resolving the addresses and symbols to something

that will be fully self-contained. Some RTOS's use relocatable object

that will be fully self-contained. Some RTOS's use relocatable object

file formats like @code{a.out}, but more commonly the final image will

file formats like @code{a.out}, but more commonly the final image will

only use absolute addresses for symbols. This enables code to be burned

only use absolute addresses for symbols. This enables code to be burned

into PROMS as well. Although LD can produce an executable image, there

into PROMS as well. Although LD can produce an executable image, there

is usually a hidden object file called @code{crt0.o} that is required as

is usually a hidden object file called @code{crt0.o} that is required as

startup code.  With this startup code and a memory map, the executable

startup code.  With this startup code and a memory map, the executable

image will actually run on the target environment. @ref{Crt0,,Startup

image will actually run on the target environment. @ref{Crt0,,Startup

Files}.

Files}.

The startup code usually defines a special symbol like @code{_start}

The startup code usually defines a special symbol like @code{_start}

that is the default base address for the application, and the first

that is the default base address for the application, and the first

symbol in the executable image. If you plan to use any routines from the

symbol in the executable image. If you plan to use any routines from the

standard C library, you'll also need to implement the functions that

standard C library, you'll also need to implement the functions that

this library is dependent on. @ref{Libraries,,Porting Newlib}.

this library is dependent on. @ref{Libraries,,Porting Newlib}.

@node Options, , Overview, GCC

@node Options, , Overview, GCC

@c FIXME: Need stuff here about -fpic, -Ttext, etc...

@c FIXME: Need stuff here about -fpic, -Ttext, etc...

Options for the various development tools are covered in more detail

Options for the various development tools are covered in more detail

elsewhere. Still, the amount of options can be an overwhelming amount of

elsewhere. Still, the amount of options can be an overwhelming amount of

stuff, so the options most suited to embedded systems are summarized

stuff, so the options most suited to embedded systems are summarized

here. If you use GCC as the main driver for all the passes, most of the

here. If you use GCC as the main driver for all the passes, most of the

linker options can be passed directly to the compiler. There are also

linker options can be passed directly to the compiler. There are also

GCC options that control how the GCC driver formats the command line

GCC options that control how the GCC driver formats the command line

arguments for the linker.

arguments for the linker.

@menu

@menu

* GCC Options::         Options for the compiler.

* GCC Options::         Options for the compiler.

* GAS Options::         Options for the assembler.

* GAS Options::         Options for the assembler.

* LD Options::          Options for the linker.

* LD Options::          Options for the linker.

@end menu

@end menu

@node GCC Options, GAS Options, , Options

@node GCC Options, GAS Options, , Options

Most of the GCC options that we're interested control how the GCC driver

Most of the GCC options that we're interested control how the GCC driver

formats the options for the linker pass.

formats the options for the linker pass.

@c FIXME: this section is still under work.

@c FIXME: this section is still under work.

@table @code

@table @code

@item -nostartfiles

@item -nostartfiles

@item -nostdlib

@item -nostdlib

@item -Xlinker

@item -Xlinker

Pass the next option directly to the linker.

Pass the next option directly to the linker.

@item -v

@item -v

@item -fpic

@item -fpic

@end table

@end table

@node GAS Options, LD Options, GCC Options, Options

@node GAS Options, LD Options, GCC Options, Options

@c FIXME: Needs stuff here

@c FIXME: Needs stuff here

@node LD Options, , GAS Options, Options

@node LD Options, , GAS Options, Options

@c FIXME: Needs stuff here

@c FIXME: Needs stuff here

@node Libraries, GDB, GCC, Top

@node Libraries, GDB, GCC, Top

@chapter Porting newlib

@chapter Porting newlib

@menu

@menu

* Crt0::                Crt0.S.

* Crt0::                Crt0.S.

* Linker Scripts::      Linker scripts for memory management.

* Linker Scripts::      Linker scripts for memory management.

* What to do now::      Tricks for manipulating formats.

* What to do now::      Tricks for manipulating formats.

* Libc::                Making libc work.

* Libc::                Making libc work.

@end menu

@end menu

@node Crt0, Linker Scripts, , Libraries

@node Crt0, Linker Scripts, , Libraries

@section Crt0, the main startup file

@section Crt0, the main startup file

To make a program that has been compiled with GCC to run, you

To make a program that has been compiled with GCC to run, you

need to write some startup code. The initial piece of startup code is

need to write some startup code. The initial piece of startup code is

called a crt0. (C RunTime 0) This is usually written in assembler, and

called a crt0. (C RunTime 0) This is usually written in assembler, and

it's object gets linked in first, and bootstraps the rest of the

it's object gets linked in first, and bootstraps the rest of the

application when executed. This file needs to do the following things.

application when executed. This file needs to do the following things.

@enumerate

@enumerate

@item

@item

Initialize anything that needs it. This init section varies. If you are

Initialize anything that needs it. This init section varies. If you are

developing an application that gets download to a ROM monitor, then

developing an application that gets download to a ROM monitor, then

there is usually no need for any special initialization. The ROM monitor

there is usually no need for any special initialization. The ROM monitor

handles it for you.

handles it for you.

If you plan to burn your code in a ROM, then the crt0 typically has to

If you plan to burn your code in a ROM, then the crt0 typically has to

do all the hardware initialization that is required to run an

do all the hardware initialization that is required to run an

application. This can include things like initializing serial ports or

application. This can include things like initializing serial ports or

run a memory check. It all depends on the hardware.

run a memory check. It all depends on the hardware.

@item

@item

Zero the BSS section. This is for uninitialized data. All the addresses in

Zero the BSS section. This is for uninitialized data. All the addresses in

this section need to be initialized to zero so that programs that forget

this section need to be initialized to zero so that programs that forget

to check new variables default value will get unpredictable results.

to check new variables default value will get unpredictable results.

@item

@item

Call main()

Call main()

This is what basically starts things running. If your ROM monitor

This is what basically starts things running. If your ROM monitor

supports it, then first setup argc and argv for command line arguments

supports it, then first setup argc and argv for command line arguments

and an environment pointer. Then branch to main(). For G++ the the main

and an environment pointer. Then branch to main(). For G++ the the main

routine gets a branch to __main inserted by the code generator at the

routine gets a branch to __main inserted by the code generator at the

very top.  __main() is used by G++ to initialize it's internal tables.

very top.  __main() is used by G++ to initialize it's internal tables.

__main() then returns back to your original main() and your code gets

__main() then returns back to your original main() and your code gets

executed.

executed.

@item

@item

Call exit()

Call exit()

After main() has returned, you need to cleanup things and return control

After main() has returned, you need to cleanup things and return control

of the hardware from the application. On some hardware, there is nothing

of the hardware from the application. On some hardware, there is nothing

to return to, especially if your program is in ROM.  Sometimes the best

to return to, especially if your program is in ROM.  Sometimes the best

thing to do in this case is do a hardware reset, or branch back to the

thing to do in this case is do a hardware reset, or branch back to the

start address all over again.

start address all over again.

When there is a ROM monitor present, usually a user trap can be called

When there is a ROM monitor present, usually a user trap can be called

and then the ROM takes over. Pick a safe vector with no side

and then the ROM takes over. Pick a safe vector with no side

effects. Some ROMs have a builtin trap handler just for this case.

effects. Some ROMs have a builtin trap handler just for this case.

@end enumerate

@end enumerate

portable between all the m68k based boards we have here.

portable between all the m68k based boards we have here.

@ref{crt0.S,,Example Crt0.S}.

@ref{crt0.S,,Example Crt0.S}.

@smallexample

@smallexample

/* ANSI concatenation macros.  */

/* ANSI concatenation macros.  */

#define CONCAT1(a, b) CONCAT2(a, b)

#define CONCAT1(a, b) CONCAT2(a, b)

#define CONCAT2(a, b) a ## b

#define CONCAT2(a, b) a ## b

@end smallexample

@end smallexample

These we'll use later.

These we'll use later.

@smallexample

@smallexample

/* These are predefined by new versions of GNU cpp.  */

/* These are predefined by new versions of GNU cpp.  */

#ifndef __USER_LABEL_PREFIX__

#ifndef __USER_LABEL_PREFIX__

#define __USER_LABEL_PREFIX__ _

#define __USER_LABEL_PREFIX__ _

#endif

#endif

/* Use the right prefix for global labels.  */

/* Use the right prefix for global labels.  */

#define SYM(x) CONCAT1 (__USER_LABEL_PREFIX__, x)

#define SYM(x) CONCAT1 (__USER_LABEL_PREFIX__, x)

@end smallexample

@end smallexample

These macros are to make this code portable between both @emph{COFF} and

These macros are to make this code portable between both @emph{COFF} and

@emph{a.out}. @emph{COFF} always has an @var{_ (underline)} prepended on

@emph{a.out}. @emph{COFF} always has an @var{_ (underline)} prepended on

the front of all global symbol names. @emph{a.out} has none.

the front of all global symbol names. @emph{a.out} has none.

@smallexample

@smallexample

#ifndef __REGISTER_PREFIX__

#ifndef __REGISTER_PREFIX__

#define __REGISTER_PREFIX__

#define __REGISTER_PREFIX__

#endif

#endif

/* Use the right prefix for registers.  */

/* Use the right prefix for registers.  */

#define REG(x) CONCAT1 (__REGISTER_PREFIX__, x)

#define REG(x) CONCAT1 (__REGISTER_PREFIX__, x)

#define d0 REG (d0)

#define d0 REG (d0)

#define d1 REG (d1)

#define d1 REG (d1)

#define d2 REG (d2)

#define d2 REG (d2)

#define d3 REG (d3)

#define d3 REG (d3)

#define d4 REG (d4)

#define d4 REG (d4)

#define d5 REG (d5)

#define d5 REG (d5)

#define d6 REG (d6)

#define d6 REG (d6)

#define d7 REG (d7)

#define d7 REG (d7)

#define a0 REG (a0)

#define a0 REG (a0)

#define a1 REG (a1)

#define a1 REG (a1)

#define a2 REG (a2)

#define a2 REG (a2)

#define a3 REG (a3)

#define a3 REG (a3)

#define a4 REG (a4)

#define a4 REG (a4)

#define a5 REG (a5)

#define a5 REG (a5)

#define a6 REG (a6)

#define a6 REG (a6)

#define fp REG (fp)

#define fp REG (fp)

#define sp REG (sp)

#define sp REG (sp)

@end smallexample

@end smallexample

This is for portability between assemblers. Some register names have a

This is for portability between assemblers. Some register names have a

@var{%} or @var{$} prepended to the register name.

@var{%} or @var{$} prepended to the register name.

@smallexample

@smallexample

/*

/*

 * Set up some room for a stack. We just grab a chunk of memory.

 * Set up some room for a stack. We just grab a chunk of memory.

 */

 */

        .set    stack_size, 0x2000

        .set    stack_size, 0x2000

        .comm   SYM (stack), stack_size

        .comm   SYM (stack), stack_size

@end smallexample

@end smallexample

Set up space for the stack. This can also be done in the linker script,

Set up space for the stack. This can also be done in the linker script,

but it typically gets done here.

but it typically gets done here.

@smallexample

@smallexample

/*

/*

 * Define an empty environment.

 * Define an empty environment.

 */

 */

        .data

        .data

        .align 2

        .align 2

SYM (environ):

SYM (environ):

        .long 0

        .long 0

@end smallexample

@end smallexample

Set up an empty space for the environment. This is bogus on any most ROM

Set up an empty space for the environment. This is bogus on any most ROM

monitor, but we setup a valid address for it, and pass it to main. At

monitor, but we setup a valid address for it, and pass it to main. At

least that way if an application checks for it, it won't crash.

least that way if an application checks for it, it won't crash.

@smallexample

@smallexample

        .align  2

        .align  2

        .text

        .text

        .global SYM (stack)

        .global SYM (stack)

        .global SYM (main)

        .global SYM (main)

        .global SYM (exit)

        .global SYM (exit)

/*

/*

 * This really should be __bss_start, not SYM (__bss_start).

 * This really should be __bss_start, not SYM (__bss_start).

 */

 */

        .global __bss_start

        .global __bss_start

@end smallexample

@end smallexample

Setup a few global symbols that get used elsewhere. @var{__bss_start}

Setup a few global symbols that get used elsewhere. @var{__bss_start}

needs to be unchanged, as it's setup by the linker script.

needs to be unchanged, as it's setup by the linker script.

@smallexample

@smallexample

/*

/*

 * start -- set things up so the application will run.

 * start -- set things up so the application will run.

 */

 */

SYM (start):

SYM (start):

        link    a6, #-8

        link    a6, #-8

        moveal  #SYM (stack) + stack_size, sp

        moveal  #SYM (stack) + stack_size, sp

/*

/*

 * zerobss -- zero out the bss section

 * zerobss -- zero out the bss section

 */

 */

        moveal  #__bss_start, a0

        moveal  #__bss_start, a0

        moveal  #SYM (end), a1

        moveal  #SYM (end), a1

1:

1:

        movel   #0, (a0)

        movel   #0, (a0)

        leal    4(a0), a0

        leal    4(a0), a0

        cmpal   a0, a1

        cmpal   a0, a1

        bne     1b

        bne     1b

@end smallexample

@end smallexample

The global symbol @code{start} is used by the linker as the default

The global symbol @code{start} is used by the linker as the default

address to use for the @code{.text} section. then it zeros the

address to use for the @code{.text} section. then it zeros the

@code{.bss} section so the uninitialized data will all be cleared. Some

@code{.bss} section so the uninitialized data will all be cleared. Some

programs have wild side effects from having the .bss section let

programs have wild side effects from having the .bss section let

uncleared. Particularly it causes problems with some implementations of

uncleared. Particularly it causes problems with some implementations of

@code{malloc}.

@code{malloc}.

@smallexample

@smallexample

/*

/*

 * Call the main routine from the application to get it going.

 * Call the main routine from the application to get it going.

 * main (argc, argv, environ)

 * main (argc, argv, environ)

 * We pass argv as a pointer to NULL.

 * We pass argv as a pointer to NULL.

 */

 */

        pea     0

        pea     0

        pea     SYM (environ)

        pea     SYM (environ)

        pea     sp@@(4)

        pea     sp@@(4)

        pea     0

        pea     0

        jsr     SYM (main)

        jsr     SYM (main)

        movel   d0, sp@@-

        movel   d0, sp@@-

@end smallexample

@end smallexample

Setup the environment pointer and jump to @code{main()}. When

Setup the environment pointer and jump to @code{main()}. When

@code{main()} returns, it drops down to the @code{exit} routine below.

@code{main()} returns, it drops down to the @code{exit} routine below.

@smallexample

@smallexample

/*

/*

 * _exit -- Exit from the application. Normally we cause a user trap

 * _exit -- Exit from the application. Normally we cause a user trap

 *          to return to the ROM monitor for another run.

 *          to return to the ROM monitor for another run.

 */

 */

SYM (exit):

SYM (exit):

        trap    #0

        trap    #0

@end smallexample

@end smallexample

Implementing @code{exit} here is easy. Both the @code{rom68k} and @code{bug}

Implementing @code{exit} here is easy. Both the @code{rom68k} and @code{bug}

can handle a user caused exception of @code{zero} with no side effects.

can handle a user caused exception of @code{zero} with no side effects.

Although the @code{bug} monitor has a user caused trap that will return

Although the @code{bug} monitor has a user caused trap that will return

control to the ROM monitor, this solution has been more portable.

control to the ROM monitor, this solution has been more portable.

@node Linker Scripts, What to do now, Crt0, Libraries

@node Linker Scripts, What to do now, Crt0, Libraries

@section Linker scripts for memory management

@section Linker scripts for memory management

The linker script sets up the memory map of an application. It also

The linker script sets up the memory map of an application. It also

sets up default values for variables used elsewhere by sbrk() and the

sets up default values for variables used elsewhere by sbrk() and the

crt0. These default variables are typically called @code{_bss_start} and

crt0. These default variables are typically called @code{_bss_start} and

@code{_end}.

@code{_end}.

For G++, the constructor and destructor tables must also be setup here.

For G++, the constructor and destructor tables must also be setup here.

The actual section names vary depending on the object file format. For

The actual section names vary depending on the object file format. For

@code{a.out} and @code{coff}, the three main sections are @code{.text},

@code{a.out} and @code{coff}, the three main sections are @code{.text},

@code{.data}, and @code{.bss}.

@code{.data}, and @code{.bss}.

Now that you have an image, you can test to make sure it got the

Now that you have an image, you can test to make sure it got the

memory map right. You can do this by having the linker create a memory

memory map right. You can do this by having the linker create a memory

map (by using the @code{-Map} option), or afterwards by using @code{nm} to

map (by using the @code{-Map} option), or afterwards by using @code{nm} to

check a few critical addresses like @code{start}, @code{bss_end}, and

check a few critical addresses like @code{start}, @code{bss_end}, and

@code{_etext}.

@code{_etext}.

Here's a breakdown of a linker script for a m68k based target board.

Here's a breakdown of a linker script for a m68k based target board.

See the file @code{libgloss/m68k/idp.ld}, or go to the appendixes in

See the file @code{libgloss/m68k/idp.ld}, or go to the appendixes in

the end of the manual. @ref{idp.ld,,Example Linker Script}.

the end of the manual. @ref{idp.ld,,Example Linker Script}.

@smallexample

@smallexample

STARTUP(crt0.o)

STARTUP(crt0.o)

OUTPUT_ARCH(m68k)

OUTPUT_ARCH(m68k)

INPUT(idp.o)

INPUT(idp.o)

SEARCH_DIR(.)

SEARCH_DIR(.)

__DYNAMIC  =  0;

__DYNAMIC  =  0;

@end smallexample

@end smallexample

The @code{STARTUP} command loads the file specified so that it's

The @code{STARTUP} command loads the file specified so that it's

first. In this case it also doubles to load the file as well, because

first. In this case it also doubles to load the file as well, because

the m68k-coff configuration defaults to not linking in the crt0.o by

the m68k-coff configuration defaults to not linking in the crt0.o by

default. It assumes that the developer probably has their own crt0.o.

default. It assumes that the developer probably has their own crt0.o.

This behavior is controlled in the config file for each architecture.

This behavior is controlled in the config file for each architecture.

It's a macro called @code{STARTFILE_SPEC}, and if it's set to

It's a macro called @code{STARTFILE_SPEC}, and if it's set to

@code{null}, then when @code{gcc} formats it's command line, it doesn't

@code{null}, then when @code{gcc} formats it's command line, it doesn't

add @code{crto.o}. Any file name can be specified here, but the default

add @code{crto.o}. Any file name can be specified here, but the default

is always @code{crt0.o}.

is always @code{crt0.o}.

Course if you only use @code{ld} to link, then the control of whether or

Course if you only use @code{ld} to link, then the control of whether or

not to link in @code{crt0.o} is done on the command line. If you have

not to link in @code{crt0.o} is done on the command line. If you have

multiple crto files, then you can leave this out all together, and link

multiple crto files, then you can leave this out all together, and link

in the @code{crt0.o} in the makefile, or by having different linker

in the @code{crt0.o} in the makefile, or by having different linker

scripts. Sometimes this is done for initializing floating point

scripts. Sometimes this is done for initializing floating point

optionally, or to add device support.

optionally, or to add device support.

The @code{OUTPUT_ARCH} sets architecture the output file is for.

The @code{OUTPUT_ARCH} sets architecture the output file is for.

@code{INPUT} loads in the file specified. In this case, it's a relocated

@code{INPUT} loads in the file specified. In this case, it's a relocated

library that contains the definitions for the low-level functions need

library that contains the definitions for the low-level functions need

by libc.a.  This could have also been specified on the command line, but

by libc.a.  This could have also been specified on the command line, but

as it's always needed, it might as well be here as a default.

as it's always needed, it might as well be here as a default.

@code{SEARCH_DIR} specifies the path to look for files, and

@code{SEARCH_DIR} specifies the path to look for files, and

@code{_DYNAMIC} means in this case there are no shared libraries.

@code{_DYNAMIC} means in this case there are no shared libraries.

@c FIXME: Check the linker manual to make sure this is accurate.

@c FIXME: Check the linker manual to make sure this is accurate.

@smallexample

@smallexample

/*

/*

 * Setup the memory map of the MC68ec0x0 Board (IDP)

 * Setup the memory map of the MC68ec0x0 Board (IDP)

 * stack grows up towards high memory. This works for

 * stack grows up towards high memory. This works for

 * both the rom68k and the mon68k monitors.

 * both the rom68k and the mon68k monitors.

 */

 */

MEMORY

MEMORY

@{

@{

  ram     : ORIGIN = 0x10000, LENGTH = 2M

  ram     : ORIGIN = 0x10000, LENGTH = 2M

@}

@}

@end smallexample

@end smallexample

This specifies a name for a section that can be referred to later in the

This specifies a name for a section that can be referred to later in the

script. In this case, it's only a pointer to the beginning of free RAM

script. In this case, it's only a pointer to the beginning of free RAM

space, with an upper limit at 2M. If the output file exceeds the upper

space, with an upper limit at 2M. If the output file exceeds the upper

limit, it will produce an error message.

limit, it will produce an error message.

@smallexample

@smallexample

/*

/*

 * stick everything in ram (of course)

 * stick everything in ram (of course)

 */

 */

SECTIONS

SECTIONS

@{

@{

  .text :

  .text :

  @{

  @{

    CREATE_OBJECT_SYMBOLS

    CREATE_OBJECT_SYMBOLS

    *(.text)

    *(.text)

     etext  =  .;

     etext  =  .;

     __CTOR_LIST__ = .;

     __CTOR_LIST__ = .;

     LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)

     LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)

    *(.ctors)

    *(.ctors)

     LONG(0)

     LONG(0)

     __CTOR_END__ = .;

     __CTOR_END__ = .;

     __DTOR_LIST__ = .;

     __DTOR_LIST__ = .;

     LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)

     LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)

    *(.dtors)

    *(.dtors)

     LONG(0)

     LONG(0)

     __DTOR_END__ = .;

     __DTOR_END__ = .;

    *(.lit)

    *(.lit)

    *(.shdata)

    *(.shdata)

  @}  > ram

  @}  > ram

  .shbss SIZEOF(.text) + ADDR(.text) :  @{

  .shbss SIZEOF(.text) + ADDR(.text) :  @{

    *(.shbss)

    *(.shbss)

  @}

  @}

@end smallexample

@end smallexample

Set up the @code{.text} section. In a @code{COFF} file, .text is where

Set up the @code{.text} section. In a @code{COFF} file, .text is where

all the actual instructions are. This also sets up the @emph{CONTRUCTOR}

all the actual instructions are. This also sets up the @emph{CONTRUCTOR}

and the @emph{DESTRUCTOR} tables for @code{G++}. Notice that the section

and the @emph{DESTRUCTOR} tables for @code{G++}. Notice that the section

description redirects itself to the @emph{ram} variable setup earlier.

description redirects itself to the @emph{ram} variable setup earlier.

@smallexample

@smallexample

  .talias :      @{ @}  > ram

  .talias :      @{ @}  > ram

  .data  : @{

  .data  : @{

    *(.data)

    *(.data)

    CONSTRUCTORS

    CONSTRUCTORS

    _edata  =  .;

    _edata  =  .;

  @} > ram

  @} > ram

@end smallexample

@end smallexample

Setup the @code{.data} section. In a @code{coff} file, this is where all

Setup the @code{.data} section. In a @code{coff} file, this is where all

he initialized data goes. @code{CONSTRUCTORS} is a special command used

he initialized data goes. @code{CONSTRUCTORS} is a special command used

by @code{ld}.

by @code{ld}.

@smallexample

@smallexample

  .bss SIZEOF(.data) + ADDR(.data) :

  .bss SIZEOF(.data) + ADDR(.data) :

  @{

  @{

   __bss_start = ALIGN(0x8);

   __bss_start = ALIGN(0x8);

   *(.bss)

   *(.bss)

   *(COMMON)

   *(COMMON)

      end = ALIGN(0x8);

      end = ALIGN(0x8);

      _end = ALIGN(0x8);

      _end = ALIGN(0x8);

      __end = ALIGN(0x8);

      __end = ALIGN(0x8);

  @}

  @}

  .mstack  : @{ @}  > ram

  .mstack  : @{ @}  > ram

  .rstack  : @{ @}  > ram

  .rstack  : @{ @}  > ram

  .stab  . (NOLOAD) :

  .stab  . (NOLOAD) :

  @{

  @{

    [ .stab ]

    [ .stab ]

  @}

  @}

  .stabstr  . (NOLOAD) :

  .stabstr  . (NOLOAD) :

  @{

  @{

    [ .stabstr ]

    [ .stabstr ]

  @}

  @}

@}

@}

@end smallexample

@end smallexample

Setup the @code{.bss} section. In a @code{COFF} file, this is where

Setup the @code{.bss} section. In a @code{COFF} file, this is where

unitialized data goes. The symbols @code{_bss_start} and @code{_end}

unitialized data goes. The symbols @code{_bss_start} and @code{_end}

are setup here for use by the @code{crt0.o} when it zero's the

are setup here for use by the @code{crt0.o} when it zero's the

@code{.bss} section.

@code{.bss} section.

@node What to do now, Libc, Linker Scripts, Libraries

@node What to do now, Libc, Linker Scripts, Libraries

@section What to do when you have a binary image

@section What to do when you have a binary image

A few ROM monitors load binary images, typically @code{a.out}, but most all

A few ROM monitors load binary images, typically @code{a.out}, but most all

will load an @code{srecord}. An srecord is an ASCII representation of a binary

will load an @code{srecord}. An srecord is an ASCII representation of a binary

image. At it's simplest, an srecord is an address, followed by a byte

image. At it's simplest, an srecord is an address, followed by a byte

count, followed by the bytes, and a 2's compliment checksum. A whole

count, followed by the bytes, and a 2's compliment checksum. A whole

srecord file has an optional @emph{start} record, and a required @emph{end}

srecord file has an optional @emph{start} record, and a required @emph{end}

record. To make an srecord from a binary image, the GNU @code{objcopy} program

record. To make an srecord from a binary image, the GNU @code{objcopy} program

is used. This will read the image and make an srecord from it. To do

is used. This will read the image and make an srecord from it. To do

this, invoke objcopy like this: @code{objcopy -O srec infile outfile}. Most

this, invoke objcopy like this: @code{objcopy -O srec infile outfile}. Most

PROM burners also read srecords or a similar format. Use @code{objdump -i} to

PROM burners also read srecords or a similar format. Use @code{objdump -i} to

get a list of support object files types for your architecture.

get a list of support object files types for your architecture.

@node Libc, , What to do now, Libraries

@node Libc, , What to do now, Libraries

@section Libraries

@section Libraries

This describes @code{newlib}, a freely available libc replacement. Most

This describes @code{newlib}, a freely available libc replacement. Most

applications use calls in the standard C library. When initially linking

applications use calls in the standard C library. When initially linking

in libc.a, several I/O functions are undefined. If you don't plan on

in libc.a, several I/O functions are undefined. If you don't plan on

doing any I/O, then you're OK, otherwise they need to be created. These

doing any I/O, then you're OK, otherwise they need to be created. These

routines are read, write, open, close. sbrk, and kill. Open & close

routines are read, write, open, close. sbrk, and kill. Open & close

don't need to be fully supported unless you have a filesystems, so

don't need to be fully supported unless you have a filesystems, so

typically they are stubbed out. Kill is also a stub, since you can't do

typically they are stubbed out. Kill is also a stub, since you can't do

process control on an embedded system.

process control on an embedded system.

Sbrk() is only needed by applications that do dynamic memory

Sbrk() is only needed by applications that do dynamic memory

allocation. It's uses the symbol @code{_end} that is setup in the linker

allocation. It's uses the symbol @code{_end} that is setup in the linker

script. It also requires a compile time option to set the upper size

script. It also requires a compile time option to set the upper size

limit on the heap space. This leaves us with read and write, which are

limit on the heap space. This leaves us with read and write, which are

required for serial I/O. Usually these two routines are written in C,

required for serial I/O. Usually these two routines are written in C,

and call a lower level function for the actual I/O operation. These two

and call a lower level function for the actual I/O operation. These two

lowest level I/O primitives are inbyte() and outbyte(), and are also

lowest level I/O primitives are inbyte() and outbyte(), and are also

used by GDB back ends if you've written an exception handler. Some

used by GDB back ends if you've written an exception handler. Some

systems also implement a havebyte() for input as well.

systems also implement a havebyte() for input as well.

Other commonly included functions are routines for manipulating

Other commonly included functions are routines for manipulating

LED's on the target (if they exist) or low level debug help. Typically a

LED's on the target (if they exist) or low level debug help. Typically a

putnum() for printing words and bytes as a hex number is helpful, as

putnum() for printing words and bytes as a hex number is helpful, as

well as a low-level print() to output simple strings.

well as a low-level print() to output simple strings.

As libg++ uses the I/O routines in libc.a, if read and write work,

As libg++ uses the I/O routines in libc.a, if read and write work,

then libg++ will also work with no additional changes.

then libg++ will also work with no additional changes.

@menu

@menu

* I/O Support::         Functions that make serial I/O work.

* I/O Support::         Functions that make serial I/O work.

* Memory Support::      Memory support.

* Memory Support::      Memory support.

* Misc Support::        Other needed functions.

* Misc Support::        Other needed functions.

* Debugging::            Useful Debugging Functions

* Debugging::            Useful Debugging Functions

@end menu

@end menu

@node I/O Support, Memory Support, , Libc

@node I/O Support, Memory Support, , Libc

@subsection Making I/O work

@subsection Making I/O work

@node Memory Support, Misc Support, I/O Support, Libc

@node Memory Support, Misc Support, I/O Support, Libc

@subsection Routines for dynamic memory allocation

@subsection Routines for dynamic memory allocation

To support using any of the memory functions, you need to implement

To support using any of the memory functions, you need to implement

sbrk(). @code{malloc()}, @code{calloc()}, and @code{realloc()} all call

sbrk(). @code{malloc()}, @code{calloc()}, and @code{realloc()} all call

@code{sbrk()} at there lowest level. @code{caddr_t} is defined elsewhere

@code{sbrk()} at there lowest level. @code{caddr_t} is defined elsewhere

as @code{char *}. @code{RAMSIZE} is presently a compile time option. All

as @code{char *}. @code{RAMSIZE} is presently a compile time option. All

this does is move a pointer to heap memory and check for the upper

this does is move a pointer to heap memory and check for the upper

limit. @ref{glue.c,,Example libc support code}. @code{sbrk()} returns a

limit. @ref{glue.c,,Example libc support code}. @code{sbrk()} returns a

pointer to the previous value before more memory was allocated.

pointer to the previous value before more memory was allocated.

@smallexample

@smallexample

/* _end is set in the linker command file *

/* _end is set in the linker command file *

extern caddr_t _end;/

extern caddr_t _end;/

/* just in case, most boards have at least some memory */

/* just in case, most boards have at least some memory */

#ifndef RAMSIZE

#ifndef RAMSIZE

#  define RAMSIZE             (caddr_t)0x100000

#  define RAMSIZE             (caddr_t)0x100000

#endif

#endif

/*

/*

 * sbrk -- changes heap size size. Get nbytes more

 * sbrk -- changes heap size size. Get nbytes more

 *         RAM. We just increment a pointer in what's

 *         RAM. We just increment a pointer in what's

 *         left of memory on the board.

 *         left of memory on the board.

 */

 */

caddr_t

caddr_t

sbrk(nbytes)

sbrk(nbytes)

     int nbytes;

     int nbytes;

@{

@{

  static caddr_t heap_ptr = NULL;

  static caddr_t heap_ptr = NULL;

  caddr_t        base;

  caddr_t        base;

  if (heap_ptr == NULL) @{

  if (heap_ptr == NULL) @{

    heap_ptr = (caddr_t)&_end;

    heap_ptr = (caddr_t)&_end;

  @}

  @}

  if ((RAMSIZE - heap_ptr) >= 0) @{

  if ((RAMSIZE - heap_ptr) >= 0) @{

    base = heap_ptr;

    base = heap_ptr;

    heap_ptr += nbytes;

    heap_ptr += nbytes;

    return (base);

    return (base);

  @} else @{

  @} else @{

    errno = ENOMEM;

    errno = ENOMEM;

    return ((caddr_t)-1);

    return ((caddr_t)-1);

  @}

  @}

@}

@}

@end smallexample

@end smallexample

@node Misc Support, Debugging, Memory Support, Libc

@node Misc Support, Debugging, Memory Support, Libc

@subsection Misc support routines

@subsection Misc support routines

These are called by @code{newlib} but don't apply to the embedded

These are called by @code{newlib} but don't apply to the embedded

environment. @code{isatty()} is self explanatory. @code{kill()} doesn't

environment. @code{isatty()} is self explanatory. @code{kill()} doesn't

apply either in an environment withno process control, so it justs

apply either in an environment withno process control, so it justs

exits, which is a similar enough behavior. @code{getpid()} can safely

exits, which is a similar enough behavior. @code{getpid()} can safely

return any value greater than 1. The value doesn't effect anything in

return any value greater than 1. The value doesn't effect anything in

@code{newlib} because once again there is no process control.

@code{newlib} because once again there is no process control.

@smallexample

@smallexample

/*

/*

 * isatty -- returns 1 if connected to a terminal device,

 * isatty -- returns 1 if connected to a terminal device,

 *           returns 0 if not. Since we're hooked up to a

 *           returns 0 if not. Since we're hooked up to a

 *           serial port, we'll say yes and return a 1.

 *           serial port, we'll say yes and return a 1.

 */

 */

int