1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Symbol access for symbols set up by binman as part of the build.
4 *
5 * This allows C code to access the position of a particular part of the image
6 * assembled by binman.
7 *
8 * Copyright (c) 2017 Google, Inc
9 */
10
11#ifndef __BINMAN_SYM_H
12#define __BINMAN_SYM_H
13
14/* BSYM in little endian, keep in sync with tools/binman/elf.py */
15#define BINMAN_SYM_MAGIC_VALUE	(0x4d595342UL)
16#define BINMAN_SYM_MISSING	(-1UL)
17
18#if CONFIG_IS_ENABLED(BINMAN_SYMBOLS)
19
20/**
21 * binman_symname() - Internal function to get a binman symbol name
22 *
23 * @entry_name: Name of the entry to look for (e.g. 'u_boot_spl')
24 * @_prop_name: Property value to get from that entry (e.g. 'pos')
25 * @returns name of the symbol for that entry and property
26 */
27#define binman_symname(_entry_name, _prop_name) \
28	_binman_ ## _entry_name ## _prop_ ## _prop_name
29
30/**
31 * binman_sym_declare() - Declare a symbol that will be used at run-time
32 *
33 * @_type: Type f the symbol (e.g. unsigned long)
34 * @entry_name: Name of the entry to look for (e.g. 'u_boot_spl')
35 * @_prop_name: Property value to get from that entry (e.g. 'pos')
36 */
37#define binman_sym_declare(_type, _entry_name, _prop_name) \
38	_type binman_symname(_entry_name, _prop_name) \
39		__attribute__((aligned(4), unused, section(".binman_sym")))
40
41/**
42 * binman_sym_extern() - Declare a extern symbol that will be used at run-time
43 *
44 * @_type: Type f the symbol (e.g. unsigned long)
45 * @entry_name: Name of the entry to look for (e.g. 'u_boot_spl')
46 * @_prop_name: Property value to get from that entry (e.g. 'pos')
47 */
48#define binman_sym_extern(_type, _entry_name, _prop_name) \
49	extern _type binman_symname(_entry_name, _prop_name) \
50		__attribute__((aligned(4), unused, section(".binman_sym")))
51
52/**
53 * binman_sym_declare_optional() - Declare an optional symbol
54 *
55 * If this symbol cannot be provided by binman, an error will not be generated.
56 * Instead the image will be assigned the value BINMAN_SYM_MISSING.
57 *
58 * @_type: Type f the symbol (e.g. unsigned long)
59 * @entry_name: Name of the entry to look for (e.g. 'u_boot_spl')
60 * @_prop_name: Property value to get from that entry (e.g. 'pos')
61 */
62#define binman_sym_declare_optional(_type, _entry_name, _prop_name) \
63	_type binman_symname(_entry_name, _prop_name) \
64		__attribute__((aligned(4), weak, unused, \
65		section(".binman_sym")))
66
67/**
68 * _binman_sym_magic - Internal magic symbol for validity checks
69 *
70 * When building images, binman fills in this symbol with the magic
71 * value #defined above. This is used to check at runtime if the
72 * symbol values were filled in and are OK to use.
73 */
74extern unsigned long _binman_sym_magic;
75
76/**
77 * DECLARE_BINMAN_MAGIC_SYM - Declare the internal magic symbol
78 *
79 * This macro declares the _binman_sym_magic symbol so that it exists.
80 * Declaring it here would cause errors during linking due to multiple
81 * definitions of the symbol.
82 */
83#define DECLARE_BINMAN_MAGIC_SYM \
84	unsigned long _binman_sym_magic \
85		__attribute__((aligned(4), section(".binman_sym")))
86
87/**
88 * BINMAN_SYMS_OK - Check if the symbol values are valid
89 *
90 * This macro checks if the magic symbol's value is filled properly,
91 * which indicates that other symbols are OK to use as well.
92 *
93 * Return: 1 if binman symbol values are usable, 0 if not
94 */
95#define BINMAN_SYMS_OK \
96	(*(unsigned long *)&_binman_sym_magic == BINMAN_SYM_MAGIC_VALUE)
97
98/**
99 * binman_sym() - Access a previously declared symbol
100 *
101 * This is used to get the value of a symbol. E.g.:
102 *
103 *    unsigned long address = binman_sym(unsigned long, u_boot_spl, pos);
104 *
105 * @_type: Type f the symbol (e.g. unsigned long)
106 * @entry_name: Name of the entry to look for (e.g. 'u_boot_spl')
107 * @_prop_name: Property value to get from that entry (e.g. 'pos')
108 *
109 * Return: value of that property (filled in by binman), or
110 *	   BINMAN_SYM_MISSING if the value is unavailable
111 */
112#define binman_sym(_type, _entry_name, _prop_name) \
113	(BINMAN_SYMS_OK ? \
114	 (*(_type *)&binman_symname(_entry_name, _prop_name)) : \
115	 BINMAN_SYM_MISSING)
116
117#else /* !CONFIG_IS_ENABLED(BINMAN_SYMBOLS) */
118
119#define binman_sym_declare(_type, _entry_name, _prop_name)
120
121#define binman_sym_declare_optional(_type, _entry_name, _prop_name)
122
123#define binman_sym_extern(_type, _entry_name, _prop_name)
124
125#define DECLARE_BINMAN_MAGIC_SYM
126
127#define BINMAN_SYMS_OK (0)
128
129#define binman_sym(_type, _entry_name, _prop_name) BINMAN_SYM_MISSING
130
131#endif /* CONFIG_IS_ENABLED(BINMAN_SYMBOLS) */
132
133#endif
134