iPXE
Defines | Functions
tables.h File Reference

Linker tables. More...

Go to the source code of this file.

Defines

#define __attribute__(x)
#define __table(type, name)   ( type, name )
 Declare a linker table.
#define __table_type(table)   __table_extract_type table
 Get linker table data type.
#define __table_extract_type(type, name)   type
#define __table_name(table)   __table_extract_name table
 Get linker table name.
#define __table_extract_name(type, name)   name
#define __table_section(table, idx)   ".tbl." __table_name ( table ) "." __table_str ( idx )
 Get linker table section name.
#define __table_str(x)   #x
#define __table_alignment(table)   __alignof__ ( __table_type ( 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_start(table)   __table_entries ( table, 00 )
 Get start of linker table.
#define table_end(table)   __table_entries ( table, 99 )
 Get end of linker table.
#define table_num_entries(table)
 Get number of entries in linker table.
#define table_index(table, entry)   ( ( unsigned int ) ( (entry) - table_start ( table ) ) )
 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.
#define ICC_ALIGN_HACK_FACTOR   128

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.


Define Documentation

#define __attribute__ (   x)

Definition at line 169 of file tables.h.

#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.

#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.

#define __table_extract_type (   type,
  name 
)    type

Definition at line 188 of file tables.h.

#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.

#define __table_extract_name (   type,
  name 
)    name

Definition at line 197 of file tables.h.

#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.

#define __table_str (   x)    #x

Definition at line 208 of file tables.h.

#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.

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

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.

#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:
tableLinker table
idxSub-table index
Return values:
entriesStart of entries

Definition at line 249 of file tables.h.

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

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

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

Referenced by resmux_child_close(), and sec80211_detect_ie().

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

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

Referenced by alloc_netdev(), dhcp_create_request(), netdev_close(), and netdev_has_configuration_rc().

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

Referenced by netdev_configuration().

#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:
pointerEntry pointer
tableLinker table

Example usage:

   #define FROBNICATORS __table ( struct frobnicator, "frobnicators" )

   struct frobnicator *frob;

   for_each_table_entry ( frob, FROBNICATORS ) {
     ...
   }

Definition at line 358 of file tables.h.

Referenced by acpi_install(), alloc_netdev(), applicable_setting(), apply_settings(), arp_find_protocol(), asn1_find_algorithm(), bios_keymap(), bofm_find_driver(), builtin_fetch(), console_configure(), discard_cache(), eapol_rx(), efi_driver_start(), efi_driver_supported(), efi_init(), efi_snp_hii_extract_config(), efi_snp_hii_questions(), eisa_probe(), 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(), 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(), init_processes(), initialise(), ipstat(), ipxe(), isabus_probe(), isapnp_probe(), mca_probe(), net80211_prepare_assoc(), net_rx(), netdev_configure_all(), netdev_notify(), parse_fc_els_handler(), parse_setting_name(), pci_find_driver(), 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_find_cipher_suite(), tls_send_client_hello(), tls_signature_hash_algorithm(), unquiesce(), usb_find_driver(), vmbus_find_driver(), wpa_find_cryptosystem(), wpa_find_kie(), xenbus_find_driver(), xfer_open_socket(), and xfer_uri_opener().

#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:
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 387 of file tables.h.

#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:
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 413 of file tables.h.

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

#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:
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 442 of file tables.h.

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

#define ICC_ALIGN_HACK_FACTOR   128

Definition at line 454 of file tables.h.


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )