xfa.h File Reference

Cross File Arrays. More...

Detailed Description

Cross File Arrays.

This macro, in combination with an entry in the linker scripts, allows the definition of constant arrays to be spread over multiple C compilation units. These arrays are called "cross-file arrays" or short xfa.

Warning
This feature is experimental!
This API is considered experimental and will probably change without notice!
Author
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Definition in file xfa.h.

#include <inttypes.h>
#include "compiler_hints.h"
+ Include dependency graph for xfa.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define _XFA(name, prio)
 helper macro for other XFA_* macros More...
 
#define _XFA_CONST(name, prio)
 helper macro for other XFA_* macros More...
 
#define XFA_INIT_CONST(type, name)
 Define a read-only cross-file array. More...
 
#define XFA_INIT(type, name)
 Define a writable cross-file array. More...
 
#define XFA_USE_CONST(type, name)    XFA_USE(type, name)
 Declare an external read-only cross-file array. More...
 
#define XFA_USE(type, name)
 Declare an external writable cross-file array. More...
 
#define XFA(xfa_name, prio)   _XFA(xfa_name, 5_ ## prio)
 Define variable in writable cross-file array. More...
 
#define XFA_CONST(xfa_name, prio)   _XFA_CONST(xfa_name, 5_ ## prio)
 Define variable in read-only cross-file array. More...
 
#define XFA_ADD_PTR(xfa_name, prio, name, entry)
 Add a pointer to cross-file array. More...
 
#define XFA_LEN(type, name)
 Calculate number of entries in cross-file array. More...
 

Macro Definition Documentation

◆ _XFA

#define _XFA (   name,
  prio 
)
Value:
NO_SANITIZE_ARRAY \
__attribute__((used, section(".xfa." #name "." #prio)))

helper macro for other XFA_* macros

Definition at line 46 of file xfa.h.

◆ _XFA_CONST

#define _XFA_CONST (   name,
  prio 
)
Value:
NO_SANITIZE_ARRAY \
__attribute__((used, section(".roxfa." #name "." #prio)))

helper macro for other XFA_* macros

Definition at line 55 of file xfa.h.

◆ XFA

#define XFA (   xfa_name,
  prio 
)    _XFA(xfa_name, 5_ ## prio)

Define variable in writable cross-file array.

Variables will end up sorted by prio.

Add this to the type in a variable definition, e.g.:

XFA(driver_params, 0) driver_params_t _onboard = { .pin=42 };
Parameters
[in]xfa_namename of the xfa
[in]priopriority within the xfa

Definition at line 144 of file xfa.h.

◆ XFA_ADD_PTR

#define XFA_ADD_PTR (   xfa_name,
  prio,
  name,
  entry 
)
Value:
_XFA_CONST(xfa_name, 5_ ## prio) \
__typeof__(entry) xfa_name ## _ ## prio ## _ ## name = entry
#define _XFA_CONST(name, prio)
helper macro for other XFA_* macros
Definition: xfa.h:55

Add a pointer to cross-file array.

Pointers will end up sorted by prio.

Note
This implementation uses the typeof() C extension. It is available both in GCC and LLVM, and both don't complain with plain "-std=c11". If deemed necessary, use of typeof can be removed and the type can be added as parameter, at the cost of much less convenience.
Parameters
[in]xfa_namename of the xfa
[in]priopriority within the xfa
[in]namesymbol name
[in]entrypointer variable to add to xfa

Definition at line 176 of file xfa.h.

◆ XFA_CONST

#define XFA_CONST (   xfa_name,
  prio 
)    _XFA_CONST(xfa_name, 5_ ## prio)

Define variable in read-only cross-file array.

Variables will end up sorted by prio.

Add this to the type in a variable definition, e.g.:

XFA(driver_params, 0) driver_params_t _onboard = { .pin=42 };
Parameters
[in]xfa_namename of the xfa
[in]priopriority within the xfa

Definition at line 158 of file xfa.h.

◆ XFA_INIT

#define XFA_INIT (   type,
  name 
)
Value:
_Pragma("GCC diagnostic push") \
_Pragma("GCC diagnostic ignored \"-Wpedantic\"") \
_XFA(name, 0_) type name [0] = {}; \
_XFA(name, 9_) type name ## _end [0] = {}; \
_Pragma("GCC diagnostic pop") \
extern const unsigned __xfa_dummy

Define a writable cross-file array.

This macro defines the symbols necessary to use XFA_START() and XFA_END(). It needs to be part of one single compilation unit.

The pragmas prevent these errors:

error: ISO C forbids empty initializer braces
error: ISO C forbids zero-size array ‘xfatest_end’
Parameters
[in]typetype of the cross-file array
[in]namename of the cross-file array

Definition at line 95 of file xfa.h.

◆ XFA_INIT_CONST

#define XFA_INIT_CONST (   type,
  name 
)
Value:
_Pragma("GCC diagnostic push") \
_Pragma("GCC diagnostic ignored \"-Wpedantic\"") \
_XFA_CONST(name, 0_) type name [0] = {}; \
_XFA_CONST(name, 9_) type name ## _end [0] = {}; \
_Pragma("GCC diagnostic pop") \
extern const unsigned __xfa_dummy

Define a read-only cross-file array.

This macro defines the symbols necessary to use XFA_START() and XFA_END(). It needs to be part of one single compilation unit.

The pragmas prevent these errors:

error: ISO C forbids empty initializer braces
error: ISO C forbids zero-size array ‘xfatest_const_end’
Parameters
[in]typetype of the cross-file array
[in]namename of the cross-file array

Definition at line 73 of file xfa.h.

◆ XFA_LEN

#define XFA_LEN (   type,
  name 
)
Value:
(((uintptr_t)name ## _end - (uintptr_t)name) / \
sizeof(type))

Calculate number of entries in cross-file array.

Definition at line 183 of file xfa.h.

◆ XFA_USE

#define XFA_USE (   type,
  name 
)
Value:
extern type name []; \
extern type name ## _end []

Declare an external writable cross-file array.

This macro defines the symbols necessary to use XFA_START() and XFA_END(). Think of this as XFA_INIT() but with "extern" keyword. It is supposed to be used in compilation units where the cross file array is being accessed, but not defined using XFA_INIT.

Parameters
[in]typetype of the cross-file array
[in]namename of the cross-file array

Definition at line 128 of file xfa.h.

◆ XFA_USE_CONST

#define XFA_USE_CONST (   type,
  name 
)     XFA_USE(type, name)

Declare an external read-only cross-file array.

This macro defines the symbols necessary to use XFA_START() and XFA_END(). Think of this as XFA_INIT() but with "extern" keyword. It is supposed to be used in compilation units where the cross file array is being accessed, but not defined using XFA_INIT.

Parameters
[in]typetype of the cross-file array
[in]namename of the cross-file array

Definition at line 114 of file xfa.h.