Kconfig Macro Language

매크로 언어의 개념과 평가 단계

기본 발상은 Make에서 가져왔습니다. Make에는 사실상 두 언어가 함께 있습니다. 하나는 target과 prerequisite로 이루어진 dependency graph를 기술하고, 다른 하나는 textual substitution을 수행하는 macro language입니다.

이 두 언어의 처리 단계는 분명히 구분됩니다. 예제 makefile에서 `APP := foo`, `SRC := foo.c`, `CC := gcc`를 정의하고 `$(APP): $(SRC)`와 `$(CC) -o $(APP) $(SRC)`를 쓰면, macro language가 variable reference를 먼저 확장합니다.

APP := foo
SRC := foo.c
CC := gcc

$(APP): $(SRC)
        $(CC) -o $(APP) $(SRC)

확장 결과는 `foo: foo.c`와 `gcc -o foo foo.c`가 입력된 것처럼 처리됩니다. 그 뒤에야 Make가 dependency graph를 분석하고 갱신할 target을 결정합니다.

Kconfig도 같은 생각을 따릅니다. `CC := gcc`와 `def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))`를 작성하면 macro language가 source를 먼저 처리합니다. shell check가 성공해 `y`를 반환한 경우 중간 표현은 `def_bool y`가 됩니다.

CC := gcc

config CC_HAS_FOO
        def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))

# 매크로 확장 뒤의 중간 표현
config CC_HAS_FOO
        def_bool y

매크로 확장이 끝난 다음 Kconfig는 `kconfig-language.rst`에서 설명한 평가 단계로 이동해 symbol 사이의 dependency를 해석합니다. 즉 shell 명령과 variable reference는 dependency 계산 전에 정적으로 텍스트로 치환됩니다.

======================
Kconfig macro language
======================

Concept
-------

The basic idea was inspired by Make. When we look at Make, we notice sort of
two languages in one. One language describes dependency graphs consisting of
targets and prerequisites. The other is a macro language for performing textual
substitution.

There is clear distinction between the two language stages. For example, you
can write a makefile like follows::

    APP := foo
    SRC := foo.c
    CC := gcc

    $(APP): $(SRC)
            $(CC) -o $(APP) $(SRC)

The macro language replaces the variable references with their expanded form,
and handles as if the source file were input like follows::

    foo: foo.c
            gcc -o foo foo.c

Then, Make analyzes the dependency graph and determines the targets to be
updated.

The idea is quite similar in Kconfig - it is possible to describe a Kconfig
file like this::

    CC := gcc

    config CC_HAS_FOO
            def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))

The macro language in Kconfig processes the source file into the following
intermediate::

    config CC_HAS_FOO
            def_bool y

Then, Kconfig moves onto the evaluation stage to resolve inter-symbol
dependency as explained in kconfig-language.rst.

변수와 사용자 정의 함수

Kconfig variable은 Make와 마찬가지로 macro variable로 동작합니다. Variable은 사용 위치에서 text string으로 확장되며, 그 결과가 다시 확장될 수도 있습니다. 값을 얻으려면 이름을 반드시 `$( )`로 감싸야 합니다. 한 글자 이름도 `$(X)`로 써야 하며 `$X`는 syntax error입니다. `${CC}` 형태도 지원하지 않습니다.

Variable에는 simply expanded variable과 recursively expanded variable 두 종류가 있습니다. `:=`로 정의한 simply expanded variable은 Kconfig가 해당 줄을 읽을 때 우변을 즉시 확장합니다. `=`로 정의한 recursively expanded variable은 우변을 확장하지 않고 그대로 저장했다가 실제 사용 시점에 확장합니다.

`+=`는 variable 끝에 text를 덧붙입니다. 좌변이 처음에 simple variable로 정의되었다면 `+=` 우변도 즉시 확장하고, 그렇지 않으면 확장을 사용 시점까지 미룹니다.

Variable reference는 `$(name,arg1,arg2,arg3)` 형태로 parameter를 받을 수 있습니다. 이런 parameterized reference는 아래의 built-in function과 구분해 user-defined function으로 볼 수 있습니다.

