docs/dev/modular_format.rst - llvm-project/libc - Git at Google

 .. _modular_format:

 ======================
 Modular format strings
 ======================

 Introduction
 ============

 Several C standard library functions (most notably, ``printf`` and ``scanf``),
 present a large amount of related features to the caller configured via a
 format string. This benefits code size at the caller, since format strings are
 typically quite dense, and the equivalent of many individual calls can be
 performed with only one. Overall this is a benefit, since to a function calls
 typically outnumber the one definition of that function.

 However, the implementations of various libc features gated behind aspects of
 those format strings can be large enough that they completely swamp the
 programs that call them. Floating point and errno conversion in particular can
 involve large tables which may be wholly dead. However, due to the format
 string structure, this code is dead in a way previously invisible to the
 compiler.

 To address this, an clang attribute was introduced: ``modular_format(<impl_fn>,
 <impl_name>, <aspects>...)``. This adds to the semantics of the existing
 ``format`` attribute (which must also be present, if implicitly.) The first
 argument is a symbol naming a modular version of the implementation; this
 version only weakly refers to "aspects" of the implementation that may not be
 necessary for certain format strings. The second argument is general
 "implementation name" string, and the remaining arguments are a list of handled
 aspects of the format string. When the compiler sees that a given call only
 needs a fixed set of aspects of the implementation, it may redirect the call to
 the implementation function and emit a series of relocations to symbols named
 ``<impl_name>_<aspect>``. These in turn bring the needed aspects of the call
 into the link. The default entrypoints fall the modular ones, except they bring
 in every possible implementation aspect.

 Mechanism
 =========

 This functionality is currently gated behind ``LIBC_COPT_PRINTF_MODULAR``. When
 set, the ``printf``-family functions gain modular variants, and the regular
 variants are modified to call them and emit NONE relocations against all
 implementation aspects.

 The implementation aspects are defined in headers using the
 ``LIBC_PRINTF_MODULE((<decl>), { <body> })`` macro. If
 ``LIBC_COPT_PRINTF_MODULAR`` is not defined, then this macro makes these
 ``LIBC_INLINE`` definitions as per usual. Otherwise, for normal usage, these
 become weak declarations, which causes any references to the module to become
 weak. The implementations are moved to a dedicated impl file for groups of
 modules. These define the aspect symbol and the module impls by defining
 ``LIBC_PRINTF_DEFINE_MODULES`` before including the header. This causes the to
 be brought into the link exactly when the aspect symbol is referenced.

 Template functions present a special complication: the implementation must
 instantiate them for any value that may be used. Since the purpose of the
 templates is to implement a fixed interface, the possible arguments should
 always be fixed and finite. Accordingly, libc contains def files to enumerate
 possible arguments and provide handling for each. Templates are instantiated in
 the headers whenever ``LIBC_PRINTF_DEFINE_MODULES`` is defined.

 libc and the compiler may understand different sets of aspect names, but their
 understanding of what an aspect name means must be identical. libc reports the
 set of aspect names that it needs a verdict on, and the compiler will only
 provide a verdict for those aspects. If libc asks for a verdict on an aspect
 unknown to the compiler, the aspect must be summarily considered to be
 required.
	.. _modular_format:

	======================
	Modular format strings
	======================

	Introduction
	============

	Several C standard library functions (most notably, ``printf`` and ``scanf``),
	present a large amount of related features to the caller configured via a
	format string. This benefits code size at the caller, since format strings are
	typically quite dense, and the equivalent of many individual calls can be
	performed with only one. Overall this is a benefit, since to a function calls
	typically outnumber the one definition of that function.

	However, the implementations of various libc features gated behind aspects of
	those format strings can be large enough that they completely swamp the
	programs that call them. Floating point and errno conversion in particular can
	involve large tables which may be wholly dead. However, due to the format
	string structure, this code is dead in a way previously invisible to the
	compiler.

	To address this, an clang attribute was introduced: ``modular_format(<impl_fn>,
	<impl_name>, <aspects>...)``. This adds to the semantics of the existing
	``format`` attribute (which must also be present, if implicitly.) The first
	argument is a symbol naming a modular version of the implementation; this
	version only weakly refers to "aspects" of the implementation that may not be
	necessary for certain format strings. The second argument is general
	"implementation name" string, and the remaining arguments are a list of handled
	aspects of the format string. When the compiler sees that a given call only
	needs a fixed set of aspects of the implementation, it may redirect the call to
	the implementation function and emit a series of relocations to symbols named
	``<impl_name>_<aspect>``. These in turn bring the needed aspects of the call
	into the link. The default entrypoints fall the modular ones, except they bring
	in every possible implementation aspect.

	Mechanism
	=========

	This functionality is currently gated behind ``LIBC_COPT_PRINTF_MODULAR``. When
	set, the ``printf``-family functions gain modular variants, and the regular
	variants are modified to call them and emit NONE relocations against all
	implementation aspects.

	The implementation aspects are defined in headers using the
	``LIBC_PRINTF_MODULE((<decl>), { <body> })`` macro. If
	``LIBC_COPT_PRINTF_MODULAR`` is not defined, then this macro makes these
	``LIBC_INLINE`` definitions as per usual. Otherwise, for normal usage, these
	become weak declarations, which causes any references to the module to become
	weak. The implementations are moved to a dedicated impl file for groups of
	modules. These define the aspect symbol and the module impls by defining
	``LIBC_PRINTF_DEFINE_MODULES`` before including the header. This causes the to
	be brought into the link exactly when the aspect symbol is referenced.

	Template functions present a special complication: the implementation must
	instantiate them for any value that may be used. Since the purpose of the
	templates is to implement a fixed interface, the possible arguments should
	always be fixed and finite. Accordingly, libc contains def files to enumerate
	possible arguments and provide handling for each. Templates are instantiated in
	the headers whenever ``LIBC_PRINTF_DEFINE_MODULES`` is defined.

	libc and the compiler may understand different sets of aspect names, but their
	understanding of what an aspect name means must be identical. libc reports the
	set of aspect names that it needs a verdict on, and the compiler will only
	provide a verdict for those aspects. If libc asks for a verdict on an aspect
	unknown to the compiler, the aspect must be summarily considered to be
	required.