iPXE
Macros | Functions
tables.h File Reference

Linker tables. More...

Go to the source code of this file.

Macros

#define __attribute__(x)
 
#define __table(type, name)   ( type, name )
 Declare a linker table. More...
 
#define __table_type(table)   __table_extract_type table
 Get linker table data type. More...
 
#define __table_extract_type(type, name)   type
 
#define __table_name(table)   __table_extract_name table
 Get linker table name. More...
 
#define __table_extract_name(type, name)   name
 
#define __table_section(table, idx)   ".tbl." __table_name ( table ) "." __table_str ( idx )
 Get linker table section name. More...
 
#define __table_str(x)   #x
 
#define __table_alignment(table)   __alignof__ ( __table_type ( table ) )
 Get linker table alignment. More...
 
#define __table_entry(table, idx)
 Declare a linker table entry. More...
 
#define __table_entries(table, idx)
 Get start of linker table entries. More...
 
#define __TABLE_ENTRIES(entries, table, idx)
 Declare start of linker table entries. More...
 
#define table_start(table)   __table_entries ( table, 00 )
 Get start of linker table. More...
 
#define TABLE_START(start, table)   __TABLE_ENTRIES ( start, table, 00 )
 Declare start of linker table. More...
 
#define table_end(table)   __table_entries ( table, 99 )
 Get end of linker table. More...
 
#define TABLE_END(end, table)   __TABLE_ENTRIES ( end, table, 99 )
 Declare end of linker table. More...
 
#define table_num_entries(table)
 Get number of entries in linker table. More...
 
#define table_index(table, entry)   ( ( unsigned int ) ( (entry) - table_start ( table ) ) )
 Get index of entry within linker table. More...
 
#define for_each_table_entry(pointer, table)
 Iterate through all entries within a linker table. More...
 
#define for_each_table_entry_continue(pointer, table)
 Iterate through all remaining entries within a linker table. More...
 
#define for_each_table_entry_reverse(pointer, table)
 Iterate through all entries within a linker table in reverse order. More...
 
#define for_each_table_entry_continue_reverse(pointer, table)
 Iterate through all remaining entries within a linker table in reverse order. More...
 

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
 

Detailed Description

Linker tables.

Read #ifdef considered harmful first for some background on the motivation for using linker tables.

This file provides macros for dealing with linker-generated tables of fixed-size symbols. We make fairly extensive use of these in order to avoid #ifdef spaghetti and/or linker symbol pollution. For example, instead of having code such as

#ifdef CONSOLE_SERIAL
#endif

we make serial.c generate an entry in the initialisation function table, and then have a function call_init_fns() that simply calls all functions present in this table. If and only if serial.o gets linked in, then its initialisation function will be called. We avoid linker symbol pollution (i.e. always dragging in serial.o just because of a call to serial_init()) and we also avoid #ifdef spaghetti (having to conditionalise every reference to functions in serial.c).

The linker script takes care of assembling the tables for us. All our table sections have names of the format .tbl.NAME.NN where NAME designates the data structure stored in the table (e.g. init_fns) and NN is a two-digit decimal number used to impose an ordering upon the tables if required. NN=00 is reserved for the symbol indicating "table start", and NN=99 is reserved for the symbol indicating "table end".

As an example, suppose that we want to create a "frobnicator" feature framework, and allow for several independent modules to provide frobnicating services. Then we would create a frob.h header file containing e.g.

struct frobnicator {
const char *name; // Name of the frobnicator
void ( *frob ) ( void ); // The frobnicating function itself
};
#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
#define __frobnicator __table_entry ( FROBNICATORS, 01 )

Any module providing frobnicating services would look something like

#include "frob.h"
static void my_frob ( void ) {
// Do my frobnicating
...
}
struct frob my_frobnicator __frobnicator = {
.name = "my_frob",
.frob = my_frob,
};

The central frobnicator code (frob.c) would use the frobnicating modules as follows

#include "frob.h"
// Call all linked-in frobnicators
void frob_all ( void ) {
struct frob *frob;
for_each_table ( frob, FROBNICATORS ) {
printf ( "Calling frobnicator \"%s\"\n", frob->name );
frob->frob ();
}
}