유용한 function은 전달된 parameter에 따라 결과가 달라지므로 사용할 때 확장되어야 합니다. 따라서 user-defined function은 `=` 연산자로 정의하고, body에서는 `$(1)`, `$(2)`처럼 각 parameter를 참조합니다.

format = $(1): $(2)
MESSAGE := $(format,level,text)

내부적으로 recursively expanded variable과 user-defined function은 같습니다. 다시 말해 variable은 argument가 0개인 function입니다. 이 문서가 넓은 의미에서 variable이라고 할 때는 user-defined function도 포함합니다.

Variables
---------

Like in Make, a variable in Kconfig works as a macro variable.  A macro
variable is expanded "in place" to yield a text string that may then be
expanded further. To get the value of a variable, enclose the variable name in
$( ). The parentheses are required even for single-letter variable names; $X is
a syntax error. The curly brace form as in ${CC} is not supported either.

There are two types of variables: simply expanded variables and recursively
expanded variables.

A simply expanded variable is defined using the := assignment operator. Its
righthand side is expanded immediately upon reading the line from the Kconfig
file.

A recursively expanded variable is defined using the = assignment operator.
Its righthand side is simply stored as the value of the variable without
expanding it in any way. Instead, the expansion is performed when the variable
is used.

There is another type of assignment operator; += is used to append text to a
variable. The righthand side of += is expanded immediately if the lefthand
side was originally defined as a simple variable. Otherwise, its evaluation is
deferred.

The variable reference can take parameters, in the following form::

  $(name,arg1,arg2,arg3)

You can consider the parameterized reference as a function. (more precisely,
"user-defined function" in contrast to "built-in function" listed below).

Useful functions must be expanded when they are used since the same function is
expanded differently if different parameters are passed. Hence, a user-defined
function is defined using the = assignment operator. The parameters are
referenced within the body definition with $(1), $(2), etc.

In fact, recursively expanded variables and user-defined functions are the same
internally. (In other words, "variable" is "function with zero argument".)
When we say "variable" in a broad sense, it includes "user-defined function".

내장 함수

Kconfig는 Make처럼 여러 built-in function을 제공하며, 각 함수는 정해진 수의 argument를 받습니다. Make의 built-in function은 적어도 argument 하나를 받지만 Kconfig는 `$(filename)`, `$(lineno)`처럼 argument가 0개인 함수도 허용합니다. 이를 built-in variable이라고 부를 수도 있지만, 여기서는 native functionality 전체를 built-in function이라고 부릅니다.

`shell`은 argument 하나를 먼저 확장한 뒤 subshell에 넘겨 실행합니다. Command의 standard output을 읽어 함수 값으로 반환하며, 출력의 모든 newline은 space로 바꾸고 끝의 newline은 제거합니다. Standard error와 program exit status는 반환하지 않습니다.

`info`는 argument 하나를 stdout에 출력하고 빈 문자열로 평가됩니다. `warning-if`는 condition과 text 두 argument를 받으며 condition이 `y`일 때 text를 stderr로 보냅니다. 이 경고 앞에는 현재 Kconfig file name과 line number가 붙습니다. `error-if`도 같지만 condition이 `y`이면 parsing을 즉시 종료합니다.

Argument가 없는 `filename`은 parsing 중인 file name으로, `lineno`는 parsing 중인 line number로 확장됩니다.

Built-in functions
------------------

Like Make, Kconfig provides several built-in functions. Every function takes a
particular number of arguments.

In Make, every built-in function takes at least one argument. Kconfig allows
zero argument for built-in functions, such as $(filename), $(lineno). You could
consider those as "built-in variable", but it is just a matter of how we call
it after all. Let's say "built-in function" here to refer to natively supported
functionality.

