1cd238effSMauro Carvalho Chehab====================== 2cd238effSMauro Carvalho ChehabKconfig macro language 3cd238effSMauro Carvalho Chehab====================== 4cd238effSMauro Carvalho Chehab 5cd238effSMauro Carvalho ChehabConcept 6cd238effSMauro Carvalho Chehab------- 7cd238effSMauro Carvalho Chehab 8cd238effSMauro Carvalho ChehabThe basic idea was inspired by Make. When we look at Make, we notice sort of 9cd238effSMauro Carvalho Chehabtwo languages in one. One language describes dependency graphs consisting of 10cd238effSMauro Carvalho Chehabtargets and prerequisites. The other is a macro language for performing textual 11cd238effSMauro Carvalho Chehabsubstitution. 12cd238effSMauro Carvalho Chehab 13cd238effSMauro Carvalho ChehabThere is clear distinction between the two language stages. For example, you 14cd238effSMauro Carvalho Chehabcan write a makefile like follows:: 15cd238effSMauro Carvalho Chehab 16cd238effSMauro Carvalho Chehab APP := foo 17cd238effSMauro Carvalho Chehab SRC := foo.c 18cd238effSMauro Carvalho Chehab CC := gcc 19cd238effSMauro Carvalho Chehab 20cd238effSMauro Carvalho Chehab $(APP): $(SRC) 21cd238effSMauro Carvalho Chehab $(CC) -o $(APP) $(SRC) 22cd238effSMauro Carvalho Chehab 23cd238effSMauro Carvalho ChehabThe macro language replaces the variable references with their expanded form, 24cd238effSMauro Carvalho Chehaband handles as if the source file were input like follows:: 25cd238effSMauro Carvalho Chehab 26cd238effSMauro Carvalho Chehab foo: foo.c 27cd238effSMauro Carvalho Chehab gcc -o foo foo.c 28cd238effSMauro Carvalho Chehab 29cd238effSMauro Carvalho ChehabThen, Make analyzes the dependency graph and determines the targets to be 30cd238effSMauro Carvalho Chehabupdated. 31cd238effSMauro Carvalho Chehab 32cd238effSMauro Carvalho ChehabThe idea is quite similar in Kconfig - it is possible to describe a Kconfig 33cd238effSMauro Carvalho Chehabfile like this:: 34cd238effSMauro Carvalho Chehab 35cd238effSMauro Carvalho Chehab CC := gcc 36cd238effSMauro Carvalho Chehab 37cd238effSMauro Carvalho Chehab config CC_HAS_FOO 38cd238effSMauro Carvalho Chehab def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC)) 39cd238effSMauro Carvalho Chehab 40cd238effSMauro Carvalho ChehabThe macro language in Kconfig processes the source file into the following 41cd238effSMauro Carvalho Chehabintermediate:: 42cd238effSMauro Carvalho Chehab 43cd238effSMauro Carvalho Chehab config CC_HAS_FOO 44cd238effSMauro Carvalho Chehab def_bool y 45cd238effSMauro Carvalho Chehab 46cd238effSMauro Carvalho ChehabThen, Kconfig moves onto the evaluation stage to resolve inter-symbol 47cd238effSMauro Carvalho Chehabdependency as explained in kconfig-language.txt. 48cd238effSMauro Carvalho Chehab 49cd238effSMauro Carvalho Chehab 50cd238effSMauro Carvalho ChehabVariables 51cd238effSMauro Carvalho Chehab--------- 52cd238effSMauro Carvalho Chehab 53cd238effSMauro Carvalho ChehabLike in Make, a variable in Kconfig works as a macro variable. A macro 54cd238effSMauro Carvalho Chehabvariable is expanded "in place" to yield a text string that may then be 55cd238effSMauro Carvalho Chehabexpanded further. To get the value of a variable, enclose the variable name in 56cd238effSMauro Carvalho Chehab$( ). The parentheses are required even for single-letter variable names; $X is 57cd238effSMauro Carvalho Chehaba syntax error. The curly brace form as in ${CC} is not supported either. 58cd238effSMauro Carvalho Chehab 59cd238effSMauro Carvalho ChehabThere are two types of variables: simply expanded variables and recursively 60cd238effSMauro Carvalho Chehabexpanded variables. 61cd238effSMauro Carvalho Chehab 62cd238effSMauro Carvalho ChehabA simply expanded variable is defined using the := assignment operator. Its 63cd238effSMauro Carvalho Chehabrighthand side is expanded immediately upon reading the line from the Kconfig 64cd238effSMauro Carvalho Chehabfile. 65cd238effSMauro Carvalho Chehab 66cd238effSMauro Carvalho ChehabA recursively expanded variable is defined using the = assignment operator. 67cd238effSMauro Carvalho ChehabIts righthand side is simply stored as the value of the variable without 68cd238effSMauro Carvalho Chehabexpanding it in any way. Instead, the expansion is performed when the variable 69cd238effSMauro Carvalho Chehabis used. 70cd238effSMauro Carvalho Chehab 71cd238effSMauro Carvalho ChehabThere is another type of assignment operator; += is used to append text to a 72cd238effSMauro Carvalho Chehabvariable. The righthand side of += is expanded immediately if the lefthand 73cd238effSMauro Carvalho Chehabside was originally defined as a simple variable. Otherwise, its evaluation is 74cd238effSMauro Carvalho Chehabdeferred. 75cd238effSMauro Carvalho Chehab 76cd238effSMauro Carvalho ChehabThe variable reference can take parameters, in the following form:: 77cd238effSMauro Carvalho Chehab 78cd238effSMauro Carvalho Chehab $(name,arg1,arg2,arg3) 79cd238effSMauro Carvalho Chehab 80cd238effSMauro Carvalho ChehabYou can consider the parameterized reference as a function. (more precisely, 81cd238effSMauro Carvalho Chehab"user-defined function" in contrast to "built-in function" listed below). 82cd238effSMauro Carvalho Chehab 83cd238effSMauro Carvalho ChehabUseful functions must be expanded when they are used since the same function is 84cd238effSMauro Carvalho Chehabexpanded differently if different parameters are passed. Hence, a user-defined 85cd238effSMauro Carvalho Chehabfunction is defined using the = assignment operator. The parameters are 86cd238effSMauro Carvalho Chehabreferenced within the body definition with $(1), $(2), etc. 87cd238effSMauro Carvalho Chehab 88cd238effSMauro Carvalho ChehabIn fact, recursively expanded variables and user-defined functions are the same 89cd238effSMauro Carvalho Chehabinternally. (In other words, "variable" is "function with zero argument".) 90cd238effSMauro Carvalho ChehabWhen we say "variable" in a broad sense, it includes "user-defined function". 91cd238effSMauro Carvalho Chehab 92cd238effSMauro Carvalho Chehab 93cd238effSMauro Carvalho ChehabBuilt-in functions 94cd238effSMauro Carvalho Chehab------------------ 95cd238effSMauro Carvalho Chehab 96cd238effSMauro Carvalho ChehabLike Make, Kconfig provides several built-in functions. Every function takes a 97cd238effSMauro Carvalho Chehabparticular number of arguments. 98cd238effSMauro Carvalho Chehab 99cd238effSMauro Carvalho ChehabIn Make, every built-in function takes at least one argument. Kconfig allows 100cd238effSMauro Carvalho Chehabzero argument for built-in functions, such as $(fileno), $(lineno). You could 101cd238effSMauro Carvalho Chehabconsider those as "built-in variable", but it is just a matter of how we call 102cd238effSMauro Carvalho Chehabit after all. Let's say "built-in function" here to refer to natively supported 103cd238effSMauro Carvalho Chehabfunctionality. 104cd238effSMauro Carvalho Chehab 105cd238effSMauro Carvalho ChehabKconfig currently supports the following built-in functions. 106cd238effSMauro Carvalho Chehab 107cd238effSMauro Carvalho Chehab - $(shell,command) 108cd238effSMauro Carvalho Chehab 109cd238effSMauro Carvalho Chehab The "shell" function accepts a single argument that is expanded and passed 110cd238effSMauro Carvalho Chehab to a subshell for execution. The standard output of the command is then read 111cd238effSMauro Carvalho Chehab and returned as the value of the function. Every newline in the output is 112cd238effSMauro Carvalho Chehab replaced with a space. Any trailing newlines are deleted. The standard error 113cd238effSMauro Carvalho Chehab is not returned, nor is any program exit status. 114cd238effSMauro Carvalho Chehab 115cd238effSMauro Carvalho Chehab - $(info,text) 116cd238effSMauro Carvalho Chehab 117cd238effSMauro Carvalho Chehab The "info" function takes a single argument and prints it to stdout. 118cd238effSMauro Carvalho Chehab It evaluates to an empty string. 119cd238effSMauro Carvalho Chehab 120cd238effSMauro Carvalho Chehab - $(warning-if,condition,text) 121cd238effSMauro Carvalho Chehab 122cd238effSMauro Carvalho Chehab The "warning-if" function takes two arguments. If the condition part is "y", 123cd238effSMauro Carvalho Chehab the text part is sent to stderr. The text is prefixed with the name of the 124cd238effSMauro Carvalho Chehab current Kconfig file and the current line number. 125cd238effSMauro Carvalho Chehab 126cd238effSMauro Carvalho Chehab - $(error-if,condition,text) 127cd238effSMauro Carvalho Chehab 128cd238effSMauro Carvalho Chehab The "error-if" function is similar to "warning-if", but it terminates the 129cd238effSMauro Carvalho Chehab parsing immediately if the condition part is "y". 130cd238effSMauro Carvalho Chehab 131cd238effSMauro Carvalho Chehab - $(filename) 132cd238effSMauro Carvalho Chehab 133cd238effSMauro Carvalho Chehab The 'filename' takes no argument, and $(filename) is expanded to the file 134cd238effSMauro Carvalho Chehab name being parsed. 135cd238effSMauro Carvalho Chehab 136cd238effSMauro Carvalho Chehab - $(lineno) 137cd238effSMauro Carvalho Chehab 138cd238effSMauro Carvalho Chehab The 'lineno' takes no argument, and $(lineno) is expanded to the line number 139cd238effSMauro Carvalho Chehab being parsed. 140cd238effSMauro Carvalho Chehab 141cd238effSMauro Carvalho Chehab 142cd238effSMauro Carvalho ChehabMake vs Kconfig 143cd238effSMauro Carvalho Chehab--------------- 144cd238effSMauro Carvalho Chehab 145cd238effSMauro Carvalho ChehabKconfig adopts Make-like macro language, but the function call syntax is 146cd238effSMauro Carvalho Chehabslightly different. 147cd238effSMauro Carvalho Chehab 148cd238effSMauro Carvalho ChehabA function call in Make looks like this:: 149cd238effSMauro Carvalho Chehab 150cd238effSMauro Carvalho Chehab $(func-name arg1,arg2,arg3) 151cd238effSMauro Carvalho Chehab 152cd238effSMauro Carvalho ChehabThe function name and the first argument are separated by at least one 153cd238effSMauro Carvalho Chehabwhitespace. Then, leading whitespaces are trimmed from the first argument, 154cd238effSMauro Carvalho Chehabwhile whitespaces in the other arguments are kept. You need to use a kind of 155cd238effSMauro Carvalho Chehabtrick to start the first parameter with spaces. For example, if you want 156cd238effSMauro Carvalho Chehabto make "info" function print " hello", you can write like follows:: 157cd238effSMauro Carvalho Chehab 158cd238effSMauro Carvalho Chehab empty := 159cd238effSMauro Carvalho Chehab space := $(empty) $(empty) 160cd238effSMauro Carvalho Chehab $(info $(space)$(space)hello) 161cd238effSMauro Carvalho Chehab 162cd238effSMauro Carvalho ChehabKconfig uses only commas for delimiters, and keeps all whitespaces in the 163cd238effSMauro Carvalho Chehabfunction call. Some people prefer putting a space after each comma delimiter:: 164cd238effSMauro Carvalho Chehab 165cd238effSMauro Carvalho Chehab $(func-name, arg1, arg2, arg3) 166cd238effSMauro Carvalho Chehab 167cd238effSMauro Carvalho ChehabIn this case, "func-name" will receive " arg1", " arg2", " arg3". The presence 168cd238effSMauro Carvalho Chehabof leading spaces may matter depending on the function. The same applies to 169cd238effSMauro Carvalho ChehabMake - for example, $(subst .c, .o, $(sources)) is a typical mistake; it 170cd238effSMauro Carvalho Chehabreplaces ".c" with " .o". 171cd238effSMauro Carvalho Chehab 172cd238effSMauro Carvalho ChehabIn Make, a user-defined function is referenced by using a built-in function, 173cd238effSMauro Carvalho Chehab'call', like this:: 174cd238effSMauro Carvalho Chehab 175cd238effSMauro Carvalho Chehab $(call my-func,arg1,arg2,arg3) 176cd238effSMauro Carvalho Chehab 177cd238effSMauro Carvalho ChehabKconfig invokes user-defined functions and built-in functions in the same way. 178cd238effSMauro Carvalho ChehabThe omission of 'call' makes the syntax shorter. 179cd238effSMauro Carvalho Chehab 180cd238effSMauro Carvalho ChehabIn Make, some functions treat commas verbatim instead of argument separators. 181cd238effSMauro Carvalho ChehabFor example, $(shell echo hello, world) runs the command "echo hello, world". 182cd238effSMauro Carvalho ChehabLikewise, $(info hello, world) prints "hello, world" to stdout. You could say 183cd238effSMauro Carvalho Chehabthis is _useful_ inconsistency. 184cd238effSMauro Carvalho Chehab 185cd238effSMauro Carvalho ChehabIn Kconfig, for simpler implementation and grammatical consistency, commas that 186cd238effSMauro Carvalho Chehabappear in the $( ) context are always delimiters. It means:: 187cd238effSMauro Carvalho Chehab 188cd238effSMauro Carvalho Chehab $(shell, echo hello, world) 189cd238effSMauro Carvalho Chehab 190cd238effSMauro Carvalho Chehabis an error because it is passing two parameters where the 'shell' function 191cd238effSMauro Carvalho Chehabaccepts only one. To pass commas in arguments, you can use the following trick:: 192cd238effSMauro Carvalho Chehab 193cd238effSMauro Carvalho Chehab comma := , 194cd238effSMauro Carvalho Chehab $(shell, echo hello$(comma) world) 195cd238effSMauro Carvalho Chehab 196cd238effSMauro Carvalho Chehab 197cd238effSMauro Carvalho ChehabCaveats 198cd238effSMauro Carvalho Chehab------- 199cd238effSMauro Carvalho Chehab 200cd238effSMauro Carvalho ChehabA variable (or function) cannot be expanded across tokens. So, you cannot use 201cd238effSMauro Carvalho Chehaba variable as a shorthand for an expression that consists of multiple tokens. 202cd238effSMauro Carvalho ChehabThe following works:: 203cd238effSMauro Carvalho Chehab 204cd238effSMauro Carvalho Chehab RANGE_MIN := 1 205cd238effSMauro Carvalho Chehab RANGE_MAX := 3 206cd238effSMauro Carvalho Chehab 207cd238effSMauro Carvalho Chehab config FOO 208cd238effSMauro Carvalho Chehab int "foo" 209cd238effSMauro Carvalho Chehab range $(RANGE_MIN) $(RANGE_MAX) 210cd238effSMauro Carvalho Chehab 211cd238effSMauro Carvalho ChehabBut, the following does not work:: 212cd238effSMauro Carvalho Chehab 213cd238effSMauro Carvalho Chehab RANGES := 1 3 214cd238effSMauro Carvalho Chehab 215cd238effSMauro Carvalho Chehab config FOO 216cd238effSMauro Carvalho Chehab int "foo" 217cd238effSMauro Carvalho Chehab range $(RANGES) 218cd238effSMauro Carvalho Chehab 219cd238effSMauro Carvalho ChehabA variable cannot be expanded to any keyword in Kconfig. The following does 220cd238effSMauro Carvalho Chehabnot work:: 221cd238effSMauro Carvalho Chehab 222cd238effSMauro Carvalho Chehab MY_TYPE := tristate 223cd238effSMauro Carvalho Chehab 224cd238effSMauro Carvalho Chehab config FOO 225cd238effSMauro Carvalho Chehab $(MY_TYPE) "foo" 226cd238effSMauro Carvalho Chehab default y 227cd238effSMauro Carvalho Chehab 228cd238effSMauro Carvalho ChehabObviously from the design, $(shell command) is expanded in the textual 229cd238effSMauro Carvalho Chehabsubstitution phase. You cannot pass symbols to the 'shell' function. 230cd238effSMauro Carvalho Chehab 231cd238effSMauro Carvalho ChehabThe following does not work as expected:: 232cd238effSMauro Carvalho Chehab 233cd238effSMauro Carvalho Chehab config ENDIAN_FLAG 234cd238effSMauro Carvalho Chehab string 235cd238effSMauro Carvalho Chehab default "-mbig-endian" if CPU_BIG_ENDIAN 236cd238effSMauro Carvalho Chehab default "-mlittle-endian" if CPU_LITTLE_ENDIAN 237cd238effSMauro Carvalho Chehab 238cd238effSMauro Carvalho Chehab config CC_HAS_ENDIAN_FLAG 239cd238effSMauro Carvalho Chehab def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG) 240cd238effSMauro Carvalho Chehab 241cd238effSMauro Carvalho ChehabInstead, you can do like follows so that any function call is statically 242cd238effSMauro Carvalho Chehabexpanded:: 243cd238effSMauro Carvalho Chehab 244cd238effSMauro Carvalho Chehab config CC_HAS_ENDIAN_FLAG 245cd238effSMauro Carvalho Chehab bool 246cd238effSMauro Carvalho Chehab default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN 247cd238effSMauro Carvalho Chehab default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN 248