harvey/sys/doc/libmach.ms

.TL
Adding Application Support for a New Architecture in Plan 9
.AU
Bob Flandrena
bobf@plan9.bell-labs.com
.SH
Introduction
.LP
Plan 9 has five classes of architecture-dependent software:
headers, kernels, compilers and loaders, the
.CW libc
system library, and a few application programs.  In general,
architecture-dependent programs
consist of a portable part shared by all architectures and a
processor-specific portion for each supported architecture.
The portable code is often compiled and stored in a library
associated with
each architecture.  A program is built by
compiling the architecture-specific code and loading it with the
library.  Support for a new architecture is provided
by building a compiler for the architecture, using it to
compile the portable code into libraries,
writing the architecture-specific code, and
then loading that code with
the libraries.
.LP
This document describes the organization of the architecture-dependent
code and headers on Plan 9.
The first section briefly discusses the layout of
the headers and the source code for the kernels, compilers, loaders, and the
system library, 
.CW libc .
The second section provides a detailed
discussion of the structure of
.CW libmach ,
a library containing almost
all architecture-dependent code
used by application programs.
The final section describes the steps required to add
application program support for a new architecture.
.SH
Directory Structure
.PP
Architecture-dependent information for the new processor
is stored in the directory tree rooted at \f(CW/\fP\fIm\fP
where
.I m
is the name of the new architecture (e.g.,
.CW mips ).
The new directory should be initialized with several important
subdirectories, notably
.CW bin ,
.CW include ,
and
.CW lib .
The directory tree of an existing architecture
serves as a good model for the new tree.
The architecture-dependent
.CW mkfile
must be stored in the newly created root directory
for the architecture.  It is easiest to copy the
mkfile for an existing architecture and modify
it for the new architecture.  When the mkfile
is correct, change the
.CW OS
and
.CW CPUS
variables in the
.CW /sys/src/mkfile.proto
to reflect the addition of the new architecture.
.SH
Headers
.LP
Architecture-dependent headers are stored in directory
.CW /\fIm\fP/include
where
.I m
is the name of the architecture (e.g.,
.CW mips ).
Two header files are required:
.CW u.h 
and
.CW ureg.h .
The first defines fundamental data types,
bit settings for the floating point
status and control registers, and
.CW va_list
processing which depends on the stack
model for the architecture.  This file
is best built by copying and modifying the
.CW u.h
file from an architecture
with a similar stack model.
The
.CW ureg.h
file
contains a structure describing the layout
of the saved register set for
the architecture; it is defined by the kernel.
.LP
Header file
.CW /sys/include/a.out.h
contains the definitions of the magic
numbers used to identify executables for
each architecture.  When support for a new
architecture is added, the magic number
for the architecture must be added to this file.
.LP
The header format of a bootable executable is defined by
each manufacturer.  Header file
.CW /sys/include/bootexec.h
contains structures describing the headers currently
supported.  If the new architecture uses a common header
such as COFF,
the header format is probably already defined,
but if the bootable header format is non-standard,
a structure defining the format must be added to this file.
.LP
.SH
Kernel
.LP
Although the kernel depends critically on the properties of the underlying
hardware, most of the
higher-level kernel functions, including process
management, paging, pseudo-devices, and some
networking code, are independent of processor
architecture.  The portable kernel code
is divided into two parts: that implementing kernel
functions and that devoted to the boot process.
Code in the first class is stored in directory
.CW /sys/src/9/port
and the portable boot code is stored in
.CW /sys/src/9/boot .
Architecture-dependent kernel code is stored in the
subdirectories of
.CW /sys/src/9
named for each architecture.
.LP
The relationship between the kernel code and the boot code
is convoluted and subtle.  The portable boot code
is compiled into a library for each architecture.  An architecture-specific
main program is loaded with the appropriate library and the resulting
executable is compiled into the kernel where it is executed as
a user process during the final stages of kernel initialization.  The boot process
performs authentication, attaches the name space root to the appropriate
file system and starts the
.CW init
process.
.LP
The organization of the portable kernel source code differs from that
of most other architecture-specific code.
Instead of storing the portable code in a library
and loading it with the architecture-specific
code, the portable code is compiled directly into
the directory containing the architecture-specific code
and linked with the object files built from the source in that directory.
.LP
.SH
Compilers and Loaders
.LP
The compiler source code conforms to the usual
organization: portable code is compiled into a library
for each architecture
and the architecture-dependent code is loaded with
that library.
The common compiler code is stored in
.CW /sys/src/cmd/cc .
The
.CW mkfile
in this directory compiles the portable source and
archives the objects in a library for each architecture.
The architecture-specific compiler source
is stored in a subdirectory of
.CW /sys/src/cmd
with the same name as the compiler (e.g.,
.CW /sys/src/cmd/vc ).
.LP
There is no portable code shared by the loaders.
Each directory of loader source
code is self-contained, except for
a header file and an instruction name table
included from the
directory of the associated
compiler.
.LP
.SH
Libraries
.LP
Most C library modules are
portable; the source code is stored in
directories
.CW /sys/src/libc/port
and
.CW /sys/src/libc/9sys .
Architecture-dependent library code
is stored in the subdirectory of
.CW /sys/src/libc
named the same as the target processor.
Non-portable functions not only
implement architecture-dependent operations
but also supply assembly language implementations
of functions where speed is critical.
Directory
.CW /sys/src/libc/9syscall
is unusual because it
contains architecture-dependent information
for all architectures.
It holds only a header file defining
the names and numbers of system calls
and a
.CW mkfile .
The
.CW mkfile
executes an
.CW rc
script that parses the header file, constructs
assembler language functions implementing the system
call for each architecture, assembles the code,
and archives the object files in
.CW libc .
The assembler language syntax and the system interface
differ for each architecture.
The
.CW rc
script in this
.CW mkfile
must be modified to support a new architecture.
.LP
.SH
Applications
.LP
Application programs process two forms of architecture-dependent
information: executable images and intermediate object files.
Almost all processing is on executable files.
System library
.CW libmach
provides functions that convert
architecture-specific data
to a portable format so application programs
can process this data independent of its
underlying representation.
Further, when a new architecture is implemented
almost all code changes
are confined to the library;
most affected application programs need only be reloaded.
The source code for the library is stored in
.CW /sys/src/libmach .
.LP
An application program running on one type of
processor must be able to interpret
architecture-dependent information for all
supported processors.
For example, a debugger must be able to debug
the executables of
all architectures, not just the
architecture on which it is executing, since
.CW /proc
may be imported from a different machine.
.LP
A small part of the application library
provides functions to
extract symbol references from object files.
The remainder provides the following processing
of executable files or memory images:
.RS
.LP
.IP \(bu
Header interpretation.
.IP \(bu
Symbol table interpretation.
.IP \(bu
Execution context interpretation, such as stack traces
and stack frame location.
.IP \(bu
Instruction interpretation including disassembly and
instruction size and follow-set calculations.
.IP \(bu
Exception and floating point number interpretation.
.IP \(bu
Architecture-independent read and write access through a
relocation map.
.RE
.LP
Header file
.CW /sys/include/mach.h
defines the interfaces to the
application library.  Manual pages
.I mach (2),
.I symbol (2),
and
.I object (2)
describe the details of the
library functions.
.LP
Two data structures, called
.CW Mach
and
.CW Machdata ,
contain architecture-dependent  parameters and
a jump table of functions.
Global variables
.CW mach
and
.CW machdata
point to the
.CW Mach
and
.CW Machdata
data structures associated with the target architecture.
An application determines the target architecture of
a file or executable image, sets the global pointers
to the data structures associated with that architecture,
and subsequently performs all references indirectly through the
pointers.
As a result, direct references to the tables for each
architecture are avoided and the application code intrinsically
supports all architectures (though only one at a time).
.LP
Object file processing is handled similarly: architecture-dependent
functions identify and
decode the intermediate files for the processor.
The application indirectly
invokes a classification function to identify
the architecture of the object code and to select the
appropriate decoding function.  Subsequent calls
then use that function to decode each record.  Again,
the layer of indirection allows the application code
to support all architectures without modification.
.LP
Splitting the architecture-dependent information
between the
.CW Mach
and
.CW Machdata
data structures
allows applications to choose
an appropriate level of service.  Even though an application
does not directly reference the architecture-specific data structures,
it must load the
architecture-dependent tables and code 
for all architectures it supports.  The size of this data
can be substantial and many applications do not require
the full range of architecture-dependent functionality.
For example, the
.CW size
command does not require the disassemblers for every architecture;
it only needs to decode the header.
The
.CW Mach
data structure contains a few architecture-specific parameters
and a description of the processor register set.
The size of the structure
varies with the size of the register
set but is generally small.
The
.CW Machdata
data structure contains
a jump table of architecture-dependent functions;
the amount of code and data referenced by this table
is usually large.
.SH
Libmach Source Code Organization
.LP
The
.CW libmach
library provides four classes of functionality:
.LP
.IP "Header and Symbol Table Decoding\ -\ "
Files
.CW executable.c
and
.CW sym.c
contain code to interpret the header and
symbol tables of
an executable file or executing image.
Function
.CW crackhdr
decodes the header,
reformats the
information into an
.CW Fhdr
data structure, and points
global variable
.CW mach
to the
.CW Mach
data structure of the target architecture.
The symbol table processing
uses the data in the
.CW Fhdr
structure to decode the symbol table.
A variety of symbol table access functions then support
queries on the reformatted table.
.IP "Debugger Support\ -\ "
Files named
.CW \fIm\fP.c ,
where
.I m
is the code letter assigned to the architecture,
contain the initialized
.CW Mach
data structure and the definition of the register
set for each architecture.
Architecture-specific debugger support functions and
an initialized
.CW Machdata
structure are stored in
files named
.CW \fIm\fPdb.c .
Files
.CW machdata.c 
and
.CW setmach.c
contain debugger support functions shared
by multiple architectures.
.IP "Architecture-Independent Access\ -\ "
Files
.CW map.c ,
.CW access.c ,
and
.CW swap.c
provide accesses through a relocation map
to data in an executable file or executing image.
Byte-swapping is performed as needed.  Global variables
.CW mach
and
.CW machdata
must point to the
.CW Mach
and
.CW Machdata
data structures of the target architecture.
.IP "Object File Interpretation\ -\ "
These files contain functions to identify the
target architecture of an
intermediate object file
and extract references to symbols.  File
.CW obj.c
contains code common to all architectures;
file
.CW \fIm\fPobj.c
contains the architecture-specific source code
for the machine with code character
.I m .
.LP
The
.CW Machdata
data structure is primarily a jump
table of architecture-dependent debugger support
functions. Functions select the
.CW Machdata
structure for a target architecture based
on the value of the
.CW type
code in the
.CW Fhdr
structure or the name of the architecture.
The jump table provides functions to swap bytes, interpret
machine instructions,
perform stack
traces, find stack frames, format floating point
numbers, and decode machine exceptions.  Some functions, such as
machine exception decoding, are idiosyncratic and must be
supplied for each architecture.  Others depend
on the compiler run-time model and several
architectures may share code common to a model.  For
example, many architectures share the code to
process the fixed-frame stack model implemented by
several of the compilers.
Finally, some
functions, such as byte-swapping, provide a general capability and
the jump table need only select an implementation appropriate
to the architecture.
.LP
.SH
Adding Application Support for a New Architecture
.LP
This section describes the
steps required to add application-level
support for a new architecture.
We assume
the kernel, compilers, loaders and system libraries
for the new architecture are already in place.  This
implies that a code-character has been assigned and
that the architecture-specific headers have been
updated.
With the exception of two programs,
application-level changes are confined to header
files and the source code in
.CW /sys/src/libmach .
.LP
.IP 1.
Begin by updating the application library
header file in
.CW /sys/include/mach.h .
Add the following symbolic codes to the
.CW enum
statement near the beginning of the file:
.RS
.IP \(bu
The processor type code, e.g., 
.CW MSPARC .
.IP \(bu
The type of the executable.  There are usually
two codes needed: one for a bootable
executable (i.e., a kernel) and one for an
application executable.
.IP \(bu
The disassembler type code.  Add one entry for
each supported disassembler for the architecture.
.IP \(bu
A symbolic code for the object file.
.RE
.LP
.IP 2.
In a file name
.CW /sys/src/libmach/\fIm\fP.c
(where
.I m
is the identifier character assigned to the architecture),
initialize
.CW Reglist
and
.CW Mach
data structures with values defining
the register set and various system parameters.
The source file for a similar architecture
can serve as template.
Most of the fields of the
.CW Mach
data structure are obvious
but a few require further explanation.
.RS
.IP "\f(CWkbase\fP\ -\ "
This field
contains the address of the kernel 
.CW ublock .
The debuggers
assume the first entry of the kernel
.CW ublock
points to the
.CW Proc
structure for a kernel thread.
.IP "\f(CWktmask\fP\ -\ "
This field
is a bit mask used to calculate the kernel text address from
the kernel 
.CW ublock
address.
The first page of the
kernel text segment is calculated by
ANDing
the negation of this mask with
.CW kbase .
.IP "\f(CWkspoff\fP\ -\ "
This field
contains the byte offset in the
.CW Proc
data structure to the saved kernel
stack pointer for a suspended kernel thread.  This
is the offset to the 
.CW sched.sp
field of a
.CW Proc
table entry.
.IP "\f(CWkpcoff\fP\ -\ "
This field contains the byte offset into the
.CW Proc
data structure
of
the program counter of a suspended kernel thread.
This is the offset to
field
.CW sched.pc
in that structure.
.IP "\f(CWkspdelta\fP and \f(CWkpcdelta\fP\ -\ "
These fields
contain corrections to be added to
the stack pointer and program counter, respectively,
to properly locate the stack and next
instruction of a kernel thread.  These
values bias the saved registers retrieved
from the
.CW Label
structure named
.CW sched
in the
.CW Proc
data structure.
Most architectures require no bias
and these fields contain zeros.
.IP "\f(CWscalloff\fP\ -\ "
This field
contains the byte offset of the
.CW scallnr
field in the
.CW ublock
data structure associated with a process.
The
.CW scallnr
field contains the number of the
last system call executed by the process.
The location of the field varies depending on
the size of the floating point register set
which precedes it in the
.CW ublock .
.RE
.LP
.IP 3.
Add an entry to the initialization of the
.CW ExecTable
data structure at the beginning of file
.CW /sys/src/libmach/executable.c .
Most architectures
require two entries: one for
a normal executable and
one for a bootable
image.  Each table entry contains:
.RS
.IP \(bu
Magic Number\ \-\ 
The big-endian magic number assigned to the architecture in
.CW /sys/include/a.out.h .
.IP \(bu
Name\ \-\ 
A string describing the executable.
.IP \(bu
Executable type code\ \-\ 
The executable code assigned in
.CW /sys/include/mach.h .
.IP \(bu
\f(CWMach\fP pointer\ \-\ 
The address of the initialized
.CW Mach
data structure constructed in Step 2.
You must also add the name of this table to the
list of
.CW Mach
table definitions immediately preceding the
.CW ExecTable
initialization.
.IP \(bu
Header size\ \-\ 
The number of bytes in the executable file header.
The size of a normal executable header is always
.CW sizeof(Exec) .
The size of a bootable header is
determined by the size of the structure
for the architecture defined in
.CW /sys/include/bootexec.h .
.IP \(bu
Byte-swapping function\ \-\ 
The address of
.CW beswal
or
.CW leswal
for big-endian and little-endian
architectures, respectively.
.IP \(bu
Decoder function\ -\ 
The address of a function to decode the header.
Function
.CW adotout
decodes the common header shared by all normal
(i.e., non-bootable) executable files.
The header format of bootable
executable files is defined by the manufacturer and
a custom function is almost always
required to decode it.
Header file
.CW /sys/include/bootexec.h
contains data structures defining the bootable
headers for all architectures.  If the new architecture
uses an existing format, the appropriate
decoding function should already be in
.CW executable.c .
If the header format is unique, then
a new function must be added to this file.
Usually the decoding function for an existing
architecture can be adopted with minor modifications.
.RE
.LP
.IP 4.
Write an object file parser and
store it in file
.CW /sys/src/libmach/\fIm\fPobj.c
where
.I m
is the identifier character assigned to the architecture.
Two functions are required: a predicate to identify an
object file for the architecture and a function to extract
symbol references from the object code.
The object code format is obscure but
it is often possible to adopt the
code of an existing architecture
with minor modifications.
When these
functions are in hand, insert their addresses
in the jump table at the beginning of file
.CW /sys/src/libmach/obj.c .
.LP
.IP 5.
Implement the required debugger support functions and
initialize the parameters and jump table of the
.CW Machdata
data structure for the architecture.
This code is conventionally stored in
a file named
.CW /sys/src/libmach/\fIm\fPdb.c
where
.I m
is the identifier character assigned to the architecture.
The fields of the
.CW Machdata
structure are:
.RS
.IP "\f(CWbpinst\fP and \f(CWbpsize\fP\ -\ "
These fields
contain the breakpoint instruction and the size
of the instruction, respectively.
.IP "\f(CWswab\fP\ -\ "
This field
contains the address of a function to
byte-swap a 16-bit value.  Choose
.CW leswab
or
.CW beswab
for little-endian or big-endian architectures, respectively.
.IP "\f(CWswal\fP\ -\ "
This field
contains the address of a function to
byte-swap a 32-bit value.  Choose
.CW leswal
or
.CW beswal
for little-endian or big-endian architectures, respectively.
.IP "\f(CWctrace\fP\ -\ "
This field
contains the address of a function to perform a
C-language stack trace.  Two general trace functions,
.CW risctrace
and
.CW cisctrace ,
traverse fixed-frame and relative-frame stacks,
respectively.  If the compiler for the
new architecture conforms to one of
these models, select the appropriate function.  If the
stack model is unique,
supply a custom stack trace function.
.IP "\f(CWfindframe\fP\ -\ "
This field
contains the address of a function to locate the stack
frame associated with a text address.
Generic functions
.CW riscframe
and
.CW ciscframe
process fixed-frame and relative-frame stack
models.
.IP "\f(CWufixup\fP\ -\ "
This field
contains the address of a function to adjust
the base address of the register save area.
Currently, only the
68020 requires this bias
to offset over the active
exception frame.
.IP "\f(CWexcep\fP\ -\ "
This field
contains the address of a function to produce a
text
string describing the
current exception.
Each architecture stores exception
information uniquely, so this code must always be supplied.
.IP "\f(CWbpfix\fP\ -\ "
This field
contains the address of a function to adjust an
address prior to laying down a breakpoint.
.IP "\f(CWsftos\fP\ -\ "
This field
contains the address of a function to convert a single
precision floating point value
to a string.  Choose
.CW leieeesftos
for little-endian
or
.CW beieeesftos
for big-endian architectures.
.IP "\f(CWdftos\fP\ -\ "
This field
contains the address of a function to convert a double
precision floating point value
to a string.  Choose
.CW leieeedftos
for little-endian
or
.CW beieeedftos
for big-endian architectures.
.IP "\f(CWfoll\fP, \f(CWdas\fP, \f(CWhexinst\fP, and \f(CWinstsize\fP\ -\ "
These fields point to functions that interpret machine
instructions.
They rely on disassembly of the instruction
and are unique to each architecture.
.CW Foll
calculates the follow set of an instruction.
.CW Das
disassembles a machine instruction to assembly language.
.CW Hexinst
formats a machine instruction as a text
string of
hexadecimal digits.
.CW Instsize
calculates the size in bytes, of an instruction.
Once the disassembler is written, the other functions
can usually be implemented as trivial extensions of it.
.LP
It is possible to provide support for a new architecture
incrementally by filling the jump table entries
of the
.CW Machdata
structure as code is written.  In general, if
a jump table entry contains a zero, application
programs requiring that function will issue an
error message instead of attempting to
call the function.  For example,
the
.CW foll ,
.CW das ,
.CW hexinst ,
and
.CW instsize
jump table slots can be zeroed until a
disassembler is written.
Other capabilities, such as
stack trace or variable inspection,
can be supplied and will be available to
the debuggers but attempts to use the
disassembler will result in an error message.
.RE
.IP 6.
Update the table named
.CW machines
near the beginning of
.CW /sys/src/libmach/setmach.c .
This table binds the
file type code and machine name to the
.CW Mach
and
.CW Machdata
structures of an architecture.
The names of the initialized
.CW Mach
and
.CW Machdata
structures built in steps 2 and 5
must be added to the list of
structure definitions immediately
preceding the table initialization.
If both Plan 9 and
native disassembly are supported, add
an entry for each disassembler to the table.  The
entry for the default disassembler (usually
Plan 9) must be first.
.IP 7.
Add an entry describing the architecture to
the table named
.CW trans
near the end of
.CW /sys/src/cmd/prof.c .
.RE
.IP 8.
Add an entry describing the architecture to
the table named
.CW objtype
near the start of
.CW /sys/src/cmd/pcc.c .
.RE
.IP 9.
Recompile and install
all application programs that include header file
.CW mach.h
and load with
.CW libmach.a .