Name Date Size #Lines LOC

..12-Jul-2022-

README.XLINKH A D14-Feb-202116 KiB374296

_libld.hH A D12-Jul-202237.5 KiB1,043638

_map.hH A D10-Dec-202113.8 KiB374220

args.cH A D12-Jul-202265.9 KiB2,2531,515

debug.cH A D14-Feb-20215.7 KiB232123

entry.cH A D14-Feb-202115 KiB504214

exit.cH A D14-Feb-20214.6 KiB17569

files.cH A D17-Apr-2023106.5 KiB3,7822,130

globals.cH A D17-Apr-20234 KiB14181

groups.cH A D17-Apr-20239.5 KiB347178

ldentry.cH A D10-Dec-20216.4 KiB225121

ldlibs.cH A D14-Feb-202111.5 KiB435242

ldmachdep.cH A D17-Apr-20231.7 KiB5613

ldmain.cH A D12-Jul-202215.5 KiB577268

libld.intel.msgH A D14-Feb-20211.5 KiB5038

libld.msgH A D17-Apr-202361.6 KiB1,6681,498

libld.sparc.msgH A D14-Feb-20213.1 KiB8272

libs.cH A D12-Jul-202224.6 KiB873399

machrel.amd.cH A D14-Feb-202145.8 KiB1,739955

machrel.intel.cH A D17-Apr-202345.4 KiB1,750973

machrel.sparc.cH A D14-Feb-202163.3 KiB2,3051,285

machsym.sparc.cH A D12-Jul-20226.9 KiB249142

machsym.sparc.hH A D14-Feb-20212.1 KiB7130

map.cH A D12-Jul-202237.5 KiB1,463956

map_core.cH A D12-Jul-202279.9 KiB2,8691,627

map_support.cH A D17-Apr-202341.1 KiB1,512742

map_v2.cH A D17-Apr-202391 KiB3,6772,211

mapfile-versH A D14-Feb-20212.1 KiB9585

order.cH A D14-Feb-202115 KiB486188

outfile.cH A D12-Jul-202224.2 KiB879437

place.cH A D12-Jul-202241.4 KiB1,369621

relocate.cH A D17-Apr-202392.3 KiB3,1611,622

resolve.cH A D14-Feb-202139.5 KiB1,262698

sections.cH A D17-Apr-202394.9 KiB3,5901,903

sunwmove.cH A D12-Jul-202210.5 KiB396220

support.cH A D14-Feb-20219.2 KiB335206

syms.cH A D12-Jul-202298.4 KiB3,3411,725

unwind.cH A D12-Jul-202223.4 KiB858329

update.cH A D17-Apr-2023123.8 KiB4,6102,693

util.cH A D12-Jul-202216.2 KiB638375

version.cH A D12-Jul-202227.6 KiB1,075598

wrap.cH A D14-Feb-20213.8 KiB13245

README.XLINK

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