iPXE
tables.h
Go to the documentation of this file.
1 #ifndef _IPXE_TABLES_H
2 #define _IPXE_TABLES_H
3 
4 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
5 
6 /** @page ifdef_harmful #ifdef considered harmful
7  *
8  * Overuse of @c #ifdef has long been a problem in Etherboot.
9  * Etherboot provides a rich array of features, but all these features
10  * take up valuable space in a ROM image. The traditional solution to
11  * this problem has been for each feature to have its own @c #ifdef
12  * option, allowing the feature to be compiled in only if desired.
13  *
14  * The problem with this is that it becomes impossible to compile, let
15  * alone test, all possible versions of Etherboot. Code that is not
16  * typically used tends to suffer from bit-rot over time. It becomes
17  * extremely difficult to predict which combinations of compile-time
18  * options will result in code that can even compile and link
19  * correctly.
20  *
21  * To solve this problem, we have adopted a new approach from
22  * Etherboot 5.5 onwards. @c #ifdef is now "considered harmful", and
23  * its use should be minimised. Separate features should be
24  * implemented in separate @c .c files, and should \b always be
25  * compiled (i.e. they should \b not be guarded with a @c #ifdef @c
26  * MY_PET_FEATURE statement). By making (almost) all code always
27  * compile, we avoid the problem of bit-rot in rarely-used code.
28  *
29  * The file config.h, in combination with the @c make command line,
30  * specifies the objects that will be included in any particular build
31  * of Etherboot. For example, suppose that config.h includes the line
32  *
33  * @code
34  *
35  * #define CONSOLE_SERIAL
36  * #define DOWNLOAD_PROTO_TFTP
37  *
38  * @endcode
39  *
40  * When a particular Etherboot image (e.g. @c bin/rtl8139.zdsk) is
41  * built, the options specified in config.h are used to drag in the
42  * relevant objects at link-time. For the above example, serial.o and
43  * tftp.o would be linked in.
44  *
45  * There remains one problem to solve: how do these objects get used?
46  * Traditionally, we had code such as
47  *
48  * @code
49  *
50  * #ifdef CONSOLE_SERIAL
51  * serial_init();
52  * #endif
53  *
54  * @endcode
55  *
56  * in main.c, but this reintroduces @c #ifdef and so is a Bad Idea.
57  * We cannot simply remove the @c #ifdef and make it
58  *
59  * @code
60  *
61  * serial_init();
62  *
63  * @endcode
64  *
65  * because then serial.o would end up always being linked in.
66  *
67  * The solution is to use @link tables.h linker tables @endlink.
68  *
69  */
70 
71 /** @file
72  *
73  * Linker tables
74  *
75  * Read @ref ifdef_harmful first for some background on the motivation
76  * for using linker tables.
77  *
78  * This file provides macros for dealing with linker-generated tables
79  * of fixed-size symbols. We make fairly extensive use of these in
80  * order to avoid @c #ifdef spaghetti and/or linker symbol pollution.
81  * For example, instead of having code such as
82  *
83  * @code
84  *
85  * #ifdef CONSOLE_SERIAL
86  * serial_init();
87  * #endif
88  *
89  * @endcode
90  *
91  * we make serial.c generate an entry in the initialisation function
92  * table, and then have a function call_init_fns() that simply calls
93  * all functions present in this table. If and only if serial.o gets
94  * linked in, then its initialisation function will be called. We
95  * avoid linker symbol pollution (i.e. always dragging in serial.o
96  * just because of a call to serial_init()) and we also avoid @c
97  * #ifdef spaghetti (having to conditionalise every reference to
98  * functions in serial.c).
99  *
100  * The linker script takes care of assembling the tables for us. All
101  * our table sections have names of the format @c .tbl.NAME.NN where
102  * @c NAME designates the data structure stored in the table (e.g. @c
103  * init_fns) and @c NN is a two-digit decimal number used to impose an
104  * ordering upon the tables if required. @c NN=00 is reserved for the
105  * symbol indicating "table start", and @c NN=99 is reserved for the
106  * symbol indicating "table end".
107  *
108  * As an example, suppose that we want to create a "frobnicator"
109  * feature framework, and allow for several independent modules to
110  * provide frobnicating services. Then we would create a frob.h
111  * header file containing e.g.
112  *
113  * @code
114  *
115  * struct frobnicator {
116  * const char *name; // Name of the frobnicator
117  * void ( *frob ) ( void ); // The frobnicating function itself
118  * };
119  *
120  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
121  *
122  * #define __frobnicator __table_entry ( FROBNICATORS, 01 )
123  *
124  * @endcode
125  *
126  * Any module providing frobnicating services would look something
127  * like
128  *
129  * @code
130  *
131  * #include "frob.h"
132  *
133  * static void my_frob ( void ) {
134  * // Do my frobnicating
135  * ...
136  * }
137  *
138  * struct frob my_frobnicator __frobnicator = {
139  * .name = "my_frob",
140  * .frob = my_frob,
141  * };
142  *
143  * @endcode
144  *
145  * The central frobnicator code (frob.c) would use the frobnicating
146  * modules as follows
147  *
148  * @code
149  *
150  * #include "frob.h"
151  *
152  * // Call all linked-in frobnicators
153  * void frob_all ( void ) {
154  * struct frob *frob;
155  *
156  * for_each_table ( frob, FROBNICATORS ) {
157  * printf ( "Calling frobnicator \"%s\"\n", frob->name );
158  * frob->frob ();
159  * }
160  * }
161  *
162  * @endcode
163  *
164  * See init.h and init.c for a real-life example.
165  *
166  */
167 
168 #ifdef DOXYGEN
169 #define __attribute__( x )
170 #endif
171 
172 /**
173  * Declare a linker table
174  *
175  * @v type Data type
176  * @v name Table name
177  * @ret table Linker table
178  */
179 #define __table( type, name ) ( type, name )
180 
181 /**
182  * Get linker table data type
183  *
184  * @v table Linker table
185  * @ret type Data type
186  */
187 #define __table_type( table ) __table_extract_type table
188 #define __table_extract_type( type, name ) type
189 
190 /**
191  * Get linker table name
192  *
193  * @v table Linker table
194  * @ret name Table name
195  */
196 #define __table_name( table ) __table_extract_name table
197 #define __table_extract_name( type, name ) name
198 
199 /**
200  * Get linker table section name
201  *
202  * @v table Linker table
203  * @v idx Sub-table index
204  * @ret section Section name
205  */
206 #define __table_section( table, idx ) \
207  ".tbl." __table_name ( table ) "." __table_str ( idx )
208 #define __table_str( x ) #x
209 
210 /**
211  * Get linker table alignment
212  *
213  * @v table Linker table
214  * @ret align Alignment
215  */
216 #define __table_alignment( table ) __alignof__ ( __table_type ( table ) )
217 
218 /**
219  * Declare a linker table entry
220  *
221  * @v table Linker table
222  * @v idx Sub-table index
223  *
224  * Example usage:
225  *
226  * @code
227  *
228  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
229  *
230  * #define __frobnicator __table_entry ( FROBNICATORS, 01 )
231  *
232  * struct frobnicator my_frob __frobnicator = {
233  * ...
234  * };
235  *
236  * @endcode
237  */
238 #define __table_entry( table, idx ) \
239  __attribute__ (( __section__ ( __table_section ( table, idx ) ),\
240  __aligned__ ( __table_alignment ( table ) ) ))
241 
242 /**
243  * Get start of linker table entries
244  *
245  * @v table Linker table
246  * @v idx Sub-table index
247  * @ret entries Start of entries
248  */
249 #define __table_entries( table, idx ) ( { \
250  static __table_type ( table ) __table_entries[0] \
251  __table_entry ( table, idx ) \
252  __attribute__ (( unused )); \
253  __table_entries; } )
254 
255 /**
256  * Get start of linker table
257  *
258  * @v table Linker table
259  * @ret start Start of linker table
260  *
261  * Example usage:
262  *
263  * @code
264  *
265  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
266  *
267  * struct frobnicator *frobs = table_start ( FROBNICATORS );
268  *
269  * @endcode
270  */
271 #define table_start( table ) __table_entries ( table, 00 )
272 
273 /**
274  * Get end of linker table
275  *
276  * @v table Linker table
277  * @ret end End of linker table
278  *
279  * Example usage:
280  *
281  * @code
282  *
283  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
284  *
285  * struct frobnicator *frobs_end = table_end ( FROBNICATORS );
286  *
287  * @endcode
288  */
289 #define table_end( table ) __table_entries ( table, 99 )
290 
291 /**
292  * Get number of entries in linker table
293  *
294  * @v table Linker table
295  * @ret num_entries Number of entries in linker table
296  *
297  * Example usage:
298  *
299  * @code
300  *
301  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
302  *
303  * unsigned int num_frobs = table_num_entries ( FROBNICATORS );
304  *
305  * @endcode
306  *
307  */
308 #define table_num_entries( table ) \
309  ( ( unsigned int ) ( table_end ( table ) - \
310  table_start ( table ) ) )
311 
312 /**
313  * Get index of entry within linker table
314  *
315  * @v table Linker table
316  * @v entry Table entry
317  *
318  * Example usage:
319  *
320  * @code
321  *
322  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
323  *
324  * #define __frobnicator __table_entry ( FROBNICATORS, 01 )
325  *
326  * struct frobnicator my_frob __frobnicator = {
327  * ...
328  * };
329  *
330  * unsigned int my_frob_idx = table_index ( FROBNICATORS, &my_frob );
331  *
332  * @endcode
333  */
334 #define table_index( table, entry ) \
335  ( ( unsigned int ) ( (entry) - table_start ( table ) ) )
336 
337 /**
338  * Iterate through all entries within a linker table
339  *
340  * @v pointer Entry pointer
341  * @v table Linker table
342  *
343  * Example usage:
344  *
345  * @code
346  *
347  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
348  *
349  * struct frobnicator *frob;
350  *
351  * for_each_table_entry ( frob, FROBNICATORS ) {
352  * ...
353  * }
354  *
355  * @endcode
356  *
357  */
358 #define for_each_table_entry( pointer, table ) \
359  for ( pointer = table_start ( table ) ; \
360  pointer < table_end ( table ) ; \
361  pointer++ )
362 
363 /**
364  * Iterate through all remaining entries within a linker table
365  *
366  * @v pointer Entry pointer, preset to most recent entry
367  * @v table Linker table
368  *
369  * Example usage:
370  *
371  * @code
372  *
373  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
374  * #define __frobnicator __table_entry ( FROBNICATORS, 01 )
375  *
376  * struct frob my_frobnicator __frobnicator;
377  * struct frobnicator *frob;
378  *
379  * frob = &my_frobnicator;
380  * for_each_table_entry_continue ( frob, FROBNICATORS ) {
381  * ...
382  * }
383  *
384  * @endcode
385  *
386  */
387 #define for_each_table_entry_continue( pointer, table ) \
388  for ( pointer++ ; \
389  pointer < table_end ( table ) ; \
390  pointer++ )
391 
392 /**
393  * Iterate through all entries within a linker table in reverse order
394  *
395  * @v pointer Entry pointer
396  * @v table Linker table
397  *
398  * Example usage:
399  *
400  * @code
401  *
402  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
403  *
404  * struct frobnicator *frob;
405  *
406  * for_each_table_entry_reverse ( frob, FROBNICATORS ) {
407  * ...
408  * }
409  *
410  * @endcode
411  *
412  */
413 #define for_each_table_entry_reverse( pointer, table ) \
414  for ( pointer = ( table_end ( table ) - 1 ) ; \
415  pointer >= table_start ( table ) ; \
416  pointer-- )
417 
418 /**
419  * Iterate through all remaining entries within a linker table in reverse order
420  *
421  * @v pointer Entry pointer, preset to most recent entry
422  * @v table Linker table
423  *
424  * Example usage:
425  *
426  * @code
427  *
428  * #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
429  * #define __frobnicator __table_entry ( FROBNICATORS, 01 )
430  *
431  * struct frob my_frobnicator __frobnicator;
432  * struct frobnicator *frob;
433  *
434  * frob = &my_frobnicator;
435  * for_each_table_entry_continue_reverse ( frob, FROBNICATORS ) {
436  * ...
437  * }
438  *
439  * @endcode
440  *
441  */
442 #define for_each_table_entry_continue_reverse( pointer, table ) \
443  for ( pointer-- ; \
444  pointer >= table_start ( table ) ; \
445  pointer-- )
446 
447 /******************************************************************************
448  *
449  * Intel's C compiler chokes on several of the constructs used in this
450  * file. The workarounds are ugly, so we use them only for an icc
451  * build.
452  *
453  */
454 #define ICC_ALIGN_HACK_FACTOR 128
455 #ifdef __ICC
456 
457 /*
458  * icc miscompiles zero-length arrays by inserting padding to a length
459  * of two array elements. We therefore have to generate the
460  * __table_entries() symbols by hand in asm.
461  *
462  */
463 #undef __table_entries
464 #define __table_entries( table, idx ) ( { \
465  extern __table_type ( table ) \
466  __table_temp_sym ( idx, __LINE__ ) [] \
467  __table_entry ( table, idx ) \
468  asm ( __table_entries_sym ( table, idx ) ); \
469  __asm__ ( ".ifndef %c0\n\t" \
470  ".section " __table_section ( table, idx ) "\n\t" \
471  ".align %c1\n\t" \
472  "\n%c0:\n\t" \
473  ".previous\n\t" \
474  ".endif\n\t" \
475  : : "i" ( __table_temp_sym ( idx, __LINE__ ) ), \
476  "i" ( __table_alignment ( table ) ) ); \
477  __table_temp_sym ( idx, __LINE__ ); } )
478 #define __table_entries_sym( table, idx ) \
479  "__tbl_" __table_name ( table ) "_" #idx
480 #define __table_temp_sym( a, b ) \
481  ___table_temp_sym( __table_, a, _, b )
482 #define ___table_temp_sym( a, b, c, d ) a ## b ## c ## d
483 
484 /*
485  * icc ignores __attribute__ (( aligned (x) )) when it is used to
486  * decrease the compiler's default choice of alignment (which may be
487  * higher than the alignment actually required by the structure). We
488  * work around this by forcing the alignment to a large multiple of
489  * the required value (so that we are never attempting to decrease the
490  * default alignment) and then postprocessing the object file to
491  * reduce the alignment back down to the "real" value.
492  *
493  */
494 #undef __table_alignment
495 #define __table_alignment( table ) \
496  ( ICC_ALIGN_HACK_FACTOR * __alignof__ ( __table_type ( table ) ) )
497 
498 /*
499  * Because of the alignment hack, we must ensure that the compiler
500  * never tries to place multiple objects within the same section,
501  * otherwise the assembler will insert padding to the (incorrect)
502  * alignment boundary. Do this by appending the line number to table
503  * section names.
504  *
505  * Note that we don't need to worry about padding between array
506  * elements, since the alignment is declared on the variable (i.e. the
507  * whole array) rather than on the type (i.e. on all individual array
508  * elements).
509  */
510 #undef __table_section
511 #define __table_section( table, idx ) \
512  ".tbl." __table_name ( table ) "." __table_str ( idx ) \
513  "." __table_xstr ( __LINE__ )
514 #define __table_xstr( x ) __table_str ( x )
515 
516 #endif /* __ICC */
517 
518 #endif /* _IPXE_TABLES_H */
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)