Kconfig currently supports the following built-in functions.

 - $(shell,command)

  The "shell" function accepts a single argument that is expanded and passed
  to a subshell for execution. The standard output of the command is then read
  and returned as the value of the function. Every newline in the output is
  replaced with a space. Any trailing newlines are deleted. The standard error
  is not returned, nor is any program exit status.

 - $(info,text)

  The "info" function takes a single argument and prints it to stdout.
  It evaluates to an empty string.

 - $(warning-if,condition,text)

  The "warning-if" function takes two arguments. If the condition part is "y",
  the text part is sent to stderr. The text is prefixed with the name of the
  current Kconfig file and the current line number.

 - $(error-if,condition,text)

  The "error-if" function is similar to "warning-if", but it terminates the
  parsing immediately if the condition part is "y".

 - $(filename)

  The 'filename' takes no argument, and $(filename) is expanded to the file
  name being parsed.

 - $(lineno)

  The 'lineno' takes no argument, and $(lineno) is expanded to the line number
  being parsed.

Make와 Kconfig 호출 문법의 차이

Kconfig는 Make와 비슷한 macro language를 채택했지만 function call syntax에는 차이가 있습니다. Make 호출은 `$(func-name arg1,arg2,arg3)`처럼 function name과 첫 argument를 적어도 하나의 whitespace로 구분합니다.

Make는 첫 argument 앞의 leading whitespace를 제거하지만 나머지 argument의 whitespace는 보존합니다. 첫 parameter를 space로 시작하려면 빈 variable로 `space`를 만든 뒤 조합하는 우회 기법이 필요합니다.

empty :=
space := $(empty) $(empty)
$(info $(space)$(space)hello)

Kconfig는 delimiter로 comma만 사용하며 function call 내부 whitespace를 모두 보존합니다. `$(func-name, arg1, arg2, arg3)`처럼 comma 뒤에 space를 넣으면 함수는 실제로 `" arg1"`, `" arg2"`, `" arg3"`을 받습니다. Leading space가 중요한 함수에서는 결과가 달라질 수 있습니다.

Make에도 같은 주의점이 있습니다. `$(subst .c, .o, $(sources))`는 `.c`를 `.o`가 아니라 앞에 space가 붙은 ` .o`로 바꾸는 전형적인 실수입니다.

Make는 user-defined function을 `$(call my-func,arg1,arg2,arg3)`처럼 built-in `call`을 통해 참조합니다. Kconfig는 user-defined function과 built-in function을 같은 방식으로 호출하므로 `call`을 생략하고 더 짧게 씁니다.

Make의 일부 함수는 comma를 argument separator가 아닌 literal로 취급합니다. 그래서 `$(shell echo hello, world)`는 `echo hello, world`를 실행하고 `$(info hello, world)`는 해당 문장을 출력합니다. 이는 유용하지만 일관되지 않은 동작입니다.

Kconfig는 구현과 grammar를 단순하고 일관되게 유지하기 위해 `$( )` 안의 모든 comma를 delimiter로 해석합니다. 따라서 `$(shell, echo hello, world)`는 argument 하나만 받는 `shell`에 두 parameter를 전달하므로 error입니다.

Argument에 comma를 넣으려면 `comma := ,`를 먼저 정의한 뒤 `$(shell, echo hello$(comma) world)`처럼 variable expansion으로 삽입해야 합니다.

Make vs Kconfig
---------------

Kconfig adopts Make-like macro language, but the function call syntax is
slightly different.

A function call in Make looks like this::

  $(func-name arg1,arg2,arg3)

The function name and the first argument are separated by at least one
whitespace. Then, leading whitespaces are trimmed from the first argument,
while whitespaces in the other arguments are kept. You need to use a kind of
trick to start the first parameter with spaces. For example, if you want
to make "info" function print "  hello", you can write like follows::

  empty :=
  space := $(empty) $(empty)
  $(info $(space)$(space)hello)

Kconfig uses only commas for delimiters, and keeps all whitespaces in the
function call. Some people prefer putting a space after each comma delimiter::

  $(func-name, arg1, arg2, arg3)

In this case, "func-name" will receive " arg1", " arg2", " arg3". The presence
of leading spaces may matter depending on the function. The same applies to
Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it
replaces ".c" with " .o".

In Make, a user-defined function is referenced by using a built-in function,
'call', like this::

    $(call my-func,arg1,arg2,arg3)

Kconfig invokes user-defined functions and built-in functions in the same way.
The omission of 'call' makes the syntax shorter.

