XFLAT Shared Library Support Tools

<<Index>>

• XFLAT Tools Overview
• xflat-gcc
• xflat-ld
• Sample Makefile
• readxflat
• ldelflib
• ldelf2xflt

The Makefile in the xflat/tools directory builds five PC-based tools. The primary tools are:

• xflat-gcc,
• xflat-ld, and
• readxflat.

xflat-ld uses lower level sub-processes to accomplish it task. Normally, you will not have to interact with these tools directory. These include:

• ldelflib, and
• ldelf2xflt.

These tools and their interrelationships are discussed below.

xflat-gcc is a very simple "wrapper" program. This program provides some some wrapper logic for gcc: It simply inserts the files in xflat/arch-include into the standard include path. This allows header files in xflat/arch-include to replace certain header files normally included by gcc. This replacement is necessary to support sharing of global variables between different xFLT modules in a manner that is complete transparent to the user application.

The xflat-gcc command line parameters are simply those of gcc.

xflat-ld is another, relatively simple "wrapper" program that combines of the operations of the lower level sub-process, ldelflib and ldelf2xflt (see below). xflat-ld is a replacement tool for GNU ld. It accepts a subset of the GNU ld command line arguments. For most uses, it has the same "look and feel" as GNU ld; differing in that it generates xFLT binaries.

SYNOPSIS
xflat-ld [options] objfile [objfile [...]]

OPTIONS

-Bdynamic
-dy
-call_shared
   Link against dynamic libraries.  This  option is the default.
   You may use this option multiple times on the command line:
   It affects library searching for "-l" options which follow
   it.

--cxx
   Assume C++ conventions when linking (default: C conventions)

--dynamic-linker <file>
   Set the name of the dynamic linker.  This is only meaningful
   when generating  dynamically  linked xFLT executables.  The
   default dynamic linker is normally correct; don't use this
   unless you know what you are doing.

-e <name>
--entry=<name>
-init <name>   Use <name> as the explicit symbol for beginning execution of
   your program or for initialization of your shared library.
   If omitted, the default program entry point is "start;"
   for shared libraries, there is no default initialization.

-fini <name>
   When creating an xFLT executable or shared object, call <name>
   when the executable or shared  object is unloaded.  There
   is no default

-g
   In addition to the xflat binary, generate a special ELF format
   binary for use with a remote GDB debugger.  This special debug
   binary has the same name as the xflat binary but with the added
   extension, ".debug."  Note:  the "-g" is recognized by the
   GNU ld, but ignored.

--help
   Print a summary of the command-line options on the standard
   output and exit.

-L<searchdir>
--library-path=<searchdir>
-rpath <searchdir>
   Add path <searchdir> to the list of paths that will be
   searched for shared libraries.  You may use these options
   any number of times. The directories are searched in the
   order in which they are specified on the command line.
   Directories specified on the command line are searched
   before the default directories.  All "-L" and "-rpath"
   options apply to all "-l" options, regardless of the order
   in which the options appear.

