pw_build

Oveview

Integrations for Bazel, GN, and CMake. Main docs: https://pigweed.dev/pw_build.

Classes
class	pw::LinkerSymbol< T >

Macros
#define	PW_MUST_PLACE(isection)    _PW_MUST_PLACE(isection, __section_place_, __COUNTER__)
#define	PW_MUST_PLACE_SIZE(isection, isize)    _PW_MUST_PLACE_SIZE(isection, isize, __section_place_, __COUNTER__)
#define	PW_MUST_NOT_PLACE(isection)    _PW_MUST_NOT_PLACE(isection, __section_not_place_, __COUNTER__)

Functions
	pw::LinkerSymbol< T >::LinkerSymbol (const LinkerSymbol &)=delete
	pw::LinkerSymbol< T >::LinkerSymbol (const LinkerSymbol &&)=delete
LinkerSymbol &	pw::LinkerSymbol< T >::operator= (const LinkerSymbol &)=delete
LinkerSymbol &	pw::LinkerSymbol< T >::operator= (const LinkerSymbol &&)=delete
T	pw::LinkerSymbol< T >::value () const
	Gets the value of this linker symbol, converted to the specified type.

Macro Definition Documentation

PW_MUST_NOT_PLACE

#define PW_MUST_NOT_PLACE

(

isection

)

_PW_MUST_NOT_PLACE(isection, __section_not_place_, __COUNTER__)

PW_MUST_NOT_PLACE is a macro intended for use in linker scripts to ensure inputs are not present. It does the opposite of PW_MUST_PLACE.

This can be used to assert that no data members are added to an object file where there should be none. This is useful to ensure the safety of code that must run before data or bss init.

SECTIONS
{
  .zero_init_ram_early_init
  {
     PW_MUST_NOT_PLACE(*/libearly_memory_init.a:*.o(.bss*));
  }
}

When adding a new variable to a library marked with this macro it is expected to change to PW_MUST_PLACE

PW_MUST_PLACE

#define PW_MUST_PLACE

(

isection

)

_PW_MUST_PLACE(isection, __section_place_, __COUNTER__)

PW_MUST_PLACE is a macro intended for use in linker scripts to ensure inputs are non-zero sized.

Say you want to place a specific object file into a particular section. You can reference it by file path like:

SECTIONS
{
  .special_code
  {
    */src/path/libspecial_code.a:*.o
  }
}

This works but is fragile as it will silently break if the filename or path changes. Use PW_MUST_PLACE to get a linker assertion if the input is empty.

#include "pw_build/must_place.ld.h"
 
SECTIONS
{
  .special_code
  {
    PW_MUST_PLACE(*/src/path/libspecial_code.a:*.o)
  }
}

If the wildcard match fails PW_MUST_PLACE will generate an error telling you which input had no symbols.

Error: No symbols found in pattern below
*/src/path/libspecial_code.a:*.o

This could be because you had a typo, the path changed, or the symbols were dropped due to linker section garbage collection.In the latter case, you can choose to add KEEP() around your input to prevent garbage collection.

PW_MUST_PLACE_SIZE

#define PW_MUST_PLACE_SIZE	(		isection,
			isize
	)		_PW_MUST_PLACE_SIZE(isection, isize, __section_place_, __COUNTER__)

PW_MUST_PLACE_SIZE is a macro intended for use in linker scripts to ensure inputs are an expected size.

This is helpful for shared memory placements between multiple cores.

Imagine the following code is consumed while linking for 2 separate cores:

SECTIONS
{
  .shared_memory
  {
    */src/path/libspecial_code.a:shared_memory.o(.bss.shared_memory)
  }
}

This works but is fragile as it will silently break if the size of .bss.shared_memory changes on a single core. This may occur if compiler or other parameters are changed on one core and not the other.

#include "pw_build/must_place.ld.h"
 
SECTIONS
{
  .special_code
  {
    PW_MUST_PLACE_SIZE(*/src/path/libspecial_code.a:shared_memory.o(.bss.shared_memory), 16)
  }
}

If the wildcard match results in a different size from what was specified PW_MUST_PLACE_SIZE will generate an error.

Error: Pattern did not match expected size
*/src/path/libspecial_code.a:shared_memory.o(.bss.shared_memory)

This could be because you had a typo, the path changed, the symbols changed in size (either because the symbol was changed or compilation settings were changed), symbols were dropped due to linker section garbage collection. In the latter case, you can choose to add KEEP() around your input to prevent garbage collection.