1 /**
2  * Bindings for symbols and defines in `mach-o/nlist.h`
3  *
4  * This file was created based on the MacOSX 10.15 SDK.
5  *
6  * Copyright:
7  * D Language Foundation 2020
8  * Some documentation was extracted from the C headers
9  * and is the property of Apple Inc.
10  *
11  * License: $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
12  * Authors: Mathias 'Geod24' Lang
13  * Source: $(DRUNTIMESRC core/sys/darwin/mach/_nlist.d)
14  */
15 module core.sys.darwin.mach.nlist;
16 
17 import core.stdc.config;
18 
19 extern(C):
20 nothrow:
21 @nogc:
22 pure:
23 
24 /**
25  * An entry in a list of symbols for 64-bits architectures
26  *
27  * Said symbols can be used to describe many different type of data,
28  * including STABS debug infos. Introduced in MacOSX 10.8 SDK.
29  *
30  * See_Also:
31  * https://developer.apple.com/documentation/kernel/nlist_64
32  */
33 struct nlist_64
34 {
35     /// Compatibility alias, as `n_strx` is in an union in C code
36     alias n_un = n_strx;
37 
38     /**
39      * Index of this symbol's name into the string table
40      *
41      * All names are stored as NUL-terminated strings into the string table.
42      * For historical reason, the very first entry into the string table is `0`,
43      * hence all non-NULL names have an index > 0.
44      */
45     uint n_strx;
46 
47     /**
48      * A bitfield that describes the type of this symbol
49      *
50      * In reality, this describes 4 fields:
51      * - N_STAB (top 3 bits)
52      * - N_PEXT (next 1 bit)
53      * - N_TYPE (next 3 bits)
54      * - N_EXT (last 1 bit)
55      *
56      * The enum values `N_STAB`, `N_PEXT`, `N_TYPE`, and `N_EXT` should be used
57      * as masks to check which type this `nlist_64` actually is.
58      */
59     ubyte n_type;
60     /// Section number (note that `0` means `NO_SECT`)
61     ubyte n_sect;
62     /* see <mach-o/stab.h> */
63     ushort n_desc;
64     /* value of this symbol (or stab offset) */
65     ulong n_value;
66     // Note: `n_value` *is* `uint64_t`, not `c_ulong` !
67 }
68 
69 /// Mask to use with `nlist_64.n_type` to check what the entry describes
70 enum
71 {
72     /**
73      * If any of these bits set, a symbolic debugging entry
74      *
75      * Only symbolic debugging entries have some of the N_STAB bits set and if any
76      * of these bits are set then it is a symbolic debugging entry (a stab).  In
77      * which case then the values of the n_type field (the entire field) are given
78      * in <mach-o/stab.h>
79      */
80     N_STAB = 0xe0,
81     /// Private external symbol bit
82     N_PEXT = 0x10,
83     /// Mask for the type bits
84     N_TYPE = 0x0e,  /* mask for the type bits */
85     /// External symbol bit, set for external symbols
86     N_EXT  = 0x01,
87 }
88 
89 /// Values for `NTypeMask.N_TYPE` bits of the `nlist_64.n_type` field.
90 enum
91 {
92     /// Undefined (`n_sect == NO_SECT`)
93     N_UNDF = 0x0,
94     /// Absolute (`n_sect == NO_SECT`)
95     N_ABS  = 0x2,
96     /// Defined in section number `nlist_64.n_sect`
97     N_SECT = 0xe,
98     /// Prebound undefined (defined in a dylib)
99     N_PBUD = 0xc,
100     /**
101      * Indirect symbol
102      *
103      * If the type is `N_INDR` then the symbol is defined to be the same as
104      * another symbol. In this case the `n_value` field is an index into
105      * the string table of the other symbol's name. When the other symbol
106      * is defined then they both take on the defined type and value.
107      */
108     N_INDR = 0xa,
109 }
110 
111 /**
112  * Symbol is not in any section
113  *
114  * If the type is N_SECT then the n_sect field contains an ordinal of the
115  * section the symbol is defined in.  The sections are numbered from 1 and
116  * refer to sections in order they appear in the load commands for the file
117  * they are in.  This means the same ordinal may very well refer to different
118  * sections in different files.
119  *
120  * The n_value field for all symbol table entries (including N_STAB's) gets
121  * updated by the link editor based on the value of it's n_sect field and where
122  * the section n_sect references gets relocated.  If the value of the n_sect
123  * field is NO_SECT then it's n_value field is not changed by the link editor.
124  */
125 enum NO_SECT = 0;
126 
127 /// Maximum number of sections: 1 thru 255 inclusive
128 enum MAX_SECT = 255;
129 
130 /**
131  * Common symbols are represented by undefined (N_UNDF) external (N_EXT) types
132  * who's values (n_value) are non-zero.  In which case the value of the n_value
133  * field is the size (in bytes) of the common symbol.  The n_sect field is set
134  * to NO_SECT.  The alignment of a common symbol may be set as a power of 2
135  * between 2^1 and 2^15 as part of the n_desc field using the macros below. If
136  * the alignment is not set (a value of zero) then natural alignment based on
137  * the size is used.
138  */
139 extern(D) ubyte GET_COMM_ALIGN(uint n_desc) @safe
140 {
141     return (((n_desc) >> 8) & 0x0f);
142 }
143 
144 /// Ditto
145 extern(D) ref ushort SET_COMM_ALIGN(return ref ushort n_desc, size_t wanted_align) @safe
146 {
147     return n_desc = (((n_desc) & 0xf0ff) | (((wanted_align) & 0x0f) << 8));
148 }
149 
150 /**
151  * To support the lazy binding of undefined symbols in the dynamic link-editor,
152  * the undefined symbols in the symbol table (the nlist structures) are marked
153  * with the indication if the undefined reference is a lazy reference or
154  * non-lazy reference.  If both a non-lazy reference and a lazy reference is
155  * made to the same symbol the non-lazy reference takes precedence.  A reference
156  * is lazy only when all references to that symbol are made through a symbol
157  * pointer in a lazy symbol pointer section.
158  *
159  * The implementation of marking nlist structures in the symbol table for
160  * undefined symbols will be to use some of the bits of the n_desc field as a
161  * reference type.  The mask REFERENCE_TYPE will be applied to the n_desc field
162  * of an nlist structure for an undefined symbol to determine the type of
163  * undefined reference (lazy or non-lazy).
164  *
165  * The constants for the REFERENCE FLAGS are propagated to the reference table
166  * in a shared library file.  In that case the constant for a defined symbol,
167  * REFERENCE_FLAG_DEFINED, is also used.
168  */
169 enum
170 {
171     /// Reference type bits of the n_desc field of undefined symbols
172     REFERENCE_TYPE = 0x7,
173 
174     /// types of references
175     REFERENCE_FLAG_UNDEFINED_NON_LAZY = 0,
176     /// Ditto
177     REFERENCE_FLAG_UNDEFINED_LAZY     = 1,
178     /// Ditto
179     REFERENCE_FLAG_DEFINED            = 2,
180     /// Ditto
181     REFERENCE_FLAG_PRIVATE_DEFINED    = 3,
182     /// Ditto
183     REFERENCE_FLAG_PRIVATE_UNDEFINED_NON_LAZY = 4,
184     /// Ditto
185     REFERENCE_FLAG_PRIVATE_UNDEFINED_LAZY     = 5,
186 
187     /**
188      * To simplify stripping of objects that use are used with the dynamic link
189      * editor, the static link editor marks the symbols defined an object that are
190      * referenced by a dynamicly bound object (dynamic shared libraries, bundles).
191      * With this marking strip knows not to strip these symbols.
192      */
193     REFERENCED_DYNAMICALLY = 0x0010,
194 }
195 
196 /**
197  * For images created by the static link editor with the -twolevel_namespace
198  * option in effect the flags field of the mach header is marked with
199  * MH_TWOLEVEL.  And the binding of the undefined references of the image are
200  * determined by the static link editor.  Which library an undefined symbol is
201  * bound to is recorded by the static linker in the high 8 bits of the n_desc
202  * field using the SET_LIBRARY_ORDINAL macro below.  The ordinal recorded
203  * references the libraries listed in the Mach-O's LC_LOAD_DYLIB,
204  * LC_LOAD_WEAK_DYLIB, LC_REEXPORT_DYLIB, LC_LOAD_UPWARD_DYLIB, and
205  * LC_LAZY_LOAD_DYLIB, etc. load commands in the order they appear in the
206  * headers.   The library ordinals start from 1.
207  * For a dynamic library that is built as a two-level namespace image the
208  * undefined references from module defined in another use the same nlist struct
209  * an in that case SELF_LIBRARY_ORDINAL is used as the library ordinal.  For
210  * defined symbols in all images they also must have the library ordinal set to
211  * SELF_LIBRARY_ORDINAL.  The EXECUTABLE_ORDINAL refers to the executable
212  * image for references from plugins that refer to the executable that loads
213  * them.
214  *
215  * The DYNAMIC_LOOKUP_ORDINAL is for undefined symbols in a two-level namespace
216  * image that are looked up by the dynamic linker with flat namespace semantics.
217  * This ordinal was added as a feature in Mac OS X 10.3 by reducing the
218  * value of MAX_LIBRARY_ORDINAL by one.  So it is legal for existing binaries
219  * or binaries built with older tools to have 0xfe (254) dynamic libraries.  In
220  * this case the ordinal value 0xfe (254) must be treated as a library ordinal
221  * for compatibility.
222  */
223 ubyte GET_LIBRARY_ORDINAL(uint n_desc) @safe { return ((n_desc) >> 8) & 0xff; }
224 /// Ditto
225 ref ushort SET_LIBRARY_ORDINAL(return ref ushort n_desc, uint ordinal) @safe
226 {
227     return n_desc = (((n_desc) & 0x00ff) | (((ordinal) & 0xff) << 8));
228 }
229 
230 /// Ditto
231 enum
232 {
233     SELF_LIBRARY_ORDINAL   = 0x00,
234     MAX_LIBRARY_ORDINAL    = 0xfd,
235     DYNAMIC_LOOKUP_ORDINAL = 0xfe,
236     EXECUTABLE_ORDINAL     = 0xff,
237 }
238 
239 /**
240  * The bit 0x0020 of the n_desc field is used for two non-overlapping purposes
241  * and has two different symbolic names, N_NO_DEAD_STRIP and N_DESC_DISCARDED.
242  */
243 enum
244 {
245     /**
246      * Symbol is not to be dead stripped
247      *
248      * The N_NO_DEAD_STRIP bit of the n_desc field only ever appears in a
249      * relocatable .o file (MH_OBJECT filetype). And is used to indicate to the
250      * static link editor it is never to dead strip the symbol.
251      */
252     N_NO_DEAD_STRIP = 0x0020,
253 
254     /**
255      * Symbol is discarded
256      *
257      * The N_DESC_DISCARDED bit of the n_desc field never appears in linked image.
258      * But is used in very rare cases by the dynamic link editor to mark an in
259      * memory symbol as discared and longer used for linking.
260      */
261     N_DESC_DISCARDED =0x0020,
262 
263     /**
264      * Symbol is weak referenced
265      *
266      * The N_WEAK_REF bit of the n_desc field indicates to the dynamic linker that
267      * the undefined symbol is allowed to be missing and is to have the address of
268      * zero when missing.
269      */
270     N_WEAK_REF = 0x0040,
271 
272     /**
273      * Coalesed symbol is a weak definition
274      *
275      * The N_WEAK_DEF bit of the n_desc field indicates to the static and dynamic
276      * linkers that the symbol definition is weak, allowing a non-weak symbol to
277      * also be used which causes the weak definition to be discared.  Currently this
278      * is only supported for symbols in coalesed sections.
279      */
280     N_WEAK_DEF = 0x0080,
281 
282     /**
283      * Reference to a weak symbol
284      *
285      * The N_REF_TO_WEAK bit of the n_desc field indicates to the dynamic linker
286      * that the undefined symbol should be resolved using flat namespace searching.
287      */
288     N_REF_TO_WEAK = 0x0080,
289 
290     /**
291      * Symbol is a Thumb function (ARM)
292      *
293      * The N_ARM_THUMB_DEF bit of the n_desc field indicates that the symbol is
294      * a defintion of a Thumb function.
295      */
296     N_ARM_THUMB_DEF = 0x0008,
297 
298     /**
299      * The N_SYMBOL_RESOLVER bit of the n_desc field indicates that the
300      * that the function is actually a resolver function and should
301      * be called to get the address of the real function to use.
302      * This bit is only available in .o files (MH_OBJECT filetype)
303      */
304     N_SYMBOL_RESOLVER =  0x0100,
305 
306     /**
307      * The N_ALT_ENTRY bit of the n_desc field indicates that the
308      * symbol is pinned to the previous content.
309      */
310     N_ALT_ENTRY = 0x0200,
311 
312     /**
313      * The N_COLD_FUNC bit of the n_desc field indicates that the symbol is used
314      * infrequently and the linker should order it towards the end of the section.
315      */
316     N_COLD_FUNC = 0x0400,
317 }