tables.h File Reference

Linker tables. More...

Go to the source code of this file.

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

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)

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 170 of file tables.h.

__table

#define __table	(		type,
			name )

Value:

( type, name )

Declare a linker table.

Parameters

type	Data type
name	Table name

Return values

table

Linker table

Definition at line 180 of file tables.h.

__table_type

#define __table_type

(

table

)

Value:

__table_extract_type table

Get linker table data type.

Parameters

table

Linker table

Return values

type

Data type

Definition at line 188 of file tables.h.

__table_extract_type

#define __table_extract_type	(		type,
			name )

Value:

type

Definition at line 189 of file tables.h.

__table_name

#define __table_name

(

table

)

Value:

__table_extract_name table

Get linker table name.

Parameters

table

Linker table

Return values

name	Table name

Definition at line 197 of file tables.h.

__table_extract_name

#define __table_extract_name	(		type,
			name )

Value:

name

Definition at line 198 of file tables.h.

__table_section

#define __table_section	(		table,
			idx )

Value:

        ".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 207 of file tables.h.

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

__table_str

#define __table_str

(

x

)

Value:

#x

Definition at line 209 of file tables.h.

__table_alignment

#define __table_alignment

(

table

)

Value:

__alignof__ ( __table_type ( table ) )

Get linker table alignment.

Parameters

table

Linker table

Return values

align

Alignment

Definition at line 217 of file tables.h.

__table_entry

#define __table_entry	(		table,
			idx )

Value:

        __attribute__ (( __section__ ( __table_section ( table, idx ) ),\
                         __aligned__ ( __table_alignment ( table ) ) ))

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 239 of file tables.h.

#define __table_entry( table, idx )                                     \
        __attribute__ (( __section__ ( __table_section ( table, idx ) ),\
                         __aligned__ ( __table_alignment ( table ) ) ))

__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 250 of file tables.h.

#define __table_entries( table, idx ) ( {                               \
        static __table_type ( table ) __table_entries[0]                \
                __table_entry ( table, idx )                            \
                __attribute__ (( unused ));                             \
        __table_entries; } )

__TABLE_ENTRIES

#define __TABLE_ENTRIES	(		entries,
			table,
			idx )

Value:

        __table_type ( table ) entries[0]                           \
                __table_entry ( table, idx )

Declare start of linker table entries.

Parameters

entries	Start of entries
table	Linker table
idx	Sub-table index

Definition at line 263 of file tables.h.

#define __TABLE_ENTRIES( entries, table, idx )                          \
        __table_type ( table ) entries[0]                               \
                __table_entry ( table, idx )

table_start

#define table_start

(

table

)

Value:

__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 283 of file tables.h.

Referenced by dhcp_create_request(), resolv(), and sec80211_detect_ie().

TABLE_START

#define TABLE_START	(		start,
			table )

Value:

__TABLE_ENTRIES ( start, table, 00 )

Declare start of linker table.

Parameters

start	Start of linker table
table	Linker table

Definition at line 291 of file tables.h.

table_end

#define table_end

(

table

)

Value:

__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 309 of file tables.h.

Referenced by netdev_priv_offset(), pcicloud_api(), resmux_child_close(), and sec80211_detect_ie().

TABLE_END

#define TABLE_END	(		end,
			table )

Value:

__TABLE_ENTRIES ( end, table, 99 )

Declare end of linker table.

Parameters

end	End of linker table
table	Linker table

Definition at line 317 of file tables.h.

table_num_entries

#define table_num_entries

(

table

)

Value:

        ( ( unsigned int ) ( table_end ( table ) -                     \
                             table_start ( table ) ) )

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 336 of file tables.h.

#define table_num_entries( table )                                      \
        ( ( unsigned int ) ( table_end ( table ) -                      \
                             table_start ( table ) ) )

Referenced by dhcp_create_request(), eap_tx_nak(), netdev_close(), netdev_has_configuration_rc(), and netdev_priv_offset().

table_index

#define table_index	(		table,
			entry )

Value:

        ( ( 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 362 of file tables.h.

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

Referenced by netdev_configuration().

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 386 of file tables.h.

#define for_each_table_entry( pointer, table )                          \
        for ( (pointer) = table_start ( table ) ;                       \
              (pointer) < table_end ( table ) ;                         \
              (pointer)++ )

Referenced by acpi_install(), alloc_netdev(), applicable_setting(), apply_settings(), arp_find_protocol(), asn1_find_algorithm(), bofm_find_driver(), builtin_fetch(), console_configure(), discard_cache(), dt_find_driver(), eap_rx_request(), eap_tx_nak(), eapol_rx(), efi_driver_start(), efi_driver_supported(), efi_init(), efi_snp_hii_extract_config(), efi_snp_hii_questions(), efi_veto_hp_xhci(), eisa_probe(), entropy_enable_working(), entropy_sample_test_exec(), execv(), fc_els_detect(), fc_els_prli_descriptor(), fc_xchg_respond(), find_error(), find_gdb_transport(), find_netdev_configurator(), find_pxe_api_call(), find_setting(), find_setting_type(), free_image(), guestinfo_fetch(), has_input(), help_exec(), http_authentication(), http_format_accept_encoding(), http_format_headers(), http_parse_content_encoding(), http_parse_header(), http_parse_transfer_encoding(), http_scheme(), ib_mi_handle(), ib_notify(), icmp_echo_protocol(), icmpv6_handler(), image_probe(), imgstat(), init_processes(), initialise(), ipstat(), ipxe(), isabus_probe(), isapnp_probe(), keymap_find(), mca_probe(), memmap_update_used(), net80211_prepare_assoc(), net_rx(), netdev_configure_all(), netdev_notify(), parse_fc_els_handler(), parse_setting_name(), pci_find_driver(), pcicloud_find(), peerdisc_socket_close(), peerdisc_socket_open(), peerdisc_socket_tx(), probe_devices(), profstat(), putchar(), pxenv_file_api_check(), quiesce(), register_ibdev(), register_netdev(), route(), rsa_find_prefix(), rtl818x_probe(), run_all_tests(), sec80211_install(), select_setting_row(), sock_aton(), sock_ntoa(), startup(), tcpip_net_protocol(), tcpip_rx(), timer_probe(), tls_client_hello(), tls_find_cipher_suite(), tls_find_named_curve(), tls_signature_hash_algorithm(), tls_signature_hash_digest(), tls_signature_hash_pubkey(), unquiesce(), usb_find_driver(), vmbus_find_driver(), wpa_find_cryptosystem(), wpa_find_kie(), xenbus_find_driver(), xfer_open_socket(), and xfer_uri_opener().

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 415 of file tables.h.

#define for_each_table_entry_continue( pointer, table )                 \
        for ( (pointer)++ ;                                             \
              (pointer) < table_end ( table ) ;                         \
              (pointer)++ )

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 441 of file tables.h.

#define for_each_table_entry_reverse( pointer, table )                  \
        for ( (pointer) = ( table_end ( table ) - 1 ) ;                 \
              (pointer) >= table_start ( table ) ;                      \
              (pointer)-- )

Referenced by efi_driver_connect(), shutdown(), unregister_ibdev(), and unregister_netdev().

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 470 of file tables.h.

#define for_each_table_entry_continue_reverse( pointer, table )         \
        for ( (pointer)-- ;                                             \
              (pointer) >= table_start ( table ) ;                      \
              (pointer)-- )

Referenced by netdev_priv_offset(), peerdisc_socket_open(), register_ibdev(), and register_netdev().

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)