In Make, some functions treat commas verbatim instead of argument separators.
For example, $(shell echo hello, world) runs the command "echo hello, world".
Likewise, $(info hello, world) prints "hello, world" to stdout. You could say
this is _useful_ inconsistency.

In Kconfig, for simpler implementation and grammatical consistency, commas that
appear in the $( ) context are always delimiters. It means::

  $(shell, echo hello, world)

is an error because it is passing two parameters where the 'shell' function
accepts only one. To pass commas in arguments, you can use the following trick::

  comma := ,
  $(shell, echo hello$(comma) world)

확장 한계와 주의사항

Variable이나 function은 여러 token에 걸쳐 확장될 수 없습니다. 따라서 여러 token으로 이루어진 expression 전체의 shorthand로 variable을 사용할 수 없습니다.

예를 들어 `RANGE_MIN := 1`, `RANGE_MAX := 3`을 각각 정의하고 `range $(RANGE_MIN) $(RANGE_MAX)`로 쓰면 각 reference가 token 하나에 대응하므로 동작합니다.

RANGE_MIN := 1
RANGE_MAX := 3

config FOO
        int "foo"
        range $(RANGE_MIN) $(RANGE_MAX)

반면 `RANGES := 1 3`을 정의하고 `range $(RANGES)`로 쓰면 하나의 variable expansion이 두 token을 대신하려 하므로 동작하지 않습니다.

RANGES := 1 3

config FOO
        int "foo"
        range $(RANGES)

Variable을 Kconfig keyword로 확장하는 것도 허용되지 않습니다. `MY_TYPE := tristate`를 정의하고 config entry에서 `$(MY_TYPE) "foo"`를 쓰는 방식은 동작하지 않습니다. Type keyword는 source grammar에 직접 나타나야 합니다.

MY_TYPE := tristate

config FOO
        $(MY_TYPE) "foo"
        default y

설계상 `shell` 함수는 textual substitution 단계에서 확장되므로 Kconfig symbol을 shell command에 전달할 수 없습니다. Symbol value는 그 다음 evaluation 단계에서 결정되기 때문입니다.

따라서 `ENDIAN_FLAG` string symbol에 CPU endianness에 따른 compiler flag를 넣고 `gcc-check-flag ENDIAN_FLAG`를 실행하면 symbol의 값이 아니라 literal name이 전달되어 기대대로 동작하지 않습니다.

대신 각 function call이 정적으로 확장되도록 두 command를 직접 작성하고, Kconfig dependency를 각 default에 붙입니다. `CPU_BIG_ENDIAN`일 때 `-mbig-endian` 검사 결과를, `CPU_LITTLE_ENDIAN`일 때 `-mlittle-endian` 검사 결과를 사용합니다.

config CC_HAS_ENDIAN_FLAG
        bool
        default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN
        default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN

Caveats
-------

A variable (or function) cannot be expanded across tokens. So, you cannot use
a variable as a shorthand for an expression that consists of multiple tokens.
The following works::

    RANGE_MIN := 1
    RANGE_MAX := 3

    config FOO
            int "foo"
            range $(RANGE_MIN) $(RANGE_MAX)

But, the following does not work::

    RANGES := 1 3

    config FOO
            int "foo"
            range $(RANGES)

A variable cannot be expanded to any keyword in Kconfig.  The following does
not work::

    MY_TYPE := tristate

    config FOO
            $(MY_TYPE) "foo"
            default y

Obviously from the design, $(shell command) is expanded in the textual
substitution phase. You cannot pass symbols to the 'shell' function.

The following does not work as expected::

    config ENDIAN_FLAG
            string
            default "-mbig-endian" if CPU_BIG_ENDIAN
            default "-mlittle-endian" if CPU_LITTLE_ENDIAN

    config CC_HAS_ENDIAN_FLAG
            def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG)

Instead, you can do like follows so that any function call is statically
expanded::

    config CC_HAS_ENDIAN_FLAG
            bool
            default $(shell $(srctree)/scripts/gcc-check-flag -mbig-endian) if CPU_BIG_ENDIAN
            default $(shell $(srctree)/scripts/gcc-check-flag -mlittle-endian) if CPU_LITTLE_ENDIAN