This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

doc - binutils porting guide to a new target


Hello All,

Please find the attached doc on binutils porting guide to a new processor/target and
its intended (only) for the people, who want to port the binutils to a new target at first time.


Comments/suggestions are welcome.

Aim of this doc is to help the people on porting the Binutils for their target.

Thanks
Swami

***************************************************************
* Title   : Binutils Porting Guide To A New Target Architecture
* Created : 22 Sep 2009
* Modified: 03 Nov 2009
* Version:  1.0
* Contact : MR.Swami.Reddy@nsc.com
***************************************************************

Binutils Porting Guide To A New Target/Processor Architecture:
-------------------------------------------------------------

1. To whom this guide is useful (Who are the intended readers)
    1.1. Rationale
    1.2. Target Audience
    1.3. Further Sources of Information

2. Introduction to binutils
   2.1. Binutils File Organization structure:
   2.2. Main Functional Areas and Data Structures
        2.2.1 Binary File Description (BFD)
        2.2.2 Opcodes
        2.2.3 Include
        2.2.4 Binutils
        2.2.5 Gas
        2.2.6 ld

3. Build and test
   3.1 Build binutils tools
   3.2 Test binutils tools

4. Documentation

5. About the author
================================================================================

Chapter 1. Introduction

This document complements the existing documentation for binutils.  It
is intended to help software engineers who want to port the binutils
tools to a new hardware architecture for first time.

This document is based on the author's experience to date.  It will be
updated in future issues.  Suggestions for improvements are always
welcome.


1.1. Rationale

Although the binutils project includes a 100 page guide to its
internals, this document is aimed primarily at those wishing to
develop/port binutils itself at the first time.  The document also
suffers from below limitations.

1. It tends to document at a detailed level.  Individual functions are
   described well, but it is hard to get the big picture.

2. It is incomplete.  Many of the most useful sections (for example
   details of final relocation info) are yet to be written.

Consequently the engineer faced with their first port of binutils to a
new architecture is faced with discovering how binutils works by
reading the source code and looking at how other architectures have
been ported.

The author of this document went through that process when porting the
Compact-RISC (aka CR16) architecture to binutils.  This document
captures the learning experience, with the intention of helping
others, specially, who are looking for porting binutils tools to a new
target.


1.2. Target Audience

If you are about to start a port of Binutils tools to a new
architecture, this document is for you.  If at the end of your
endeavours you are better informed, please help by adding to this
document.

If you have already been through the porting process, please help
others by adding or updating to this document.


1.3. Further Sources of Information

Chapter 1.3.1. Written Documentation
The main user guides for the binutils tools provide a great deal of
context about how they are intended to work.

The binutils Internals document is essential reading before and during
any porting exercise.  It is not complete, nor is it always up to
date, but it provides the first place to look for explanation of what
a particular function does.

The binutils tools rely upon a separate specification of the Binary
File Descriptor for each architecture.  This has its own comprehensive
user guide.

The main Binutils tools code base is generally well commented,
particularly in the headers for the major interfaces.  Inevitably this
must be the definitive place to find out exactly how a particular
function is expected to behave.

1.3.2. Other Information Channels

The main Binutils tools website is at http://sourceware.org/binutils/.

The binutils developer community communicate through the binutils
mailing lists.  These are always good places to find solutions to
problems.

The main mailing list for discussion is: binutils@sourceware.org,
although for detailed understanding reading the bug reporting mailing
list: bug-binutils@sourceware.org is also recommended.  See the main
binutils website for details of subscribing to these mailing lists.

================================================================================

2.1. Binutils File Organization structure:

The bulk of the binutils source code is in a small number of
directories.  Some components of binutils are libraries which are used
internally as well as in other projects.  For example the BFD library
is used in GNU GDB debugger.  These libraries have their own top level
directories.  The main directories are:

                         binutils
			    |
			    |
    ----------------------------------------------------------
   |       |     |       |      |       |   |     |     |     |
   |       |     |       |      |       |   |     |     |     |
 include  bfd  opcodes  cpu  binutils  gas  ld  gprof  gold  elfcpp


Here is some brief information on the above directories:

 - include:
   Header files for information which straddles major components.
   For example the main simulator interface header is here
   (remote-sim.h), because it links GDB (in directory gdb) to the
   simulators (in directory sim).  Other headers, specific to a
   particular component reside in the directory of that component.

 - bfd:
   The Binary File Descriptor library.  This library contains code to
   handle specific binary file formats, such as ELF, COFF, SREC and so
   on.  If a new object file type must be recognized, code to support
   it should be added here.

 - opcodes:
   The opcodes library.  This contains information on how to assemble
   and disassemble instructions.  

 - cpu:
   Source files for a utility called CGEN.  This is a tool which can
   be used to automatically generated target specific source files for
   the opcodes library as well as for the SIM simulator used by GDB.
   
 - binutils: 
   Despite its name this is not the main binutils directory.  Rather
   it is the directory for all of the binutils tools which do not have
   their own top level source directory.  This includes tools such as
   objcopy, objdump and readelf amongst others.

 - gas: 
   The GNU assembler.  Target specific assembler code is held in the
   config sub-directory.

 - ld:
   The GNU linker.  Target specific linker files are held in
   sub-directories.

 - gprof:
   The GNU profiler.  This program does not have any target specific
   code.

 - gold:
   The new GNU linker.  This is a new linker being created to replace
   LD.  At the moment it is still in development.

 - elfccp:
   Elfcpp is a C++ library for reading and writing ELF information.
   It is currently only used by the GOLD linker.

In addition there are a couple of other directories which can be found
at the top level of a binutils source release.  They are used in the
binutils build process, but they are not part of the binutils project:
   
 - intl: 
   GNU gettext library from gettext.
   
 - libiberty: 
   Before POSIX and glibc, this was a GNU project to provide a set 
   of standard functions. It lives on in binutils.  Most valuable are
   its free store management and argument parsing functions.


2.2. Main Functional Areas and Data Structures

2.2.1. Binary File Description (BFD)

BFD is a package which allows applications to use the same routines to
operate on object files whatever the object file format.  A new object
file format can be supported simply by creating a new BFD back end and
adding it to the library.

The BFD library back end creates a number of data structures
describing the data held in a particular type of object file.
Ultimately a unique enumerated constant (of type enum
bfd_architecture) is defined for each individual architecture.  This
constant is then used to access the various data structures associated
with that particular architecture.

In the case of the Compact-RISC, 16-bit implementation (which may be a
COFF or ELF binary), the enumerated constant is bfd_cr16_arch.  This
can be used to access various structures, for example:

  const bfd_arch_info_type bfd_cr16_arch =
    {
      16,               /* 16 bits in a word.  */
      32,               /* 32 bits in an address.  */
       8,               /*  8 bits in a byte.  */
      bfd_arch_cr16,    /* enum bfd_architecture arch.  */
      bfd_mach_cr16,    /* Machine value, used to distinguish between cr16 variants.  */
      "cr16",           /* Architecture name (short version).  */
      "cr16",           /* Architecture name (long version).  */
      1,                /* Section alignment power.  */
      TRUE,             /* True if this is the default machine for the architecture.  */
      bfd_default_compatible, /* Function to call to determine if two different architectures are compatible.  */
      bfd_default_scan, /* Function to call to determine if a given string matches this architecture.  */ 
      NULL,             /* Pointer to the next CR16 machine architecture.  */
    };

This particular structure is defined in a file called cpu-<target>.c
in the bfd directory.

The file <file_format>-<target>.c (eg: elf32-cr16.c) is used to
provide target specific support for the given file format and
architecture.  At the very least it provides the following
information:

1. A reloc_map array which maps BFD relocation enumerations into a
   target specific relocation type

2. A reloc_howto_type array with target specific relocations details.
   Here is an example array entry from the cr16 port:
   
  (R_CR16_NONE,              /* Type.  */
   0,                        /* Rightshift.  */
   2,                        /* Size.  */
   32,                       /* Bitsize.  */
   FALSE,                    /* PC_relative */
   0,                        /* Bitpos */
   complain_overflow_dont,   /* Complain_on_overflow */
   bfd_elf_generic_reloc,    /* Special_function */
   "R_CR16_NONE",            /* Name */
   FALSE,                    /* Partial_inplace */
   0,                        /* Src_mask */
   0,                        /* Dst_mask */
   FALSE),                   /* PCREL_offset */


3. Define the macros below with settings specific to the target:

#define TARGET_LITTLE_SYM 
#define TARGET_LITTLE_NAME

#define ELF_ARCH         
#define ELF_MACHINE_CODE 
#define ELF_MAXPAGESIZE  
#define elf_symbol_leading_char 

#define elf_info_to_howto              
#define elf_info_to_howto_rel         

#define elf_backend_relocate_section 
#define elf_backend_gc_mark_hook 
#define elf_backend_gc_sweep_hook 
#define elf_backend_can_gc_sections  
#define elf_backend_rela_normal     
#define elf_backend_check_relocs   
#define elf_backend_final_write_processing
#define elf_backend_object_p 
#define elf_backend_create_dynamic_sections
#define elf_backend_adjust_dynamic_symbol 
#define elf_backend_size_dynamic_sections 
#define elf_backend_omit_section_dynsym 
#define elf_backend_finish_dynamic_sections 
#define elf_backend_reloc_type_class  
#define elf_backend_want_got_plt     
#define elf_backend_plt_readonly    
#define elf_backend_want_plt_sym   
#define elf_backend_got_header_size 

#define bfd_elf32_bfd_reloc_type_lookup 
#define bfd_elf32_bfd_reloc_name_lookup 
#define bfd_elf32_bfd_relax_section 
#define bfd_elf32_bfd_get_relocated_section_contents 
#define bfd_elf32_bfd_merge_private_bfd_data
#define bfd_elf32_bfd_link_hash_table_create 
#define bfd_elf32_bfd_link_hash_table_free 


In addition the files archures.c, config.bfd, Makefile.am and target.c
in the bfd directory should be updated with any necessary target specific
changes.


2.2.2  Opcodes:

The opcodes directory should have at least 2 target specific files.
One for assembling the target instructions and other for
dis-assembling them.  The file names are:

 1. <target>-opc.c and <target>-opc.h (header files are optional)
 2. <target>-dis.c and <target>-dis.h (header files are optional)

The <target>-dis.c files includes code to print disassembled
instructions and also code for matching opcodes and operands
appropriately.

The configure.in, disassemble.c and Makefile,am files in the opcodes
directory also need to have targets specific changes made to them.


2.2.3 Include:

The include directory contains target specific header files, usually
in a file format specific sub-directory.  Opcode information is
normally held in a target specific file in the opcode sub-directory.
For example:

  include/elf/cr16.h
  include/opcode/cr16.h


2.2.4 Binutils:

This directory doesn't require any new target specific files.  But the
configure.tgt, Makefile.am an readelf.c files should be updated with
any target specific information needed.


2.2.5 Gas:

The gas/config sub-directory contains the target specific files for
the assembler.  The file names are:

        tc-<target>.c
	tc-<target>.h.

The above file should include:

	 - Sizes of(ie macros defines):
	      - Registers
	      - Instructions (ie maximum size)
              - Operands
	 - Operand error types		
         - Comment character used in assembly code.
         - Comment character used in assembly code line.
	 - Line separator

         - Defining the target specific
	      - multi-character options, if any.
	      - Process machine-dependent command line options in 
	        "md_parse_option" function.
              - Include Machine-dependent usage-output in 
	        "md_show_usage" function.

	 - Redefine the assemble directive using "md_pseudo_table".
         - Functions for getting registers along with type, size,
	   and other information.
	 - md_begin function used to initialize/set-up all the tables, etc 
	   that are machine-dependent items of the assembler.
	 - Parse functions:
	     - parse_insn
	     - parse_operands
	     - parse_operand
	 - Print functions:
	     - print_insn
	     - print_operand
	     - print_operands
	 - Print functions:
	 - Function to assemble a single instruction "assemble_insn"
	 - md_assemble is the first function called to assemble instruction.


In the gas directory itself the configure.tgt and Makefile.am files
need to be modified to refer to the new files and to add support for
the new target.	 


2.2.6 ld:
In scripttempl/<format><target>.sc define the default linker script
file for the architecture.

In emulparams/<target><format>.em define the default emulation script
file.  This contains any functions necessary to customise the
behaviour of the linker.

In emulparams/<format><target>.sh define any parameters that can be
used to modify the default linker script file.


In the ld directory itself the configure.tgt file needs to be updated
to add your new target information and the Makefile.am with new target
information build rules.
  

Chapter 3. Build and test

3.1 Build binutils tools
Building binutils tools requires below steps as below:

   - Configure:
     Run configure script with target and prefix options.  For ex:
   
      > src/configure --target=cr16-elf --prefix=/local/cr16-bintuils
        Here, target -> target you want to build the binutils tools.
	      prefix -> Built binutils tools installation location/directory.

   - Build:
     Run "make" to build the binutils tools for the above configured target.  
     For ex:
      > make all
      > make install
          or
      > make all install

   NOTE: With "make" -jN option shall used to build the tools quickly 
         by using all processors/CPUs on you host PC. For example, 
	 if your host PC has 4 procesors, then "make -j4" could be 
	 used for quick build. 

3.2 Test binutils tools

To test above built tools using the binutils test suites like gas, 
binutls and ld test suites.  Running the binutils testsuite requires 
that the DejaGNU package (http://www.gnu.org/software/dejagnu/) required 
and the DEJAGNU environment variable need to be set.  The tests can 
then be run with:

     > make check

The above command runs the binutils, gas and linker testsuites.
   
With the commands below the user can run the binutils, gas and linker
testsuites separately:

   > make check-binutils   
   > make check-gas
   > make check-ld

On completion of the binutils test run, a summary of the results will
be in the binutils directory in the binutils.sum file.  More detailed
information will also be available in the binutils/binutils.log file.
For the gas testsuite the results are in the gas/testsuite/gas.sum and
gas/testsuite/gas.log files and for the linker testsuite they are in
the ld/ld.sum and ld/ld.log files.

For the most comprehensive tests in an environment where host and
target differ, DejaGNU needs some additional configuration.  This can
be achieved by setting the DEJAGNU environment variable to refer to a
suitable configuration file, and defining a custom board configuration
file in the directory ~/boards.  These configuration files can be used
to specify a suitable simulator and how to connect it when running
tests.


Chapter 4. Documentation

Some of binutils sub-directories in turn have doc sub-directories.  The
documentation is written in texinfo, from which documents can be
generated as PDF, PostScript, HTML or info files.  The documentation is
not built automatically with make all, nor with make doc.  To create
documentation, change to the individual documentation directory and
use make HTML, make PDF, make ps or make info as required.  The main
documents of interest are:

   . bfd/doc/bfd.texinfo         This is the BFD manual.
   . binutils/doc/binutils.texi  This is the main Binutils user guide.
   . ld/ld.texinfo               This is the linker user guide. 
   . gas/doc/as.texinfo          This is the assembler user guide.

The exception to automatic building is with make install. This will
build info files for any documents in the binutils/doc directory and
install them in the info sub-directory of the install directory.


Chapter 5. About author:
Author of this article has experience with GNU tools porting to
different  RISC/DSP processors and currently maintainer for National
semiconductors 32-bit and 16-bit processor of Binutils and GDB
simulator ports. Contact  e-mail id: MR.Swami.Reddy@nsc.com for
further comments/suggestions.
-------------------------------------------------------------------------------

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]