1ba2be530Sab# 2ba2be530Sab# CDDL HEADER START 3ba2be530Sab# 4ba2be530Sab# The contents of this file are subject to the terms of the 5ba2be530Sab# Common Development and Distribution License (the "License"). 6ba2be530Sab# You may not use this file except in compliance with the License. 7ba2be530Sab# 8ba2be530Sab# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9ba2be530Sab# or http://www.opensolaris.org/os/licensing. 10ba2be530Sab# See the License for the specific language governing permissions 11ba2be530Sab# and limitations under the License. 12ba2be530Sab# 13ba2be530Sab# When distributing Covered Code, include this CDDL HEADER in each 14ba2be530Sab# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15ba2be530Sab# If applicable, add the following below this CDDL HEADER, with the 16ba2be530Sab# fields enclosed by brackets "[]" replaced with your own identifying 17ba2be530Sab# information: Portions Copyright [yyyy] [name of copyright owner] 18ba2be530Sab# 19ba2be530Sab# CDDL HEADER END 20ba2be530Sab# 21ba2be530Sab 22ba2be530Sab# 23*7e16fca0SAli Bahrami# Copyright 2009 Sun Microsystems, Inc. All rights reserved. 24ba2be530Sab# Use is subject to license terms. 25ba2be530Sab# 26ba2be530Sab 27ba2be530Sab 28ba2be530Sab 29ba2be530Sab 30ba2be530SabNotes On Cross Link-Editor Support in libld.so 31ba2be530Sab----------------------------------------- 32ba2be530Sab 33ba2be530SabThe Solaris link-editor is used in two contexts: 34ba2be530Sab 35ba2be530Sab 1) The standard ld command 36ba2be530Sab 2) Via the runtime linker (ld.so.1), when a program 37ba2be530Sab calls dlopen() on a relocatable object (ET_REL). 38ba2be530Sab 39ba2be530SabTo support both uses, it is packaged as a sharable library (libld.so). 40ba2be530SabThe ld command is therefore a simple wrapper that uses libld. 41ba2be530Sab 42ba2be530Sablibld.so is a cross linker. This means that it can link objects for 43ba2be530Saba system other than the system running the link-editor (e.g. A link-editor 44ba2be530Sabrunning on an amd64 system processing sparc objects). This means that every 45ba2be530Sabinstance of libld.so contains code for building objects for every supported 463ced7af1Sabtarget. It is not necessary to build libld specifically for the 473ced7af1Sabplatform you're targeting. This is possible because we only support 483ced7af1SabSolaris/ELF, with a small number of platforms, and the additional code 493ced7af1Sabrequired per target is small. 50ba2be530Sab 51ba2be530SabAt initialization, the caller of libld.so specifies the type of objects 52ba2be530Sabbeing linked. By default, the ld command determines the machine type and 53ba2be530Sabclass of the object being generated from the first ELF object processed 54ba2be530Sabfrom the command line. The -64 and -ztarget options exists to change this 55ba2be530Sabdefault, which is useful when creating an object entirely from an archive 56ba2be530Sablibrary or a mapfile. During initialization, the link-editor configures 57ba2be530Sabitself to build an output object of the specified type. This is done via 58ba2be530Sabindirection, using the global ld_targ structure to access code, data, and 59ba2be530Sabconstants for the specified target. 60ba2be530Sab 61ba2be530SabThere are two types of source files used to build libld.so: 62ba2be530Sab 63ba2be530Sab 1) Common code used for all targets 64ba2be530Sab 2) Target specific code used only when linking for 65ba2be530Sab a given target. 66ba2be530Sab 67ba2be530SabAll of these files reside in usr/src/cmd/sgs/libld/common. However, 68ba2be530Sabit is easy to see which files belong in each category by examining 69ba2be530Sabthe object lists maintained in usr/src/cmd/sgs/libld/Makefile.com. 70ba2be530SabIn addition, the target-specific files usually include the target 71ba2be530Sabin their name (i.e. machrel.sparc.c). 72ba2be530Sab 73ba2be530SabAlthough the target dependent and independent (common) code is well separated, 74*7e16fca0SAli Bahramithey are interdependent. The common code is explicitly aware of 75*7e16fca0SAli Bahramitarget-specific section types that can occur only for some targets 76ba2be530Sab(i.e. SHT_AMD64_UNWIND). This is not an architecture that allows 77ba2be530Sabfor arbitrary target support to be dynamically plugged into an unchanged 78ba2be530Sabplatform independent core. Rather, it is an organization that allows 79ba2be530Saba common core to support all the targets it knows about in a way that 80ba2be530Sabis understandable and maintainable. A truly pluggable architecture 81ba2be530Sabwould be considerably more opaque and complex, and is neither necessary, 82ba2be530Sabnor desirable, given the wide commonality between modern computer 83ba2be530Sabarchitectures. 84ba2be530Sab 85ba2be530SabIt is possible to add support for new targets to libld.so. The process 86ba2be530Sabof doing so is largely a matter of examining the files for existing 87ba2be530Sabplatforms, studying the ABI for the new target platform, and then 88ba2be530Sabfilling in the missing pieces for the new target. The remainder of this 89ba2be530Sabfile consists of sections that describe some of the issues and steps 90ba2be530Sabthat you will encounter in adding a new target. 91ba2be530Sab 92ba2be530Sab----------------------------------------------------------------------------- 93ba2be530SabThe relocation code used by ld is shared by the runtime linker (ld.so.1) 94ba2be530Saband by the kernel module loader (ktrld), and is therefore found under 95ba2be530Sabusr/src/uts. You must add code for a relocation engine to support the 96ba2be530Sabnew target. To do so, examine the common header files: 97ba2be530Sab 98ba2be530Sab usr/src/uts/common/krtld/reloc.h 99ba2be530Sab usr/src/uts/common/krtld/reloc_defs.h 100ba2be530Sab 101ba2be530Sab and the existing relocation engines: 102ba2be530Sab 103ba2be530Sab usr/src/uts/intel/amd64/krtld/doreloc.c 104ba2be530Sab usr/src/uts/intel/ia32/krtld/doreloc.c 105ba2be530Sab usr/src/uts/sparc/krtld/doreloc.c 106ba2be530Sab 107ba2be530SabThe ABI for the target platform will be the primary information 108ba2be530Sabyou require. If your new system has attributes not found in an existing 109ba2be530Sabtarget, you may have to add/modify fields in the Rel_entry struct typedef 110ba2be530Sab(reloc_defs.h), or you may have to add new flags. Either sort of change 111ba2be530Sabmay require you to also modify the existing relocation engines, and 112ba2be530Sabundoubtedly the common code in libld.so as well. 113ba2be530Sab 114ba2be530SabWhen compiled for use by libld, the relocation engine requires an 115ba2be530Sabargument named "bswap". Each relocation engine must be prepared to 116ba2be530Sabswap the data bytes it is operating on. This support allows a link-editor 117ba2be530Sabrunning on a platform with a different byte order than the target to 118ba2be530Sabbuild objects for that target. To see how this is implemented, and how 119ba2be530Sabto ifdef that support so it only exists in the libld version of 120ba2be530Sabthe engine, examine the code for the existing engines. 121ba2be530Sab 122ba2be530Sab----------------------------------------------------------------------------- 123ba2be530SabYou must create a target subdirectory in usr/src/cmd/sgs/include, 124ba2be530Saband construct a machdep_XXX.h file (where XXX is the name of the 125ba2be530Sabtarget). The machdep files for the current platforms can be helpful: 126ba2be530Sab 127ba2be530Sab usr/src/cmd/sgs/include/sparc/machdep_sparc.h 128ba2be530Sab usr/src/cmd/sgs/include/i386/machdep_x86.h 129ba2be530Sab 130ba2be530SabNote that these files support both the 32 and 64-bit versions of 131ba2be530Saba given platform, so there is only one subdirectory and machdep 132ba2be530Sabfile for each platform (i.e. "sparc", instead of "sparc" and "sparcv9"). 133ba2be530Sab 134ba2be530SabOnce you have created the target machdep_XXX.h file, you must edit: 135ba2be530Sab 136ba2be530Sab usr/src/cmd/sgs/include/machdep.h 137ba2be530Sab 138ba2be530Saband add a #include for your new file to it, surrounded by the 139ba2be530Sabappropriate #ifdef for the target platform. 140ba2be530Sab 141ba2be530SabThis two level structure allows us to #include machdep information 142ba2be530Sabin two different ways: 143ba2be530Sab 144ba2be530Sab 1) Code that wants support for the current platform, 145ba2be530Sab regardless of which platform that is, can include 146ba2be530Sab usr/src/cmd/sgs/include/machdep.h. The runtime linker 147ba2be530Sab (ld.so.1) is the primary consumer of this form. 148ba2be530Sab 149ba2be530Sab 2) Code that needs to support multiple targets must never 150ba2be530Sab include the generic machdep.h from (1) above. Instead, 151ba2be530Sab such code explicitly includes the machdep file for the target 152ba2be530Sab it is interested in. For example: 153ba2be530Sab 154ba2be530Sab #include <sparc/machdep_sparc.h> 155ba2be530Sab 156ba2be530Sab libld.so uses this form to build non-native target 157ba2be530Sab code. 158ba2be530Sab 159ba2be530SabYou will find that most of the constants defined in the target 160ba2be530Sabmachdep file end up as initialization for the information that 161ba2be530Sablibld.so accesses via the ld_targ global variable. 162ba2be530Sab 163ba2be530Sab----------------------------------------------------------------------------- 164ba2be530SabStudy the definition of the Target typedef in 165ba2be530Sab 166ba2be530Sab usr/src/cmd/sgs/libld/common/_libld.h 167ba2be530Sab 168ba2be530SabThis is the type of the ld_targ global variable. Filling in a complete 169ba2be530Sabcopy of this definition is the primary task involved in adding support 170ba2be530Sabfor a new target to libld.so, so it will be helpful to be familiar with 171ba2be530Sabit before you dive deeper. libld follows two simple rules with regards 172ba2be530Sabto ld_targ, and the Target type: 173ba2be530Sab 174ba2be530Sab 1) The target-independent common code can only access 175ba2be530Sab target-dependent code or data via the ld_targ global 176ba2be530Sab variable. 177ba2be530Sab 178ba2be530Sab 2) The target-dependent code can access the common 179ba2be530Sab code or data freely. 180ba2be530Sab 181ba2be530SabA given link-editor invocation is always for a single target. The choice 182ba2be530Sabof target is made at initialization, and does not change within a 183ba2be530Sabsingle link. Code for the other targets is present, but is not 184ba2be530Sabaccessed. 185ba2be530Sab 186ba2be530Sab----------------------------------------------------------------------------- 187ba2be530SabFiles containing the target-specific code to support the new 188ba2be530Sabplatform must be added to libld.so. Examine the object lists 189ba2be530Sabin usr/src/cmd/sgs/libld/Makefile.com to see the files for existing 190ba2be530Sabplatforms, and read those files to get a sense of what is required. 191ba2be530Sab 192ba2be530SabAmong the other files, every platform will have a file named 193ba2be530Sabmachrel.XXX.c. This file contains the relocation-related functions, 194ba2be530Saband it also contains an init function for the target. This init function 195ba2be530Sabis responsible for initializing the ld_targ global variable so that 196ba2be530Sabthe common code will use the code and definitions for your 197ba2be530Sabtarget. 198ba2be530Sab 199ba2be530SabYou should start by creating a machrel.XXX.c file for your new 200ba2be530Sabtarget. Add other files as needed. Be aware that any functions or 201ba2be530Sabvariables you place in these target-dependent files must either 202ba2be530Sabbe static, or must have names that will not collide with the names 203ba2be530Sabused by the rest of libld.so. The easiest way to do this is to 204ba2be530Sabadd a target suffix to the end of all such non-local names 205ba2be530Sab(i.e. foo_sparc() instead of foo()). 206ba2be530Sab 207ba2be530SabThe existing code is the documentation for this phase of things: The 208ba2be530Sabbest way to determine what a given function should do is to read the 209ba2be530Sabcode for other platforms, taking into account the similarities and 210ba2be530Sabdifferences in the ABI for your new target and those existing ones. 211ba2be530Sab 212ba2be530Sab----------------------------------------------------------------------------- 213ba2be530SabYou may find that your new target requires support for new concepts 214ba2be530Sabnot found in other targets. A common example of this might be 215ba2be530Saba new target specific ELF section type (i.e. SHT_AMD64_UNWIND). Another 216ba2be530Sabmight be details involving PIC code and PLT generation (as found for 217ba2be530Sabsparc). It may be necessary to add new fields to the ld_targ global 218ba2be530Sabvariable, and to modify the libld.so common code to use these new 219ba2be530Sabfields. 220ba2be530Sab 221ba2be530SabIt is a standard convention that NULL function pointers are used to 222ba2be530Sabrepresent functionality not required by a given target. Although the 223ba2be530Sabcommon code can consult ld_targ.t_m.m_mach to determine the target it 224ba2be530Sabis linking for, and although there is some code that does this, it 225ba2be530Sabis generally undesirable and unnecessary. Instead, the common code 226ba2be530Sabshould test for such pointers, as with this sparc-specific example 227ba2be530Sabfrom update.c: 228ba2be530Sab 229ba2be530Sab /* 230ba2be530Sab * Assign a got offset if necessary. 231ba2be530Sab */ 232ba2be530Sab if ((ld_targ.t_mr.mr_assign_got != NULL) && 233ba2be530Sab (*ld_targ.t_mr.mr_assign_got)(ofl, sdp) == S_ERROR) 234ba2be530Sab return ((Addr)S_ERROR); 235ba2be530Sab 236ba2be530SabIt may be tempting to include information in the comment that explains 237ba2be530Sabthe target specific nature of this, and that may even be appropriate. 238ba2be530SabConsider however, that a new target may come along with the same feature 239ba2be530Sablater, and if that occurs, your comments will instantly be dated. In general, 240ba2be530Sabthe use of ld_targ is a strong hint to the reader that they should go read 241ba2be530Sabthe target-specific code referenced to understand what is going on. It is 242ba2be530Sabbest to supply comments at the call site that describe the operation 243ba2be530Sabin generic terms (i.e. "assign a got if necessary") instead of in 244ba2be530Sabexplicit target terms (i.e. "Assign a sparc got if necessary"). Of 245ba2be530Sabcourse, some features are extremely target-specific (like amd64 unwind 246ba2be530Sabsections), and it doesn't really help to be obscure in such cases. 247ba2be530SabThis is a judgement call. 248ba2be530Sab 249ba2be530SabIf you do add a new field to ld_targ that uses NULL to represent 250ba2be530Saban option feature *YOU MUST DOCUMENT IT AS SUCH*. You will find 251ba2be530Sabcomments in _libld.h for existing optional fields. It suffices to 252ba2be530Sabadd a comment for your new field. In the absence of such a comment, 253ba2be530Sabthe common code assumes that all function pointers are safe to call 254ba2be530Sabthrough (dereference) without first testing them. 255ba2be530Sab 256ba2be530Sab----------------------------------------------------------------------------- 257ba2be530SabByte swapping is a big issue in cross linking, as the system running 258ba2be530Sabthe link-editor may have the opposite byte order from the target. It is 259ba2be530Sabimportant to know when, and when not, to swap bytes. 260ba2be530Sab 261ba2be530SabIf the build system and target have different byte orders, the 262ba2be530SabFLG_OF1_ENCDIFF bit of the ofl_flags field of the output file 263ba2be530Sabdescriptor will be set. If this bit is not set, the target and 264ba2be530Sabsystem byte orders are the same, and no byte swapping 265ba2be530Sabis required. 266ba2be530Sab 267ba2be530Sablibld uses libelf to read and write objects. libelf automatically 268ba2be530Sabswaps bytes for the sections it knows about, such as symbol tables, 269ba2be530Sabrelocation records, and the usual ELF plumbing. It is therefore never 270ba2be530Sabnecessary for your code to swap the bytes in this data. If you find that 271ba2be530Sabthis is not the case, you have probably uncovered a bug in libelf that 272ba2be530Sabyou should look into. 273ba2be530Sab 274ba2be530SabThe big exception to libelf transparently handling byte swapping is 275ba2be530Sabprogbits sections (SHT_PROGBITS). libelf does not understand program 276ba2be530Sabcode or data as anything other than a series of byte values, and as such, 277ba2be530Sabcannot do byte swapping for them. If your code examines or modifies 278ba2be530Sabsuch data, you are responsible for handling the byte swapping required. 279ba2be530Sab 280ba2be530SabThe OFL_SWAP_RELOC macros found in _libld.h can be helpful in making such 281ba2be530Sabdeterminations. You should use these macros instead of writing your own 282ba2be530Sabtests for this, as they have high documentation value. If you find they 283ba2be530Sabdon't handle your target, add a new one that does. 284ba2be530Sab 285ba2be530SabGOT and PLT sections are SHT_PROGBITS. You will probably find 286ba2be530Sabthat the vast majority of byte swapping you have to handle 287ba2be530Sabconcern the handling of these items. 288ba2be530Sab 289ba2be530Sablibld contains generic functions for byte swapping: 290ba2be530Sab 291ba2be530Sab ld_bswap_Word(); 292ba2be530Sab ld_bswap_Xword(); 293ba2be530Sab 294ba2be530SabThese functions are built on top of the of the BSWAP_ macros found 295ba2be530Sabin usr/src/cmd/sgs/include/_machelf.h: 296ba2be530Sab 297ba2be530Sab BSWAP_HALF 298ba2be530Sab BSWAP_WORD 299ba2be530Sab BSWAP_XWORD 300ba2be530Sab 301ba2be530SabWhen copying data from one address to another in a cross link environment, 302ba2be530Sabthe source and/or destination addresses may not have adequate alignment for 303ba2be530Sabthe data type being copied. For example, a sparc platform cannot access 304ba2be530Sab8-byte data types on 4-byte boundaries, but it might need to do so when 305ba2be530Sablinking X86 objects where the alignment of such data can be 4. The 306ba2be530SabUL_ASSIGN macros can be used to copy potentially unaligned data: 307ba2be530Sab 308ba2be530Sab UL_ASSIGN_HALF 309ba2be530Sab UL_ASSIGN_WORD 310ba2be530Sab UL_ASSIGN_XWORD 311ba2be530Sab 312ba2be530SabThe UL_ASSIGN_BSWAP macros do unaligned copies, and also perform 313ba2be530Sabbyte swapping when the linker host and target byte orders are 314ba2be530Sabdifferent: 315ba2be530Sab 316ba2be530Sab UL_ASSIGN_BSWAP_HALF 317ba2be530Sab UL_ASSIGN_BSWAP_WORD 318ba2be530Sab UL_ASSIGN_BSWAP_XWORD 319ba2be530Sab 320ba2be530SabIf you are reading/writing to relocation data, the following 321ba2be530Sabroutines understand relocation records and will get/set the 322ba2be530Sabproper amount of data while handling any needed swapping: 323ba2be530Sab 324ba2be530Sab ld_reloc_targval_get() 325ba2be530Sab ld_reloc_targval_set() 326ba2be530Sab 327ba2be530SabByte swapping is a fertile area for mistakes. If you're having trouble 328ba2be530Sabgetting a successful link in a cross link situation, you should always 329ba2be530Sabdo the experiment of doing the link on a platform with the same byte 330ba2be530Saborder as the target. If that link succeeds, then you are looking at 331ba2be530Saba bug involving incorrect byte swapping. 332ba2be530Sab 333ba2be530Sab----------------------------------------------------------------------------- 334ba2be530Sab As mentioned above, incorrect byte swapping is a common 335ba2be530Saberror when developing libld target specific code. In addition to 336ba2be530Sabtrying a build machine with the same byte order as the target, elfdump 337ba2be530Sabcan also be a powerful tool for debugging. The first step with 338ba2be530Sabelfdump is to simply dump everything and read it looking for obviously 339ba2be530Sabbad information: 340ba2be530Sab 341ba2be530Sab % elfdump outobj 2>&1 | more 342ba2be530Sab 343ba2be530Sabelfdump tries to do sanity checking on the objects it 344ba2be530Sabdisplays. Hence, the following command is a a common 345ba2be530Sabidiom: 346ba2be530Sab 347ba2be530Sab % elfdump outobj > /dev/null 348ba2be530Sab 349ba2be530SabAny problems with the file that elfdump can detect will be 350ba2be530Sabwritten to stderr. 351ba2be530Sab 352ba2be530Sab----------------------------------------------------------------------------- 353ba2be530SabOnce you have the target-specific code in place, you must modify the 354ba2be530Sablibld initialization code so that it will know how to use it. This 355ba2be530Sablogic is found in 356ba2be530Sab 357ba2be530Sab usr/src/cmd/sgs/libld/common/ldmain.c 358ba2be530Sab 359ba2be530Sabin the function ld_init_target(). 360ba2be530Sab 361ba2be530Sab----------------------------------------------------------------------------- 362ba2be530SabThe ld front end program that uses libld must be modified so that 363ba2be530Sabthe "-z target=platform" command line option recognizes your 364ba2be530Sabnew target. This code is found in 365ba2be530Sab 366ba2be530Sab usr/src/cmd/sgs/ld/common 367ba2be530Sab 368ba2be530SabThe change consists of adding an additional strcasecmp() to the 369ba2be530Sabcommand line processing for -ztarget. 370ba2be530Sab 371ba2be530Sab----------------------------------------------------------------------------- 372ba2be530SabYou probably changed things getting your target integrated. 373ba2be530SabPlease update this document to reflect your changes. 374