-l<archive>
--library=<archive>
   Add a shared library file to the list of files to link.  This
   option may be used any number of times.  xflat-ld will search its
   path-list for occurrences of `lib<archive>.so' for every shared
   library specified

-o <output>
--output=<output>
   Use <output> as the name for the program or shared library
   produced by xflat-ld.  If this option is not specified, the name
   a.out is used by default.

-shared
-Bshareable
   Create a shared library.

--stack <reserve>
   Specify the amount of memory to allocate for use as stack
   for this program.  The default is 4Kb.

-Bstatic
-dn
-non_shared
-static
   Do  not  link  against shared libraries. You  may  use
   this  option  multiple  times  on the command line: it
   affects library searching for "-l" options which  follow
   it.

--dll-verbose
--verbose
   Pass the corresponding verbose option on to all xflat-ld
   sub-processes.

-W1,<arg[,arg[...]]
   Pass the specified argument(s) to the ldelflib sub-process

-W2,<arg[,arg[...]]
   Pass the specified argument(s) to the ldelf2xflt sub-process

The "Hello, World!" example resides in xflat/tests/hello. The Makefile in that directory builds hello using the low level tools, ldelflib and ldelf2xflt. The following Makefile is functionally equivalent, but illustrates how the make is simplified by xflat-gcc and xflat-ld.

WD			= ${shell pwd}
TOPDIR			= $(WD)/..

include	$(TOPDIR)/Make.defs

ARCHCFLAGS		= $(ARCHWARNINGS) $(ARCHOPTIMIZATION) \
			  $(ARCHCPUFLAGS) $(ARCHPICFLAGS)

BIN			= hello

BASE_SRCS		= $(BIN).c
BASE_OBJS		= $(BASE_SRCS:.c=.o)

VPATH			= $(TOPDIR)/tests/hello

all: $(BIN)

$(BASE_OBJS): %.o: %.c
	./xflat-gcc -c $(ARCHCFLAGS) $< -o $@

$(BIN): $(BASE_OBJS)
	./xflat-ld -o $@ $(BASE_OBJS) -lc

clean: 
	rm -f $(BIN) *.o core

user_install:
	install -D $(BIN) $(USER_TESTS_DIR)/$(BIN)

The readxflat is analogous to dump_flat but significantly more complex. It reads an xFLT binary and prints information about the content of the binary.

If you type 'readxflat' you will get the current usage of for the tool. At present, this usage for a litte-endian target:

Usage: ./readxflat [options] <flat-filename>

Where options are one or more of the following:

  -h Dump the XFLAT file header     [not dumped]
  -r Dump relocation entries        [not dumped]
  -i Dump the imported symbol table [not dumped]
  -e Dump the exported symbol table [not dumped]
  -L Dump the library search pathes [not dumped]
  -l Dump the library file names    [not dumped]
  -x Dump xFLT loader pathname      [not dumped]
  -c Disassemble the text section   [not dumped]
  -d Dump data section (hex)        [not dumped]
  -a Dump all of the above          [not dumped]
  -b Assume big-endian byteorder    [little endian]
  -v Output verbose debug info      [no output]

When compiled for a big-endian target, the behavior of the -b option is slightly different:

  -b Assume little-endian byteorder [big endian]

ldelflib is a post processing tool that receives a partially linked set of objects as its input and generates a source code file. This source code file contains all of the logic necessary to support shared libraries.

ldelflib is managed by the wrapper, xflat-ld. You should not normally have to interact with it directly. If you type 'ldelflib' you will get the current usage of for the tool. At present, this is:

Usage: ldelflib [options] <bfd-filename>

Where options are one or more of the following.  Note
that a space is always required between the option and
any following arguments.

  -L <library-path-name>
      Path to XFLAT shared libraries.  A maximum of 8
  -W Do NOT export weakly defined functions, i.e.,
     weakly defined functions will NOT be available to
     modules load-time [exported]
  -X <symbol_name>
      Export the symbol <symbol_name> from this module.
      The -X option may be specified numerous times to
      specify multiple export symbols (up to 1024 times).
      Default behavior to export [all global functions].
  -Y <symbol_name>
      Do NOT export the symbol <symbol_name> from this module.
      module. The -Y option may be specified numerous times
      to specify multiple export symbols (up to 1024 times).
      Note: -Y cannot be specified with -X.
      Default behavior to export [all global functions].
  -d Use dynamic symbol table. [symtab]
  -f <cmd-filename>
      Take next commands from <cmd-filename> [cmd-line]
  -l <abbrev>
      Include shared library of name lib<abbrev>.so
      A maximum of 16 library abbreviations may be provided.
  -o <out-filename>
     Output to <out-filename> [stdout]
  -p <max_threads>
     The maximum number of threads that can make simultaneous
     make calls into a shared library [6]
  -t Enable tracing of outbound shared library function
     calls. [no tracing]
  -v Verbose output [no output]
  -w Import weakly declared functions, i.e., weakly
     declared functions are expected to be provided at
     load-time [not imported]
  -x <loader-pathname>
     This provides the full pathname of the xFLT loader
     that should be used to load this file. If this
     name is not present, the system will use a default
     loader pathname [default loader].

ldelf2xflt is a derivative of flat's ldelf2flt. It has been extended to "understand" the special logic and symbology of the special source file generated by ldelflib. Given a partially linked ELF file (one that includes the assembled source generated by ldelflib), this tool will generate an xFLT program or shared library, ready for execution on the target machine.

ldelf2xlft is managed by the wrapper, xflat-ld. You should not normally have to interact with it directly. If you type 'ldelf2xlft' you will get the current usage of for the tool. At present, this is:

Usage: ldelf2xflt [options] <bfd-filename>

Where options are one or more of the following.  Note
that a space is always required between the option and
any following arguments.

  -d Use dynamic symbol table [symtab]
  -e <entry-point>
     Entry point to module [_start for executable]
     NULL for shared library
  -l Build a shared library binary [executable]
  -o <out-filename>
     Output to <out-filename> [<bfd-filename>.xflt]
  -s <stack-size>
     Set stack size to <stack-size>.  Ignored if -l also
     selected. [4096]
  -v Verbose output [no verbose output]
     If -v is applied twice, additional debug output
     be enabled.

<<Table of Contents>>
<<Index>>