See init.h and init.c for a real-life example.

Definition in file tables.h.

Macro Definition Documentation

◆ __attribute__

#define __attribute__ (   x)

Definition at line 169 of file tables.h.

◆ __table

#define __table (   type,
  name 
)    ( type, name )

Declare a linker table.

Parameters
typeData type
nameTable name
Return values
tableLinker table

Definition at line 179 of file tables.h.

◆ __table_type

#define __table_type (   table)    __table_extract_type table

Get linker table data type.

Parameters
tableLinker table
Return values
typeData type

Definition at line 187 of file tables.h.

◆ __table_extract_type

#define __table_extract_type (   type,
  name 
)    type

Definition at line 188 of file tables.h.

◆ __table_name

#define __table_name (   table)    __table_extract_name table

Get linker table name.

Parameters
tableLinker table
Return values
nameTable name

Definition at line 196 of file tables.h.

◆ __table_extract_name

#define __table_extract_name (   type,
  name 
)    name

Definition at line 197 of file tables.h.

◆ __table_section

#define __table_section (   table,
  idx 
)    ".tbl." __table_name ( table ) "." __table_str ( idx )

Get linker table section name.

Parameters
tableLinker table
idxSub-table index
Return values
sectionSection name

Definition at line 206 of file tables.h.

◆ __table_str

#define __table_str (   x)    #x

Definition at line 208 of file tables.h.

◆ __table_alignment

#define __table_alignment (   table)    __alignof__ ( __table_type ( table ) )

Get linker table alignment.

Parameters
tableLinker table
Return values
alignAlignment

Definition at line 216 of file tables.h.

◆ __table_entry

#define __table_entry (   table,
  idx 
)
Value:
__attribute__ (( __section__ ( __table_section ( table, idx ) ),\
__aligned__ ( __table_alignment ( table ) ) ))
#define __attribute__(x)
Definition: tables.h:169
#define __table_section(table, idx)
Get linker table section name.
Definition: tables.h:206
#define __table_alignment(table)
Get linker table alignment.
Definition: tables.h:216

Declare a linker table entry.

Parameters
tableLinker table
idxSub-table index

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
#define __frobnicator __table_entry ( FROBNICATORS, 01 )
struct frobnicator my_frob __frobnicator = {
...
};

Definition at line 238 of file tables.h.

◆ __table_entries

#define __table_entries (   table,
  idx 
)
Value:
( { \
static __table_type ( table ) __table_entries[0] \
__table_entry ( table, idx ) \
__attribute__ (( unused )); \
__table_entries; } )
#define __table_entries(table, idx)
Get start of linker table entries.
Definition: tables.h:249
#define __table_type(table)
Get linker table data type.
Definition: tables.h:187
uint8_t unused[32]
Unused.
Definition: eltorito.h:15

Get start of linker table entries.

Parameters
tableLinker table
idxSub-table index
Return values
entriesStart of entries

Definition at line 249 of file tables.h.

◆ __TABLE_ENTRIES

#define __TABLE_ENTRIES (   entries,
  table,
  idx 
)
Value:
__table_type ( table ) entries[0] \
__table_entry ( table, idx )
#define __table_type(table)
Get linker table data type.
Definition: tables.h:187

Declare start of linker table entries.

Parameters
entriesStart of entries
tableLinker table
idxSub-table index

Definition at line 262 of file tables.h.

◆ table_start

#define table_start (   table)    __table_entries ( table, 00 )

Get start of linker table.

Parameters
tableLinker table
Return values
startStart of linker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
struct frobnicator *frobs = table_start ( FROBNICATORS );

Definition at line 282 of file tables.h.

◆ TABLE_START

#define TABLE_START (   start,
  table 
)    __TABLE_ENTRIES ( start, table, 00 )

Declare start of linker table.

Parameters
startStart of linker table
tableLinker table

Definition at line 290 of file tables.h.

◆ table_end

#define table_end (   table)    __table_entries ( table, 99 )

Get end of linker table.

Parameters
tableLinker table
Return values
endEnd of linker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
struct frobnicator *frobs_end = table_end ( FROBNICATORS );

