ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# CDDL HEADER START
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# The contents of this file are subject to the terms of the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# Common Development and Distribution License (the "License").
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# You may not use this file except in compliance with the License.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# See the License for the specific language governing permissions
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# and limitations under the License.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# When distributing Covered Code, include this CDDL HEADER in each
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# If applicable, add the following below this CDDL HEADER, with the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# fields enclosed by brackets "[]" replaced with your own identifying
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# information: Portions Copyright [yyyy] [name of copyright owner]
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# CDDL HEADER END
7e16fca05dfbcfd32c2ebc9e4d1abdac1cd8657cAli Bahrami# Copyright 2009 Sun Microsystems, Inc. All rights reserved.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab# Use is subject to license terms.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abNotes On Cross Link-Editor Support in libld.so
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe Solaris link-editor is used in two contexts:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 1) The standard ld command
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 2) Via the runtime linker (ld.so.1), when a program
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab calls dlopen() on a relocatable object (ET_REL).
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abTo support both uses, it is packaged as a sharable library (libld.so).
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe ld command is therefore a simple wrapper that uses libld.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibld.so is a cross linker. This means that it can link objects for
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aba system other than the system running the link-editor (e.g. A link-editor
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abrunning on an amd64 system processing sparc objects). This means that every
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abinstance of libld.so contains code for building objects for every supported
3ced7af1ee4d7b1d1a3766385fdb7527a2abda93abtarget. It is not necessary to build libld specifically for the
3ced7af1ee4d7b1d1a3766385fdb7527a2abda93abplatform you're targeting. This is possible because we only support
3ced7af1ee4d7b1d1a3766385fdb7527a2abda93abSolaris/ELF, with a small number of platforms, and the additional code
3ced7af1ee4d7b1d1a3766385fdb7527a2abda93abrequired per target is small.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abAt initialization, the caller of libld.so specifies the type of objects
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbeing linked. By default, the ld command determines the machine type and
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abclass of the object being generated from the first ELF object processed
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfrom the command line. The -64 and -ztarget options exists to change this
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdefault, which is useful when creating an object entirely from an archive
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibrary or a mapfile. During initialization, the link-editor configures
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abitself to build an output object of the specified type. This is done via
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abindirection, using the global ld_targ structure to access code, data, and
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abconstants for the specified target.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThere are two types of source files used to build libld.so:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 1) Common code used for all targets
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 2) Target specific code used only when linking for
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab a given target.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abAll of these files reside in usr/src/cmd/sgs/libld/common. However,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abit is easy to see which files belong in each category by examining
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe object lists maintained in usr/src/cmd/sgs/libld/Makefile.com.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIn addition, the target-specific files usually include the target
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abAlthough the target dependent and independent (common) code is well separated,
7e16fca05dfbcfd32c2ebc9e4d1abdac1cd8657cAli Bahramithey are interdependent. The common code is explicitly aware of
7e16fca05dfbcfd32c2ebc9e4d1abdac1cd8657cAli Bahramitarget-specific section types that can occur only for some targets
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab(i.e. SHT_AMD64_UNWIND). This is not an architecture that allows
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfor arbitrary target support to be dynamically plugged into an unchanged
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abplatform independent core. Rather, it is an organization that allows
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aba common core to support all the targets it knows about in a way that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abis understandable and maintainable. A truly pluggable architecture
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abwould be considerably more opaque and complex, and is neither necessary,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abnor desirable, given the wide commonality between modern computer
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abarchitectures.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIt is possible to add support for new targets to libld.so. The process
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abof doing so is largely a matter of examining the files for existing
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abplatforms, studying the ABI for the new target platform, and then
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfilling in the missing pieces for the new target. The remainder of this
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfile consists of sections that describe some of the issues and steps
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthat you will encounter in adding a new target.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe relocation code used by ld is shared by the runtime linker (ld.so.1)
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aband by the kernel module loader (ktrld), and is therefore found under
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abusr/src/uts. You must add code for a relocation engine to support the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abnew target. To do so, examine the common header files:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab and the existing relocation engines:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe ABI for the target platform will be the primary information
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abyou require. If your new system has attributes not found in an existing
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abtarget, you may have to add/modify fields in the Rel_entry struct typedef
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab(reloc_defs.h), or you may have to add new flags. Either sort of change
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abmay require you to also modify the existing relocation engines, and
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abundoubtedly the common code in libld.so as well.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abWhen compiled for use by libld, the relocation engine requires an
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abargument named "bswap". Each relocation engine must be prepared to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abswap the data bytes it is operating on. This support allows a link-editor
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abrunning on a platform with a different byte order than the target to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbuild objects for that target. To see how this is implemented, and how
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abto ifdef that support so it only exists in the libld version of
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe engine, examine the code for the existing engines.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abYou must create a target subdirectory in usr/src/cmd/sgs/include,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aband construct a machdep_XXX.h file (where XXX is the name of the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abtarget). The machdep files for the current platforms can be helpful:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abNote that these files support both the 32 and 64-bit versions of
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aba given platform, so there is only one subdirectory and machdep
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfile for each platform (i.e. "sparc", instead of "sparc" and "sparcv9").
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abOnce you have created the target machdep_XXX.h file, you must edit:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aband add a #include for your new file to it, surrounded by the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abappropriate #ifdef for the target platform.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThis two level structure allows us to #include machdep information
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abin two different ways:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 1) Code that wants support for the current platform,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab regardless of which platform that is, can include
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab usr/src/cmd/sgs/include/machdep.h. The runtime linker
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab (ld.so.1) is the primary consumer of this form.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 2) Code that needs to support multiple targets must never
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab include the generic machdep.h from (1) above. Instead,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab such code explicitly includes the machdep file for the target
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab it is interested in. For example:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab libld.so uses this form to build non-native target
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abYou will find that most of the constants defined in the target
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abmachdep file end up as initialization for the information that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibld.so accesses via the ld_targ global variable.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abStudy the definition of the Target typedef in
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThis is the type of the ld_targ global variable. Filling in a complete
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcopy of this definition is the primary task involved in adding support
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abfor a new target to libld.so, so it will be helpful to be familiar with
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abit before you dive deeper. libld follows two simple rules with regards
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abto ld_targ, and the Target type:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 1) The target-independent common code can only access
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab target-dependent code or data via the ld_targ global
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab 2) The target-dependent code can access the common
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab code or data freely.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abA given link-editor invocation is always for a single target. The choice
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abof target is made at initialization, and does not change within a
ba2be53024c0b999e74ba9adcd7d80fec5df8c57absingle link. Code for the other targets is present, but is not
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abFiles containing the target-specific code to support the new
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abplatform must be added to libld.so. Examine the object lists
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abin usr/src/cmd/sgs/libld/Makefile.com to see the files for existing
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abplatforms, and read those files to get a sense of what is required.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abAmong the other files, every platform will have a file named
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abmachrel.XXX.c. This file contains the relocation-related functions,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aband it also contains an init function for the target. This init function
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abis responsible for initializing the ld_targ global variable so that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe common code will use the code and definitions for your
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abYou should start by creating a machrel.XXX.c file for your new
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abtarget. Add other files as needed. Be aware that any functions or
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abvariables you place in these target-dependent files must either
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbe static, or must have names that will not collide with the names
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abused by the rest of libld.so. The easiest way to do this is to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abadd a target suffix to the end of all such non-local names
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab(i.e. foo_sparc() instead of foo()).
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe existing code is the documentation for this phase of things: The
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbest way to determine what a given function should do is to read the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcode for other platforms, taking into account the similarities and
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdifferences in the ABI for your new target and those existing ones.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abYou may find that your new target requires support for new concepts
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abnot found in other targets. A common example of this might be
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aba new target specific ELF section type (i.e. SHT_AMD64_UNWIND). Another
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abmight be details involving PIC code and PLT generation (as found for
ba2be53024c0b999e74ba9adcd7d80fec5df8c57absparc). It may be necessary to add new fields to the ld_targ global
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abvariable, and to modify the libld.so common code to use these new
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIt is a standard convention that NULL function pointers are used to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abrepresent functionality not required by a given target. Although the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcommon code can consult ld_targ.t_m.m_mach to determine the target it
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abis linking for, and although there is some code that does this, it
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abis generally undesirable and unnecessary. Instead, the common code
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abshould test for such pointers, as with this sparc-specific example
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab * Assign a got offset if necessary.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab if ((ld_targ.t_mr.mr_assign_got != NULL) &&
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab (*ld_targ.t_mr.mr_assign_got)(ofl, sdp) == S_ERROR)
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab return ((Addr)S_ERROR);
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIt may be tempting to include information in the comment that explains
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe target specific nature of this, and that may even be appropriate.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abConsider however, that a new target may come along with the same feature
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablater, and if that occurs, your comments will instantly be dated. In general,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe use of ld_targ is a strong hint to the reader that they should go read
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe target-specific code referenced to understand what is going on. It is
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbest to supply comments at the call site that describe the operation
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abin generic terms (i.e. "assign a got if necessary") instead of in
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abexplicit target terms (i.e. "Assign a sparc got if necessary"). Of
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcourse, some features are extremely target-specific (like amd64 unwind
ba2be53024c0b999e74ba9adcd7d80fec5df8c57absections), and it doesn't really help to be obscure in such cases.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThis is a judgement call.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIf you do add a new field to ld_targ that uses NULL to represent
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aban option feature *YOU MUST DOCUMENT IT AS SUCH*. You will find
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcomments in _libld.h for existing optional fields. It suffices to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abadd a comment for your new field. In the absence of such a comment,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe common code assumes that all function pointers are safe to call
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthrough (dereference) without first testing them.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abByte swapping is a big issue in cross linking, as the system running
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe link-editor may have the opposite byte order from the target. It is
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abimportant to know when, and when not, to swap bytes.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIf the build system and target have different byte orders, the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abFLG_OF1_ENCDIFF bit of the ofl_flags field of the output file
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdescriptor will be set. If this bit is not set, the target and
ba2be53024c0b999e74ba9adcd7d80fec5df8c57absystem byte orders are the same, and no byte swapping
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abis required.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibld uses libelf to read and write objects. libelf automatically
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abswaps bytes for the sections it knows about, such as symbol tables,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abrelocation records, and the usual ELF plumbing. It is therefore never
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abnecessary for your code to swap the bytes in this data. If you find that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthis is not the case, you have probably uncovered a bug in libelf that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abyou should look into.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe big exception to libelf transparently handling byte swapping is
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abprogbits sections (SHT_PROGBITS). libelf does not understand program
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcode or data as anything other than a series of byte values, and as such,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcannot do byte swapping for them. If your code examines or modifies
ba2be53024c0b999e74ba9adcd7d80fec5df8c57absuch data, you are responsible for handling the byte swapping required.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe OFL_SWAP_RELOC macros found in _libld.h can be helpful in making such
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdeterminations. You should use these macros instead of writing your own
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abtests for this, as they have high documentation value. If you find they
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdon't handle your target, add a new one that does.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abGOT and PLT sections are SHT_PROGBITS. You will probably find
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthat the vast majority of byte swapping you have to handle
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abconcern the handling of these items.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibld contains generic functions for byte swapping:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab ld_bswap_Word();
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab ld_bswap_Xword();
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThese functions are built on top of the of the BSWAP_ macros found
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab BSWAP_HALF
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab BSWAP_WORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab BSWAP_XWORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abWhen copying data from one address to another in a cross link environment,
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe source and/or destination addresses may not have adequate alignment for
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe data type being copied. For example, a sparc platform cannot access
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab8-byte data types on 4-byte boundaries, but it might need to do so when
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablinking X86 objects where the alignment of such data can be 4. The
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abUL_ASSIGN macros can be used to copy potentially unaligned data:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_HALF
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_WORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_XWORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe UL_ASSIGN_BSWAP macros do unaligned copies, and also perform
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbyte swapping when the linker host and target byte orders are
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_BSWAP_HALF
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_BSWAP_WORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab UL_ASSIGN_BSWAP_XWORD
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abIf you are reading/writing to relocation data, the following
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abroutines understand relocation records and will get/set the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abproper amount of data while handling any needed swapping:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab ld_reloc_targval_get()
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab ld_reloc_targval_set()
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abByte swapping is a fertile area for mistakes. If you're having trouble
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abgetting a successful link in a cross link situation, you should always
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdo the experiment of doing the link on a platform with the same byte
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aborder as the target. If that link succeeds, then you are looking at
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aba bug involving incorrect byte swapping.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab As mentioned above, incorrect byte swapping is a common
ba2be53024c0b999e74ba9adcd7d80fec5df8c57aberror when developing libld target specific code. In addition to
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abtrying a build machine with the same byte order as the target, elfdump
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcan also be a powerful tool for debugging. The first step with
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abelfdump is to simply dump everything and read it looking for obviously
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abbad information:
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab % elfdump outobj 2>&1 | more
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abelfdump tries to do sanity checking on the objects it
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abdisplays. Hence, the following command is a a common
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab % elfdump outobj > /dev/null
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abAny problems with the file that elfdump can detect will be
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abwritten to stderr.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abOnce you have the target-specific code in place, you must modify the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablibld initialization code so that it will know how to use it. This
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ablogic is found in
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abin the function ld_init_target().
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe ld front end program that uses libld must be modified so that
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abthe "-z target=platform" command line option recognizes your
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abnew target. This code is found in
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abThe change consists of adding an additional strcasecmp() to the
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abcommand line processing for -ztarget.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57ab-----------------------------------------------------------------------------
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abYou probably changed things getting your target integrated.
ba2be53024c0b999e74ba9adcd7d80fec5df8c57abPlease update this document to reflect your changes.