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 #endif /* _IPXE_TABLES_H */
448