Definition at line 308 of file tables.h.

◆ TABLE_END

#define TABLE_END (   end,
  table 
)    __TABLE_ENTRIES ( end, table, 99 )

Declare end of linker table.

Parameters
endEnd of linker table
tableLinker table

Definition at line 316 of file tables.h.

◆ table_num_entries

#define table_num_entries (   table)
Value:
( ( unsigned int ) ( table_end ( table ) - \
table_start ( table ) ) )
#define table_end(table)
Get end of linker table.
Definition: tables.h:308

Get number of entries in linker table.

Parameters
tableLinker table
Return values
num_entriesNumber of entries in linker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
unsigned int num_frobs = table_num_entries ( FROBNICATORS );

Definition at line 335 of file tables.h.

◆ table_index

#define table_index (   table,
  entry 
)    ( ( unsigned int ) ( (entry) - table_start ( table ) ) )

Get index of entry within linker table.

Parameters
tableLinker table
entryTable entry

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
#define __frobnicator __table_entry ( FROBNICATORS, 01 )
struct frobnicator my_frob __frobnicator = {
...
};
unsigned int my_frob_idx = table_index ( FROBNICATORS, &my_frob );

Definition at line 361 of file tables.h.

◆ for_each_table_entry

#define for_each_table_entry (   pointer,
  table 
)
Value:
for ( (pointer) = table_start ( table ) ; \
(pointer) < table_end ( table ) ; \
(pointer)++ )
#define table_start(table)
Get start of linker table.
Definition: tables.h:282
#define table_end(table)
Get end of linker table.
Definition: tables.h:308

Iterate through all entries within a linker table.

Parameters
pointerEntry pointer
tableLinker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
struct frobnicator *frob;
for_each_table_entry ( frob, FROBNICATORS ) {
...
}

Definition at line 385 of file tables.h.

◆ for_each_table_entry_continue

#define for_each_table_entry_continue (   pointer,
  table 
)
Value:
for ( (pointer)++ ; \
(pointer) < table_end ( table ) ; \
(pointer)++ )
#define table_end(table)
Get end of linker table.
Definition: tables.h:308

Iterate through all remaining entries within a linker table.

Parameters
pointerEntry pointer, preset to most recent entry
tableLinker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
#define __frobnicator __table_entry ( FROBNICATORS, 01 )
struct frob my_frobnicator __frobnicator;
struct frobnicator *frob;
frob = &my_frobnicator;
for_each_table_entry_continue ( frob, FROBNICATORS ) {
...
}

Definition at line 414 of file tables.h.

◆ for_each_table_entry_reverse

#define for_each_table_entry_reverse (   pointer,
  table 
)
Value:
for ( (pointer) = ( table_end ( table ) - 1 ) ; \
(pointer) >= table_start ( table ) ; \
(pointer)-- )
#define table_start(table)
Get start of linker table.
Definition: tables.h:282
#define table_end(table)
Get end of linker table.
Definition: tables.h:308

Iterate through all entries within a linker table in reverse order.

Parameters
pointerEntry pointer
tableLinker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
struct frobnicator *frob;
for_each_table_entry_reverse ( frob, FROBNICATORS ) {
...
}

Definition at line 440 of file tables.h.

◆ for_each_table_entry_continue_reverse

#define for_each_table_entry_continue_reverse (   pointer,
  table 
)
Value:
for ( (pointer)-- ; \
(pointer) >= table_start ( table ) ; \
(pointer)-- )
#define table_start(table)
Get start of linker table.
Definition: tables.h:282

Iterate through all remaining entries within a linker table in reverse order.

Parameters
pointerEntry pointer, preset to most recent entry
tableLinker table

Example usage:

#define FROBNICATORS __table ( struct frobnicator, "frobnicators" )
#define __frobnicator __table_entry ( FROBNICATORS, 01 )
struct frob my_frobnicator __frobnicator;
struct frobnicator *frob;
frob = &my_frobnicator;
for_each_table_entry_continue_reverse ( frob, FROBNICATORS ) {
...
}

Definition at line 469 of file tables.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )