Linker tables. More...

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
  serial_init();
#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

type	Data type
name	Table name

Return values

table Linker 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

table Linker table

Return values

type Data 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

table Linker table

Return values

name	Table 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

table	Linker table
idx	Sub-table index

Return values

section Section 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

table Linker table

Return values

align Alignment

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 ) ) ))

__attribute__

#define __attribute__(x)

Definition: tables.h:169

__table_section

#define __table_section(table, idx)

Get linker table section name.

Definition: tables.h:206

__table_alignment

#define __table_alignment(table)

Get linker table alignment.

Definition: tables.h:216

Declare a linker table entry.

Parameters

table	Linker table
idx	Sub-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; } )

Get start of linker table entries.

Parameters

table	Linker table
idx	Sub-table index

Return values

entries Start 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 )

__table_type

#define __table_type(table)

Get linker table data type.

Definition: tables.h:187

Declare start of linker table entries.

Parameters

entries	Start of entries
table	Linker table
idx	Sub-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

table Linker table

Return values

start Start 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

start	Start of linker table
table	Linker 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

table Linker table

Return values

end	End 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

end	End of linker table
table	Linker 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 ) ) )

table_end

#define table_end(table)

Get end of linker table.

Definition: tables.h:308

Get number of entries in linker table.

Parameters

table Linker table

Return values

num_entries Number 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

table	Linker table
entry	Table 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)++ )

Iterate through all entries within a linker table.

Parameters

pointer	Entry pointer
table	Linker 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)++ )

Iterate through all remaining entries within a linker table.

Parameters

pointer	Entry pointer, preset to most recent entry
table	Linker 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)-- )

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

Parameters

pointer	Entry pointer
table	Linker 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)-- )

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

Parameters

pointer	Entry pointer, preset to most recent entry
table	Linker 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 )

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ __attribute__

◆ __table

◆ __table_type

◆ __table_extract_type

◆ __table_name

◆ __table_extract_name

◆ __table_section

◆ __table_str

◆ __table_alignment

◆ __table_entry

◆ __table_entries

◆ __TABLE_ENTRIES

◆ table_start

◆ TABLE_START

◆ table_end

◆ TABLE_END

◆ table_num_entries

◆ table_index

◆ for_each_table_entry

◆ for_each_table_entry_continue

◆ for_each_table_entry_reverse

◆ for_each_table_entry_continue_reverse

Function Documentation

◆ FILE_LICENCE()

◆ attribute