From 6f3e5177f48489ba57bc626b2b833483e4572245 Mon Sep 17 00:00:00 2001 From: Nick Clifton Date: Wed, 9 Dec 2009 12:19:45 +0000 Subject: [PATCH] Add binutils porting guide. --- binutils-porting-guide.txt | 521 +++++++++++++++++++++++++++++++++++++ index.html | 3 + 2 files changed, 524 insertions(+) create mode 100644 binutils-porting-guide.txt diff --git a/binutils-porting-guide.txt b/binutils-porting-guide.txt new file mode 100644 index 00000000..9249d28a --- /dev/null +++ b/binutils-porting-guide.txt @@ -0,0 +1,521 @@ +####################################################################### +# Copyright (c) 2009 Free Software Foundation, Inc. +# Written by MR.Swami.Reddy@nsc.com + +# Permission is granted to copy, distribute and/or modify this document +# under the terms of the GNU Free Documentation License, Version 1.3 or +# any later version published by the Free Software Foundation; with no +# Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +# Texts. A copy of the license is included in the section entitled. +# GNU Free Documentation License. +####################################################################### + +*************************************************************** +* Title : Binutils Porting Guide To A New Target Architecture +* Created : 22 Sep 2009 +* Modified: 03 Nov 2009->01 Dec 2009 +* Version: 1.1 +* 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-.c +in the bfd directory. + +The file -.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. -opc.c and -opc.h (header files are optional) + 2. -dis.c and -dis.h (header files are optional) + +The -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-.c + tc-.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/.sc define the default linker script +file for the architecture. + +In emulparams/.em define the default emulation script +file. This contains any functions necessary to customise the +behaviour of the linker. + +In emulparams/.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. +----------------------------------------------------------------------------- +============================================================================ +Activity Log (latest on top): +---------------------------------------------------------------------------- + Date Doc version Description +---------------------------------------------------------------------------- +01 Dec 2009 1.1 Included GPL copyrights info and added the + activity base log information. + +03 Nov 2009 1.0 Submitted for review on binutils mailing list. +---------------------------------------------------------------------------- + + + diff --git a/index.html b/index.html index 7cb9d3a8..87d2bb6b 100644 --- a/index.html +++ b/index.html @@ -176,6 +176,9 @@

The documentation for binutils 2.20 is available.

+

A guide to porting the binutils to a new target has been + contributed.

+

Return to GNU's home -- 2.43.5