1# Copyright (c) 2011-2019, Ulf Magnusson 2# SPDX-License-Identifier: ISC 3 4""" 5Overview 6======== 7 8Kconfiglib is a Python 2/3 library for scripting and extracting information 9from Kconfig (https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt) 10configuration systems. 11 12See the homepage at https://github.com/ulfalizer/Kconfiglib for a longer 13overview. 14 15Since Kconfiglib 12.0.0, the library version is available in 16kconfiglib.VERSION, which is a (<major>, <minor>, <patch>) tuple, e.g. 17(12, 0, 0). 18 19 20Using Kconfiglib on the Linux kernel with the Makefile targets 21============================================================== 22 23For the Linux kernel, a handy interface is provided by the 24scripts/kconfig/Makefile patch, which can be applied with either 'git am' or 25the 'patch' utility: 26 27 $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | git am 28 $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | patch -p1 29 30Warning: Not passing -p1 to patch will cause the wrong file to be patched. 31 32Please tell me if the patch does not apply. It should be trivial to apply 33manually, as it's just a block of text that needs to be inserted near the other 34*conf: targets in scripts/kconfig/Makefile. 35 36Look further down for a motivation for the Makefile patch and for instructions 37on how you can use Kconfiglib without it. 38 39If you do not wish to install Kconfiglib via pip, the Makefile patch is set up 40so that you can also just clone Kconfiglib into the kernel root: 41 42 $ git clone git://github.com/ulfalizer/Kconfiglib.git 43 $ git am Kconfiglib/makefile.patch (or 'patch -p1 < Kconfiglib/makefile.patch') 44 45Warning: The directory name Kconfiglib/ is significant in this case, because 46it's added to PYTHONPATH by the new targets in makefile.patch. 47 48The targets added by the Makefile patch are described in the following 49sections. 50 51 52make kmenuconfig 53---------------- 54 55This target runs the curses menuconfig interface with Python 3. As of 56Kconfiglib 12.2.0, both Python 2 and Python 3 are supported (previously, only 57Python 3 was supported, so this was a backport). 58 59 60make guiconfig 61-------------- 62 63This target runs the Tkinter menuconfig interface. Both Python 2 and Python 3 64are supported. To change the Python interpreter used, pass 65PYTHONCMD=<executable> to 'make'. The default is 'python'. 66 67 68make [ARCH=<arch>] iscriptconfig 69-------------------------------- 70 71This target gives an interactive Python prompt where a Kconfig instance has 72been preloaded and is available in 'kconf'. To change the Python interpreter 73used, pass PYTHONCMD=<executable> to 'make'. The default is 'python'. 74 75To get a feel for the API, try evaluating and printing the symbols in 76kconf.defined_syms, and explore the MenuNode menu tree starting at 77kconf.top_node by following 'next' and 'list' pointers. 78 79The item contained in a menu node is found in MenuNode.item (note that this can 80be one of the constants kconfiglib.MENU and kconfiglib.COMMENT), and all 81symbols and choices have a 'nodes' attribute containing their menu nodes 82(usually only one). Printing a menu node will print its item, in Kconfig 83format. 84 85If you want to look up a symbol by name, use the kconf.syms dictionary. 86 87 88make scriptconfig SCRIPT=<script> [SCRIPT_ARG=<arg>] 89---------------------------------------------------- 90 91This target runs the Python script given by the SCRIPT parameter on the 92configuration. sys.argv[1] holds the name of the top-level Kconfig file 93(currently always "Kconfig" in practice), and sys.argv[2] holds the SCRIPT_ARG 94argument, if given. 95 96See the examples/ subdirectory for example scripts. 97 98 99make dumpvarsconfig 100------------------- 101 102This target prints a list of all environment variables referenced from the 103Kconfig files, together with their values. See the 104Kconfiglib/examples/dumpvars.py script. 105 106Only environment variables that are referenced via the Kconfig preprocessor 107$(FOO) syntax are included. The preprocessor was added in Linux 4.18. 108 109 110Using Kconfiglib without the Makefile targets 111============================================= 112 113The make targets are only needed to pick up environment variables exported from 114the Kbuild makefiles and referenced inside Kconfig files, via e.g. 115'source "arch/$(SRCARCH)/Kconfig" and commands run via '$(shell,...)'. 116 117These variables are referenced as of writing (Linux 4.18), together with sample 118values: 119 120 srctree (.) 121 ARCH (x86) 122 SRCARCH (x86) 123 KERNELVERSION (4.18.0) 124 CC (gcc) 125 HOSTCC (gcc) 126 HOSTCXX (g++) 127 CC_VERSION_TEXT (gcc (Ubuntu 7.3.0-16ubuntu3) 7.3.0) 128 129Older kernels only reference ARCH, SRCARCH, and KERNELVERSION. 130 131If your kernel is recent enough (4.18+), you can get a list of referenced 132environment variables via 'make dumpvarsconfig' (see above). Note that this 133command is added by the Makefile patch. 134 135To run Kconfiglib without the Makefile patch, set the environment variables 136manually: 137 138 $ srctree=. ARCH=x86 SRCARCH=x86 KERNELVERSION=`make kernelversion` ... python(3) 139 >>> import kconfiglib 140 >>> kconf = kconfiglib.Kconfig() # filename defaults to "Kconfig" 141 142Search the top-level Makefile for "Additional ARCH settings" to see other 143possibilities for ARCH and SRCARCH. 144 145 146Intro to symbol values 147====================== 148 149Kconfiglib has the same assignment semantics as the C implementation. 150 151Any symbol can be assigned a value by the user (via Kconfig.load_config() or 152Symbol.set_value()), but this user value is only respected if the symbol is 153visible, which corresponds to it (currently) being visible in the menuconfig 154interface. 155 156For symbols with prompts, the visibility of the symbol is determined by the 157condition on the prompt. Symbols without prompts are never visible, so setting 158a user value on them is pointless. A warning will be printed by default if 159Symbol.set_value() is called on a promptless symbol. Assignments to promptless 160symbols are normal within a .config file, so no similar warning will be printed 161by load_config(). 162 163Dependencies from parents and 'if'/'depends on' are propagated to properties, 164including prompts, so these two configurations are logically equivalent: 165 166(1) 167 168 menu "menu" 169 depends on A 170 171 if B 172 173 config FOO 174 tristate "foo" if D 175 default y 176 depends on C 177 178 endif 179 180 endmenu 181 182(2) 183 184 menu "menu" 185 depends on A 186 187 config FOO 188 tristate "foo" if A && B && C && D 189 default y if A && B && C 190 191 endmenu 192 193In this example, A && B && C && D (the prompt condition) needs to be non-n for 194FOO to be visible (assignable). If its value is m, the symbol can only be 195assigned the value m: The visibility sets an upper bound on the value that can 196be assigned by the user, and any higher user value will be truncated down. 197 198'default' properties are independent of the visibility, though a 'default' will 199often get the same condition as the prompt due to dependency propagation. 200'default' properties are used if the symbol is not visible or has no user 201value. 202 203Symbols with no user value (or that have a user value but are not visible) and 204no (active) 'default' default to n for bool/tristate symbols, and to the empty 205string for other symbol types. 206 207'select' works similarly to symbol visibility, but sets a lower bound on the 208value of the symbol. The lower bound is determined by the value of the 209select*ing* symbol. 'select' does not respect visibility, so non-visible 210symbols can be forced to a particular (minimum) value by a select as well. 211 212For non-bool/tristate symbols, it only matters whether the visibility is n or 213non-n: m visibility acts the same as y visibility. 214 215Conditions on 'default' and 'select' work in mostly intuitive ways. If the 216condition is n, the 'default' or 'select' is disabled. If it is m, the 217'default' or 'select' value (the value of the selecting symbol) is truncated 218down to m. 219 220When writing a configuration with Kconfig.write_config(), only symbols that are 221visible, have an (active) default, or are selected will get written out (note 222that this includes all symbols that would accept user values). Kconfiglib 223matches the .config format produced by the C implementations down to the 224character. This eases testing. 225 226For a visible bool/tristate symbol FOO with value n, this line is written to 227.config: 228 229 # CONFIG_FOO is not set 230 231The point is to remember the user n selection (which might differ from the 232default value the symbol would get), while at the same sticking to the rule 233that undefined corresponds to n (.config uses Makefile format, making the line 234above a comment). When the .config file is read back in, this line will be 235treated the same as the following assignment: 236 237 CONFIG_FOO=n 238 239In Kconfiglib, the set of (currently) assignable values for a bool/tristate 240symbol appear in Symbol.assignable. For other symbol types, just check if 241sym.visibility is non-0 (non-n) to see whether the user value will have an 242effect. 243 244 245Intro to the menu tree 246====================== 247 248The menu structure, as seen in e.g. menuconfig, is represented by a tree of 249MenuNode objects. The top node of the configuration corresponds to an implicit 250top-level menu, the title of which is shown at the top in the standard 251menuconfig interface. (The title is also available in Kconfig.mainmenu_text in 252Kconfiglib.) 253 254The top node is found in Kconfig.top_node. From there, you can visit child menu 255nodes by following the 'list' pointer, and any following menu nodes by 256following the 'next' pointer. Usually, a non-None 'list' pointer indicates a 257menu or Choice, but menu nodes for symbols can sometimes have a non-None 'list' 258pointer too due to submenus created implicitly from dependencies. 259 260MenuNode.item is either a Symbol or a Choice object, or one of the constants 261MENU and COMMENT. The prompt of the menu node can be found in MenuNode.prompt, 262which also holds the title for menus and comments. For Symbol and Choice, 263MenuNode.help holds the help text (if any, otherwise None). 264 265Most symbols will only have a single menu node. A symbol defined in multiple 266locations will have one menu node for each location. The list of menu nodes for 267a Symbol or Choice can be found in the Symbol/Choice.nodes attribute. 268 269Note that prompts and help texts for symbols and choices are stored in their 270menu node(s) rather than in the Symbol or Choice objects themselves. This makes 271it possible to define a symbol in multiple locations with a different prompt or 272help text in each location. To get the help text or prompt for a symbol with a 273single menu node, do sym.nodes[0].help and sym.nodes[0].prompt, respectively. 274The prompt is a (text, condition) tuple, where condition determines the 275visibility (see 'Intro to expressions' below). 276 277This organization mirrors the C implementation. MenuNode is called 278'struct menu' there, but I thought "menu" was a confusing name. 279 280It is possible to give a Choice a name and define it in multiple locations, 281hence why Choice.nodes is also a list. 282 283As a convenience, the properties added at a particular definition location are 284available on the MenuNode itself, in e.g. MenuNode.defaults. This is helpful 285when generating documentation, so that symbols/choices defined in multiple 286locations can be shown with the correct properties at each location. 287 288 289Intro to expressions 290==================== 291 292Expressions can be evaluated with the expr_value() function and printed with 293the expr_str() function (these are used internally as well). Evaluating an 294expression always yields a tristate value, where n, m, and y are represented as 2950, 1, and 2, respectively. 296 297The following table should help you figure out how expressions are represented. 298A, B, C, ... are symbols (Symbol instances), NOT is the kconfiglib.NOT 299constant, etc. 300 301Expression Representation 302---------- -------------- 303A A 304"A" A (constant symbol) 305!A (NOT, A) 306A && B (AND, A, B) 307A && B && C (AND, A, (AND, B, C)) 308A || B (OR, A, B) 309A || (B && C && D) (OR, A, (AND, B, (AND, C, D))) 310A = B (EQUAL, A, B) 311A != "foo" (UNEQUAL, A, foo (constant symbol)) 312A && B = C && D (AND, A, (AND, (EQUAL, B, C), D)) 313n Kconfig.n (constant symbol) 314m Kconfig.m (constant symbol) 315y Kconfig.y (constant symbol) 316"y" Kconfig.y (constant symbol) 317 318Strings like "foo" in 'default "foo"' or 'depends on SYM = "foo"' are 319represented as constant symbols, so the only values that appear in expressions 320are symbols***. This mirrors the C implementation. 321 322***For choice symbols, the parent Choice will appear in expressions as well, 323but it's usually invisible as the value interfaces of Symbol and Choice are 324identical. This mirrors the C implementation and makes different choice modes 325"just work". 326 327Manual evaluation examples: 328 329 - The value of A && B is min(A.tri_value, B.tri_value) 330 331 - The value of A || B is max(A.tri_value, B.tri_value) 332 333 - The value of !A is 2 - A.tri_value 334 335 - The value of A = B is 2 (y) if A.str_value == B.str_value, and 0 (n) 336 otherwise. Note that str_value is used here instead of tri_value. 337 338 For constant (as well as undefined) symbols, str_value matches the name of 339 the symbol. This mirrors the C implementation and explains why 340 'depends on SYM = "foo"' above works as expected. 341 342n/m/y are automatically converted to the corresponding constant symbols 343"n"/"m"/"y" (Kconfig.n/m/y) during parsing. 344 345Kconfig.const_syms is a dictionary like Kconfig.syms but for constant symbols. 346 347If a condition is missing (e.g., <cond> when the 'if <cond>' is removed from 348'default A if <cond>'), it is actually Kconfig.y. The standard __str__() 349functions just avoid printing 'if y' conditions to give cleaner output. 350 351 352Kconfig extensions 353================== 354 355Kconfiglib includes a couple of Kconfig extensions: 356 357'source' with relative path 358--------------------------- 359 360The 'rsource' statement sources Kconfig files with a path relative to directory 361of the Kconfig file containing the 'rsource' statement, instead of relative to 362the project root. 363 364Consider following directory tree: 365 366 Project 367 +--Kconfig 368 | 369 +--src 370 +--Kconfig 371 | 372 +--SubSystem1 373 +--Kconfig 374 | 375 +--ModuleA 376 +--Kconfig 377 378In this example, assume that src/SubSystem1/Kconfig wants to source 379src/SubSystem1/ModuleA/Kconfig. 380 381With 'source', this statement would be used: 382 383 source "src/SubSystem1/ModuleA/Kconfig" 384 385With 'rsource', this turns into 386 387 rsource "ModuleA/Kconfig" 388 389If an absolute path is given to 'rsource', it acts the same as 'source'. 390 391'rsource' can be used to create "position-independent" Kconfig trees that can 392be moved around freely. 393 394 395Globbing 'source' 396----------------- 397 398'source' and 'rsource' accept glob patterns, sourcing all matching Kconfig 399files. They require at least one matching file, raising a KconfigError 400otherwise. 401 402For example, the following statement might source sub1/foofoofoo and 403sub2/foobarfoo: 404 405 source "sub[12]/foo*foo" 406 407The glob patterns accepted are the same as for the standard glob.glob() 408function. 409 410Two additional statements are provided for cases where it's acceptable for a 411pattern to match no files: 'osource' and 'orsource' (the o is for "optional"). 412 413For example, the following statements will be no-ops if neither "foo" nor any 414files matching "bar*" exist: 415 416 osource "foo" 417 osource "bar*" 418 419'orsource' does a relative optional source. 420 421'source' and 'osource' are analogous to 'include' and '-include' in Make. 422 423 424Generalized def_* keywords 425-------------------------- 426 427def_int, def_hex, and def_string are available in addition to def_bool and 428def_tristate, allowing int, hex, and string symbols to be given a type and a 429default at the same time. 430 431 432Extra optional warnings 433----------------------- 434 435Some optional warnings can be controlled via environment variables: 436 437 - KCONFIG_WARN_UNDEF: If set to 'y', warnings will be generated for all 438 references to undefined symbols within Kconfig files. The only gotcha is 439 that all hex literals must be prefixed with "0x" or "0X", to make it 440 possible to distinguish them from symbol references. 441 442 Some projects (e.g. the Linux kernel) use multiple Kconfig trees with many 443 shared Kconfig files, leading to some safe undefined symbol references. 444 KCONFIG_WARN_UNDEF is useful in projects that only have a single Kconfig 445 tree though. 446 447 KCONFIG_STRICT is an older alias for this environment variable, supported 448 for backwards compatibility. 449 450 - KCONFIG_WARN_UNDEF_ASSIGN: If set to 'y', warnings will be generated for 451 all assignments to undefined symbols within .config files. By default, no 452 such warnings are generated. 453 454 This warning can also be enabled/disabled via the Kconfig.warn_assign_undef 455 variable. 456 457 458Preprocessor user functions defined in Python 459--------------------------------------------- 460 461Preprocessor functions can be defined in Python, which makes it simple to 462integrate information from existing Python tools into Kconfig (e.g. to have 463Kconfig symbols depend on hardware information stored in some other format). 464 465Putting a Python module named kconfigfunctions(.py) anywhere in sys.path will 466cause it to be imported by Kconfiglib (in Kconfig.__init__()). Note that 467sys.path can be customized via PYTHONPATH, and includes the directory of the 468module being run by default, as well as installation directories. 469 470If the KCONFIG_FUNCTIONS environment variable is set, it gives a different 471module name to use instead of 'kconfigfunctions'. 472 473The imported module is expected to define a global dictionary named 'functions' 474that maps function names to Python functions, as follows: 475 476 def my_fn(kconf, name, arg_1, arg_2, ...): 477 # kconf: 478 # Kconfig instance 479 # 480 # name: 481 # Name of the user-defined function ("my-fn"). Think argv[0]. 482 # 483 # arg_1, arg_2, ...: 484 # Arguments passed to the function from Kconfig (strings) 485 # 486 # Returns a string to be substituted as the result of calling the 487 # function 488 ... 489 490 def my_other_fn(kconf, name, arg_1, arg_2, ...): 491 ... 492 493 functions = { 494 "my-fn": (my_fn, <min.args>, <max.args>/None), 495 "my-other-fn": (my_other_fn, <min.args>, <max.args>/None), 496 ... 497 } 498 499 ... 500 501<min.args> and <max.args> are the minimum and maximum number of arguments 502expected by the function (excluding the implicit 'name' argument). If 503<max.args> is None, there is no upper limit to the number of arguments. Passing 504an invalid number of arguments will generate a KconfigError exception. 505 506Functions can access the current parsing location as kconf.filename/linenr. 507Accessing other fields of the Kconfig object is not safe. See the warning 508below. 509 510Keep in mind that for a variable defined like 'foo = $(fn)', 'fn' will be 511called only when 'foo' is expanded. If 'fn' uses the parsing location and the 512intent is to use the location of the assignment, you want 'foo := $(fn)' 513instead, which calls the function immediately. 514 515Once defined, user functions can be called from Kconfig in the same way as 516other preprocessor functions: 517 518 config FOO 519 ... 520 depends on $(my-fn,arg1,arg2) 521 522If my_fn() returns "n", this will result in 523 524 config FOO 525 ... 526 depends on n 527 528Warning 529******* 530 531User-defined preprocessor functions are called as they're encountered at parse 532time, before all Kconfig files have been processed, and before the menu tree 533has been finalized. There are no guarantees that accessing Kconfig symbols or 534the menu tree via the 'kconf' parameter will work, and it could potentially 535lead to a crash. 536 537Preferably, user-defined functions should be stateless. 538 539 540Feedback 541======== 542 543Send bug reports, suggestions, and questions to ulfalizer a.t Google's email 544service, or open a ticket on the GitHub page. 545""" 546import errno 547import importlib 548import os 549import re 550import sys 551 552# Get rid of some attribute lookups. These are obvious in context. 553from glob import iglob 554from os.path import dirname, exists, expandvars, islink, join, realpath 555 556 557VERSION = (14, 1, 0) 558 559 560# File layout: 561# 562# Public classes 563# Public functions 564# Internal functions 565# Global constants 566 567# Line length: 79 columns 568 569 570# 571# Public classes 572# 573 574 575class Kconfig(object): 576 """ 577 Represents a Kconfig configuration, e.g. for x86 or ARM. This is the set of 578 symbols, choices, and menu nodes appearing in the configuration. Creating 579 any number of Kconfig objects (including for different architectures) is 580 safe. Kconfiglib doesn't keep any global state. 581 582 The following attributes are available. They should be treated as 583 read-only, and some are implemented through @property magic. 584 585 syms: 586 A dictionary with all symbols in the configuration, indexed by name. Also 587 includes all symbols that are referenced in expressions but never 588 defined, except for constant (quoted) symbols. 589 590 Undefined symbols can be recognized by Symbol.nodes being empty -- see 591 the 'Intro to the menu tree' section in the module docstring. 592 593 const_syms: 594 A dictionary like 'syms' for constant (quoted) symbols 595 596 named_choices: 597 A dictionary like 'syms' for named choices (choice FOO) 598 599 defined_syms: 600 A list with all defined symbols, in the same order as they appear in the 601 Kconfig files. Symbols defined in multiple locations appear multiple 602 times. 603 604 Note: You probably want to use 'unique_defined_syms' instead. This 605 attribute is mostly maintained for backwards compatibility. 606 607 unique_defined_syms: 608 A list like 'defined_syms', but with duplicates removed. Just the first 609 instance is kept for symbols defined in multiple locations. Kconfig order 610 is preserved otherwise. 611 612 Using this attribute instead of 'defined_syms' can save work, and 613 automatically gives reasonable behavior when writing configuration output 614 (symbols defined in multiple locations only generate output once, while 615 still preserving Kconfig order for readability). 616 617 choices: 618 A list with all choices, in the same order as they appear in the Kconfig 619 files. 620 621 Note: You probably want to use 'unique_choices' instead. This attribute 622 is mostly maintained for backwards compatibility. 623 624 unique_choices: 625 Analogous to 'unique_defined_syms', for choices. Named choices can have 626 multiple definition locations. 627 628 menus: 629 A list with all menus, in the same order as they appear in the Kconfig 630 files 631 632 comments: 633 A list with all comments, in the same order as they appear in the Kconfig 634 files 635 636 kconfig_filenames: 637 A list with the filenames of all Kconfig files included in the 638 configuration, relative to $srctree (or relative to the current directory 639 if $srctree isn't set), except absolute paths (e.g. 640 'source "/foo/Kconfig"') are kept as-is. 641 642 The files are listed in the order they are source'd, starting with the 643 top-level Kconfig file. If a file is source'd multiple times, it will 644 appear multiple times. Use set() to get unique filenames. 645 646 Note that Kconfig.sync_deps() already indirectly catches any file 647 modifications that change configuration output. 648 649 env_vars: 650 A set() with the names of all environment variables referenced in the 651 Kconfig files. 652 653 Only environment variables referenced with the preprocessor $(FOO) syntax 654 will be registered. The older $FOO syntax is only supported for backwards 655 compatibility. 656 657 Also note that $(FOO) won't be registered unless the environment variable 658 $FOO is actually set. If it isn't, $(FOO) is an expansion of an unset 659 preprocessor variable (which gives the empty string). 660 661 Another gotcha is that environment variables referenced in the values of 662 recursively expanded preprocessor variables (those defined with =) will 663 only be registered if the variable is actually used (expanded) somewhere. 664 665 The note from the 'kconfig_filenames' documentation applies here too. 666 667 n/m/y: 668 The predefined constant symbols n/m/y. Also available in const_syms. 669 670 modules: 671 The Symbol instance for the modules symbol. Currently hardcoded to 672 MODULES, which is backwards compatible. Kconfiglib will warn if 673 'option modules' is set on some other symbol. Tell me if you need proper 674 'option modules' support. 675 676 'modules' is never None. If the MODULES symbol is not explicitly defined, 677 its tri_value will be 0 (n), as expected. 678 679 A simple way to enable modules is to do 'kconf.modules.set_value(2)' 680 (provided the MODULES symbol is defined and visible). Modules are 681 disabled by default in the kernel Kconfig files as of writing, though 682 nearly all defconfig files enable them (with 'CONFIG_MODULES=y'). 683 684 defconfig_list: 685 The Symbol instance for the 'option defconfig_list' symbol, or None if no 686 defconfig_list symbol exists. The defconfig filename derived from this 687 symbol can be found in Kconfig.defconfig_filename. 688 689 defconfig_filename: 690 The filename given by the defconfig_list symbol. This is taken from the 691 first 'default' with a satisfied condition where the specified file 692 exists (can be opened for reading). If a defconfig file foo/defconfig is 693 not found and $srctree was set when the Kconfig was created, 694 $srctree/foo/defconfig is looked up as well. 695 696 'defconfig_filename' is None if either no defconfig_list symbol exists, 697 or if the defconfig_list symbol has no 'default' with a satisfied 698 condition that specifies a file that exists. 699 700 Gotcha: scripts/kconfig/Makefile might pass --defconfig=<defconfig> to 701 scripts/kconfig/conf when running e.g. 'make defconfig'. This option 702 overrides the defconfig_list symbol, meaning defconfig_filename might not 703 always match what 'make defconfig' would use. 704 705 top_node: 706 The menu node (see the MenuNode class) of the implicit top-level menu. 707 Acts as the root of the menu tree. 708 709 mainmenu_text: 710 The prompt (title) of the top menu (top_node). Defaults to "Main menu". 711 Can be changed with the 'mainmenu' statement (see kconfig-language.txt). 712 713 variables: 714 A dictionary with all preprocessor variables, indexed by name. See the 715 Variable class. 716 717 warn: 718 Set this variable to True/False to enable/disable warnings. See 719 Kconfig.__init__(). 720 721 When 'warn' is False, the values of the other warning-related variables 722 are ignored. 723 724 This variable as well as the other warn* variables can be read to check 725 the current warning settings. 726 727 warn_to_stderr: 728 Set this variable to True/False to enable/disable warnings on stderr. See 729 Kconfig.__init__(). 730 731 warn_assign_undef: 732 Set this variable to True to generate warnings for assignments to 733 undefined symbols in configuration files. 734 735 This variable is False by default unless the KCONFIG_WARN_UNDEF_ASSIGN 736 environment variable was set to 'y' when the Kconfig instance was 737 created. 738 739 warn_assign_override: 740 Set this variable to True to generate warnings for multiple assignments 741 to the same symbol in configuration files, where the assignments set 742 different values (e.g. CONFIG_FOO=m followed by CONFIG_FOO=y, where the 743 last value would get used). 744 745 This variable is True by default. Disabling it might be useful when 746 merging configurations. 747 748 warn_assign_redun: 749 Like warn_assign_override, but for multiple assignments setting a symbol 750 to the same value. 751 752 This variable is True by default. Disabling it might be useful when 753 merging configurations. 754 755 warnings: 756 A list of strings containing all warnings that have been generated, for 757 cases where more flexibility is needed. 758 759 See the 'warn_to_stderr' parameter to Kconfig.__init__() and the 760 Kconfig.warn_to_stderr variable as well. Note that warnings still get 761 added to Kconfig.warnings when 'warn_to_stderr' is True. 762 763 Just as for warnings printed to stderr, only warnings that are enabled 764 will get added to Kconfig.warnings. See the various Kconfig.warn* 765 variables. 766 767 missing_syms: 768 A list with (name, value) tuples for all assignments to undefined symbols 769 within the most recently loaded .config file(s). 'name' is the symbol 770 name without the 'CONFIG_' prefix. 'value' is a string that gives the 771 right-hand side of the assignment verbatim. 772 773 See Kconfig.load_config() as well. 774 775 srctree: 776 The value the $srctree environment variable had when the Kconfig instance 777 was created, or the empty string if $srctree wasn't set. This gives nice 778 behavior with os.path.join(), which treats "" as the current directory, 779 without adding "./". 780 781 Kconfig files are looked up relative to $srctree (unless absolute paths 782 are used), and .config files are looked up relative to $srctree if they 783 are not found in the current directory. This is used to support 784 out-of-tree builds. The C tools use this environment variable in the same 785 way. 786 787 Changing $srctree after creating the Kconfig instance has no effect. Only 788 the value when the configuration is loaded matters. This avoids surprises 789 if multiple configurations are loaded with different values for $srctree. 790 791 config_prefix: 792 The value the CONFIG_ environment variable had when the Kconfig instance 793 was created, or "CONFIG_" if CONFIG_ wasn't set. This is the prefix used 794 (and expected) on symbol names in .config files and C headers. Used in 795 the same way in the C tools. 796 797 config_header: 798 The value the KCONFIG_CONFIG_HEADER environment variable had when the 799 Kconfig instance was created, or the empty string if 800 KCONFIG_CONFIG_HEADER wasn't set. This string is inserted verbatim at the 801 beginning of configuration files. See write_config(). 802 803 header_header: 804 The value the KCONFIG_AUTOHEADER_HEADER environment variable had when the 805 Kconfig instance was created, or the empty string if 806 KCONFIG_AUTOHEADER_HEADER wasn't set. This string is inserted verbatim at 807 the beginning of header files. See write_autoconf(). 808 809 filename/linenr: 810 The current parsing location, for use in Python preprocessor functions. 811 See the module docstring. 812 """ 813 __slots__ = ( 814 "_encoding", 815 "_functions", 816 "_set_match", 817 "_srctree_prefix", 818 "_unset_match", 819 "_warn_assign_no_prompt", 820 "choices", 821 "comments", 822 "config_header", 823 "config_prefix", 824 "const_syms", 825 "defconfig_list", 826 "defined_syms", 827 "env_vars", 828 "header_header", 829 "kconfig_filenames", 830 "m", 831 "menus", 832 "missing_syms", 833 "modules", 834 "n", 835 "named_choices", 836 "srctree", 837 "syms", 838 "top_node", 839 "unique_choices", 840 "unique_defined_syms", 841 "variables", 842 "warn", 843 "warn_assign_override", 844 "warn_assign_redun", 845 "warn_assign_undef", 846 "warn_to_stderr", 847 "warnings", 848 "y", 849 850 # Parsing-related 851 "_parsing_kconfigs", 852 "_readline", 853 "filename", 854 "linenr", 855 "_include_path", 856 "_filestack", 857 "_line", 858 "_tokens", 859 "_tokens_i", 860 "_reuse_tokens", 861 ) 862 863 # 864 # Public interface 865 # 866 867 def __init__(self, filename="Kconfig", warn=True, warn_to_stderr=True, 868 encoding="utf-8", suppress_traceback=False): 869 """ 870 Creates a new Kconfig object by parsing Kconfig files. 871 Note that Kconfig files are not the same as .config files (which store 872 configuration symbol values). 873 874 See the module docstring for some environment variables that influence 875 default warning settings (KCONFIG_WARN_UNDEF and 876 KCONFIG_WARN_UNDEF_ASSIGN). 877 878 Raises KconfigError on syntax/semantic errors, and OSError or (possibly 879 a subclass of) IOError on IO errors ('errno', 'strerror', and 880 'filename' are available). Note that IOError is an alias for OSError on 881 Python 3, so it's enough to catch OSError there. If you need Python 2/3 882 compatibility, it's easiest to catch EnvironmentError, which is a 883 common base class of OSError/IOError on Python 2 and an alias for 884 OSError on Python 3. 885 886 filename (default: "Kconfig"): 887 The Kconfig file to load. For the Linux kernel, you'll want "Kconfig" 888 from the top-level directory, as environment variables will make sure 889 the right Kconfig is included from there (arch/$SRCARCH/Kconfig as of 890 writing). 891 892 If $srctree is set, 'filename' will be looked up relative to it. 893 $srctree is also used to look up source'd files within Kconfig files. 894 See the class documentation. 895 896 If you are using Kconfiglib via 'make scriptconfig', the filename of 897 the base base Kconfig file will be in sys.argv[1]. It's currently 898 always "Kconfig" in practice. 899 900 warn (default: True): 901 True if warnings related to this configuration should be generated. 902 This can be changed later by setting Kconfig.warn to True/False. It 903 is provided as a constructor argument since warnings might be 904 generated during parsing. 905 906 See the other Kconfig.warn_* variables as well, which enable or 907 suppress certain warnings when warnings are enabled. 908 909 All generated warnings are added to the Kconfig.warnings list. See 910 the class documentation. 911 912 warn_to_stderr (default: True): 913 True if warnings should be printed to stderr in addition to being 914 added to Kconfig.warnings. 915 916 This can be changed later by setting Kconfig.warn_to_stderr to 917 True/False. 918 919 encoding (default: "utf-8"): 920 The encoding to use when reading and writing files, and when decoding 921 output from commands run via $(shell). If None, the encoding 922 specified in the current locale will be used. 923 924 The "utf-8" default avoids exceptions on systems that are configured 925 to use the C locale, which implies an ASCII encoding. 926 927 This parameter has no effect on Python 2, due to implementation 928 issues (regular strings turning into Unicode strings, which are 929 distinct in Python 2). Python 2 doesn't decode regular strings 930 anyway. 931 932 Related PEP: https://www.python.org/dev/peps/pep-0538/ 933 934 suppress_traceback (default: False): 935 Helper for tools. When True, any EnvironmentError or KconfigError 936 generated during parsing is caught, the exception message is printed 937 to stderr together with the command name, and sys.exit(1) is called 938 (which generates SystemExit). 939 940 This hides the Python traceback for "expected" errors like syntax 941 errors in Kconfig files. 942 943 Other exceptions besides EnvironmentError and KconfigError are still 944 propagated when suppress_traceback is True. 945 """ 946 try: 947 self._init(filename, warn, warn_to_stderr, encoding) 948 except (EnvironmentError, KconfigError) as e: 949 if suppress_traceback: 950 cmd = sys.argv[0] # Empty string if missing 951 if cmd: 952 cmd += ": " 953 # Some long exception messages have extra newlines for better 954 # formatting when reported as an unhandled exception. Strip 955 # them here. 956 sys.exit(cmd + str(e).strip()) 957 raise 958 959 def _init(self, filename, warn, warn_to_stderr, encoding): 960 # See __init__() 961 962 self._encoding = encoding 963 964 self.srctree = os.getenv("srctree", "") 965 # A prefix we can reliably strip from glob() results to get a filename 966 # relative to $srctree. relpath() can cause issues for symlinks, 967 # because it assumes symlink/../foo is the same as foo/. 968 self._srctree_prefix = realpath(self.srctree) + os.sep 969 970 self.warn = warn 971 self.warn_to_stderr = warn_to_stderr 972 self.warn_assign_undef = os.getenv("KCONFIG_WARN_UNDEF_ASSIGN") == "y" 973 self.warn_assign_override = True 974 self.warn_assign_redun = True 975 self._warn_assign_no_prompt = True 976 977 self.warnings = [] 978 979 self.config_prefix = os.getenv("CONFIG_", "CONFIG_") 980 # Regular expressions for parsing .config files 981 self._set_match = _re_match(self.config_prefix + r"([^=]+)=(.*)") 982 self._unset_match = _re_match(r"# {}([^ ]+) is not set".format( 983 self.config_prefix)) 984 985 self.config_header = os.getenv("KCONFIG_CONFIG_HEADER", "") 986 self.header_header = os.getenv("KCONFIG_AUTOHEADER_HEADER", "") 987 988 self.syms = {} 989 self.const_syms = {} 990 self.defined_syms = [] 991 self.missing_syms = [] 992 self.named_choices = {} 993 self.choices = [] 994 self.menus = [] 995 self.comments = [] 996 997 for nmy in "n", "m", "y": 998 sym = Symbol() 999 sym.kconfig = self 1000 sym.name = nmy 1001 sym.is_constant = True 1002 sym.orig_type = TRISTATE 1003 sym._cached_tri_val = STR_TO_TRI[nmy] 1004 1005 self.const_syms[nmy] = sym 1006 1007 self.n = self.const_syms["n"] 1008 self.m = self.const_syms["m"] 1009 self.y = self.const_syms["y"] 1010 1011 # Make n/m/y well-formed symbols 1012 for nmy in "n", "m", "y": 1013 sym = self.const_syms[nmy] 1014 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n 1015 1016 # Maps preprocessor variables names to Variable instances 1017 self.variables = {} 1018 1019 # Predefined preprocessor functions, with min/max number of arguments 1020 self._functions = { 1021 "info": (_info_fn, 1, 1), 1022 "error-if": (_error_if_fn, 2, 2), 1023 "filename": (_filename_fn, 0, 0), 1024 "lineno": (_lineno_fn, 0, 0), 1025 "shell": (_shell_fn, 1, 1), 1026 "warning-if": (_warning_if_fn, 2, 2), 1027 } 1028 1029 # Add any user-defined preprocessor functions 1030 try: 1031 self._functions.update( 1032 importlib.import_module( 1033 os.getenv("KCONFIG_FUNCTIONS", "kconfigfunctions") 1034 ).functions) 1035 except ImportError: 1036 pass 1037 1038 # This determines whether previously unseen symbols are registered. 1039 # They shouldn't be if we parse expressions after parsing, as part of 1040 # Kconfig.eval_string(). 1041 self._parsing_kconfigs = True 1042 1043 self.modules = self._lookup_sym("MODULES") 1044 self.defconfig_list = None 1045 1046 self.top_node = MenuNode() 1047 self.top_node.kconfig = self 1048 self.top_node.item = MENU 1049 self.top_node.is_menuconfig = True 1050 self.top_node.visibility = self.y 1051 self.top_node.prompt = ("Main menu", self.y) 1052 self.top_node.parent = None 1053 self.top_node.dep = self.y 1054 self.top_node.filename = filename 1055 self.top_node.linenr = 1 1056 self.top_node.include_path = () 1057 1058 # Parse the Kconfig files 1059 1060 # Not used internally. Provided as a convenience. 1061 self.kconfig_filenames = [filename] 1062 self.env_vars = set() 1063 1064 # Keeps track of the location in the parent Kconfig files. Kconfig 1065 # files usually source other Kconfig files. See _enter_file(). 1066 self._filestack = [] 1067 self._include_path = () 1068 1069 # The current parsing location 1070 self.filename = filename 1071 self.linenr = 0 1072 1073 # Used to avoid retokenizing lines when we discover that they're not 1074 # part of the construct currently being parsed. This is kinda like an 1075 # unget operation. 1076 self._reuse_tokens = False 1077 1078 # Open the top-level Kconfig file. Store the readline() method directly 1079 # as a small optimization. 1080 self._readline = self._open(join(self.srctree, filename), "r").readline 1081 1082 try: 1083 # Parse the Kconfig files. Returns the last node, which we 1084 # terminate with '.next = None'. 1085 self._parse_block(None, self.top_node, self.top_node).next = None 1086 self.top_node.list = self.top_node.next 1087 self.top_node.next = None 1088 except UnicodeDecodeError as e: 1089 _decoding_error(e, self.filename) 1090 1091 # Close the top-level Kconfig file. __self__ fetches the 'file' object 1092 # for the method. 1093 self._readline.__self__.close() 1094 1095 self._parsing_kconfigs = False 1096 1097 # Do various menu tree post-processing 1098 self._finalize_node(self.top_node, self.y) 1099 1100 self.unique_defined_syms = _ordered_unique(self.defined_syms) 1101 self.unique_choices = _ordered_unique(self.choices) 1102 1103 # Do sanity checks. Some of these depend on everything being finalized. 1104 self._check_sym_sanity() 1105 self._check_choice_sanity() 1106 1107 # KCONFIG_STRICT is an older alias for KCONFIG_WARN_UNDEF, supported 1108 # for backwards compatibility 1109 if os.getenv("KCONFIG_WARN_UNDEF") == "y" or \ 1110 os.getenv("KCONFIG_STRICT") == "y": 1111 1112 self._check_undef_syms() 1113 1114 # Build Symbol._dependents for all symbols and choices 1115 self._build_dep() 1116 1117 # Check for dependency loops 1118 check_dep_loop_sym = _check_dep_loop_sym # Micro-optimization 1119 for sym in self.unique_defined_syms: 1120 check_dep_loop_sym(sym, False) 1121 1122 # Add extra dependencies from choices to choice symbols that get 1123 # awkward during dependency loop detection 1124 self._add_choice_deps() 1125 1126 @property 1127 def mainmenu_text(self): 1128 """ 1129 See the class documentation. 1130 """ 1131 return self.top_node.prompt[0] 1132 1133 @property 1134 def defconfig_filename(self): 1135 """ 1136 See the class documentation. 1137 """ 1138 if self.defconfig_list: 1139 for filename, cond in self.defconfig_list.defaults: 1140 if expr_value(cond): 1141 try: 1142 with self._open_config(filename.str_value) as f: 1143 return f.name 1144 except EnvironmentError: 1145 continue 1146 1147 return None 1148 1149 def load_config(self, filename=None, replace=True, verbose=None): 1150 """ 1151 Loads symbol values from a file in the .config format. Equivalent to 1152 calling Symbol.set_value() to set each of the values. 1153 1154 "# CONFIG_FOO is not set" within a .config file sets the user value of 1155 FOO to n. The C tools work the same way. 1156 1157 For each symbol, the Symbol.user_value attribute holds the value the 1158 symbol was assigned in the .config file (if any). The user value might 1159 differ from Symbol.str/tri_value if there are unsatisfied dependencies. 1160 1161 Calling this function also updates the Kconfig.missing_syms attribute 1162 with a list of all assignments to undefined symbols within the 1163 configuration file. Kconfig.missing_syms is cleared if 'replace' is 1164 True, and appended to otherwise. See the documentation for 1165 Kconfig.missing_syms as well. 1166 1167 See the Kconfig.__init__() docstring for raised exceptions 1168 (OSError/IOError). KconfigError is never raised here. 1169 1170 filename (default: None): 1171 Path to load configuration from (a string). Respects $srctree if set 1172 (see the class documentation). 1173 1174 If 'filename' is None (the default), the configuration file to load 1175 (if any) is calculated automatically, giving the behavior you'd 1176 usually want: 1177 1178 1. If the KCONFIG_CONFIG environment variable is set, it gives the 1179 path to the configuration file to load. Otherwise, ".config" is 1180 used. See standard_config_filename(). 1181 1182 2. If the path from (1.) doesn't exist, the configuration file 1183 given by kconf.defconfig_filename is loaded instead, which is 1184 derived from the 'option defconfig_list' symbol. 1185 1186 3. If (1.) and (2.) fail to find a configuration file to load, no 1187 configuration file is loaded, and symbols retain their current 1188 values (e.g., their default values). This is not an error. 1189 1190 See the return value as well. 1191 1192 replace (default: True): 1193 If True, all existing user values will be cleared before loading the 1194 .config. Pass False to merge configurations. 1195 1196 verbose (default: None): 1197 Limited backwards compatibility to prevent crashes. A warning is 1198 printed if anything but None is passed. 1199 1200 Prior to Kconfiglib 12.0.0, this option enabled printing of messages 1201 to stdout when 'filename' was None. A message is (always) returned 1202 now instead, which is more flexible. 1203 1204 Will probably be removed in some future version. 1205 1206 Returns a string with a message saying which file got loaded (or 1207 possibly that no file got loaded, when 'filename' is None). This is 1208 meant to reduce boilerplate in tools, which can do e.g. 1209 print(kconf.load_config()). The returned message distinguishes between 1210 loading (replace == True) and merging (replace == False). 1211 """ 1212 if verbose is not None: 1213 _warn_verbose_deprecated("load_config") 1214 1215 msg = None 1216 if filename is None: 1217 filename = standard_config_filename() 1218 if not exists(filename) and \ 1219 not exists(join(self.srctree, filename)): 1220 defconfig = self.defconfig_filename 1221 if defconfig is None: 1222 return "Using default symbol values (no '{}')" \ 1223 .format(filename) 1224 1225 msg = " default configuration '{}' (no '{}')" \ 1226 .format(defconfig, filename) 1227 filename = defconfig 1228 1229 if not msg: 1230 msg = " configuration '{}'".format(filename) 1231 1232 # Disable the warning about assigning to symbols without prompts. This 1233 # is normal and expected within a .config file. 1234 self._warn_assign_no_prompt = False 1235 1236 # This stub only exists to make sure _warn_assign_no_prompt gets 1237 # reenabled 1238 try: 1239 self._load_config(filename, replace) 1240 except UnicodeDecodeError as e: 1241 _decoding_error(e, filename) 1242 finally: 1243 self._warn_assign_no_prompt = True 1244 1245 return ("Loaded" if replace else "Merged") + msg 1246 1247 def _load_config(self, filename, replace): 1248 with self._open_config(filename) as f: 1249 if replace: 1250 self.missing_syms = [] 1251 1252 # If we're replacing the configuration, keep track of which 1253 # symbols and choices got set so that we can unset the rest 1254 # later. This avoids invalidating everything and is faster. 1255 # Another benefit is that invalidation must be rock solid for 1256 # it to work, making it a good test. 1257 1258 for sym in self.unique_defined_syms: 1259 sym._was_set = False 1260 1261 for choice in self.unique_choices: 1262 choice._was_set = False 1263 1264 # Small optimizations 1265 set_match = self._set_match 1266 unset_match = self._unset_match 1267 get_sym = self.syms.get 1268 1269 for linenr, line in enumerate(f, 1): 1270 # The C tools ignore trailing whitespace 1271 line = line.rstrip() 1272 1273 match = set_match(line) 1274 if match: 1275 name, val = match.groups() 1276 sym = get_sym(name) 1277 if not sym or not sym.nodes: 1278 self._undef_assign(name, val, filename, linenr) 1279 continue 1280 1281 if sym.orig_type in _BOOL_TRISTATE: 1282 # The C implementation only checks the first character 1283 # to the right of '=', for whatever reason 1284 if not (sym.orig_type is BOOL 1285 and val.startswith(("y", "n")) or 1286 sym.orig_type is TRISTATE 1287 and val.startswith(("y", "m", "n"))): 1288 self._warn("'{}' is not a valid value for the {} " 1289 "symbol {}. Assignment ignored." 1290 .format(val, TYPE_TO_STR[sym.orig_type], 1291 sym.name_and_loc), 1292 filename, linenr) 1293 continue 1294 1295 val = val[0] 1296 1297 if sym.choice and val != "n": 1298 # During .config loading, we infer the mode of the 1299 # choice from the kind of values that are assigned 1300 # to the choice symbols 1301 1302 prev_mode = sym.choice.user_value 1303 if prev_mode is not None and \ 1304 TRI_TO_STR[prev_mode] != val: 1305 1306 self._warn("both m and y assigned to symbols " 1307 "within the same choice", 1308 filename, linenr) 1309 1310 # Set the choice's mode 1311 sym.choice.set_value(val) 1312 1313 elif sym.orig_type is STRING: 1314 match = _conf_string_match(val) 1315 if not match: 1316 self._warn("malformed string literal in " 1317 "assignment to {}. Assignment ignored." 1318 .format(sym.name_and_loc), 1319 filename, linenr) 1320 continue 1321 1322 val = unescape(match.group(1)) 1323 1324 else: 1325 match = unset_match(line) 1326 if not match: 1327 # Print a warning for lines that match neither 1328 # set_match() nor unset_match() and that are not blank 1329 # lines or comments. 'line' has already been 1330 # rstrip()'d, so blank lines show up as "" here. 1331 if line and not line.lstrip().startswith("#"): 1332 self._warn("ignoring malformed line '{}'" 1333 .format(line), 1334 filename, linenr) 1335 1336 continue 1337 1338 name = match.group(1) 1339 sym = get_sym(name) 1340 if not sym or not sym.nodes: 1341 self._undef_assign(name, "n", filename, linenr) 1342 continue 1343 1344 if sym.orig_type not in _BOOL_TRISTATE: 1345 continue 1346 1347 val = "n" 1348 1349 # Done parsing the assignment. Set the value. 1350 1351 if sym._was_set: 1352 self._assigned_twice(sym, val, filename, linenr) 1353 1354 sym.set_value(val) 1355 1356 if replace: 1357 # If we're replacing the configuration, unset the symbols that 1358 # didn't get set 1359 1360 for sym in self.unique_defined_syms: 1361 if not sym._was_set: 1362 sym.unset_value() 1363 1364 for choice in self.unique_choices: 1365 if not choice._was_set: 1366 choice.unset_value() 1367 1368 def _undef_assign(self, name, val, filename, linenr): 1369 # Called for assignments to undefined symbols during .config loading 1370 1371 self.missing_syms.append((name, val)) 1372 if self.warn_assign_undef: 1373 self._warn( 1374 "attempt to assign the value '{}' to the undefined symbol {}" 1375 .format(val, name), filename, linenr) 1376 1377 def _assigned_twice(self, sym, new_val, filename, linenr): 1378 # Called when a symbol is assigned more than once in a .config file 1379 1380 # Use strings for bool/tristate user values in the warning 1381 if sym.orig_type in _BOOL_TRISTATE: 1382 user_val = TRI_TO_STR[sym.user_value] 1383 else: 1384 user_val = sym.user_value 1385 1386 msg = '{} set more than once. Old value "{}", new value "{}".'.format( 1387 sym.name_and_loc, user_val, new_val) 1388 1389 if user_val == new_val: 1390 if self.warn_assign_redun: 1391 self._warn(msg, filename, linenr) 1392 elif self.warn_assign_override: 1393 self._warn(msg, filename, linenr) 1394 1395 def load_allconfig(self, filename): 1396 """ 1397 Helper for all*config. Loads (merges) the configuration file specified 1398 by KCONFIG_ALLCONFIG, if any. See Documentation/kbuild/kconfig.txt in 1399 the Linux kernel. 1400 1401 Disables warnings for duplicated assignments within configuration files 1402 for the duration of the call 1403 (kconf.warn_assign_override/warn_assign_redun = False), and restores 1404 the previous warning settings at the end. The KCONFIG_ALLCONFIG 1405 configuration file is expected to override symbols. 1406 1407 Exits with sys.exit() (which raises a SystemExit exception) and prints 1408 an error to stderr if KCONFIG_ALLCONFIG is set but the configuration 1409 file can't be opened. 1410 1411 filename: 1412 Command-specific configuration filename - "allyes.config", 1413 "allno.config", etc. 1414 """ 1415 load_allconfig(self, filename) 1416 1417 def write_autoconf(self, filename=None, header=None): 1418 r""" 1419 Writes out symbol values as a C header file, matching the format used 1420 by include/generated/zephyr/autoconf.h in the kernel. 1421 1422 The ordering of the #defines matches the one generated by 1423 write_config(). The order in the C implementation depends on the hash 1424 table implementation as of writing, and so won't match. 1425 1426 If 'filename' exists and its contents is identical to what would get 1427 written out, it is left untouched. This avoids updating file metadata 1428 like the modification time and possibly triggering redundant work in 1429 build tools. 1430 1431 filename (default: None): 1432 Path to write header to. 1433 1434 If None (the default), the path in the environment variable 1435 KCONFIG_AUTOHEADER is used if set, and "include/generated/zephyr/autoconf.h" 1436 otherwise. This is compatible with the C tools. 1437 1438 header (default: None): 1439 Text inserted verbatim at the beginning of the file. You would 1440 usually want it enclosed in '/* */' to make it a C comment, and 1441 include a trailing newline. 1442 1443 If None (the default), the value of the environment variable 1444 KCONFIG_AUTOHEADER_HEADER had when the Kconfig instance was created 1445 will be used if it was set, and no header otherwise. See the 1446 Kconfig.header_header attribute. 1447 1448 Returns a string with a message saying that the header got saved, or 1449 that there were no changes to it. This is meant to reduce boilerplate 1450 in tools, which can do e.g. print(kconf.write_autoconf()). 1451 """ 1452 if filename is None: 1453 filename = os.getenv("KCONFIG_AUTOHEADER", 1454 "include/generated/zephyr/autoconf.h") 1455 1456 if self._write_if_changed(filename, self._autoconf_contents(header)): 1457 return "Kconfig header saved to '{}'".format(filename) 1458 return "No change to Kconfig header in '{}'".format(filename) 1459 1460 def _autoconf_contents(self, header): 1461 # write_autoconf() helper. Returns the contents to write as a string, 1462 # with 'header' or KCONFIG_AUTOHEADER_HEADER at the beginning. 1463 1464 if header is None: 1465 header = self.header_header 1466 1467 chunks = [header] # "".join()ed later 1468 add = chunks.append 1469 1470 for sym in self.unique_defined_syms: 1471 # _write_to_conf is determined when the value is calculated. This 1472 # is a hidden function call due to property magic. 1473 # 1474 # Note: In client code, you can check if sym.config_string is empty 1475 # instead, to avoid accessing the internal _write_to_conf variable 1476 # (though it's likely to keep working). 1477 val = sym.str_value 1478 if not sym._write_to_conf: 1479 continue 1480 1481 if sym.orig_type in _BOOL_TRISTATE: 1482 if val == "y": 1483 add("#define {}{} 1\n" 1484 .format(self.config_prefix, sym.name)) 1485 elif val == "m": 1486 add("#define {}{}_MODULE 1\n" 1487 .format(self.config_prefix, sym.name)) 1488 1489 elif sym.orig_type is STRING: 1490 add('#define {}{} "{}"\n' 1491 .format(self.config_prefix, sym.name, escape(val))) 1492 1493 else: # sym.orig_type in _INT_HEX: 1494 if sym.orig_type is HEX and \ 1495 not val.startswith(("0x", "0X")): 1496 val = "0x" + val 1497 1498 add("#define {}{} {}\n" 1499 .format(self.config_prefix, sym.name, val)) 1500 1501 return "".join(chunks) 1502 1503 def write_config(self, filename=None, header=None, save_old=True, 1504 verbose=None): 1505 r""" 1506 Writes out symbol values in the .config format. The format matches the 1507 C implementation, including ordering. 1508 1509 Symbols appear in the same order in generated .config files as they do 1510 in the Kconfig files. For symbols defined in multiple locations, a 1511 single assignment is written out corresponding to the first location 1512 where the symbol is defined. 1513 1514 See the 'Intro to symbol values' section in the module docstring to 1515 understand which symbols get written out. 1516 1517 If 'filename' exists and its contents is identical to what would get 1518 written out, it is left untouched. This avoids updating file metadata 1519 like the modification time and possibly triggering redundant work in 1520 build tools. 1521 1522 See the Kconfig.__init__() docstring for raised exceptions 1523 (OSError/IOError). KconfigError is never raised here. 1524 1525 filename (default: None): 1526 Path to write configuration to (a string). 1527 1528 If None (the default), the path in the environment variable 1529 KCONFIG_CONFIG is used if set, and ".config" otherwise. See 1530 standard_config_filename(). 1531 1532 header (default: None): 1533 Text inserted verbatim at the beginning of the file. You would 1534 usually want each line to start with '#' to make it a comment, and 1535 include a trailing newline. 1536 1537 if None (the default), the value of the environment variable 1538 KCONFIG_CONFIG_HEADER had when the Kconfig instance was created will 1539 be used if it was set, and no header otherwise. See the 1540 Kconfig.config_header attribute. 1541 1542 save_old (default: True): 1543 If True and <filename> already exists, a copy of it will be saved to 1544 <filename>.old in the same directory before the new configuration is 1545 written. 1546 1547 Errors are silently ignored if <filename>.old cannot be written (e.g. 1548 due to being a directory, or <filename> being something like 1549 /dev/null). 1550 1551 verbose (default: None): 1552 Limited backwards compatibility to prevent crashes. A warning is 1553 printed if anything but None is passed. 1554 1555 Prior to Kconfiglib 12.0.0, this option enabled printing of messages 1556 to stdout when 'filename' was None. A message is (always) returned 1557 now instead, which is more flexible. 1558 1559 Will probably be removed in some future version. 1560 1561 Returns a string with a message saying which file got saved. This is 1562 meant to reduce boilerplate in tools, which can do e.g. 1563 print(kconf.write_config()). 1564 """ 1565 if verbose is not None: 1566 _warn_verbose_deprecated("write_config") 1567 1568 if filename is None: 1569 filename = standard_config_filename() 1570 1571 contents = self._config_contents(header) 1572 if self._contents_eq(filename, contents): 1573 return "No change to configuration in '{}'".format(filename) 1574 1575 if save_old: 1576 _save_old(filename) 1577 1578 with self._open(filename, "w") as f: 1579 f.write(contents) 1580 1581 return "Configuration saved to '{}'".format(filename) 1582 1583 def _config_contents(self, header): 1584 # write_config() helper. Returns the contents to write as a string, 1585 # with 'header' or KCONFIG_CONFIG_HEADER at the beginning. 1586 # 1587 # More memory friendly would be to 'yield' the strings and 1588 # "".join(_config_contents()), but it was a bit slower on my system. 1589 1590 # node_iter() was used here before commit 3aea9f7 ("Add '# end of 1591 # <menu>' after menus in .config"). Those comments get tricky to 1592 # implement with it. 1593 1594 for sym in self.unique_defined_syms: 1595 sym._visited = False 1596 1597 if header is None: 1598 header = self.config_header 1599 1600 chunks = [header] # "".join()ed later 1601 add = chunks.append 1602 1603 # Did we just print an '# end of ...' comment? 1604 after_end_comment = False 1605 1606 node = self.top_node 1607 while 1: 1608 # Jump to the next node with an iterative tree walk 1609 if node.list: 1610 node = node.list 1611 elif node.next: 1612 node = node.next 1613 else: 1614 while node.parent: 1615 node = node.parent 1616 1617 # Add a comment when leaving visible menus 1618 if node.item is MENU and expr_value(node.dep) and \ 1619 expr_value(node.visibility) and \ 1620 node is not self.top_node: 1621 add("# end of {}\n".format(node.prompt[0])) 1622 after_end_comment = True 1623 1624 if node.next: 1625 node = node.next 1626 break 1627 else: 1628 # No more nodes 1629 return "".join(chunks) 1630 1631 # Generate configuration output for the node 1632 1633 item = node.item 1634 1635 if item.__class__ is Symbol: 1636 if item._visited: 1637 continue 1638 item._visited = True 1639 1640 conf_string = item.config_string 1641 if not conf_string: 1642 continue 1643 1644 if after_end_comment: 1645 # Add a blank line before the first symbol printed after an 1646 # '# end of ...' comment 1647 after_end_comment = False 1648 add("\n") 1649 add(conf_string) 1650 1651 elif expr_value(node.dep) and \ 1652 ((item is MENU and expr_value(node.visibility)) or 1653 item is COMMENT): 1654 1655 add("\n#\n# {}\n#\n".format(node.prompt[0])) 1656 after_end_comment = False 1657 1658 def write_min_config(self, filename, header=None): 1659 """ 1660 Writes out a "minimal" configuration file, omitting symbols whose value 1661 matches their default value. The format matches the one produced by 1662 'make savedefconfig'. 1663 1664 The resulting configuration file is incomplete, but a complete 1665 configuration can be derived from it by loading it. Minimal 1666 configuration files can serve as a more manageable configuration format 1667 compared to a "full" .config file, especially when configurations files 1668 are merged or edited by hand. 1669 1670 See the Kconfig.__init__() docstring for raised exceptions 1671 (OSError/IOError). KconfigError is never raised here. 1672 1673 filename: 1674 Path to write minimal configuration to. 1675 1676 header (default: None): 1677 Text inserted verbatim at the beginning of the file. You would 1678 usually want each line to start with '#' to make it a comment, and 1679 include a final terminating newline. 1680 1681 if None (the default), the value of the environment variable 1682 KCONFIG_CONFIG_HEADER had when the Kconfig instance was created will 1683 be used if it was set, and no header otherwise. See the 1684 Kconfig.config_header attribute. 1685 1686 Returns a string with a message saying the minimal configuration got 1687 saved, or that there were no changes to it. This is meant to reduce 1688 boilerplate in tools, which can do e.g. 1689 print(kconf.write_min_config()). 1690 """ 1691 if self._write_if_changed(filename, self._min_config_contents(header)): 1692 return "Minimal configuration saved to '{}'".format(filename) 1693 return "No change to minimal configuration in '{}'".format(filename) 1694 1695 def _min_config_contents(self, header): 1696 # write_min_config() helper. Returns the contents to write as a string, 1697 # with 'header' or KCONFIG_CONFIG_HEADER at the beginning. 1698 1699 if header is None: 1700 header = self.config_header 1701 1702 chunks = [header] # "".join()ed later 1703 add = chunks.append 1704 1705 for sym in self.unique_defined_syms: 1706 # Skip symbols that cannot be changed. Only check 1707 # non-choice symbols, as selects don't affect choice 1708 # symbols. 1709 if not sym.choice and \ 1710 sym.visibility <= expr_value(sym.rev_dep): 1711 continue 1712 1713 # Skip symbols whose value matches their default 1714 if sym.str_value == sym._str_default(): 1715 continue 1716 1717 # Skip symbols that would be selected by default in a 1718 # choice, unless the choice is optional or the symbol type 1719 # isn't bool (it might be possible to set the choice mode 1720 # to n or the symbol to m in those cases). 1721 if sym.choice and \ 1722 not sym.choice.is_optional and \ 1723 sym.choice._selection_from_defaults() is sym and \ 1724 sym.orig_type is BOOL and \ 1725 sym.tri_value == 2: 1726 continue 1727 1728 add(sym.config_string) 1729 1730 return "".join(chunks) 1731 1732 def sync_deps(self, path): 1733 """ 1734 Creates or updates a directory structure that can be used to avoid 1735 doing a full rebuild whenever the configuration is changed, mirroring 1736 include/config/ in the kernel. 1737 1738 This function is intended to be called during each build, before 1739 compiling source files that depend on configuration symbols. 1740 1741 See the Kconfig.__init__() docstring for raised exceptions 1742 (OSError/IOError). KconfigError is never raised here. 1743 1744 path: 1745 Path to directory 1746 1747 sync_deps(path) does the following: 1748 1749 1. If the directory <path> does not exist, it is created. 1750 1751 2. If <path>/auto.conf exists, old symbol values are loaded from it, 1752 which are then compared against the current symbol values. If a 1753 symbol has changed value (would generate different output in 1754 autoconf.h compared to before), the change is signaled by 1755 touch'ing a file corresponding to the symbol. 1756 1757 The first time sync_deps() is run on a directory, <path>/auto.conf 1758 won't exist, and no old symbol values will be available. This 1759 logically has the same effect as updating the entire 1760 configuration. 1761 1762 The path to a symbol's file is calculated from the symbol's name 1763 by replacing all '_' with '/' and appending '.h'. For example, the 1764 symbol FOO_BAR_BAZ gets the file <path>/foo/bar/baz.h, and FOO 1765 gets the file <path>/foo.h. 1766 1767 This scheme matches the C tools. The point is to avoid having a 1768 single directory with a huge number of files, which the underlying 1769 filesystem might not handle well. 1770 1771 3. A new auto.conf with the current symbol values is written, to keep 1772 track of them for the next build. 1773 1774 If auto.conf exists and its contents is identical to what would 1775 get written out, it is left untouched. This avoids updating file 1776 metadata like the modification time and possibly triggering 1777 redundant work in build tools. 1778 1779 1780 The last piece of the puzzle is knowing what symbols each source file 1781 depends on. Knowing that, dependencies can be added from source files 1782 to the files corresponding to the symbols they depends on. The source 1783 file will then get recompiled (only) when the symbol value changes 1784 (provided sync_deps() is run first during each build). 1785 1786 The tool in the kernel that extracts symbol dependencies from source 1787 files is scripts/basic/fixdep.c. Missing symbol files also correspond 1788 to "not changed", which fixdep deals with by using the $(wildcard) Make 1789 function when adding symbol prerequisites to source files. 1790 1791 In case you need a different scheme for your project, the sync_deps() 1792 implementation can be used as a template. 1793 """ 1794 if not exists(path): 1795 os.mkdir(path, 0o755) 1796 1797 # Load old values from auto.conf, if any 1798 self._load_old_vals(path) 1799 1800 for sym in self.unique_defined_syms: 1801 # _write_to_conf is determined when the value is calculated. This 1802 # is a hidden function call due to property magic. 1803 # 1804 # Note: In client code, you can check if sym.config_string is empty 1805 # instead, to avoid accessing the internal _write_to_conf variable 1806 # (though it's likely to keep working). 1807 val = sym.str_value 1808 1809 # n tristate values do not get written to auto.conf and autoconf.h, 1810 # making a missing symbol logically equivalent to n 1811 1812 if sym._write_to_conf: 1813 if sym._old_val is None and \ 1814 sym.orig_type in _BOOL_TRISTATE and \ 1815 val == "n": 1816 # No old value (the symbol was missing or n), new value n. 1817 # No change. 1818 continue 1819 1820 if val == sym._old_val: 1821 # New value matches old. No change. 1822 continue 1823 1824 elif sym._old_val is None: 1825 # The symbol wouldn't appear in autoconf.h (because 1826 # _write_to_conf is false), and it wouldn't have appeared in 1827 # autoconf.h previously either (because it didn't appear in 1828 # auto.conf). No change. 1829 continue 1830 1831 # 'sym' has a new value. Flag it. 1832 _touch_dep_file(path, sym.name) 1833 1834 # Remember the current values as the "new old" values. 1835 # 1836 # This call could go anywhere after the call to _load_old_vals(), but 1837 # putting it last means _sync_deps() can be safely rerun if it fails 1838 # before this point. 1839 self._write_old_vals(path) 1840 1841 def _load_old_vals(self, path): 1842 # Loads old symbol values from auto.conf into a dedicated 1843 # Symbol._old_val field. Mirrors load_config(). 1844 # 1845 # The extra field could be avoided with some trickery involving dumping 1846 # symbol values and restoring them later, but this is simpler and 1847 # faster. The C tools also use a dedicated field for this purpose. 1848 1849 for sym in self.unique_defined_syms: 1850 sym._old_val = None 1851 1852 try: 1853 auto_conf = self._open(join(path, "auto.conf"), "r") 1854 except EnvironmentError as e: 1855 if e.errno == errno.ENOENT: 1856 # No old values 1857 return 1858 raise 1859 1860 with auto_conf as f: 1861 for line in f: 1862 match = self._set_match(line) 1863 if not match: 1864 # We only expect CONFIG_FOO=... (and possibly a header 1865 # comment) in auto.conf 1866 continue 1867 1868 name, val = match.groups() 1869 if name in self.syms: 1870 sym = self.syms[name] 1871 1872 if sym.orig_type is STRING: 1873 match = _conf_string_match(val) 1874 if not match: 1875 continue 1876 val = unescape(match.group(1)) 1877 1878 self.syms[name]._old_val = val 1879 else: 1880 # Flag that the symbol no longer exists, in 1881 # case something still depends on it 1882 _touch_dep_file(path, name) 1883 1884 def _write_old_vals(self, path): 1885 # Helper for writing auto.conf. Basically just a simplified 1886 # write_config() that doesn't write any comments (including 1887 # '# CONFIG_FOO is not set' comments). The format matches the C 1888 # implementation, though the ordering is arbitrary there (depends on 1889 # the hash table implementation). 1890 # 1891 # A separate helper function is neater than complicating write_config() 1892 # by passing a flag to it, plus we only need to look at symbols here. 1893 1894 self._write_if_changed( 1895 os.path.join(path, "auto.conf"), 1896 self._old_vals_contents()) 1897 1898 def _old_vals_contents(self): 1899 # _write_old_vals() helper. Returns the contents to write as a string. 1900 1901 # Temporary list instead of generator makes this a bit faster 1902 return "".join([ 1903 sym.config_string for sym in self.unique_defined_syms 1904 if not (sym.orig_type in _BOOL_TRISTATE and not sym.tri_value) 1905 ]) 1906 1907 def node_iter(self, unique_syms=False): 1908 """ 1909 Returns a generator for iterating through all MenuNode's in the Kconfig 1910 tree. The iteration is done in Kconfig definition order (each node is 1911 visited before its children, and the children of a node are visited 1912 before the next node). 1913 1914 The Kconfig.top_node menu node is skipped. It contains an implicit menu 1915 that holds the top-level items. 1916 1917 As an example, the following code will produce a list equal to 1918 Kconfig.defined_syms: 1919 1920 defined_syms = [node.item for node in kconf.node_iter() 1921 if isinstance(node.item, Symbol)] 1922 1923 unique_syms (default: False): 1924 If True, only the first MenuNode will be included for symbols defined 1925 in multiple locations. 1926 1927 Using kconf.node_iter(True) in the example above would give a list 1928 equal to unique_defined_syms. 1929 """ 1930 if unique_syms: 1931 for sym in self.unique_defined_syms: 1932 sym._visited = False 1933 1934 node = self.top_node 1935 while 1: 1936 # Jump to the next node with an iterative tree walk 1937 if node.list: 1938 node = node.list 1939 elif node.next: 1940 node = node.next 1941 else: 1942 while node.parent: 1943 node = node.parent 1944 if node.next: 1945 node = node.next 1946 break 1947 else: 1948 # No more nodes 1949 return 1950 1951 if unique_syms and node.item.__class__ is Symbol: 1952 if node.item._visited: 1953 continue 1954 node.item._visited = True 1955 1956 yield node 1957 1958 def eval_string(self, s): 1959 """ 1960 Returns the tristate value of the expression 's', represented as 0, 1, 1961 and 2 for n, m, and y, respectively. Raises KconfigError on syntax 1962 errors. Warns if undefined symbols are referenced. 1963 1964 As an example, if FOO and BAR are tristate symbols at least one of 1965 which has the value y, then eval_string("y && (FOO || BAR)") returns 1966 2 (y). 1967 1968 To get the string value of non-bool/tristate symbols, use 1969 Symbol.str_value. eval_string() always returns a tristate value, and 1970 all non-bool/tristate symbols have the tristate value 0 (n). 1971 1972 The expression parsing is consistent with how parsing works for 1973 conditional ('if ...') expressions in the configuration, and matches 1974 the C implementation. m is rewritten to 'm && MODULES', so 1975 eval_string("m") will return 0 (n) unless modules are enabled. 1976 """ 1977 # The parser is optimized to be fast when parsing Kconfig files (where 1978 # an expression can never appear at the beginning of a line). We have 1979 # to monkey-patch things a bit here to reuse it. 1980 1981 self.filename = None 1982 1983 self._tokens = self._tokenize("if " + s) 1984 # Strip "if " to avoid giving confusing error messages 1985 self._line = s 1986 self._tokens_i = 1 # Skip the 'if' token 1987 1988 return expr_value(self._expect_expr_and_eol()) 1989 1990 def unset_values(self): 1991 """ 1992 Removes any user values from all symbols, as if Kconfig.load_config() 1993 or Symbol.set_value() had never been called. 1994 """ 1995 self._warn_assign_no_prompt = False 1996 try: 1997 # set_value() already rejects undefined symbols, and they don't 1998 # need to be invalidated (because their value never changes), so we 1999 # can just iterate over defined symbols 2000 for sym in self.unique_defined_syms: 2001 sym.unset_value() 2002 2003 for choice in self.unique_choices: 2004 choice.unset_value() 2005 finally: 2006 self._warn_assign_no_prompt = True 2007 2008 def enable_warnings(self): 2009 """ 2010 Do 'Kconfig.warn = True' instead. Maintained for backwards 2011 compatibility. 2012 """ 2013 self.warn = True 2014 2015 def disable_warnings(self): 2016 """ 2017 Do 'Kconfig.warn = False' instead. Maintained for backwards 2018 compatibility. 2019 """ 2020 self.warn = False 2021 2022 def enable_stderr_warnings(self): 2023 """ 2024 Do 'Kconfig.warn_to_stderr = True' instead. Maintained for backwards 2025 compatibility. 2026 """ 2027 self.warn_to_stderr = True 2028 2029 def disable_stderr_warnings(self): 2030 """ 2031 Do 'Kconfig.warn_to_stderr = False' instead. Maintained for backwards 2032 compatibility. 2033 """ 2034 self.warn_to_stderr = False 2035 2036 def enable_undef_warnings(self): 2037 """ 2038 Do 'Kconfig.warn_assign_undef = True' instead. Maintained for backwards 2039 compatibility. 2040 """ 2041 self.warn_assign_undef = True 2042 2043 def disable_undef_warnings(self): 2044 """ 2045 Do 'Kconfig.warn_assign_undef = False' instead. Maintained for 2046 backwards compatibility. 2047 """ 2048 self.warn_assign_undef = False 2049 2050 def enable_override_warnings(self): 2051 """ 2052 Do 'Kconfig.warn_assign_override = True' instead. Maintained for 2053 backwards compatibility. 2054 """ 2055 self.warn_assign_override = True 2056 2057 def disable_override_warnings(self): 2058 """ 2059 Do 'Kconfig.warn_assign_override = False' instead. Maintained for 2060 backwards compatibility. 2061 """ 2062 self.warn_assign_override = False 2063 2064 def enable_redun_warnings(self): 2065 """ 2066 Do 'Kconfig.warn_assign_redun = True' instead. Maintained for backwards 2067 compatibility. 2068 """ 2069 self.warn_assign_redun = True 2070 2071 def disable_redun_warnings(self): 2072 """ 2073 Do 'Kconfig.warn_assign_redun = False' instead. Maintained for 2074 backwards compatibility. 2075 """ 2076 self.warn_assign_redun = False 2077 2078 def __repr__(self): 2079 """ 2080 Returns a string with information about the Kconfig object when it is 2081 evaluated on e.g. the interactive Python prompt. 2082 """ 2083 def status(flag): 2084 return "enabled" if flag else "disabled" 2085 2086 return "<{}>".format(", ".join(( 2087 "configuration with {} symbols".format(len(self.syms)), 2088 'main menu prompt "{}"'.format(self.mainmenu_text), 2089 "srctree is current directory" if not self.srctree else 2090 'srctree "{}"'.format(self.srctree), 2091 'config symbol prefix "{}"'.format(self.config_prefix), 2092 "warnings " + status(self.warn), 2093 "printing of warnings to stderr " + status(self.warn_to_stderr), 2094 "undef. symbol assignment warnings " + 2095 status(self.warn_assign_undef), 2096 "overriding symbol assignment warnings " + 2097 status(self.warn_assign_override), 2098 "redundant symbol assignment warnings " + 2099 status(self.warn_assign_redun) 2100 ))) 2101 2102 # 2103 # Private methods 2104 # 2105 2106 2107 # 2108 # File reading 2109 # 2110 2111 def _open_config(self, filename): 2112 # Opens a .config file. First tries to open 'filename', then 2113 # '$srctree/filename' if $srctree was set when the configuration was 2114 # loaded. 2115 2116 try: 2117 return self._open(filename, "r") 2118 except EnvironmentError as e: 2119 # This will try opening the same file twice if $srctree is unset, 2120 # but it's not a big deal 2121 try: 2122 return self._open(join(self.srctree, filename), "r") 2123 except EnvironmentError as e2: 2124 # This is needed for Python 3, because e2 is deleted after 2125 # the try block: 2126 # 2127 # https://docs.python.org/3/reference/compound_stmts.html#the-try-statement 2128 e = e2 2129 2130 raise _KconfigIOError( 2131 e, "Could not open '{}' ({}: {}). Check that the $srctree " 2132 "environment variable ({}) is set correctly." 2133 .format(filename, errno.errorcode[e.errno], e.strerror, 2134 "set to '{}'".format(self.srctree) if self.srctree 2135 else "unset or blank")) 2136 2137 def _enter_file(self, filename): 2138 # Jumps to the beginning of a sourced Kconfig file, saving the previous 2139 # position and file object. 2140 # 2141 # filename: 2142 # Absolute path to file 2143 2144 # Path relative to $srctree, stored in e.g. self.filename (which makes 2145 # it indirectly show up in MenuNode.filename). Equals 'filename' for 2146 # absolute paths passed to 'source'. 2147 if filename.startswith(self._srctree_prefix): 2148 # Relative path (or a redundant absolute path to within $srctree, 2149 # but it's probably fine to reduce those too) 2150 rel_filename = filename[len(self._srctree_prefix):] 2151 else: 2152 # Absolute path 2153 rel_filename = filename 2154 2155 self.kconfig_filenames.append(rel_filename) 2156 2157 # The parent Kconfig files are represented as a list of 2158 # (<include path>, <Python 'file' object for Kconfig file>) tuples. 2159 # 2160 # <include path> is immutable and holds a *tuple* of 2161 # (<filename>, <linenr>) tuples, giving the locations of the 'source' 2162 # statements in the parent Kconfig files. The current include path is 2163 # also available in Kconfig._include_path. 2164 # 2165 # The point of this redundant setup is to allow Kconfig._include_path 2166 # to be assigned directly to MenuNode.include_path without having to 2167 # copy it, sharing it wherever possible. 2168 2169 # Save include path and 'file' object (via its 'readline' function) 2170 # before entering the file 2171 self._filestack.append((self._include_path, self._readline)) 2172 2173 # _include_path is a tuple, so this rebinds the variable instead of 2174 # doing in-place modification 2175 self._include_path += ((self.filename, self.linenr),) 2176 2177 # Check for recursive 'source' 2178 for name, _ in self._include_path: 2179 if name == rel_filename: 2180 raise KconfigError( 2181 "\n{}:{}: recursive 'source' of '{}' detected. Check that " 2182 "environment variables are set correctly.\n" 2183 "Include path:\n{}" 2184 .format(self.filename, self.linenr, rel_filename, 2185 "\n".join("{}:{}".format(name, linenr) 2186 for name, linenr in self._include_path))) 2187 2188 try: 2189 self._readline = self._open(filename, "r").readline 2190 except EnvironmentError as e: 2191 # We already know that the file exists 2192 raise _KconfigIOError( 2193 e, "{}:{}: Could not open '{}' (in '{}') ({}: {})" 2194 .format(self.filename, self.linenr, filename, 2195 self._line.strip(), 2196 errno.errorcode[e.errno], e.strerror)) 2197 2198 self.filename = rel_filename 2199 self.linenr = 0 2200 2201 def _leave_file(self): 2202 # Returns from a Kconfig file to the file that sourced it. See 2203 # _enter_file(). 2204 2205 # Restore location from parent Kconfig file 2206 self.filename, self.linenr = self._include_path[-1] 2207 # Restore include path and 'file' object 2208 self._readline.__self__.close() # __self__ fetches the 'file' object 2209 self._include_path, self._readline = self._filestack.pop() 2210 2211 def _next_line(self): 2212 # Fetches and tokenizes the next line from the current Kconfig file. 2213 # Returns False at EOF and True otherwise. 2214 2215 # We might already have tokens from parsing a line and discovering that 2216 # it's part of a different construct 2217 if self._reuse_tokens: 2218 self._reuse_tokens = False 2219 # self._tokens_i is known to be 1 here, because _parse_props() 2220 # leaves it like that when it can't recognize a line (or parses a 2221 # help text) 2222 return True 2223 2224 # readline() returns '' over and over at EOF, which we rely on for help 2225 # texts at the end of files (see _line_after_help()) 2226 line = self._readline() 2227 if not line: 2228 return False 2229 self.linenr += 1 2230 2231 # Handle line joining 2232 while line.endswith("\\\n"): 2233 line = line[:-2] + self._readline() 2234 self.linenr += 1 2235 2236 self._tokens = self._tokenize(line) 2237 # Initialize to 1 instead of 0 to factor out code from _parse_block() 2238 # and _parse_props(). They immediately fetch self._tokens[0]. 2239 self._tokens_i = 1 2240 2241 return True 2242 2243 def _line_after_help(self, line): 2244 # Tokenizes a line after a help text. This case is special in that the 2245 # line has already been fetched (to discover that it isn't part of the 2246 # help text). 2247 # 2248 # An earlier version used a _saved_line variable instead that was 2249 # checked in _next_line(). This special-casing gets rid of it and makes 2250 # _reuse_tokens alone sufficient to handle unget. 2251 2252 # Handle line joining 2253 while line.endswith("\\\n"): 2254 line = line[:-2] + self._readline() 2255 self.linenr += 1 2256 2257 self._tokens = self._tokenize(line) 2258 self._reuse_tokens = True 2259 2260 def _write_if_changed(self, filename, contents): 2261 # Writes 'contents' into 'filename', but only if it differs from the 2262 # current contents of the file. 2263 # 2264 # Another variant would be write a temporary file on the same 2265 # filesystem, compare the files, and rename() the temporary file if it 2266 # differs, but it breaks stuff like write_config("/dev/null"), which is 2267 # used out there to force evaluation-related warnings to be generated. 2268 # This simple version is pretty failsafe and portable. 2269 # 2270 # Returns True if the file has changed and is updated, and False 2271 # otherwise. 2272 2273 if self._contents_eq(filename, contents): 2274 return False 2275 with self._open(filename, "w") as f: 2276 f.write(contents) 2277 return True 2278 2279 def _contents_eq(self, filename, contents): 2280 # Returns True if the contents of 'filename' is 'contents' (a string), 2281 # and False otherwise (including if 'filename' can't be opened/read) 2282 2283 try: 2284 with self._open(filename, "r") as f: 2285 # Robust re. things like encoding and line endings (mmap() 2286 # trickery isn't) 2287 return f.read(len(contents) + 1) == contents 2288 except EnvironmentError: 2289 # If the error here would prevent writing the file as well, we'll 2290 # notice it later 2291 return False 2292 2293 # 2294 # Tokenization 2295 # 2296 2297 def _lookup_sym(self, name): 2298 # Fetches the symbol 'name' from the symbol table, creating and 2299 # registering it if it does not exist. If '_parsing_kconfigs' is False, 2300 # it means we're in eval_string(), and new symbols won't be registered. 2301 2302 if name in self.syms: 2303 return self.syms[name] 2304 2305 sym = Symbol() 2306 sym.kconfig = self 2307 sym.name = name 2308 sym.is_constant = False 2309 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n 2310 2311 if self._parsing_kconfigs: 2312 self.syms[name] = sym 2313 else: 2314 self._warn("no symbol {} in configuration".format(name)) 2315 2316 return sym 2317 2318 def _lookup_const_sym(self, name): 2319 # Like _lookup_sym(), for constant (quoted) symbols 2320 2321 if name in self.const_syms: 2322 return self.const_syms[name] 2323 2324 sym = Symbol() 2325 sym.kconfig = self 2326 sym.name = name 2327 sym.is_constant = True 2328 sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n 2329 2330 if self._parsing_kconfigs: 2331 self.const_syms[name] = sym 2332 2333 return sym 2334 2335 def _tokenize(self, s): 2336 # Parses 's', returning a None-terminated list of tokens. Registers any 2337 # new symbols encountered with _lookup(_const)_sym(). 2338 # 2339 # Tries to be reasonably speedy by processing chunks of text via 2340 # regexes and string operations where possible. This is the biggest 2341 # hotspot during parsing. 2342 # 2343 # It might be possible to rewrite this to 'yield' tokens instead, 2344 # working across multiple lines. Lookback and compatibility with old 2345 # janky versions of the C tools complicate things though. 2346 2347 self._line = s # Used for error reporting 2348 2349 # Initial token on the line 2350 match = _command_match(s) 2351 if not match: 2352 if s.isspace() or s.lstrip().startswith("#"): 2353 return (None,) 2354 self._parse_error("unknown token at start of line") 2355 2356 # Tricky implementation detail: While parsing a token, 'token' refers 2357 # to the previous token. See _STRING_LEX for why this is needed. 2358 token = _get_keyword(match.group(1)) 2359 if not token: 2360 # Backwards compatibility with old versions of the C tools, which 2361 # (accidentally) accepted stuff like "--help--" and "-help---". 2362 # This was fixed in the C tools by commit c2264564 ("kconfig: warn 2363 # of unhandled characters in Kconfig commands"), committed in July 2364 # 2015, but it seems people still run Kconfiglib on older kernels. 2365 if s.strip(" \t\n-") == "help": 2366 return (_T_HELP, None) 2367 2368 # If the first token is not a keyword (and not a weird help token), 2369 # we have a preprocessor variable assignment (or a bare macro on a 2370 # line) 2371 self._parse_assignment(s) 2372 return (None,) 2373 2374 tokens = [token] 2375 # The current index in the string being tokenized 2376 i = match.end() 2377 2378 # Main tokenization loop (for tokens past the first one) 2379 while i < len(s): 2380 # Test for an identifier/keyword first. This is the most common 2381 # case. 2382 match = _id_keyword_match(s, i) 2383 if match: 2384 # We have an identifier or keyword 2385 2386 # Check what it is. lookup_sym() will take care of allocating 2387 # new symbols for us the first time we see them. Note that 2388 # 'token' still refers to the previous token. 2389 2390 name = match.group(1) 2391 keyword = _get_keyword(name) 2392 if keyword: 2393 # It's a keyword 2394 token = keyword 2395 # Jump past it 2396 i = match.end() 2397 2398 elif token not in _STRING_LEX: 2399 # It's a non-const symbol, except we translate n, m, and y 2400 # into the corresponding constant symbols, like the C 2401 # implementation 2402 2403 if "$" in name: 2404 # Macro expansion within symbol name 2405 name, s, i = self._expand_name(s, i) 2406 else: 2407 i = match.end() 2408 2409 token = self.const_syms[name] if name in STR_TO_TRI else \ 2410 self._lookup_sym(name) 2411 2412 else: 2413 # It's a case of missing quotes. For example, the 2414 # following is accepted: 2415 # 2416 # menu unquoted_title 2417 # 2418 # config A 2419 # tristate unquoted_prompt 2420 # 2421 # endmenu 2422 # 2423 # Named choices ('choice FOO') also end up here. 2424 2425 if token is not _T_CHOICE: 2426 self._warn("style: quotes recommended around '{}' in '{}'" 2427 .format(name, self._line.strip()), 2428 self.filename, self.linenr) 2429 2430 token = name 2431 i = match.end() 2432 2433 else: 2434 # Neither a keyword nor a non-const symbol 2435 2436 # We always strip whitespace after tokens, so it is safe to 2437 # assume that s[i] is the start of a token here. 2438 c = s[i] 2439 2440 if c in "\"'": 2441 if "$" not in s and "\\" not in s: 2442 # Fast path for lines without $ and \. Find the 2443 # matching quote. 2444 end_i = s.find(c, i + 1) + 1 2445 if not end_i: 2446 self._parse_error("unterminated string") 2447 val = s[i + 1:end_i - 1] 2448 i = end_i 2449 else: 2450 # Slow path 2451 s, end_i = self._expand_str(s, i) 2452 2453 # os.path.expandvars() and the $UNAME_RELEASE replace() 2454 # is a backwards compatibility hack, which should be 2455 # reasonably safe as expandvars() leaves references to 2456 # undefined env. vars. as is. 2457 # 2458 # The preprocessor functionality changed how 2459 # environment variables are referenced, to $(FOO). 2460 val = expandvars(s[i + 1:end_i - 1] 2461 .replace("$UNAME_RELEASE", 2462 _UNAME_RELEASE)) 2463 2464 i = end_i 2465 2466 # This is the only place where we don't survive with a 2467 # single token of lookback: 'option env="FOO"' does not 2468 # refer to a constant symbol named "FOO". 2469 token = \ 2470 val if token in _STRING_LEX or tokens[0] is _T_OPTION \ 2471 else self._lookup_const_sym(val) 2472 2473 elif s.startswith("&&", i): 2474 token = _T_AND 2475 i += 2 2476 2477 elif s.startswith("||", i): 2478 token = _T_OR 2479 i += 2 2480 2481 elif c == "=": 2482 token = _T_EQUAL 2483 i += 1 2484 2485 elif s.startswith("!=", i): 2486 token = _T_UNEQUAL 2487 i += 2 2488 2489 elif c == "!": 2490 token = _T_NOT 2491 i += 1 2492 2493 elif c == "(": 2494 token = _T_OPEN_PAREN 2495 i += 1 2496 2497 elif c == ")": 2498 token = _T_CLOSE_PAREN 2499 i += 1 2500 2501 elif c == "#": 2502 break 2503 2504 2505 # Very rare 2506 2507 elif s.startswith("<=", i): 2508 token = _T_LESS_EQUAL 2509 i += 2 2510 2511 elif c == "<": 2512 token = _T_LESS 2513 i += 1 2514 2515 elif s.startswith(">=", i): 2516 token = _T_GREATER_EQUAL 2517 i += 2 2518 2519 elif c == ">": 2520 token = _T_GREATER 2521 i += 1 2522 2523 2524 else: 2525 self._parse_error("unknown tokens in line") 2526 2527 2528 # Skip trailing whitespace 2529 while i < len(s) and s[i].isspace(): 2530 i += 1 2531 2532 2533 # Add the token 2534 tokens.append(token) 2535 2536 # None-terminating the token list makes token fetching simpler/faster 2537 tokens.append(None) 2538 2539 return tokens 2540 2541 # Helpers for syntax checking and token fetching. See the 2542 # 'Intro to expressions' section for what a constant symbol is. 2543 # 2544 # More of these could be added, but the single-use cases are inlined as an 2545 # optimization. 2546 2547 def _expect_sym(self): 2548 token = self._tokens[self._tokens_i] 2549 self._tokens_i += 1 2550 2551 if token.__class__ is not Symbol: 2552 self._parse_error("expected symbol") 2553 2554 return token 2555 2556 def _expect_nonconst_sym(self): 2557 # Used for 'select' and 'imply' only. We know the token indices. 2558 2559 token = self._tokens[1] 2560 self._tokens_i = 2 2561 2562 if token.__class__ is not Symbol or token.is_constant: 2563 self._parse_error("expected nonconstant symbol") 2564 2565 return token 2566 2567 def _expect_str_and_eol(self): 2568 token = self._tokens[self._tokens_i] 2569 self._tokens_i += 1 2570 2571 if token.__class__ is not str: 2572 self._parse_error("expected string") 2573 2574 if self._tokens[self._tokens_i] is not None: 2575 self._trailing_tokens_error() 2576 2577 return token 2578 2579 def _expect_expr_and_eol(self): 2580 expr = self._parse_expr(True) 2581 2582 if self._tokens[self._tokens_i] is not None: 2583 self._trailing_tokens_error() 2584 2585 return expr 2586 2587 def _check_token(self, token): 2588 # If the next token is 'token', removes it and returns True 2589 2590 if self._tokens[self._tokens_i] is token: 2591 self._tokens_i += 1 2592 return True 2593 return False 2594 2595 # 2596 # Preprocessor logic 2597 # 2598 2599 def _parse_assignment(self, s): 2600 # Parses a preprocessor variable assignment, registering the variable 2601 # if it doesn't already exist. Also takes care of bare macros on lines 2602 # (which are allowed, and can be useful for their side effects). 2603 2604 # Expand any macros in the left-hand side of the assignment (the 2605 # variable name) 2606 s = s.lstrip() 2607 i = 0 2608 while 1: 2609 i = _assignment_lhs_fragment_match(s, i).end() 2610 if s.startswith("$(", i): 2611 s, i = self._expand_macro(s, i, ()) 2612 else: 2613 break 2614 2615 if s.isspace(): 2616 # We also accept a bare macro on a line (e.g. 2617 # $(warning-if,$(foo),ops)), provided it expands to a blank string 2618 return 2619 2620 # Assigned variable 2621 name = s[:i] 2622 2623 2624 # Extract assignment operator (=, :=, or +=) and value 2625 rhs_match = _assignment_rhs_match(s, i) 2626 if not rhs_match: 2627 self._parse_error("syntax error") 2628 2629 op, val = rhs_match.groups() 2630 2631 2632 if name in self.variables: 2633 # Already seen variable 2634 var = self.variables[name] 2635 else: 2636 # New variable 2637 var = Variable() 2638 var.kconfig = self 2639 var.name = name 2640 var._n_expansions = 0 2641 self.variables[name] = var 2642 2643 # += acts like = on undefined variables (defines a recursive 2644 # variable) 2645 if op == "+=": 2646 op = "=" 2647 2648 if op == "=": 2649 var.is_recursive = True 2650 var.value = val 2651 elif op == ":=": 2652 var.is_recursive = False 2653 var.value = self._expand_whole(val, ()) 2654 else: # op == "+=" 2655 # += does immediate expansion if the variable was last set 2656 # with := 2657 var.value += " " + (val if var.is_recursive else 2658 self._expand_whole(val, ())) 2659 2660 def _expand_whole(self, s, args): 2661 # Expands preprocessor macros in all of 's'. Used whenever we don't 2662 # have to worry about delimiters. See _expand_macro() re. the 'args' 2663 # parameter. 2664 # 2665 # Returns the expanded string. 2666 2667 i = 0 2668 while 1: 2669 i = s.find("$(", i) 2670 if i == -1: 2671 break 2672 s, i = self._expand_macro(s, i, args) 2673 return s 2674 2675 def _expand_name(self, s, i): 2676 # Expands a symbol name starting at index 'i' in 's'. 2677 # 2678 # Returns the expanded name, the expanded 's' (including the part 2679 # before the name), and the index of the first character in the next 2680 # token after the name. 2681 2682 s, end_i = self._expand_name_iter(s, i) 2683 name = s[i:end_i] 2684 # isspace() is False for empty strings 2685 if not name.strip(): 2686 # Avoid creating a Kconfig symbol with a blank name. It's almost 2687 # guaranteed to be an error. 2688 self._parse_error("macro expanded to blank string") 2689 2690 # Skip trailing whitespace 2691 while end_i < len(s) and s[end_i].isspace(): 2692 end_i += 1 2693 2694 return name, s, end_i 2695 2696 def _expand_name_iter(self, s, i): 2697 # Expands a symbol name starting at index 'i' in 's'. 2698 # 2699 # Returns the expanded 's' (including the part before the name) and the 2700 # index of the first character after the expanded name in 's'. 2701 2702 while 1: 2703 match = _name_special_search(s, i) 2704 2705 if match.group() != "$(": 2706 return (s, match.start()) 2707 s, i = self._expand_macro(s, match.start(), ()) 2708 2709 def _expand_str(self, s, i): 2710 # Expands a quoted string starting at index 'i' in 's'. Handles both 2711 # backslash escapes and macro expansion. 2712 # 2713 # Returns the expanded 's' (including the part before the string) and 2714 # the index of the first character after the expanded string in 's'. 2715 2716 quote = s[i] 2717 i += 1 # Skip over initial "/' 2718 while 1: 2719 match = _string_special_search(s, i) 2720 if not match: 2721 self._parse_error("unterminated string") 2722 2723 2724 if match.group() == quote: 2725 # Found the end of the string 2726 return (s, match.end()) 2727 2728 elif match.group() == "\\": 2729 # Replace '\x' with 'x'. 'i' ends up pointing to the character 2730 # after 'x', which allows macros to be canceled with '\$(foo)'. 2731 i = match.end() 2732 s = s[:match.start()] + s[i:] 2733 2734 elif match.group() == "$(": 2735 # A macro call within the string 2736 s, i = self._expand_macro(s, match.start(), ()) 2737 2738 else: 2739 # A ' quote within " quotes or vice versa 2740 i += 1 2741 2742 def _expand_macro(self, s, i, args): 2743 # Expands a macro starting at index 'i' in 's'. If this macro resulted 2744 # from the expansion of another macro, 'args' holds the arguments 2745 # passed to that macro. 2746 # 2747 # Returns the expanded 's' (including the part before the macro) and 2748 # the index of the first character after the expanded macro in 's'. 2749 2750 res = s[:i] 2751 i += 2 # Skip over "$(" 2752 2753 arg_start = i # Start of current macro argument 2754 new_args = [] # Arguments of this macro call 2755 nesting = 0 # Current parentheses nesting level 2756 2757 while 1: 2758 match = _macro_special_search(s, i) 2759 if not match: 2760 self._parse_error("missing end parenthesis in macro expansion") 2761 2762 2763 if match.group() == "(": 2764 nesting += 1 2765 i = match.end() 2766 2767 elif match.group() == ")": 2768 if nesting: 2769 nesting -= 1 2770 i = match.end() 2771 continue 2772 2773 # Found the end of the macro 2774 2775 new_args.append(s[arg_start:match.start()]) 2776 2777 # $(1) is replaced by the first argument to the function, etc., 2778 # provided at least that many arguments were passed 2779 2780 try: 2781 # Does the macro look like an integer, with a corresponding 2782 # argument? If so, expand it to the value of the argument. 2783 res += args[int(new_args[0])] 2784 except (ValueError, IndexError): 2785 # Regular variables are just functions without arguments, 2786 # and also go through the function value path 2787 res += self._fn_val(new_args) 2788 2789 return (res + s[match.end():], len(res)) 2790 2791 elif match.group() == ",": 2792 i = match.end() 2793 if nesting: 2794 continue 2795 2796 # Found the end of a macro argument 2797 new_args.append(s[arg_start:match.start()]) 2798 arg_start = i 2799 2800 else: # match.group() == "$(" 2801 # A nested macro call within the macro 2802 s, i = self._expand_macro(s, match.start(), args) 2803 2804 def _fn_val(self, args): 2805 # Returns the result of calling the function args[0] with the arguments 2806 # args[1..len(args)-1]. Plain variables are treated as functions 2807 # without arguments. 2808 2809 fn = args[0] 2810 2811 if fn in self.variables: 2812 var = self.variables[fn] 2813 2814 if len(args) == 1: 2815 # Plain variable 2816 if var._n_expansions: 2817 self._parse_error("Preprocessor variable {} recursively " 2818 "references itself".format(var.name)) 2819 elif var._n_expansions > 100: 2820 # Allow functions to call themselves, but guess that functions 2821 # that are overly recursive are stuck 2822 self._parse_error("Preprocessor function {} seems stuck " 2823 "in infinite recursion".format(var.name)) 2824 2825 var._n_expansions += 1 2826 res = self._expand_whole(self.variables[fn].value, args) 2827 var._n_expansions -= 1 2828 return res 2829 2830 if fn in self._functions: 2831 # Built-in or user-defined function 2832 2833 py_fn, min_arg, max_arg = self._functions[fn] 2834 2835 if len(args) - 1 < min_arg or \ 2836 (max_arg is not None and len(args) - 1 > max_arg): 2837 2838 if min_arg == max_arg: 2839 expected_args = min_arg 2840 elif max_arg is None: 2841 expected_args = "{} or more".format(min_arg) 2842 else: 2843 expected_args = "{}-{}".format(min_arg, max_arg) 2844 2845 raise KconfigError("{}:{}: bad number of arguments in call " 2846 "to {}, expected {}, got {}" 2847 .format(self.filename, self.linenr, fn, 2848 expected_args, len(args) - 1)) 2849 2850 return py_fn(self, *args) 2851 2852 # Environment variables are tried last 2853 if fn in os.environ: 2854 self.env_vars.add(fn) 2855 return os.environ[fn] 2856 2857 return "" 2858 2859 # 2860 # Parsing 2861 # 2862 2863 def _make_and(self, e1, e2): 2864 # Constructs an AND (&&) expression. Performs trivial simplification. 2865 2866 if e1 is self.y: 2867 return e2 2868 2869 if e2 is self.y: 2870 return e1 2871 2872 if e1 is self.n or e2 is self.n: 2873 return self.n 2874 2875 return (AND, e1, e2) 2876 2877 def _make_or(self, e1, e2): 2878 # Constructs an OR (||) expression. Performs trivial simplification. 2879 2880 if e1 is self.n: 2881 return e2 2882 2883 if e2 is self.n: 2884 return e1 2885 2886 if e1 is self.y or e2 is self.y: 2887 return self.y 2888 2889 return (OR, e1, e2) 2890 2891 def _parse_block(self, end_token, parent, prev): 2892 # Parses a block, which is the contents of either a file or an if, 2893 # menu, or choice statement. 2894 # 2895 # end_token: 2896 # The token that ends the block, e.g. _T_ENDIF ("endif") for ifs. 2897 # None for files. 2898 # 2899 # parent: 2900 # The parent menu node, corresponding to a menu, Choice, or 'if'. 2901 # 'if's are flattened after parsing. 2902 # 2903 # prev: 2904 # The previous menu node. New nodes will be added after this one (by 2905 # modifying 'next' pointers). 2906 # 2907 # 'prev' is reused to parse a list of child menu nodes (for a menu or 2908 # Choice): After parsing the children, the 'next' pointer is assigned 2909 # to the 'list' pointer to "tilt up" the children above the node. 2910 # 2911 # Returns the final menu node in the block (or 'prev' if the block is 2912 # empty). This allows chaining. 2913 2914 while self._next_line(): 2915 t0 = self._tokens[0] 2916 2917 if t0 is _T_CONFIG or t0 is _T_MENUCONFIG: 2918 # The tokenizer allocates Symbol objects for us 2919 sym = self._tokens[1] 2920 2921 if sym.__class__ is not Symbol or sym.is_constant: 2922 self._parse_error("missing or bad symbol name") 2923 2924 if self._tokens[2] is not None: 2925 self._trailing_tokens_error() 2926 2927 self.defined_syms.append(sym) 2928 2929 node = MenuNode() 2930 node.kconfig = self 2931 node.item = sym 2932 node.is_menuconfig = (t0 is _T_MENUCONFIG) 2933 node.prompt = node.help = node.list = None 2934 node.parent = parent 2935 node.filename = self.filename 2936 node.linenr = self.linenr 2937 node.include_path = self._include_path 2938 2939 sym.nodes.append(node) 2940 2941 self._parse_props(node) 2942 2943 if node.is_menuconfig and not node.prompt: 2944 self._warn("the menuconfig symbol {} has no prompt" 2945 .format(sym.name_and_loc)) 2946 2947 # Equivalent to 2948 # 2949 # prev.next = node 2950 # prev = node 2951 # 2952 # due to tricky Python semantics. The order matters. 2953 prev.next = prev = node 2954 2955 elif t0 is None: 2956 # Blank line 2957 continue 2958 2959 elif t0 in _SOURCE_TOKENS: 2960 pattern = self._expect_str_and_eol() 2961 2962 if t0 in _REL_SOURCE_TOKENS: 2963 # Relative source 2964 pattern = join(dirname(self.filename), pattern) 2965 2966 # - glob() doesn't support globbing relative to a directory, so 2967 # we need to prepend $srctree to 'pattern'. Use join() 2968 # instead of '+' so that an absolute path in 'pattern' is 2969 # preserved. 2970 # 2971 # - Sort the glob results to ensure a consistent ordering of 2972 # Kconfig symbols, which indirectly ensures a consistent 2973 # ordering in e.g. .config files 2974 filenames = sorted(iglob(join(self._srctree_prefix, pattern))) 2975 2976 if not filenames and t0 in _OBL_SOURCE_TOKENS: 2977 raise KconfigError( 2978 "{}:{}: '{}' not found (in '{}'). Check that " 2979 "environment variables are set correctly (e.g. " 2980 "$srctree, which is {}). Also note that unset " 2981 "environment variables expand to the empty string." 2982 .format(self.filename, self.linenr, pattern, 2983 self._line.strip(), 2984 "set to '{}'".format(self.srctree) 2985 if self.srctree else "unset or blank")) 2986 2987 for filename in filenames: 2988 self._enter_file(filename) 2989 prev = self._parse_block(None, parent, prev) 2990 self._leave_file() 2991 2992 elif t0 is end_token: 2993 # Reached the end of the block. Terminate the final node and 2994 # return it. 2995 2996 if self._tokens[1] is not None: 2997 self._trailing_tokens_error() 2998 2999 prev.next = None 3000 return prev 3001 3002 elif t0 is _T_IF: 3003 node = MenuNode() 3004 node.item = node.prompt = None 3005 node.parent = parent 3006 node.dep = self._expect_expr_and_eol() 3007 3008 self._parse_block(_T_ENDIF, node, node) 3009 node.list = node.next 3010 3011 prev.next = prev = node 3012 3013 elif t0 is _T_MENU: 3014 node = MenuNode() 3015 node.kconfig = self 3016 node.item = t0 # _T_MENU == MENU 3017 node.is_menuconfig = True 3018 node.prompt = (self._expect_str_and_eol(), self.y) 3019 node.visibility = self.y 3020 node.parent = parent 3021 node.filename = self.filename 3022 node.linenr = self.linenr 3023 node.include_path = self._include_path 3024 3025 self.menus.append(node) 3026 3027 self._parse_props(node) 3028 self._parse_block(_T_ENDMENU, node, node) 3029 node.list = node.next 3030 3031 prev.next = prev = node 3032 3033 elif t0 is _T_COMMENT: 3034 node = MenuNode() 3035 node.kconfig = self 3036 node.item = t0 # _T_COMMENT == COMMENT 3037 node.is_menuconfig = False 3038 node.prompt = (self._expect_str_and_eol(), self.y) 3039 node.list = None 3040 node.parent = parent 3041 node.filename = self.filename 3042 node.linenr = self.linenr 3043 node.include_path = self._include_path 3044 3045 self.comments.append(node) 3046 3047 self._parse_props(node) 3048 3049 prev.next = prev = node 3050 3051 elif t0 is _T_CHOICE: 3052 if self._tokens[1] is None: 3053 choice = Choice() 3054 choice.direct_dep = self.n 3055 else: 3056 # Named choice 3057 name = self._expect_str_and_eol() 3058 choice = self.named_choices.get(name) 3059 if not choice: 3060 choice = Choice() 3061 choice.name = name 3062 choice.direct_dep = self.n 3063 self.named_choices[name] = choice 3064 3065 self.choices.append(choice) 3066 3067 node = MenuNode() 3068 node.kconfig = choice.kconfig = self 3069 node.item = choice 3070 node.is_menuconfig = True 3071 node.prompt = node.help = None 3072 node.parent = parent 3073 node.filename = self.filename 3074 node.linenr = self.linenr 3075 node.include_path = self._include_path 3076 3077 choice.nodes.append(node) 3078 3079 self._parse_props(node) 3080 self._parse_block(_T_ENDCHOICE, node, node) 3081 node.list = node.next 3082 3083 prev.next = prev = node 3084 3085 elif t0 is _T_MAINMENU: 3086 self.top_node.prompt = (self._expect_str_and_eol(), self.y) 3087 3088 else: 3089 # A valid endchoice/endif/endmenu is caught by the 'end_token' 3090 # check above 3091 self._parse_error( 3092 "no corresponding 'choice'" if t0 is _T_ENDCHOICE else 3093 "no corresponding 'if'" if t0 is _T_ENDIF else 3094 "no corresponding 'menu'" if t0 is _T_ENDMENU else 3095 "unrecognized construct") 3096 3097 # End of file reached. Return the last node. 3098 3099 if end_token: 3100 raise KconfigError( 3101 "error: expected '{}' at end of '{}'" 3102 .format("endchoice" if end_token is _T_ENDCHOICE else 3103 "endif" if end_token is _T_ENDIF else 3104 "endmenu", 3105 self.filename)) 3106 3107 return prev 3108 3109 def _parse_cond(self): 3110 # Parses an optional 'if <expr>' construct and returns the parsed 3111 # <expr>, or self.y if the next token is not _T_IF 3112 3113 expr = self._parse_expr(True) if self._check_token(_T_IF) else self.y 3114 3115 if self._tokens[self._tokens_i] is not None: 3116 self._trailing_tokens_error() 3117 3118 return expr 3119 3120 def _parse_props(self, node): 3121 # Parses and adds properties to the MenuNode 'node' (type, 'prompt', 3122 # 'default's, etc.) Properties are later copied up to symbols and 3123 # choices in a separate pass after parsing, in e.g. 3124 # _add_props_to_sym(). 3125 # 3126 # An older version of this code added properties directly to symbols 3127 # and choices instead of to their menu nodes (and handled dependency 3128 # propagation simultaneously), but that loses information on where a 3129 # property is added when a symbol or choice is defined in multiple 3130 # locations. Some Kconfig configuration systems rely heavily on such 3131 # symbols, and better docs can be generated by keeping track of where 3132 # properties are added. 3133 # 3134 # node: 3135 # The menu node we're parsing properties on 3136 3137 # Dependencies from 'depends on'. Will get propagated to the properties 3138 # below. 3139 node.dep = self.y 3140 3141 while self._next_line(): 3142 t0 = self._tokens[0] 3143 3144 if t0 in _TYPE_TOKENS: 3145 # Relies on '_T_BOOL is BOOL', etc., to save a conversion 3146 self._set_type(node.item, t0) 3147 if self._tokens[1] is not None: 3148 self._parse_prompt(node) 3149 3150 elif t0 is _T_DEPENDS: 3151 if not self._check_token(_T_ON): 3152 self._parse_error("expected 'on' after 'depends'") 3153 3154 node.dep = self._make_and(node.dep, 3155 self._expect_expr_and_eol()) 3156 3157 elif t0 is _T_HELP: 3158 self._parse_help(node) 3159 3160 elif t0 is _T_SELECT: 3161 if node.item.__class__ is not Symbol: 3162 self._parse_error("only symbols can select") 3163 3164 node.selects.append((self._expect_nonconst_sym(), 3165 self._parse_cond())) 3166 3167 elif t0 is None: 3168 # Blank line 3169 continue 3170 3171 elif t0 is _T_DEFAULT: 3172 node.defaults.append((self._parse_expr(False), 3173 self._parse_cond())) 3174 3175 elif t0 in _DEF_TOKEN_TO_TYPE: 3176 self._set_type(node.item, _DEF_TOKEN_TO_TYPE[t0]) 3177 node.defaults.append((self._parse_expr(False), 3178 self._parse_cond())) 3179 3180 elif t0 is _T_PROMPT: 3181 self._parse_prompt(node) 3182 3183 elif t0 is _T_RANGE: 3184 node.ranges.append((self._expect_sym(), self._expect_sym(), 3185 self._parse_cond())) 3186 3187 elif t0 is _T_IMPLY: 3188 if node.item.__class__ is not Symbol: 3189 self._parse_error("only symbols can imply") 3190 3191 node.implies.append((self._expect_nonconst_sym(), 3192 self._parse_cond())) 3193 3194 elif t0 is _T_VISIBLE: 3195 if not self._check_token(_T_IF): 3196 self._parse_error("expected 'if' after 'visible'") 3197 3198 node.visibility = self._make_and(node.visibility, 3199 self._expect_expr_and_eol()) 3200 3201 elif t0 is _T_OPTION: 3202 if self._check_token(_T_ENV): 3203 if not self._check_token(_T_EQUAL): 3204 self._parse_error("expected '=' after 'env'") 3205 3206 env_var = self._expect_str_and_eol() 3207 node.item.env_var = env_var 3208 3209 if env_var in os.environ: 3210 node.defaults.append( 3211 (self._lookup_const_sym(os.environ[env_var]), 3212 self.y)) 3213 else: 3214 self._warn("{1} has 'option env=\"{0}\"', " 3215 "but the environment variable {0} is not " 3216 "set".format(node.item.name, env_var), 3217 self.filename, self.linenr) 3218 3219 if env_var != node.item.name: 3220 self._warn("Kconfiglib expands environment variables " 3221 "in strings directly, meaning you do not " 3222 "need 'option env=...' \"bounce\" symbols. " 3223 "For compatibility with the C tools, " 3224 "rename {} to {} (so that the symbol name " 3225 "matches the environment variable name)." 3226 .format(node.item.name, env_var), 3227 self.filename, self.linenr) 3228 3229 elif self._check_token(_T_DEFCONFIG_LIST): 3230 if not self.defconfig_list: 3231 self.defconfig_list = node.item 3232 else: 3233 self._warn("'option defconfig_list' set on multiple " 3234 "symbols ({0} and {1}). Only {0} will be " 3235 "used.".format(self.defconfig_list.name, 3236 node.item.name), 3237 self.filename, self.linenr) 3238 3239 elif self._check_token(_T_MODULES): 3240 # To reduce warning spam, only warn if 'option modules' is 3241 # set on some symbol that isn't MODULES, which should be 3242 # safe. I haven't run into any projects that make use 3243 # modules besides the kernel yet, and there it's likely to 3244 # keep being called "MODULES". 3245 if node.item is not self.modules: 3246 self._warn("the 'modules' option is not supported. " 3247 "Let me know if this is a problem for you, " 3248 "as it wouldn't be that hard to implement. " 3249 "Note that modules are supported -- " 3250 "Kconfiglib just assumes the symbol name " 3251 "MODULES, like older versions of the C " 3252 "implementation did when 'option modules' " 3253 "wasn't used.", 3254 self.filename, self.linenr) 3255 3256 elif self._check_token(_T_ALLNOCONFIG_Y): 3257 if node.item.__class__ is not Symbol: 3258 self._parse_error("the 'allnoconfig_y' option is only " 3259 "valid for symbols") 3260 3261 node.item.is_allnoconfig_y = True 3262 3263 else: 3264 self._parse_error("unrecognized option") 3265 3266 elif t0 is _T_OPTIONAL: 3267 if node.item.__class__ is not Choice: 3268 self._parse_error('"optional" is only valid for choices') 3269 3270 node.item.is_optional = True 3271 3272 else: 3273 # Reuse the tokens for the non-property line later 3274 self._reuse_tokens = True 3275 return 3276 3277 def _set_type(self, sc, new_type): 3278 # Sets the type of 'sc' (symbol or choice) to 'new_type' 3279 3280 # UNKNOWN is falsy 3281 if sc.orig_type and sc.orig_type is not new_type: 3282 self._warn("{} defined with multiple types, {} will be used" 3283 .format(sc.name_and_loc, TYPE_TO_STR[new_type])) 3284 3285 sc.orig_type = new_type 3286 3287 def _parse_prompt(self, node): 3288 # 'prompt' properties override each other within a single definition of 3289 # a symbol, but additional prompts can be added by defining the symbol 3290 # multiple times 3291 3292 if node.prompt: 3293 self._warn(node.item.name_and_loc + 3294 " defined with multiple prompts in single location") 3295 3296 prompt = self._tokens[1] 3297 self._tokens_i = 2 3298 3299 if prompt.__class__ is not str: 3300 self._parse_error("expected prompt string") 3301 3302 if prompt != prompt.strip(): 3303 self._warn(node.item.name_and_loc + 3304 " has leading or trailing whitespace in its prompt") 3305 3306 # This avoid issues for e.g. reStructuredText documentation, where 3307 # '*prompt *' is invalid 3308 prompt = prompt.strip() 3309 3310 node.prompt = (prompt, self._parse_cond()) 3311 3312 def _parse_help(self, node): 3313 if node.help is not None: 3314 self._warn(node.item.name_and_loc + " defined with more than " 3315 "one help text -- only the last one will be used") 3316 3317 # Micro-optimization. This code is pretty hot. 3318 readline = self._readline 3319 3320 # Find first non-blank (not all-space) line and get its 3321 # indentation 3322 3323 while 1: 3324 line = readline() 3325 self.linenr += 1 3326 if not line: 3327 self._empty_help(node, line) 3328 return 3329 if not line.isspace(): 3330 break 3331 3332 len_ = len # Micro-optimization 3333 3334 # Use a separate 'expline' variable here and below to avoid stomping on 3335 # any tabs people might've put deliberately into the first line after 3336 # the help text 3337 expline = line.expandtabs() 3338 indent = len_(expline) - len_(expline.lstrip()) 3339 if not indent: 3340 self._empty_help(node, line) 3341 return 3342 3343 # The help text goes on till the first non-blank line with less indent 3344 # than the first line 3345 3346 # Add the first line 3347 lines = [expline[indent:]] 3348 add_line = lines.append # Micro-optimization 3349 3350 while 1: 3351 line = readline() 3352 if line.isspace(): 3353 # No need to preserve the exact whitespace in these 3354 add_line("\n") 3355 elif not line: 3356 # End of file 3357 break 3358 else: 3359 expline = line.expandtabs() 3360 if len_(expline) - len_(expline.lstrip()) < indent: 3361 break 3362 add_line(expline[indent:]) 3363 3364 self.linenr += len_(lines) 3365 node.help = "".join(lines).rstrip() 3366 if line: 3367 self._line_after_help(line) 3368 3369 def _empty_help(self, node, line): 3370 self._warn(node.item.name_and_loc + 3371 " has 'help' but empty help text") 3372 node.help = "" 3373 if line: 3374 self._line_after_help(line) 3375 3376 def _parse_expr(self, transform_m): 3377 # Parses an expression from the tokens in Kconfig._tokens using a 3378 # simple top-down approach. See the module docstring for the expression 3379 # format. 3380 # 3381 # transform_m: 3382 # True if m should be rewritten to m && MODULES. See the 3383 # Kconfig.eval_string() documentation. 3384 3385 # Grammar: 3386 # 3387 # expr: and_expr ['||' expr] 3388 # and_expr: factor ['&&' and_expr] 3389 # factor: <symbol> ['='/'!='/'<'/... <symbol>] 3390 # '!' factor 3391 # '(' expr ')' 3392 # 3393 # It helps to think of the 'expr: and_expr' case as a single-operand OR 3394 # (no ||), and of the 'and_expr: factor' case as a single-operand AND 3395 # (no &&). Parsing code is always a bit tricky. 3396 3397 # Mind dump: parse_factor() and two nested loops for OR and AND would 3398 # work as well. The straightforward implementation there gives a 3399 # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing 3400 # expressions as (op, [list of operands]) instead goes nicely with that 3401 # version, but is wasteful for short expressions and complicates 3402 # expression evaluation and other code that works on expressions (more 3403 # complicated code likely offsets any performance gain from less 3404 # recursion too). If we also try to optimize the list representation by 3405 # merging lists when possible (e.g. when ANDing two AND expressions), 3406 # we end up allocating a ton of lists instead of reusing expressions, 3407 # which is bad. 3408 3409 and_expr = self._parse_and_expr(transform_m) 3410 3411 # Return 'and_expr' directly if we have a "single-operand" OR. 3412 # Otherwise, parse the expression on the right and make an OR node. 3413 # This turns A || B || C || D into (OR, A, (OR, B, (OR, C, D))). 3414 return and_expr if not self._check_token(_T_OR) else \ 3415 (OR, and_expr, self._parse_expr(transform_m)) 3416 3417 def _parse_and_expr(self, transform_m): 3418 factor = self._parse_factor(transform_m) 3419 3420 # Return 'factor' directly if we have a "single-operand" AND. 3421 # Otherwise, parse the right operand and make an AND node. This turns 3422 # A && B && C && D into (AND, A, (AND, B, (AND, C, D))). 3423 return factor if not self._check_token(_T_AND) else \ 3424 (AND, factor, self._parse_and_expr(transform_m)) 3425 3426 def _parse_factor(self, transform_m): 3427 token = self._tokens[self._tokens_i] 3428 self._tokens_i += 1 3429 3430 if token.__class__ is Symbol: 3431 # Plain symbol or relation 3432 3433 if self._tokens[self._tokens_i] not in _RELATIONS: 3434 # Plain symbol 3435 3436 # For conditional expressions ('depends on <expr>', 3437 # '... if <expr>', etc.), m is rewritten to m && MODULES. 3438 if transform_m and token is self.m: 3439 return (AND, self.m, self.modules) 3440 3441 return token 3442 3443 # Relation 3444 # 3445 # _T_EQUAL, _T_UNEQUAL, etc., deliberately have the same values as 3446 # EQUAL, UNEQUAL, etc., so we can just use the token directly 3447 self._tokens_i += 1 3448 return (self._tokens[self._tokens_i - 1], token, 3449 self._expect_sym()) 3450 3451 if token is _T_NOT: 3452 # token == _T_NOT == NOT 3453 return (token, self._parse_factor(transform_m)) 3454 3455 if token is _T_OPEN_PAREN: 3456 expr_parse = self._parse_expr(transform_m) 3457 if self._check_token(_T_CLOSE_PAREN): 3458 return expr_parse 3459 3460 self._parse_error("malformed expression") 3461 3462 # 3463 # Caching and invalidation 3464 # 3465 3466 def _build_dep(self): 3467 # Populates the Symbol/Choice._dependents sets, which contain all other 3468 # items (symbols and choices) that immediately depend on the item in 3469 # the sense that changing the value of the item might affect the value 3470 # of the dependent items. This is used for caching/invalidation. 3471 # 3472 # The calculated sets might be larger than necessary as we don't do any 3473 # complex analysis of the expressions. 3474 3475 depend_on = _depend_on # Micro-optimization 3476 3477 # Only calculate _dependents for defined symbols. Constant and 3478 # undefined symbols could theoretically be selected/implied, but it 3479 # wouldn't change their value, so it's not a true dependency. 3480 for sym in self.unique_defined_syms: 3481 # Symbols depend on the following: 3482 3483 # The prompt conditions 3484 for node in sym.nodes: 3485 if node.prompt: 3486 depend_on(sym, node.prompt[1]) 3487 3488 # The default values and their conditions 3489 for value, cond in sym.defaults: 3490 depend_on(sym, value) 3491 depend_on(sym, cond) 3492 3493 # The reverse and weak reverse dependencies 3494 depend_on(sym, sym.rev_dep) 3495 depend_on(sym, sym.weak_rev_dep) 3496 3497 # The ranges along with their conditions 3498 for low, high, cond in sym.ranges: 3499 depend_on(sym, low) 3500 depend_on(sym, high) 3501 depend_on(sym, cond) 3502 3503 # The direct dependencies. This is usually redundant, as the direct 3504 # dependencies get propagated to properties, but it's needed to get 3505 # invalidation solid for 'imply', which only checks the direct 3506 # dependencies (even if there are no properties to propagate it 3507 # to). 3508 depend_on(sym, sym.direct_dep) 3509 3510 # In addition to the above, choice symbols depend on the choice 3511 # they're in, but that's handled automatically since the Choice is 3512 # propagated to the conditions of the properties before 3513 # _build_dep() runs. 3514 3515 for choice in self.unique_choices: 3516 # Choices depend on the following: 3517 3518 # The prompt conditions 3519 for node in choice.nodes: 3520 if node.prompt: 3521 depend_on(choice, node.prompt[1]) 3522 3523 # The default symbol conditions 3524 for _, cond in choice.defaults: 3525 depend_on(choice, cond) 3526 3527 def _add_choice_deps(self): 3528 # Choices also depend on the choice symbols themselves, because the 3529 # y-mode selection of the choice might change if a choice symbol's 3530 # visibility changes. 3531 # 3532 # We add these dependencies separately after dependency loop detection. 3533 # The invalidation algorithm can handle the resulting 3534 # <choice symbol> <-> <choice> dependency loops, but they make loop 3535 # detection awkward. 3536 3537 for choice in self.unique_choices: 3538 for sym in choice.syms: 3539 sym._dependents.add(choice) 3540 3541 def _invalidate_all(self): 3542 # Undefined symbols never change value and don't need to be 3543 # invalidated, so we can just iterate over defined symbols. 3544 # Invalidating constant symbols would break things horribly. 3545 for sym in self.unique_defined_syms: 3546 sym._invalidate() 3547 3548 for choice in self.unique_choices: 3549 choice._invalidate() 3550 3551 # 3552 # Post-parsing menu tree processing, including dependency propagation and 3553 # implicit submenu creation 3554 # 3555 3556 def _finalize_node(self, node, visible_if): 3557 # Finalizes a menu node and its children: 3558 # 3559 # - Copies properties from menu nodes up to their contained 3560 # symbols/choices 3561 # 3562 # - Propagates dependencies from parent to child nodes 3563 # 3564 # - Creates implicit menus (see kconfig-language.txt) 3565 # 3566 # - Removes 'if' nodes 3567 # 3568 # - Sets 'choice' types and registers choice symbols 3569 # 3570 # menu_finalize() in the C implementation is similar. 3571 # 3572 # node: 3573 # The menu node to finalize. This node and its children will have 3574 # been finalized when the function returns, and any implicit menus 3575 # will have been created. 3576 # 3577 # visible_if: 3578 # Dependencies from 'visible if' on parent menus. These are added to 3579 # the prompts of symbols and choices. 3580 3581 if node.item.__class__ is Symbol: 3582 # Copy defaults, ranges, selects, and implies to the Symbol 3583 self._add_props_to_sym(node) 3584 3585 # Find any items that should go in an implicit menu rooted at the 3586 # symbol 3587 cur = node 3588 while cur.next and _auto_menu_dep(node, cur.next): 3589 # This makes implicit submenu creation work recursively, with 3590 # implicit menus inside implicit menus 3591 self._finalize_node(cur.next, visible_if) 3592 cur = cur.next 3593 cur.parent = node 3594 3595 if cur is not node: 3596 # Found symbols that should go in an implicit submenu. Tilt 3597 # them up above us. 3598 node.list = node.next 3599 node.next = cur.next 3600 cur.next = None 3601 3602 elif node.list: 3603 # The menu node is a choice, menu, or if. Finalize each child node. 3604 3605 if node.item is MENU: 3606 visible_if = self._make_and(visible_if, node.visibility) 3607 3608 # Propagate the menu node's dependencies to each child menu node. 3609 # 3610 # This needs to go before the recursive _finalize_node() call so 3611 # that implicit submenu creation can look ahead at dependencies. 3612 self._propagate_deps(node, visible_if) 3613 3614 # Finalize the children 3615 cur = node.list 3616 while cur: 3617 self._finalize_node(cur, visible_if) 3618 cur = cur.next 3619 3620 if node.list: 3621 # node's children have been individually finalized. Do final steps 3622 # to finalize this "level" in the menu tree. 3623 _flatten(node.list) 3624 _remove_ifs(node) 3625 3626 # Empty choices (node.list None) are possible, so this needs to go 3627 # outside 3628 if node.item.__class__ is Choice: 3629 # Add the node's non-node-specific properties to the choice, like 3630 # _add_props_to_sym() does 3631 choice = node.item 3632 choice.direct_dep = self._make_or(choice.direct_dep, node.dep) 3633 choice.defaults += node.defaults 3634 3635 _finalize_choice(node) 3636 3637 def _propagate_deps(self, node, visible_if): 3638 # Propagates 'node's dependencies to its child menu nodes 3639 3640 # If the parent node holds a Choice, we use the Choice itself as the 3641 # parent dependency. This makes sense as the value (mode) of the choice 3642 # limits the visibility of the contained choice symbols. The C 3643 # implementation works the same way. 3644 # 3645 # Due to the similar interface, Choice works as a drop-in replacement 3646 # for Symbol here. 3647 basedep = node.item if node.item.__class__ is Choice else node.dep 3648 3649 cur = node.list 3650 while cur: 3651 dep = cur.dep = self._make_and(cur.dep, basedep) 3652 3653 if cur.item.__class__ in _SYMBOL_CHOICE: 3654 # Propagate 'visible if' and dependencies to the prompt 3655 if cur.prompt: 3656 cur.prompt = (cur.prompt[0], 3657 self._make_and( 3658 cur.prompt[1], 3659 self._make_and(visible_if, dep))) 3660 3661 # Propagate dependencies to defaults 3662 if cur.defaults: 3663 cur.defaults = [(default, self._make_and(cond, dep)) 3664 for default, cond in cur.defaults] 3665 3666 # Propagate dependencies to ranges 3667 if cur.ranges: 3668 cur.ranges = [(low, high, self._make_and(cond, dep)) 3669 for low, high, cond in cur.ranges] 3670 3671 # Propagate dependencies to selects 3672 if cur.selects: 3673 cur.selects = [(target, self._make_and(cond, dep)) 3674 for target, cond in cur.selects] 3675 3676 # Propagate dependencies to implies 3677 if cur.implies: 3678 cur.implies = [(target, self._make_and(cond, dep)) 3679 for target, cond in cur.implies] 3680 3681 elif cur.prompt: # Not a symbol/choice 3682 # Propagate dependencies to the prompt. 'visible if' is only 3683 # propagated to symbols/choices. 3684 cur.prompt = (cur.prompt[0], 3685 self._make_and(cur.prompt[1], dep)) 3686 3687 cur = cur.next 3688 3689 def _add_props_to_sym(self, node): 3690 # Copies properties from the menu node 'node' up to its contained 3691 # symbol, and adds (weak) reverse dependencies to selected/implied 3692 # symbols. 3693 # 3694 # This can't be rolled into _propagate_deps(), because that function 3695 # traverses the menu tree roughly breadth-first, meaning properties on 3696 # symbols defined in multiple locations could end up in the wrong 3697 # order. 3698 3699 sym = node.item 3700 3701 # See the Symbol class docstring 3702 sym.direct_dep = self._make_or(sym.direct_dep, node.dep) 3703 3704 sym.defaults += node.defaults 3705 sym.ranges += node.ranges 3706 sym.selects += node.selects 3707 sym.implies += node.implies 3708 3709 # Modify the reverse dependencies of the selected symbol 3710 for target, cond in node.selects: 3711 target.rev_dep = self._make_or( 3712 target.rev_dep, 3713 self._make_and(sym, cond)) 3714 3715 # Modify the weak reverse dependencies of the implied 3716 # symbol 3717 for target, cond in node.implies: 3718 target.weak_rev_dep = self._make_or( 3719 target.weak_rev_dep, 3720 self._make_and(sym, cond)) 3721 3722 # 3723 # Misc. 3724 # 3725 3726 def _check_sym_sanity(self): 3727 # Checks various symbol properties that are handiest to check after 3728 # parsing. Only generates errors and warnings. 3729 3730 def num_ok(sym, type_): 3731 # Returns True if the (possibly constant) symbol 'sym' is valid as a value 3732 # for a symbol of type type_ (INT or HEX) 3733 3734 # 'not sym.nodes' implies a constant or undefined symbol, e.g. a plain 3735 # "123" 3736 if not sym.nodes: 3737 return _is_base_n(sym.name, _TYPE_TO_BASE[type_]) 3738 3739 return sym.orig_type is type_ 3740 3741 for sym in self.unique_defined_syms: 3742 if sym.orig_type in _BOOL_TRISTATE: 3743 # A helper function could be factored out here, but keep it 3744 # speedy/straightforward 3745 3746 for target_sym, _ in sym.selects: 3747 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN: 3748 self._warn("{} selects the {} symbol {}, which is not " 3749 "bool or tristate" 3750 .format(sym.name_and_loc, 3751 TYPE_TO_STR[target_sym.orig_type], 3752 target_sym.name_and_loc)) 3753 3754 for target_sym, _ in sym.implies: 3755 if target_sym.orig_type not in _BOOL_TRISTATE_UNKNOWN: 3756 self._warn("{} implies the {} symbol {}, which is not " 3757 "bool or tristate" 3758 .format(sym.name_and_loc, 3759 TYPE_TO_STR[target_sym.orig_type], 3760 target_sym.name_and_loc)) 3761 3762 elif sym.orig_type: # STRING/INT/HEX 3763 for default, _ in sym.defaults: 3764 if default.__class__ is not Symbol: 3765 raise KconfigError( 3766 "the {} symbol {} has a malformed default {} -- " 3767 "expected a single symbol" 3768 .format(TYPE_TO_STR[sym.orig_type], 3769 sym.name_and_loc, expr_str(default))) 3770 3771 if sym.orig_type is STRING: 3772 if not default.is_constant and not default.nodes and \ 3773 not default.name.isupper(): 3774 # 'default foo' on a string symbol could be either a symbol 3775 # reference or someone leaving out the quotes. Guess that 3776 # the quotes were left out if 'foo' isn't all-uppercase 3777 # (and no symbol named 'foo' exists). 3778 self._warn("style: quotes recommended around " 3779 "default value for string symbol " 3780 + sym.name_and_loc) 3781 3782 elif not num_ok(default, sym.orig_type): # INT/HEX 3783 self._warn("the {0} symbol {1} has a non-{0} default {2}" 3784 .format(TYPE_TO_STR[sym.orig_type], 3785 sym.name_and_loc, 3786 default.name_and_loc)) 3787 3788 if sym.selects or sym.implies: 3789 self._warn("the {} symbol {} has selects or implies" 3790 .format(TYPE_TO_STR[sym.orig_type], 3791 sym.name_and_loc)) 3792 3793 else: # UNKNOWN 3794 self._warn("{} defined without a type" 3795 .format(sym.name_and_loc)) 3796 3797 3798 if sym.ranges: 3799 if sym.orig_type not in _INT_HEX: 3800 self._warn( 3801 "the {} symbol {} has ranges, but is not int or hex" 3802 .format(TYPE_TO_STR[sym.orig_type], 3803 sym.name_and_loc)) 3804 else: 3805 for low, high, _ in sym.ranges: 3806 if not num_ok(low, sym.orig_type) or \ 3807 not num_ok(high, sym.orig_type): 3808 3809 self._warn("the {0} symbol {1} has a non-{0} " 3810 "range [{2}, {3}]" 3811 .format(TYPE_TO_STR[sym.orig_type], 3812 sym.name_and_loc, 3813 low.name_and_loc, 3814 high.name_and_loc)) 3815 3816 def _check_choice_sanity(self): 3817 # Checks various choice properties that are handiest to check after 3818 # parsing. Only generates errors and warnings. 3819 3820 def warn_select_imply(sym, expr, expr_type): 3821 msg = "the choice symbol {} is {} by the following symbols, but " \ 3822 "select/imply has no effect on choice symbols" \ 3823 .format(sym.name_and_loc, expr_type) 3824 3825 # si = select/imply 3826 for si in split_expr(expr, OR): 3827 msg += "\n - " + split_expr(si, AND)[0].name_and_loc 3828 3829 self._warn(msg) 3830 3831 for choice in self.unique_choices: 3832 if choice.orig_type not in _BOOL_TRISTATE: 3833 self._warn("{} defined with type {}" 3834 .format(choice.name_and_loc, 3835 TYPE_TO_STR[choice.orig_type])) 3836 3837 for node in choice.nodes: 3838 if node.prompt: 3839 break 3840 else: 3841 self._warn(choice.name_and_loc + " defined without a prompt") 3842 3843 for default, _ in choice.defaults: 3844 if default.__class__ is not Symbol: 3845 raise KconfigError( 3846 "{} has a malformed default {}" 3847 .format(choice.name_and_loc, expr_str(default))) 3848 3849 if default.choice is not choice: 3850 self._warn("the default selection {} of {} is not " 3851 "contained in the choice" 3852 .format(default.name_and_loc, 3853 choice.name_and_loc)) 3854 3855 for sym in choice.syms: 3856 if sym.defaults: 3857 self._warn("default on the choice symbol {} will have " 3858 "no effect, as defaults do not affect choice " 3859 "symbols".format(sym.name_and_loc)) 3860 3861 if sym.rev_dep is not sym.kconfig.n: 3862 warn_select_imply(sym, sym.rev_dep, "selected") 3863 3864 if sym.weak_rev_dep is not sym.kconfig.n: 3865 warn_select_imply(sym, sym.weak_rev_dep, "implied") 3866 3867 for node in sym.nodes: 3868 if node.parent.item is choice: 3869 if not node.prompt: 3870 self._warn("the choice symbol {} has no prompt" 3871 .format(sym.name_and_loc)) 3872 3873 elif node.prompt: 3874 self._warn("the choice symbol {} is defined with a " 3875 "prompt outside the choice" 3876 .format(sym.name_and_loc)) 3877 3878 def _parse_error(self, msg): 3879 raise KconfigError("{}error: couldn't parse '{}': {}".format( 3880 "" if self.filename is None else 3881 "{}:{}: ".format(self.filename, self.linenr), 3882 self._line.strip(), msg)) 3883 3884 def _trailing_tokens_error(self): 3885 self._parse_error("extra tokens at end of line") 3886 3887 def _open(self, filename, mode): 3888 # open() wrapper: 3889 # 3890 # - Enable universal newlines mode on Python 2 to ease 3891 # interoperability between Linux and Windows. It's already the 3892 # default on Python 3. 3893 # 3894 # The "U" flag would currently work for both Python 2 and 3, but it's 3895 # deprecated on Python 3, so play it future-safe. 3896 # 3897 # io.open() defaults to universal newlines on Python 2 (and is an 3898 # alias for open() on Python 3), but it returns 'unicode' strings and 3899 # slows things down: 3900 # 3901 # Parsing x86 Kconfigs on Python 2 3902 # 3903 # with open(..., "rU"): 3904 # 3905 # real 0m0.930s 3906 # user 0m0.905s 3907 # sys 0m0.025s 3908 # 3909 # with io.open(): 3910 # 3911 # real 0m1.069s 3912 # user 0m1.040s 3913 # sys 0m0.029s 3914 # 3915 # There's no appreciable performance difference between "r" and 3916 # "rU" for parsing performance on Python 2. 3917 # 3918 # - For Python 3, force the encoding. Forcing the encoding on Python 2 3919 # turns strings into Unicode strings, which gets messy. Python 2 3920 # doesn't decode regular strings anyway. 3921 return open(filename, "rU" if mode == "r" else mode) if _IS_PY2 else \ 3922 open(filename, mode, encoding=self._encoding) 3923 3924 def _check_undef_syms(self): 3925 # Prints warnings for all references to undefined symbols within the 3926 # Kconfig files 3927 3928 def is_num(s): 3929 # Returns True if the string 's' looks like a number. 3930 # 3931 # Internally, all operands in Kconfig are symbols, only undefined symbols 3932 # (which numbers usually are) get their name as their value. 3933 # 3934 # Only hex numbers that start with 0x/0X are classified as numbers. 3935 # Otherwise, symbols whose names happen to contain only the letters A-F 3936 # would trigger false positives. 3937 3938 try: 3939 int(s) 3940 except ValueError: 3941 if not s.startswith(("0x", "0X")): 3942 return False 3943 3944 try: 3945 int(s, 16) 3946 except ValueError: 3947 return False 3948 3949 return True 3950 3951 for sym in (self.syms.viewvalues if _IS_PY2 else self.syms.values)(): 3952 # - sym.nodes empty means the symbol is undefined (has no 3953 # definition locations) 3954 # 3955 # - Due to Kconfig internals, numbers show up as undefined Kconfig 3956 # symbols, but shouldn't be flagged 3957 # 3958 # - The MODULES symbol always exists 3959 if not sym.nodes and not is_num(sym.name) and \ 3960 sym.name != "MODULES": 3961 3962 msg = "undefined symbol {}:".format(sym.name) 3963 for node in self.node_iter(): 3964 if sym in node.referenced: 3965 msg += "\n\n- Referenced at {}:{}:\n\n{}" \ 3966 .format(node.filename, node.linenr, node) 3967 self._warn(msg) 3968 3969 def _warn(self, msg, filename=None, linenr=None): 3970 # For printing general warnings 3971 3972 if not self.warn: 3973 return 3974 3975 msg = "warning: " + msg 3976 if filename is not None: 3977 msg = "{}:{}: {}".format(filename, linenr, msg) 3978 3979 self.warnings.append(msg) 3980 if self.warn_to_stderr: 3981 sys.stderr.write(msg + "\n") 3982 3983 3984class Symbol(object): 3985 """ 3986 Represents a configuration symbol: 3987 3988 (menu)config FOO 3989 ... 3990 3991 The following attributes are available. They should be viewed as read-only, 3992 and some are implemented through @property magic (but are still efficient 3993 to access due to internal caching). 3994 3995 Note: Prompts, help texts, and locations are stored in the Symbol's 3996 MenuNode(s) rather than in the Symbol itself. Check the MenuNode class and 3997 the Symbol.nodes attribute. This organization matches the C tools. 3998 3999 name: 4000 The name of the symbol, e.g. "FOO" for 'config FOO'. 4001 4002 type: 4003 The type of the symbol. One of BOOL, TRISTATE, STRING, INT, HEX, UNKNOWN. 4004 UNKNOWN is for undefined symbols, (non-special) constant symbols, and 4005 symbols defined without a type. 4006 4007 When running without modules (MODULES having the value n), TRISTATE 4008 symbols magically change type to BOOL. This also happens for symbols 4009 within choices in "y" mode. This matches the C tools, and makes sense for 4010 menuconfig-like functionality. 4011 4012 orig_type: 4013 The type as given in the Kconfig file, without any magic applied. Used 4014 when printing the symbol. 4015 4016 tri_value: 4017 The tristate value of the symbol as an integer. One of 0, 1, 2, 4018 representing n, m, y. Always 0 (n) for non-bool/tristate symbols. 4019 4020 This is the symbol value that's used outside of relation expressions 4021 (A, !A, A && B, A || B). 4022 4023 str_value: 4024 The value of the symbol as a string. Gives the value for string/int/hex 4025 symbols. For bool/tristate symbols, gives "n", "m", or "y". 4026 4027 This is the symbol value that's used in relational expressions 4028 (A = B, A != B, etc.) 4029 4030 Gotcha: For int/hex symbols, the exact format of the value is often 4031 preserved (e.g. when writing a .config file), hence why you can't get it 4032 directly as an int. Do int(int_sym.str_value) or 4033 int(hex_sym.str_value, 16) to get the integer value. 4034 4035 user_value: 4036 The user value of the symbol. None if no user value has been assigned 4037 (via Kconfig.load_config() or Symbol.set_value()). 4038 4039 Holds 0, 1, or 2 for bool/tristate symbols, and a string for the other 4040 symbol types. 4041 4042 WARNING: Do not assign directly to this. It will break things. Use 4043 Symbol.set_value(). 4044 4045 assignable: 4046 A tuple containing the tristate user values that can currently be 4047 assigned to the symbol (that would be respected), ordered from lowest (0, 4048 representing n) to highest (2, representing y). This corresponds to the 4049 selections available in the menuconfig interface. The set of assignable 4050 values is calculated from the symbol's visibility and selects/implies. 4051 4052 Returns the empty set for non-bool/tristate symbols and for symbols with 4053 visibility n. The other possible values are (0, 2), (0, 1, 2), (1, 2), 4054 (1,), and (2,). A (1,) or (2,) result means the symbol is visible but 4055 "locked" to m or y through a select, perhaps in combination with the 4056 visibility. menuconfig represents this as -M- and -*-, respectively. 4057 4058 For string/hex/int symbols, check if Symbol.visibility is non-0 (non-n) 4059 instead to determine if the value can be changed. 4060 4061 Some handy 'assignable' idioms: 4062 4063 # Is 'sym' an assignable (visible) bool/tristate symbol? 4064 if sym.assignable: 4065 # What's the highest value it can be assigned? [-1] in Python 4066 # gives the last element. 4067 sym_high = sym.assignable[-1] 4068 4069 # The lowest? 4070 sym_low = sym.assignable[0] 4071 4072 # Can the symbol be set to at least m? 4073 if sym.assignable[-1] >= 1: 4074 ... 4075 4076 # Can the symbol be set to m? 4077 if 1 in sym.assignable: 4078 ... 4079 4080 visibility: 4081 The visibility of the symbol. One of 0, 1, 2, representing n, m, y. See 4082 the module documentation for an overview of symbol values and visibility. 4083 4084 config_string: 4085 The .config assignment string that would get written out for the symbol 4086 by Kconfig.write_config(). Returns the empty string if no .config 4087 assignment would get written out. 4088 4089 In general, visible symbols, symbols with (active) defaults, and selected 4090 symbols get written out. This includes all non-n-valued bool/tristate 4091 symbols, and all visible string/int/hex symbols. 4092 4093 Symbols with the (no longer needed) 'option env=...' option generate no 4094 configuration output, and neither does the special 4095 'option defconfig_list' symbol. 4096 4097 Tip: This field is useful when generating custom configuration output, 4098 even for non-.config-like formats. To write just the symbols that would 4099 get written out to .config files, do this: 4100 4101 if sym.config_string: 4102 *Write symbol, e.g. by looking sym.str_value* 4103 4104 This is a superset of the symbols written out by write_autoconf(). 4105 That function skips all n-valued symbols. 4106 4107 There usually won't be any great harm in just writing all symbols either, 4108 though you might get some special symbols and possibly some "redundant" 4109 n-valued symbol entries in there. 4110 4111 name_and_loc: 4112 Holds a string like 4113 4114 "MY_SYMBOL (defined at foo/Kconfig:12, bar/Kconfig:14)" 4115 4116 , giving the name of the symbol and its definition location(s). 4117 4118 If the symbol is undefined, the location is given as "(undefined)". 4119 4120 nodes: 4121 A list of MenuNodes for this symbol. Will contain a single MenuNode for 4122 most symbols. Undefined and constant symbols have an empty nodes list. 4123 Symbols defined in multiple locations get one node for each location. 4124 4125 choice: 4126 Holds the parent Choice for choice symbols, and None for non-choice 4127 symbols. Doubles as a flag for whether a symbol is a choice symbol. 4128 4129 defaults: 4130 List of (default, cond) tuples for the symbol's 'default' properties. For 4131 example, 'default A && B if C || D' is represented as 4132 ((AND, A, B), (OR, C, D)). If no condition was given, 'cond' is 4133 self.kconfig.y. 4134 4135 Note that 'depends on' and parent dependencies are propagated to 4136 'default' conditions. 4137 4138 selects: 4139 List of (symbol, cond) tuples for the symbol's 'select' properties. For 4140 example, 'select A if B && C' is represented as (A, (AND, B, C)). If no 4141 condition was given, 'cond' is self.kconfig.y. 4142 4143 Note that 'depends on' and parent dependencies are propagated to 'select' 4144 conditions. 4145 4146 implies: 4147 Like 'selects', for imply. 4148 4149 ranges: 4150 List of (low, high, cond) tuples for the symbol's 'range' properties. For 4151 example, 'range 1 2 if A' is represented as (1, 2, A). If there is no 4152 condition, 'cond' is self.kconfig.y. 4153 4154 Note that 'depends on' and parent dependencies are propagated to 'range' 4155 conditions. 4156 4157 Gotcha: 1 and 2 above will be represented as (undefined) Symbols rather 4158 than plain integers. Undefined symbols get their name as their string 4159 value, so this works out. The C tools work the same way. 4160 4161 orig_defaults: 4162 orig_selects: 4163 orig_implies: 4164 orig_ranges: 4165 See the corresponding attributes on the MenuNode class. 4166 4167 rev_dep: 4168 Reverse dependency expression from other symbols selecting this symbol. 4169 Multiple selections get ORed together. A condition on a select is ANDed 4170 with the selecting symbol. 4171 4172 For example, if A has 'select FOO' and B has 'select FOO if C', then 4173 FOO's rev_dep will be (OR, A, (AND, B, C)). 4174 4175 weak_rev_dep: 4176 Like rev_dep, for imply. 4177 4178 direct_dep: 4179 The direct ('depends on') dependencies for the symbol, or self.kconfig.y 4180 if there are no direct dependencies. 4181 4182 This attribute includes any dependencies from surrounding menus and ifs. 4183 Those get propagated to the direct dependencies, and the resulting direct 4184 dependencies in turn get propagated to the conditions of all properties. 4185 4186 If the symbol is defined in multiple locations, the dependencies from the 4187 different locations get ORed together. 4188 4189 referenced: 4190 A set() with all symbols and choices referenced in the properties and 4191 property conditions of the symbol. 4192 4193 Also includes dependencies from surrounding menus and ifs, because those 4194 get propagated to the symbol (see the 'Intro to symbol values' section in 4195 the module docstring). 4196 4197 Choices appear in the dependencies of choice symbols. 4198 4199 For the following definitions, only B and not C appears in A's 4200 'referenced'. To get transitive references, you'll have to recursively 4201 expand 'references' until no new items appear. 4202 4203 config A 4204 bool 4205 depends on B 4206 4207 config B 4208 bool 4209 depends on C 4210 4211 config C 4212 bool 4213 4214 See the Symbol.direct_dep attribute if you're only interested in the 4215 direct dependencies of the symbol (its 'depends on'). You can extract the 4216 symbols in it with the global expr_items() function. 4217 4218 env_var: 4219 If the Symbol has an 'option env="FOO"' option, this contains the name 4220 ("FOO") of the environment variable. None for symbols without no 4221 'option env'. 4222 4223 'option env="FOO"' acts like a 'default' property whose value is the 4224 value of $FOO. 4225 4226 Symbols with 'option env' are never written out to .config files, even if 4227 they are visible. env_var corresponds to a flag called SYMBOL_AUTO in the 4228 C implementation. 4229 4230 is_allnoconfig_y: 4231 True if the symbol has 'option allnoconfig_y' set on it. This has no 4232 effect internally (except when printing symbols), but can be checked by 4233 scripts. 4234 4235 is_constant: 4236 True if the symbol is a constant (quoted) symbol. 4237 4238 kconfig: 4239 The Kconfig instance this symbol is from. 4240 """ 4241 __slots__ = ( 4242 "_cached_assignable", 4243 "_cached_str_val", 4244 "_cached_tri_val", 4245 "_cached_vis", 4246 "_dependents", 4247 "_old_val", 4248 "_visited", 4249 "_was_set", 4250 "_write_to_conf", 4251 "choice", 4252 "defaults", 4253 "direct_dep", 4254 "env_var", 4255 "implies", 4256 "is_allnoconfig_y", 4257 "is_constant", 4258 "kconfig", 4259 "name", 4260 "nodes", 4261 "orig_type", 4262 "ranges", 4263 "rev_dep", 4264 "selects", 4265 "user_value", 4266 "weak_rev_dep", 4267 ) 4268 4269 # 4270 # Public interface 4271 # 4272 4273 @property 4274 def type(self): 4275 """ 4276 See the class documentation. 4277 """ 4278 if self.orig_type is TRISTATE and \ 4279 (self.choice and self.choice.tri_value == 2 or 4280 not self.kconfig.modules.tri_value): 4281 4282 return BOOL 4283 4284 return self.orig_type 4285 4286 @property 4287 def str_value(self): 4288 """ 4289 See the class documentation. 4290 """ 4291 if self._cached_str_val is not None: 4292 return self._cached_str_val 4293 4294 if self.orig_type in _BOOL_TRISTATE: 4295 # Also calculates the visibility, so invalidation safe 4296 self._cached_str_val = TRI_TO_STR[self.tri_value] 4297 return self._cached_str_val 4298 4299 # As a quirk of Kconfig, undefined symbols get their name as their 4300 # string value. This is why things like "FOO = bar" work for seeing if 4301 # FOO has the value "bar". 4302 if not self.orig_type: # UNKNOWN 4303 self._cached_str_val = self.name 4304 return self.name 4305 4306 val = "" 4307 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 4308 # function call (property magic) 4309 vis = self.visibility 4310 4311 self._write_to_conf = (vis != 0) 4312 4313 if self.orig_type in _INT_HEX: 4314 # The C implementation checks the user value against the range in a 4315 # separate code path (post-processing after loading a .config). 4316 # Checking all values here instead makes more sense for us. It 4317 # requires that we check for a range first. 4318 4319 base = _TYPE_TO_BASE[self.orig_type] 4320 4321 # Check if a range is in effect 4322 for low_expr, high_expr, cond in self.ranges: 4323 if expr_value(cond): 4324 has_active_range = True 4325 4326 # The zeros are from the C implementation running strtoll() 4327 # on empty strings 4328 low = int(low_expr.str_value, base) if \ 4329 _is_base_n(low_expr.str_value, base) else 0 4330 high = int(high_expr.str_value, base) if \ 4331 _is_base_n(high_expr.str_value, base) else 0 4332 4333 break 4334 else: 4335 has_active_range = False 4336 4337 # Defaults are used if the symbol is invisible, lacks a user value, 4338 # or has an out-of-range user value 4339 use_defaults = True 4340 4341 if vis and self.user_value: 4342 user_val = int(self.user_value, base) 4343 if has_active_range and not low <= user_val <= high: 4344 num2str = str if base == 10 else hex 4345 self.kconfig._warn( 4346 "user value {} on the {} symbol {} ignored due to " 4347 "being outside the active range ([{}, {}]) -- falling " 4348 "back on defaults" 4349 .format(num2str(user_val), TYPE_TO_STR[self.orig_type], 4350 self.name_and_loc, 4351 num2str(low), num2str(high))) 4352 else: 4353 # If the user value is well-formed and satisfies range 4354 # contraints, it is stored in exactly the same form as 4355 # specified in the assignment (with or without "0x", etc.) 4356 val = self.user_value 4357 use_defaults = False 4358 4359 if use_defaults: 4360 # No user value or invalid user value. Look at defaults. 4361 4362 # Used to implement the warning below 4363 has_default = False 4364 4365 for sym, cond in self.defaults: 4366 if expr_value(cond): 4367 has_default = self._write_to_conf = True 4368 4369 val = sym.str_value 4370 4371 if _is_base_n(val, base): 4372 val_num = int(val, base) 4373 else: 4374 val_num = 0 # strtoll() on empty string 4375 4376 break 4377 else: 4378 val_num = 0 # strtoll() on empty string 4379 4380 # This clamping procedure runs even if there's no default 4381 if has_active_range: 4382 clamp = None 4383 if val_num < low: 4384 clamp = low 4385 elif val_num > high: 4386 clamp = high 4387 4388 if clamp is not None: 4389 # The value is rewritten to a standard form if it is 4390 # clamped 4391 val = str(clamp) \ 4392 if self.orig_type is INT else \ 4393 hex(clamp) 4394 4395 if has_default: 4396 num2str = str if base == 10 else hex 4397 self.kconfig._warn( 4398 "default value {} on {} clamped to {} due to " 4399 "being outside the active range ([{}, {}])" 4400 .format(val_num, self.name_and_loc, 4401 num2str(clamp), num2str(low), 4402 num2str(high))) 4403 4404 elif self.orig_type is STRING: 4405 if vis and self.user_value is not None: 4406 # If the symbol is visible and has a user value, use that 4407 val = self.user_value 4408 else: 4409 # Otherwise, look at defaults 4410 for sym, cond in self.defaults: 4411 if expr_value(cond): 4412 val = sym.str_value 4413 self._write_to_conf = True 4414 break 4415 4416 # env_var corresponds to SYMBOL_AUTO in the C implementation, and is 4417 # also set on the defconfig_list symbol there. Test for the 4418 # defconfig_list symbol explicitly instead here, to avoid a nonsensical 4419 # env_var setting and the defconfig_list symbol being printed 4420 # incorrectly. This code is pretty cold anyway. 4421 if self.env_var is not None or self is self.kconfig.defconfig_list: 4422 self._write_to_conf = False 4423 4424 self._cached_str_val = val 4425 return val 4426 4427 @property 4428 def tri_value(self): 4429 """ 4430 See the class documentation. 4431 """ 4432 if self._cached_tri_val is not None: 4433 return self._cached_tri_val 4434 4435 if self.orig_type not in _BOOL_TRISTATE: 4436 if self.orig_type: # != UNKNOWN 4437 # Would take some work to give the location here 4438 self.kconfig._warn( 4439 "The {} symbol {} is being evaluated in a logical context " 4440 "somewhere. It will always evaluate to n." 4441 .format(TYPE_TO_STR[self.orig_type], self.name_and_loc)) 4442 4443 self._cached_tri_val = 0 4444 return 0 4445 4446 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 4447 # function call (property magic) 4448 vis = self.visibility 4449 self._write_to_conf = (vis != 0) 4450 4451 val = 0 4452 4453 if not self.choice: 4454 # Non-choice symbol 4455 4456 if vis and self.user_value is not None: 4457 # If the symbol is visible and has a user value, use that 4458 val = min(self.user_value, vis) 4459 4460 else: 4461 # Otherwise, look at defaults and weak reverse dependencies 4462 # (implies) 4463 4464 for default, cond in self.defaults: 4465 dep_val = expr_value(cond) 4466 if dep_val: 4467 val = min(expr_value(default), dep_val) 4468 if val: 4469 self._write_to_conf = True 4470 break 4471 4472 # Weak reverse dependencies are only considered if our 4473 # direct dependencies are met 4474 dep_val = expr_value(self.weak_rev_dep) 4475 if dep_val and expr_value(self.direct_dep): 4476 val = max(dep_val, val) 4477 self._write_to_conf = True 4478 4479 # Reverse (select-related) dependencies take precedence 4480 dep_val = expr_value(self.rev_dep) 4481 if dep_val: 4482 if expr_value(self.direct_dep) < dep_val: 4483 self._warn_select_unsatisfied_deps() 4484 4485 val = max(dep_val, val) 4486 self._write_to_conf = True 4487 4488 # m is promoted to y for (1) bool symbols and (2) symbols with a 4489 # weak_rev_dep (from imply) of y 4490 if val == 1 and \ 4491 (self.type is BOOL or expr_value(self.weak_rev_dep) == 2): 4492 val = 2 4493 4494 elif vis == 2: 4495 # Visible choice symbol in y-mode choice. The choice mode limits 4496 # the visibility of choice symbols, so it's sufficient to just 4497 # check the visibility of the choice symbols themselves. 4498 val = 2 if self.choice.selection is self else 0 4499 4500 elif vis and self.user_value: 4501 # Visible choice symbol in m-mode choice, with set non-0 user value 4502 val = 1 4503 4504 self._cached_tri_val = val 4505 return val 4506 4507 @property 4508 def assignable(self): 4509 """ 4510 See the class documentation. 4511 """ 4512 if self._cached_assignable is None: 4513 self._cached_assignable = self._assignable() 4514 return self._cached_assignable 4515 4516 @property 4517 def visibility(self): 4518 """ 4519 See the class documentation. 4520 """ 4521 if self._cached_vis is None: 4522 self._cached_vis = _visibility(self) 4523 return self._cached_vis 4524 4525 @property 4526 def config_string(self): 4527 """ 4528 See the class documentation. 4529 """ 4530 # _write_to_conf is determined when the value is calculated. This is a 4531 # hidden function call due to property magic. 4532 val = self.str_value 4533 if not self._write_to_conf: 4534 return "" 4535 4536 if self.orig_type in _BOOL_TRISTATE: 4537 return "{}{}={}\n" \ 4538 .format(self.kconfig.config_prefix, self.name, val) \ 4539 if val != "n" else \ 4540 "# {}{} is not set\n" \ 4541 .format(self.kconfig.config_prefix, self.name) 4542 4543 if self.orig_type in _INT_HEX: 4544 return "{}{}={}\n" \ 4545 .format(self.kconfig.config_prefix, self.name, val) 4546 4547 # sym.orig_type is STRING 4548 return '{}{}="{}"\n' \ 4549 .format(self.kconfig.config_prefix, self.name, escape(val)) 4550 4551 @property 4552 def name_and_loc(self): 4553 """ 4554 See the class documentation. 4555 """ 4556 return self.name + " " + _locs(self) 4557 4558 def set_value(self, value): 4559 """ 4560 Sets the user value of the symbol. 4561 4562 Equal in effect to assigning the value to the symbol within a .config 4563 file. For bool and tristate symbols, use the 'assignable' attribute to 4564 check which values can currently be assigned. Setting values outside 4565 'assignable' will cause Symbol.user_value to differ from 4566 Symbol.str/tri_value (be truncated down or up). 4567 4568 Setting a choice symbol to 2 (y) sets Choice.user_selection to the 4569 choice symbol in addition to setting Symbol.user_value. 4570 Choice.user_selection is considered when the choice is in y mode (the 4571 "normal" mode). 4572 4573 Other symbols that depend (possibly indirectly) on this symbol are 4574 automatically recalculated to reflect the assigned value. 4575 4576 value: 4577 The user value to give to the symbol. For bool and tristate symbols, 4578 n/m/y can be specified either as 0/1/2 (the usual format for tristate 4579 values in Kconfiglib) or as one of the strings "n", "m", or "y". For 4580 other symbol types, pass a string. 4581 4582 Note that the value for an int/hex symbol is passed as a string, e.g. 4583 "123" or "0x0123". The format of this string is preserved in the 4584 output. 4585 4586 Values that are invalid for the type (such as "foo" or 1 (m) for a 4587 BOOL or "0x123" for an INT) are ignored and won't be stored in 4588 Symbol.user_value. Kconfiglib will print a warning by default for 4589 invalid assignments, and set_value() will return False. 4590 4591 Returns True if the value is valid for the type of the symbol, and 4592 False otherwise. This only looks at the form of the value. For BOOL and 4593 TRISTATE symbols, check the Symbol.assignable attribute to see what 4594 values are currently in range and would actually be reflected in the 4595 value of the symbol. For other symbol types, check whether the 4596 visibility is non-n. 4597 """ 4598 if self.orig_type in _BOOL_TRISTATE and value in STR_TO_TRI: 4599 value = STR_TO_TRI[value] 4600 4601 # If the new user value matches the old, nothing changes, and we can 4602 # avoid invalidating cached values. 4603 # 4604 # This optimization is skipped for choice symbols: Setting a choice 4605 # symbol's user value to y might change the state of the choice, so it 4606 # wouldn't be safe (symbol user values always match the values set in a 4607 # .config file or via set_value(), and are never implicitly updated). 4608 if value == self.user_value and not self.choice: 4609 self._was_set = True 4610 return True 4611 4612 # Check if the value is valid for our type 4613 if not (self.orig_type is BOOL and value in (2, 0) or 4614 self.orig_type is TRISTATE and value in TRI_TO_STR or 4615 value.__class__ is str and 4616 (self.orig_type is STRING or 4617 self.orig_type is INT and _is_base_n(value, 10) or 4618 self.orig_type is HEX and _is_base_n(value, 16) 4619 and int(value, 16) >= 0)): 4620 4621 # Display tristate values as n, m, y in the warning 4622 self.kconfig._warn( 4623 "the value {} is invalid for {}, which has type {} -- " 4624 "assignment ignored" 4625 .format(TRI_TO_STR[value] if value in TRI_TO_STR else 4626 "'{}'".format(value), 4627 self.name_and_loc, TYPE_TO_STR[self.orig_type])) 4628 4629 return False 4630 4631 self.user_value = value 4632 self._was_set = True 4633 4634 if self.choice and value == 2: 4635 # Setting a choice symbol to y makes it the user selection of the 4636 # choice. Like for symbol user values, the user selection is not 4637 # guaranteed to match the actual selection of the choice, as 4638 # dependencies come into play. 4639 self.choice.user_selection = self 4640 self.choice._was_set = True 4641 self.choice._rec_invalidate() 4642 else: 4643 self._rec_invalidate_if_has_prompt() 4644 4645 return True 4646 4647 def unset_value(self): 4648 """ 4649 Removes any user value from the symbol, as if the symbol had never 4650 gotten a user value via Kconfig.load_config() or Symbol.set_value(). 4651 """ 4652 if self.user_value is not None: 4653 self.user_value = None 4654 self._rec_invalidate_if_has_prompt() 4655 4656 @property 4657 def referenced(self): 4658 """ 4659 See the class documentation. 4660 """ 4661 return {item for node in self.nodes for item in node.referenced} 4662 4663 @property 4664 def orig_defaults(self): 4665 """ 4666 See the class documentation. 4667 """ 4668 return [d for node in self.nodes for d in node.orig_defaults] 4669 4670 @property 4671 def orig_selects(self): 4672 """ 4673 See the class documentation. 4674 """ 4675 return [s for node in self.nodes for s in node.orig_selects] 4676 4677 @property 4678 def orig_implies(self): 4679 """ 4680 See the class documentation. 4681 """ 4682 return [i for node in self.nodes for i in node.orig_implies] 4683 4684 @property 4685 def orig_ranges(self): 4686 """ 4687 See the class documentation. 4688 """ 4689 return [r for node in self.nodes for r in node.orig_ranges] 4690 4691 def __repr__(self): 4692 """ 4693 Returns a string with information about the symbol (including its name, 4694 value, visibility, and location(s)) when it is evaluated on e.g. the 4695 interactive Python prompt. 4696 """ 4697 fields = ["symbol " + self.name, TYPE_TO_STR[self.type]] 4698 add = fields.append 4699 4700 for node in self.nodes: 4701 if node.prompt: 4702 add('"{}"'.format(node.prompt[0])) 4703 4704 # Only add quotes for non-bool/tristate symbols 4705 add("value " + (self.str_value if self.orig_type in _BOOL_TRISTATE 4706 else '"{}"'.format(self.str_value))) 4707 4708 if not self.is_constant: 4709 # These aren't helpful to show for constant symbols 4710 4711 if self.user_value is not None: 4712 # Only add quotes for non-bool/tristate symbols 4713 add("user value " + (TRI_TO_STR[self.user_value] 4714 if self.orig_type in _BOOL_TRISTATE 4715 else '"{}"'.format(self.user_value))) 4716 4717 add("visibility " + TRI_TO_STR[self.visibility]) 4718 4719 if self.choice: 4720 add("choice symbol") 4721 4722 if self.is_allnoconfig_y: 4723 add("allnoconfig_y") 4724 4725 if self is self.kconfig.defconfig_list: 4726 add("is the defconfig_list symbol") 4727 4728 if self.env_var is not None: 4729 add("from environment variable " + self.env_var) 4730 4731 if self is self.kconfig.modules: 4732 add("is the modules symbol") 4733 4734 add("direct deps " + TRI_TO_STR[expr_value(self.direct_dep)]) 4735 4736 if self.nodes: 4737 for node in self.nodes: 4738 add("{}:{}".format(node.filename, node.linenr)) 4739 else: 4740 add("constant" if self.is_constant else "undefined") 4741 4742 return "<{}>".format(", ".join(fields)) 4743 4744 def __str__(self): 4745 """ 4746 Returns a string representation of the symbol when it is printed. 4747 Matches the Kconfig format, with any parent dependencies propagated to 4748 the 'depends on' condition. 4749 4750 The string is constructed by joining the strings returned by 4751 MenuNode.__str__() for each of the symbol's menu nodes, so symbols 4752 defined in multiple locations will return a string with all 4753 definitions. 4754 4755 The returned string does not end in a newline. An empty string is 4756 returned for undefined and constant symbols. 4757 """ 4758 return self.custom_str(standard_sc_expr_str) 4759 4760 def custom_str(self, sc_expr_str_fn): 4761 """ 4762 Works like Symbol.__str__(), but allows a custom format to be used for 4763 all symbol/choice references. See expr_str(). 4764 """ 4765 return "\n\n".join(node.custom_str(sc_expr_str_fn) 4766 for node in self.nodes) 4767 4768 # 4769 # Private methods 4770 # 4771 4772 def __init__(self): 4773 """ 4774 Symbol constructor -- not intended to be called directly by Kconfiglib 4775 clients. 4776 """ 4777 # These attributes are always set on the instance from outside and 4778 # don't need defaults: 4779 # kconfig 4780 # direct_dep 4781 # is_constant 4782 # name 4783 # rev_dep 4784 # weak_rev_dep 4785 4786 # - UNKNOWN == 0 4787 # - _visited is used during tree iteration and dep. loop detection 4788 self.orig_type = self._visited = 0 4789 4790 self.nodes = [] 4791 4792 self.defaults = [] 4793 self.selects = [] 4794 self.implies = [] 4795 self.ranges = [] 4796 4797 self.user_value = \ 4798 self.choice = \ 4799 self.env_var = \ 4800 self._cached_str_val = self._cached_tri_val = self._cached_vis = \ 4801 self._cached_assignable = None 4802 4803 # _write_to_conf is calculated along with the value. If True, the 4804 # Symbol gets a .config entry. 4805 4806 self.is_allnoconfig_y = \ 4807 self._was_set = \ 4808 self._write_to_conf = False 4809 4810 # See Kconfig._build_dep() 4811 self._dependents = set() 4812 4813 def _assignable(self): 4814 # Worker function for the 'assignable' attribute 4815 4816 if self.orig_type not in _BOOL_TRISTATE: 4817 return () 4818 4819 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 4820 # function call (property magic) 4821 vis = self.visibility 4822 if not vis: 4823 return () 4824 4825 rev_dep_val = expr_value(self.rev_dep) 4826 4827 if vis == 2: 4828 if self.choice: 4829 return (2,) 4830 4831 if not rev_dep_val: 4832 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2: 4833 return (0, 2) 4834 return (0, 1, 2) 4835 4836 if rev_dep_val == 2: 4837 return (2,) 4838 4839 # rev_dep_val == 1 4840 4841 if self.type is BOOL or expr_value(self.weak_rev_dep) == 2: 4842 return (2,) 4843 return (1, 2) 4844 4845 # vis == 1 4846 4847 # Must be a tristate here, because bool m visibility gets promoted to y 4848 4849 if not rev_dep_val: 4850 return (0, 1) if expr_value(self.weak_rev_dep) != 2 else (0, 2) 4851 4852 if rev_dep_val == 2: 4853 return (2,) 4854 4855 # vis == rev_dep_val == 1 4856 4857 return (1,) 4858 4859 def _invalidate(self): 4860 # Marks the symbol as needing to be recalculated 4861 4862 self._cached_str_val = self._cached_tri_val = self._cached_vis = \ 4863 self._cached_assignable = None 4864 4865 def _rec_invalidate(self): 4866 # Invalidates the symbol and all items that (possibly) depend on it 4867 4868 if self is self.kconfig.modules: 4869 # Invalidating MODULES has wide-ranging effects 4870 self.kconfig._invalidate_all() 4871 else: 4872 self._invalidate() 4873 4874 for item in self._dependents: 4875 # _cached_vis doubles as a flag that tells us whether 'item' 4876 # has cached values, because it's calculated as a side effect 4877 # of calculating all other (non-constant) cached values. 4878 # 4879 # If item._cached_vis is None, it means there can't be cached 4880 # values on other items that depend on 'item', because if there 4881 # were, some value on 'item' would have been calculated and 4882 # item._cached_vis set as a side effect. It's therefore safe to 4883 # stop the invalidation at symbols with _cached_vis None. 4884 # 4885 # This approach massively speeds up scripts that set a lot of 4886 # values, vs simply invalidating all possibly dependent symbols 4887 # (even when you already have a list of all the dependent 4888 # symbols, because some symbols get huge dependency trees). 4889 # 4890 # This gracefully handles dependency loops too, which is nice 4891 # for choices, where the choice depends on the choice symbols 4892 # and vice versa. 4893 if item._cached_vis is not None: 4894 item._rec_invalidate() 4895 4896 def _rec_invalidate_if_has_prompt(self): 4897 # Invalidates the symbol and its dependent symbols, but only if the 4898 # symbol has a prompt. User values never have an effect on promptless 4899 # symbols, so we skip invalidation for them as an optimization. 4900 # 4901 # This also prevents constant (quoted) symbols from being invalidated 4902 # if set_value() is called on them, which would make them lose their 4903 # value and break things. 4904 # 4905 # Prints a warning if the symbol has no prompt. In some contexts (e.g. 4906 # when loading a .config files) assignments to promptless symbols are 4907 # normal and expected, so the warning can be disabled. 4908 4909 for node in self.nodes: 4910 if node.prompt: 4911 self._rec_invalidate() 4912 return 4913 4914 if self.kconfig._warn_assign_no_prompt: 4915 self.kconfig._warn(self.name_and_loc + " has no prompt, meaning " 4916 "user values have no effect on it") 4917 4918 def _str_default(self): 4919 # write_min_config() helper function. Returns the value the symbol 4920 # would get from defaults if it didn't have a user value. Uses exactly 4921 # the same algorithm as the C implementation (though a bit cleaned up), 4922 # for compatibility. 4923 4924 if self.orig_type in _BOOL_TRISTATE: 4925 val = 0 4926 4927 # Defaults, selects, and implies do not affect choice symbols 4928 if not self.choice: 4929 for default, cond in self.defaults: 4930 cond_val = expr_value(cond) 4931 if cond_val: 4932 val = min(expr_value(default), cond_val) 4933 break 4934 4935 val = max(expr_value(self.rev_dep), 4936 expr_value(self.weak_rev_dep), 4937 val) 4938 4939 # Transpose mod to yes if type is bool (possibly due to modules 4940 # being disabled) 4941 if val == 1 and self.type is BOOL: 4942 val = 2 4943 4944 return TRI_TO_STR[val] 4945 4946 if self.orig_type: # STRING/INT/HEX 4947 for default, cond in self.defaults: 4948 if expr_value(cond): 4949 return default.str_value 4950 4951 return "" 4952 4953 def _warn_select_unsatisfied_deps(self): 4954 # Helper for printing an informative warning when a symbol with 4955 # unsatisfied direct dependencies (dependencies from 'depends on', ifs, 4956 # and menus) is selected by some other symbol. Also warn if a symbol 4957 # whose direct dependencies evaluate to m is selected to y. 4958 4959 msg = "{} has direct dependencies {} with value {}, but is " \ 4960 "currently being {}-selected by the following symbols:" \ 4961 .format(self.name_and_loc, expr_str(self.direct_dep), 4962 TRI_TO_STR[expr_value(self.direct_dep)], 4963 TRI_TO_STR[expr_value(self.rev_dep)]) 4964 4965 # The reverse dependencies from each select are ORed together 4966 for select in split_expr(self.rev_dep, OR): 4967 if expr_value(select) <= expr_value(self.direct_dep): 4968 # Only include selects that exceed the direct dependencies 4969 continue 4970 4971 # - 'select A if B' turns into A && B 4972 # - 'select A' just turns into A 4973 # 4974 # In both cases, we can split on AND and pick the first operand 4975 selecting_sym = split_expr(select, AND)[0] 4976 4977 msg += "\n - {}, with value {}, direct dependencies {} " \ 4978 "(value: {})" \ 4979 .format(selecting_sym.name_and_loc, 4980 selecting_sym.str_value, 4981 expr_str(selecting_sym.direct_dep), 4982 TRI_TO_STR[expr_value(selecting_sym.direct_dep)]) 4983 4984 if select.__class__ is tuple: 4985 msg += ", and select condition {} (value: {})" \ 4986 .format(expr_str(select[2]), 4987 TRI_TO_STR[expr_value(select[2])]) 4988 4989 self.kconfig._warn(msg) 4990 4991 4992class Choice(object): 4993 """ 4994 Represents a choice statement: 4995 4996 choice 4997 ... 4998 endchoice 4999 5000 The following attributes are available on Choice instances. They should be 5001 treated as read-only, and some are implemented through @property magic (but 5002 are still efficient to access due to internal caching). 5003 5004 Note: Prompts, help texts, and locations are stored in the Choice's 5005 MenuNode(s) rather than in the Choice itself. Check the MenuNode class and 5006 the Choice.nodes attribute. This organization matches the C tools. 5007 5008 name: 5009 The name of the choice, e.g. "FOO" for 'choice FOO', or None if the 5010 Choice has no name. 5011 5012 type: 5013 The type of the choice. One of BOOL, TRISTATE, UNKNOWN. UNKNOWN is for 5014 choices defined without a type where none of the contained symbols have a 5015 type either (otherwise the choice inherits the type of the first symbol 5016 defined with a type). 5017 5018 When running without modules (CONFIG_MODULES=n), TRISTATE choices 5019 magically change type to BOOL. This matches the C tools, and makes sense 5020 for menuconfig-like functionality. 5021 5022 orig_type: 5023 The type as given in the Kconfig file, without any magic applied. Used 5024 when printing the choice. 5025 5026 tri_value: 5027 The tristate value (mode) of the choice. A choice can be in one of three 5028 modes: 5029 5030 0 (n) - The choice is disabled and no symbols can be selected. For 5031 visible choices, this mode is only possible for choices with 5032 the 'optional' flag set (see kconfig-language.txt). 5033 5034 1 (m) - Any number of choice symbols can be set to m, the rest will 5035 be n. 5036 5037 2 (y) - One symbol will be y, the rest n. 5038 5039 Only tristate choices can be in m mode. The visibility of the choice is 5040 an upper bound on the mode, and the mode in turn is an upper bound on the 5041 visibility of the choice symbols. 5042 5043 To change the mode, use Choice.set_value(). 5044 5045 Implementation note: 5046 The C tools internally represent choices as a type of symbol, with 5047 special-casing in many code paths. This is why there is a lot of 5048 similarity to Symbol. The value (mode) of a choice is really just a 5049 normal symbol value, and an implicit reverse dependency forces its 5050 lower bound to m for visible non-optional choices (the reverse 5051 dependency is 'm && <visibility>'). 5052 5053 Symbols within choices get the choice propagated as a dependency to 5054 their properties. This turns the mode of the choice into an upper bound 5055 on e.g. the visibility of choice symbols, and explains the gotcha 5056 related to printing choice symbols mentioned in the module docstring. 5057 5058 Kconfiglib uses a separate Choice class only because it makes the code 5059 and interface less confusing (especially in a user-facing interface). 5060 Corresponding attributes have the same name in the Symbol and Choice 5061 classes, for consistency and compatibility. 5062 5063 str_value: 5064 Like choice.tri_value, but gives the value as one of the strings 5065 "n", "m", or "y" 5066 5067 user_value: 5068 The value (mode) selected by the user through Choice.set_value(). Either 5069 0, 1, or 2, or None if the user hasn't selected a mode. See 5070 Symbol.user_value. 5071 5072 WARNING: Do not assign directly to this. It will break things. Use 5073 Choice.set_value() instead. 5074 5075 assignable: 5076 See the symbol class documentation. Gives the assignable values (modes). 5077 5078 selection: 5079 The Symbol instance of the currently selected symbol. None if the Choice 5080 is not in y mode or has no selected symbol (due to unsatisfied 5081 dependencies on choice symbols). 5082 5083 WARNING: Do not assign directly to this. It will break things. Call 5084 sym.set_value(2) on the choice symbol you want to select instead. 5085 5086 user_selection: 5087 The symbol selected by the user (by setting it to y). Ignored if the 5088 choice is not in y mode, but still remembered so that the choice "snaps 5089 back" to the user selection if the mode is changed back to y. This might 5090 differ from 'selection' due to unsatisfied dependencies. 5091 5092 WARNING: Do not assign directly to this. It will break things. Call 5093 sym.set_value(2) on the choice symbol to be selected instead. 5094 5095 visibility: 5096 See the Symbol class documentation. Acts on the value (mode). 5097 5098 name_and_loc: 5099 Holds a string like 5100 5101 "<choice MY_CHOICE> (defined at foo/Kconfig:12)" 5102 5103 , giving the name of the choice and its definition location(s). If the 5104 choice has no name (isn't defined with 'choice MY_CHOICE'), then it will 5105 be shown as "<choice>" before the list of locations (always a single one 5106 in that case). 5107 5108 syms: 5109 List of symbols contained in the choice. 5110 5111 Obscure gotcha: If a symbol depends on the previous symbol within a 5112 choice so that an implicit menu is created, it won't be a choice symbol, 5113 and won't be included in 'syms'. 5114 5115 nodes: 5116 A list of MenuNodes for this choice. In practice, the list will probably 5117 always contain a single MenuNode, but it is possible to give a choice a 5118 name and define it in multiple locations. 5119 5120 defaults: 5121 List of (symbol, cond) tuples for the choice's 'defaults' properties. For 5122 example, 'default A if B && C' is represented as (A, (AND, B, C)). If 5123 there is no condition, 'cond' is self.kconfig.y. 5124 5125 Note that 'depends on' and parent dependencies are propagated to 5126 'default' conditions. 5127 5128 orig_defaults: 5129 See the corresponding attribute on the MenuNode class. 5130 5131 direct_dep: 5132 See Symbol.direct_dep. 5133 5134 referenced: 5135 A set() with all symbols referenced in the properties and property 5136 conditions of the choice. 5137 5138 Also includes dependencies from surrounding menus and ifs, because those 5139 get propagated to the choice (see the 'Intro to symbol values' section in 5140 the module docstring). 5141 5142 is_optional: 5143 True if the choice has the 'optional' flag set on it and can be in 5144 n mode. 5145 5146 kconfig: 5147 The Kconfig instance this choice is from. 5148 """ 5149 __slots__ = ( 5150 "_cached_assignable", 5151 "_cached_selection", 5152 "_cached_vis", 5153 "_dependents", 5154 "_visited", 5155 "_was_set", 5156 "defaults", 5157 "direct_dep", 5158 "is_constant", 5159 "is_optional", 5160 "kconfig", 5161 "name", 5162 "nodes", 5163 "orig_type", 5164 "syms", 5165 "user_selection", 5166 "user_value", 5167 ) 5168 5169 # 5170 # Public interface 5171 # 5172 5173 @property 5174 def type(self): 5175 """ 5176 Returns the type of the choice. See Symbol.type. 5177 """ 5178 if self.orig_type is TRISTATE and not self.kconfig.modules.tri_value: 5179 return BOOL 5180 return self.orig_type 5181 5182 @property 5183 def str_value(self): 5184 """ 5185 See the class documentation. 5186 """ 5187 return TRI_TO_STR[self.tri_value] 5188 5189 @property 5190 def tri_value(self): 5191 """ 5192 See the class documentation. 5193 """ 5194 # This emulates a reverse dependency of 'm && visibility' for 5195 # non-optional choices, which is how the C implementation does it 5196 5197 val = 0 if self.is_optional else 1 5198 5199 if self.user_value is not None: 5200 val = max(val, self.user_value) 5201 5202 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 5203 # function call (property magic) 5204 val = min(val, self.visibility) 5205 5206 # Promote m to y for boolean choices 5207 return 2 if val == 1 and self.type is BOOL else val 5208 5209 @property 5210 def assignable(self): 5211 """ 5212 See the class documentation. 5213 """ 5214 if self._cached_assignable is None: 5215 self._cached_assignable = self._assignable() 5216 return self._cached_assignable 5217 5218 @property 5219 def visibility(self): 5220 """ 5221 See the class documentation. 5222 """ 5223 if self._cached_vis is None: 5224 self._cached_vis = _visibility(self) 5225 return self._cached_vis 5226 5227 @property 5228 def name_and_loc(self): 5229 """ 5230 See the class documentation. 5231 """ 5232 # Reuse the expression format, which is '<choice (name, if any)>'. 5233 return standard_sc_expr_str(self) + " " + _locs(self) 5234 5235 @property 5236 def selection(self): 5237 """ 5238 See the class documentation. 5239 """ 5240 if self._cached_selection is _NO_CACHED_SELECTION: 5241 self._cached_selection = self._selection() 5242 return self._cached_selection 5243 5244 def set_value(self, value): 5245 """ 5246 Sets the user value (mode) of the choice. Like for Symbol.set_value(), 5247 the visibility might truncate the value. Choices without the 'optional' 5248 attribute (is_optional) can never be in n mode, but 0/"n" is still 5249 accepted since it's not a malformed value (though it will have no 5250 effect). 5251 5252 Returns True if the value is valid for the type of the choice, and 5253 False otherwise. This only looks at the form of the value. Check the 5254 Choice.assignable attribute to see what values are currently in range 5255 and would actually be reflected in the mode of the choice. 5256 """ 5257 if value in STR_TO_TRI: 5258 value = STR_TO_TRI[value] 5259 5260 if value == self.user_value: 5261 # We know the value must be valid if it was successfully set 5262 # previously 5263 self._was_set = True 5264 return True 5265 5266 if not (self.orig_type is BOOL and value in (2, 0) or 5267 self.orig_type is TRISTATE and value in TRI_TO_STR): 5268 5269 # Display tristate values as n, m, y in the warning 5270 self.kconfig._warn( 5271 "the value {} is invalid for {}, which has type {} -- " 5272 "assignment ignored" 5273 .format(TRI_TO_STR[value] if value in TRI_TO_STR else 5274 "'{}'".format(value), 5275 self.name_and_loc, TYPE_TO_STR[self.orig_type])) 5276 5277 return False 5278 5279 self.user_value = value 5280 self._was_set = True 5281 self._rec_invalidate() 5282 5283 return True 5284 5285 def unset_value(self): 5286 """ 5287 Resets the user value (mode) and user selection of the Choice, as if 5288 the user had never touched the mode or any of the choice symbols. 5289 """ 5290 if self.user_value is not None or self.user_selection: 5291 self.user_value = self.user_selection = None 5292 self._rec_invalidate() 5293 5294 @property 5295 def referenced(self): 5296 """ 5297 See the class documentation. 5298 """ 5299 return {item for node in self.nodes for item in node.referenced} 5300 5301 @property 5302 def orig_defaults(self): 5303 """ 5304 See the class documentation. 5305 """ 5306 return [d for node in self.nodes for d in node.orig_defaults] 5307 5308 def __repr__(self): 5309 """ 5310 Returns a string with information about the choice when it is evaluated 5311 on e.g. the interactive Python prompt. 5312 """ 5313 fields = ["choice " + self.name if self.name else "choice", 5314 TYPE_TO_STR[self.type]] 5315 add = fields.append 5316 5317 for node in self.nodes: 5318 if node.prompt: 5319 add('"{}"'.format(node.prompt[0])) 5320 5321 add("mode " + self.str_value) 5322 5323 if self.user_value is not None: 5324 add('user mode {}'.format(TRI_TO_STR[self.user_value])) 5325 5326 if self.selection: 5327 add("{} selected".format(self.selection.name)) 5328 5329 if self.user_selection: 5330 user_sel_str = "{} selected by user" \ 5331 .format(self.user_selection.name) 5332 5333 if self.selection is not self.user_selection: 5334 user_sel_str += " (overridden)" 5335 5336 add(user_sel_str) 5337 5338 add("visibility " + TRI_TO_STR[self.visibility]) 5339 5340 if self.is_optional: 5341 add("optional") 5342 5343 for node in self.nodes: 5344 add("{}:{}".format(node.filename, node.linenr)) 5345 5346 return "<{}>".format(", ".join(fields)) 5347 5348 def __str__(self): 5349 """ 5350 Returns a string representation of the choice when it is printed. 5351 Matches the Kconfig format (though without the contained choice 5352 symbols), with any parent dependencies propagated to the 'depends on' 5353 condition. 5354 5355 The returned string does not end in a newline. 5356 5357 See Symbol.__str__() as well. 5358 """ 5359 return self.custom_str(standard_sc_expr_str) 5360 5361 def custom_str(self, sc_expr_str_fn): 5362 """ 5363 Works like Choice.__str__(), but allows a custom format to be used for 5364 all symbol/choice references. See expr_str(). 5365 """ 5366 return "\n\n".join(node.custom_str(sc_expr_str_fn) 5367 for node in self.nodes) 5368 5369 # 5370 # Private methods 5371 # 5372 5373 def __init__(self): 5374 """ 5375 Choice constructor -- not intended to be called directly by Kconfiglib 5376 clients. 5377 """ 5378 # These attributes are always set on the instance from outside and 5379 # don't need defaults: 5380 # direct_dep 5381 # kconfig 5382 5383 # - UNKNOWN == 0 5384 # - _visited is used during dep. loop detection 5385 self.orig_type = self._visited = 0 5386 5387 self.nodes = [] 5388 5389 self.syms = [] 5390 self.defaults = [] 5391 5392 self.name = \ 5393 self.user_value = self.user_selection = \ 5394 self._cached_vis = self._cached_assignable = None 5395 5396 self._cached_selection = _NO_CACHED_SELECTION 5397 5398 # is_constant is checked by _depend_on(). Just set it to avoid having 5399 # to special-case choices. 5400 self.is_constant = self.is_optional = False 5401 5402 # See Kconfig._build_dep() 5403 self._dependents = set() 5404 5405 def _assignable(self): 5406 # Worker function for the 'assignable' attribute 5407 5408 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 5409 # function call (property magic) 5410 vis = self.visibility 5411 5412 if not vis: 5413 return () 5414 5415 if vis == 2: 5416 if not self.is_optional: 5417 return (2,) if self.type is BOOL else (1, 2) 5418 return (0, 2) if self.type is BOOL else (0, 1, 2) 5419 5420 # vis == 1 5421 5422 return (0, 1) if self.is_optional else (1,) 5423 5424 def _selection(self): 5425 # Worker function for the 'selection' attribute 5426 5427 # Warning: See Symbol._rec_invalidate(), and note that this is a hidden 5428 # function call (property magic) 5429 if self.tri_value != 2: 5430 # Not in y mode, so no selection 5431 return None 5432 5433 # Use the user selection if it's visible 5434 if self.user_selection and self.user_selection.visibility: 5435 return self.user_selection 5436 5437 # Otherwise, check if we have a default 5438 return self._selection_from_defaults() 5439 5440 def _selection_from_defaults(self): 5441 # Check if we have a default 5442 for sym, cond in self.defaults: 5443 # The default symbol must be visible too 5444 if expr_value(cond) and sym.visibility: 5445 return sym 5446 5447 # Otherwise, pick the first visible symbol, if any 5448 for sym in self.syms: 5449 if sym.visibility: 5450 return sym 5451 5452 # Couldn't find a selection 5453 return None 5454 5455 def _invalidate(self): 5456 self._cached_vis = self._cached_assignable = None 5457 self._cached_selection = _NO_CACHED_SELECTION 5458 5459 def _rec_invalidate(self): 5460 # See Symbol._rec_invalidate() 5461 5462 self._invalidate() 5463 5464 for item in self._dependents: 5465 if item._cached_vis is not None: 5466 item._rec_invalidate() 5467 5468 5469class MenuNode(object): 5470 """ 5471 Represents a menu node in the configuration. This corresponds to an entry 5472 in e.g. the 'make menuconfig' interface, though non-visible choices, menus, 5473 and comments also get menu nodes. If a symbol or choice is defined in 5474 multiple locations, it gets one menu node for each location. 5475 5476 The top-level menu node, corresponding to the implicit top-level menu, is 5477 available in Kconfig.top_node. 5478 5479 The menu nodes for a Symbol or Choice can be found in the 5480 Symbol/Choice.nodes attribute. Menus and comments are represented as plain 5481 menu nodes, with their text stored in the prompt attribute (prompt[0]). 5482 This mirrors the C implementation. 5483 5484 The following attributes are available on MenuNode instances. They should 5485 be viewed as read-only. 5486 5487 item: 5488 Either a Symbol, a Choice, or one of the constants MENU and COMMENT. 5489 Menus and comments are represented as plain menu nodes. Ifs are collapsed 5490 (matching the C implementation) and do not appear in the final menu tree. 5491 5492 next: 5493 The following menu node. None if there is no following node. 5494 5495 list: 5496 The first child menu node. None if there are no children. 5497 5498 Choices and menus naturally have children, but Symbols can also have 5499 children because of menus created automatically from dependencies (see 5500 kconfig-language.txt). 5501 5502 parent: 5503 The parent menu node. None if there is no parent. 5504 5505 prompt: 5506 A (string, cond) tuple with the prompt for the menu node and its 5507 conditional expression (which is self.kconfig.y if there is no 5508 condition). None if there is no prompt. 5509 5510 For symbols and choices, the prompt is stored in the MenuNode rather than 5511 the Symbol or Choice instance. For menus and comments, the prompt holds 5512 the text. 5513 5514 defaults: 5515 The 'default' properties for this particular menu node. See 5516 symbol.defaults. 5517 5518 When evaluating defaults, you should use Symbol/Choice.defaults instead, 5519 as it include properties from all menu nodes (a symbol/choice can have 5520 multiple definition locations/menu nodes). MenuNode.defaults is meant for 5521 documentation generation. 5522 5523 selects: 5524 Like MenuNode.defaults, for selects. 5525 5526 implies: 5527 Like MenuNode.defaults, for implies. 5528 5529 ranges: 5530 Like MenuNode.defaults, for ranges. 5531 5532 orig_prompt: 5533 orig_defaults: 5534 orig_selects: 5535 orig_implies: 5536 orig_ranges: 5537 These work the like the corresponding attributes without orig_*, but omit 5538 any dependencies propagated from 'depends on' and surrounding 'if's (the 5539 direct dependencies, stored in MenuNode.dep). 5540 5541 One use for this is generating less cluttered documentation, by only 5542 showing the direct dependencies in one place. 5543 5544 help: 5545 The help text for the menu node for Symbols and Choices. None if there is 5546 no help text. Always stored in the node rather than the Symbol or Choice. 5547 It is possible to have a separate help text at each location if a symbol 5548 is defined in multiple locations. 5549 5550 Trailing whitespace (including a final newline) is stripped from the help 5551 text. This was not the case before Kconfiglib 10.21.0, where the format 5552 was undocumented. 5553 5554 dep: 5555 The direct ('depends on') dependencies for the menu node, or 5556 self.kconfig.y if there are no direct dependencies. 5557 5558 This attribute includes any dependencies from surrounding menus and ifs. 5559 Those get propagated to the direct dependencies, and the resulting direct 5560 dependencies in turn get propagated to the conditions of all properties. 5561 5562 If a symbol or choice is defined in multiple locations, only the 5563 properties defined at a particular location get the corresponding 5564 MenuNode.dep dependencies propagated to them. 5565 5566 visibility: 5567 The 'visible if' dependencies for the menu node (which must represent a 5568 menu), or self.kconfig.y if there are no 'visible if' dependencies. 5569 'visible if' dependencies are recursively propagated to the prompts of 5570 symbols and choices within the menu. 5571 5572 referenced: 5573 A set() with all symbols and choices referenced in the properties and 5574 property conditions of the menu node. 5575 5576 Also includes dependencies inherited from surrounding menus and ifs. 5577 Choices appear in the dependencies of choice symbols. 5578 5579 is_menuconfig: 5580 Set to True if the children of the menu node should be displayed in a 5581 separate menu. This is the case for the following items: 5582 5583 - Menus (node.item == MENU) 5584 5585 - Choices 5586 5587 - Symbols defined with the 'menuconfig' keyword. The children come from 5588 implicitly created submenus, and should be displayed in a separate 5589 menu rather than being indented. 5590 5591 'is_menuconfig' is just a hint on how to display the menu node. It's 5592 ignored internally by Kconfiglib, except when printing symbols. 5593 5594 filename/linenr: 5595 The location where the menu node appears. The filename is relative to 5596 $srctree (or to the current directory if $srctree isn't set), except 5597 absolute paths are used for paths outside $srctree. 5598 5599 include_path: 5600 A tuple of (filename, linenr) tuples, giving the locations of the 5601 'source' statements via which the Kconfig file containing this menu node 5602 was included. The first element is the location of the 'source' statement 5603 in the top-level Kconfig file passed to Kconfig.__init__(), etc. 5604 5605 Note that the Kconfig file of the menu node itself isn't included. Check 5606 'filename' and 'linenr' for that. 5607 5608 kconfig: 5609 The Kconfig instance the menu node is from. 5610 """ 5611 __slots__ = ( 5612 "dep", 5613 "filename", 5614 "help", 5615 "include_path", 5616 "is_menuconfig", 5617 "item", 5618 "kconfig", 5619 "linenr", 5620 "list", 5621 "next", 5622 "parent", 5623 "prompt", 5624 "visibility", 5625 5626 # Properties 5627 "defaults", 5628 "selects", 5629 "implies", 5630 "ranges", 5631 ) 5632 5633 def __init__(self): 5634 # Properties defined on this particular menu node. A local 'depends on' 5635 # only applies to these, in case a symbol is defined in multiple 5636 # locations. 5637 self.defaults = [] 5638 self.selects = [] 5639 self.implies = [] 5640 self.ranges = [] 5641 5642 @property 5643 def orig_prompt(self): 5644 """ 5645 See the class documentation. 5646 """ 5647 if not self.prompt: 5648 return None 5649 return (self.prompt[0], self._strip_dep(self.prompt[1])) 5650 5651 @property 5652 def orig_defaults(self): 5653 """ 5654 See the class documentation. 5655 """ 5656 return [(default, self._strip_dep(cond)) 5657 for default, cond in self.defaults] 5658 5659 @property 5660 def orig_selects(self): 5661 """ 5662 See the class documentation. 5663 """ 5664 return [(select, self._strip_dep(cond)) 5665 for select, cond in self.selects] 5666 5667 @property 5668 def orig_implies(self): 5669 """ 5670 See the class documentation. 5671 """ 5672 return [(imply, self._strip_dep(cond)) 5673 for imply, cond in self.implies] 5674 5675 @property 5676 def orig_ranges(self): 5677 """ 5678 See the class documentation. 5679 """ 5680 return [(low, high, self._strip_dep(cond)) 5681 for low, high, cond in self.ranges] 5682 5683 @property 5684 def referenced(self): 5685 """ 5686 See the class documentation. 5687 """ 5688 # self.dep is included to catch dependencies from a lone 'depends on' 5689 # when there are no properties to propagate it to 5690 res = expr_items(self.dep) 5691 5692 if self.prompt: 5693 res |= expr_items(self.prompt[1]) 5694 5695 if self.item is MENU: 5696 res |= expr_items(self.visibility) 5697 5698 for value, cond in self.defaults: 5699 res |= expr_items(value) 5700 res |= expr_items(cond) 5701 5702 for value, cond in self.selects: 5703 res.add(value) 5704 res |= expr_items(cond) 5705 5706 for value, cond in self.implies: 5707 res.add(value) 5708 res |= expr_items(cond) 5709 5710 for low, high, cond in self.ranges: 5711 res.add(low) 5712 res.add(high) 5713 res |= expr_items(cond) 5714 5715 return res 5716 5717 def __repr__(self): 5718 """ 5719 Returns a string with information about the menu node when it is 5720 evaluated on e.g. the interactive Python prompt. 5721 """ 5722 fields = [] 5723 add = fields.append 5724 5725 if self.item.__class__ is Symbol: 5726 add("menu node for symbol " + self.item.name) 5727 5728 elif self.item.__class__ is Choice: 5729 s = "menu node for choice" 5730 if self.item.name is not None: 5731 s += " " + self.item.name 5732 add(s) 5733 5734 elif self.item is MENU: 5735 add("menu node for menu") 5736 5737 else: # self.item is COMMENT 5738 add("menu node for comment") 5739 5740 if self.prompt: 5741 add('prompt "{}" (visibility {})'.format( 5742 self.prompt[0], TRI_TO_STR[expr_value(self.prompt[1])])) 5743 5744 if self.item.__class__ is Symbol and self.is_menuconfig: 5745 add("is menuconfig") 5746 5747 add("deps " + TRI_TO_STR[expr_value(self.dep)]) 5748 5749 if self.item is MENU: 5750 add("'visible if' deps " + TRI_TO_STR[expr_value(self.visibility)]) 5751 5752 if self.item.__class__ in _SYMBOL_CHOICE and self.help is not None: 5753 add("has help") 5754 5755 if self.list: 5756 add("has child") 5757 5758 if self.next: 5759 add("has next") 5760 5761 add("{}:{}".format(self.filename, self.linenr)) 5762 5763 return "<{}>".format(", ".join(fields)) 5764 5765 def __str__(self): 5766 """ 5767 Returns a string representation of the menu node. Matches the Kconfig 5768 format, with any parent dependencies propagated to the 'depends on' 5769 condition. 5770 5771 The output could (almost) be fed back into a Kconfig parser to redefine 5772 the object associated with the menu node. See the module documentation 5773 for a gotcha related to choice symbols. 5774 5775 For symbols and choices with multiple menu nodes (multiple definition 5776 locations), properties that aren't associated with a particular menu 5777 node are shown on all menu nodes ('option env=...', 'optional' for 5778 choices, etc.). 5779 5780 The returned string does not end in a newline. 5781 """ 5782 return self.custom_str(standard_sc_expr_str) 5783 5784 def custom_str(self, sc_expr_str_fn): 5785 """ 5786 Works like MenuNode.__str__(), but allows a custom format to be used 5787 for all symbol/choice references. See expr_str(). 5788 """ 5789 return self._menu_comment_node_str(sc_expr_str_fn) \ 5790 if self.item in _MENU_COMMENT else \ 5791 self._sym_choice_node_str(sc_expr_str_fn) 5792 5793 def _menu_comment_node_str(self, sc_expr_str_fn): 5794 s = '{} "{}"'.format("menu" if self.item is MENU else "comment", 5795 self.prompt[0]) 5796 5797 if self.dep is not self.kconfig.y: 5798 s += "\n\tdepends on {}".format(expr_str(self.dep, sc_expr_str_fn)) 5799 5800 if self.item is MENU and self.visibility is not self.kconfig.y: 5801 s += "\n\tvisible if {}".format(expr_str(self.visibility, 5802 sc_expr_str_fn)) 5803 5804 return s 5805 5806 def _sym_choice_node_str(self, sc_expr_str_fn): 5807 def indent_add(s): 5808 lines.append("\t" + s) 5809 5810 def indent_add_cond(s, cond): 5811 if cond is not self.kconfig.y: 5812 s += " if " + expr_str(cond, sc_expr_str_fn) 5813 indent_add(s) 5814 5815 sc = self.item 5816 5817 if sc.__class__ is Symbol: 5818 lines = [("menuconfig " if self.is_menuconfig else "config ") 5819 + sc.name] 5820 else: 5821 lines = ["choice " + sc.name if sc.name else "choice"] 5822 5823 if sc.orig_type and not self.prompt: # sc.orig_type != UNKNOWN 5824 # If there's a prompt, we'll use the '<type> "prompt"' shorthand 5825 # instead 5826 indent_add(TYPE_TO_STR[sc.orig_type]) 5827 5828 if self.prompt: 5829 if sc.orig_type: 5830 prefix = TYPE_TO_STR[sc.orig_type] 5831 else: 5832 # Symbol defined without a type (which generates a warning) 5833 prefix = "prompt" 5834 5835 indent_add_cond(prefix + ' "{}"'.format(escape(self.prompt[0])), 5836 self.orig_prompt[1]) 5837 5838 if sc.__class__ is Symbol: 5839 if sc.is_allnoconfig_y: 5840 indent_add("option allnoconfig_y") 5841 5842 if sc is sc.kconfig.defconfig_list: 5843 indent_add("option defconfig_list") 5844 5845 if sc.env_var is not None: 5846 indent_add('option env="{}"'.format(sc.env_var)) 5847 5848 if sc is sc.kconfig.modules: 5849 indent_add("option modules") 5850 5851 for low, high, cond in self.orig_ranges: 5852 indent_add_cond( 5853 "range {} {}".format(sc_expr_str_fn(low), 5854 sc_expr_str_fn(high)), 5855 cond) 5856 5857 for default, cond in self.orig_defaults: 5858 indent_add_cond("default " + expr_str(default, sc_expr_str_fn), 5859 cond) 5860 5861 if sc.__class__ is Choice and sc.is_optional: 5862 indent_add("optional") 5863 5864 if sc.__class__ is Symbol: 5865 for select, cond in self.orig_selects: 5866 indent_add_cond("select " + sc_expr_str_fn(select), cond) 5867 5868 for imply, cond in self.orig_implies: 5869 indent_add_cond("imply " + sc_expr_str_fn(imply), cond) 5870 5871 if self.dep is not sc.kconfig.y: 5872 indent_add("depends on " + expr_str(self.dep, sc_expr_str_fn)) 5873 5874 if self.help is not None: 5875 indent_add("help") 5876 for line in self.help.splitlines(): 5877 indent_add(" " + line) 5878 5879 return "\n".join(lines) 5880 5881 def _strip_dep(self, expr): 5882 # Helper function for removing MenuNode.dep from 'expr'. Uses two 5883 # pieces of internal knowledge: (1) Expressions are reused rather than 5884 # copied, and (2) the direct dependencies always appear at the end. 5885 5886 # ... if dep -> ... if y 5887 if self.dep is expr: 5888 return self.kconfig.y 5889 5890 # (AND, X, dep) -> X 5891 if expr.__class__ is tuple and expr[0] is AND and expr[2] is self.dep: 5892 return expr[1] 5893 5894 return expr 5895 5896 5897class Variable(object): 5898 """ 5899 Represents a preprocessor variable/function. 5900 5901 The following attributes are available: 5902 5903 name: 5904 The name of the variable. 5905 5906 value: 5907 The unexpanded value of the variable. 5908 5909 expanded_value: 5910 The expanded value of the variable. For simple variables (those defined 5911 with :=), this will equal 'value'. Accessing this property will raise a 5912 KconfigError if the expansion seems to be stuck in a loop. 5913 5914 Accessing this field is the same as calling expanded_value_w_args() with 5915 no arguments. I hadn't considered function arguments when adding it. It 5916 is retained for backwards compatibility though. 5917 5918 is_recursive: 5919 True if the variable is recursive (defined with =). 5920 """ 5921 __slots__ = ( 5922 "_n_expansions", 5923 "is_recursive", 5924 "kconfig", 5925 "name", 5926 "value", 5927 ) 5928 5929 @property 5930 def expanded_value(self): 5931 """ 5932 See the class documentation. 5933 """ 5934 return self.expanded_value_w_args() 5935 5936 def expanded_value_w_args(self, *args): 5937 """ 5938 Returns the expanded value of the variable/function. Any arguments 5939 passed will be substituted for $(1), $(2), etc. 5940 5941 Raises a KconfigError if the expansion seems to be stuck in a loop. 5942 """ 5943 return self.kconfig._fn_val((self.name,) + args) 5944 5945 def __repr__(self): 5946 return "<variable {}, {}, value '{}'>" \ 5947 .format(self.name, 5948 "recursive" if self.is_recursive else "immediate", 5949 self.value) 5950 5951 5952class KconfigError(Exception): 5953 """ 5954 Exception raised for Kconfig-related errors. 5955 5956 KconfigError and KconfigSyntaxError are the same class. The 5957 KconfigSyntaxError alias is only maintained for backwards compatibility. 5958 """ 5959 5960KconfigSyntaxError = KconfigError # Backwards compatibility 5961 5962 5963class InternalError(Exception): 5964 "Never raised. Kept around for backwards compatibility." 5965 5966 5967# Workaround: 5968# 5969# If 'errno' and 'strerror' are set on IOError, then __str__() always returns 5970# "[Errno <errno>] <strerror>", ignoring any custom message passed to the 5971# constructor. By defining our own subclass, we can use a custom message while 5972# also providing 'errno', 'strerror', and 'filename' to scripts. 5973class _KconfigIOError(IOError): 5974 def __init__(self, ioerror, msg): 5975 self.msg = msg 5976 super(_KconfigIOError, self).__init__( 5977 ioerror.errno, ioerror.strerror, ioerror.filename) 5978 5979 def __str__(self): 5980 return self.msg 5981 5982 5983# 5984# Public functions 5985# 5986 5987 5988def expr_value(expr): 5989 """ 5990 Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m), 5991 or 2 (y). 5992 5993 'expr' must be an already-parsed expression from a Symbol, Choice, or 5994 MenuNode property. To evaluate an expression represented as a string, use 5995 Kconfig.eval_string(). 5996 5997 Passing subexpressions of expressions to this function works as expected. 5998 """ 5999 if expr.__class__ is not tuple: 6000 return expr.tri_value 6001 6002 if expr[0] is AND: 6003 v1 = expr_value(expr[1]) 6004 # Short-circuit the n case as an optimization (~5% faster 6005 # allnoconfig.py and allyesconfig.py, as of writing) 6006 return 0 if not v1 else min(v1, expr_value(expr[2])) 6007 6008 if expr[0] is OR: 6009 v1 = expr_value(expr[1]) 6010 # Short-circuit the y case as an optimization 6011 return 2 if v1 == 2 else max(v1, expr_value(expr[2])) 6012 6013 if expr[0] is NOT: 6014 return 2 - expr_value(expr[1]) 6015 6016 # Relation 6017 # 6018 # Implements <, <=, >, >= comparisons as well. These were added to 6019 # kconfig in 31847b67 (kconfig: allow use of relations other than 6020 # (in)equality). 6021 6022 rel, v1, v2 = expr 6023 6024 # If both operands are strings... 6025 if v1.orig_type is STRING and v2.orig_type is STRING: 6026 # ...then compare them lexicographically 6027 comp = _strcmp(v1.str_value, v2.str_value) 6028 else: 6029 # Otherwise, try to compare them as numbers 6030 try: 6031 comp = _sym_to_num(v1) - _sym_to_num(v2) 6032 except ValueError: 6033 # Fall back on a lexicographic comparison if the operands don't 6034 # parse as numbers 6035 comp = _strcmp(v1.str_value, v2.str_value) 6036 6037 return 2*(comp == 0 if rel is EQUAL else 6038 comp != 0 if rel is UNEQUAL else 6039 comp < 0 if rel is LESS else 6040 comp <= 0 if rel is LESS_EQUAL else 6041 comp > 0 if rel is GREATER else 6042 comp >= 0) 6043 6044 6045def standard_sc_expr_str(sc): 6046 """ 6047 Standard symbol/choice printing function. Uses plain Kconfig syntax, and 6048 displays choices as <choice> (or <choice NAME>, for named choices). 6049 6050 See expr_str(). 6051 """ 6052 if sc.__class__ is Symbol: 6053 if sc.is_constant and sc.name not in STR_TO_TRI: 6054 return '"{}"'.format(escape(sc.name)) 6055 return sc.name 6056 6057 return "<choice {}>".format(sc.name) if sc.name else "<choice>" 6058 6059 6060def expr_str(expr, sc_expr_str_fn=standard_sc_expr_str): 6061 """ 6062 Returns the string representation of the expression 'expr', as in a Kconfig 6063 file. 6064 6065 Passing subexpressions of expressions to this function works as expected. 6066 6067 sc_expr_str_fn (default: standard_sc_expr_str): 6068 This function is called for every symbol/choice (hence "sc") appearing in 6069 the expression, with the symbol/choice as the argument. It is expected to 6070 return a string to be used for the symbol/choice. 6071 6072 This can be used e.g. to turn symbols/choices into links when generating 6073 documentation, or for printing the value of each symbol/choice after it. 6074 6075 Note that quoted values are represented as constants symbols 6076 (Symbol.is_constant == True). 6077 """ 6078 if expr.__class__ is not tuple: 6079 return sc_expr_str_fn(expr) 6080 6081 if expr[0] is AND: 6082 return "{} && {}".format(_parenthesize(expr[1], OR, sc_expr_str_fn), 6083 _parenthesize(expr[2], OR, sc_expr_str_fn)) 6084 6085 if expr[0] is OR: 6086 # This turns A && B || C && D into "(A && B) || (C && D)", which is 6087 # redundant, but more readable 6088 return "{} || {}".format(_parenthesize(expr[1], AND, sc_expr_str_fn), 6089 _parenthesize(expr[2], AND, sc_expr_str_fn)) 6090 6091 if expr[0] is NOT: 6092 if expr[1].__class__ is tuple: 6093 return "!({})".format(expr_str(expr[1], sc_expr_str_fn)) 6094 return "!" + sc_expr_str_fn(expr[1]) # Symbol 6095 6096 # Relation 6097 # 6098 # Relation operands are always symbols (quoted strings are constant 6099 # symbols) 6100 return "{} {} {}".format(sc_expr_str_fn(expr[1]), REL_TO_STR[expr[0]], 6101 sc_expr_str_fn(expr[2])) 6102 6103 6104def expr_items(expr): 6105 """ 6106 Returns a set() of all items (symbols and choices) that appear in the 6107 expression 'expr'. 6108 6109 Passing subexpressions of expressions to this function works as expected. 6110 """ 6111 res = set() 6112 6113 def rec(subexpr): 6114 if subexpr.__class__ is tuple: 6115 # AND, OR, NOT, or relation 6116 6117 rec(subexpr[1]) 6118 6119 # NOTs only have a single operand 6120 if subexpr[0] is not NOT: 6121 rec(subexpr[2]) 6122 6123 else: 6124 # Symbol or choice 6125 res.add(subexpr) 6126 6127 rec(expr) 6128 return res 6129 6130 6131def split_expr(expr, op): 6132 """ 6133 Returns a list containing the top-level AND or OR operands in the 6134 expression 'expr', in the same (left-to-right) order as they appear in 6135 the expression. 6136 6137 This can be handy e.g. for splitting (weak) reverse dependencies 6138 from 'select' and 'imply' into individual selects/implies. 6139 6140 op: 6141 Either AND to get AND operands, or OR to get OR operands. 6142 6143 (Having this as an operand might be more future-safe than having two 6144 hardcoded functions.) 6145 6146 6147 Pseudo-code examples: 6148 6149 split_expr( A , OR ) -> [A] 6150 split_expr( A && B , OR ) -> [A && B] 6151 split_expr( A || B , OR ) -> [A, B] 6152 split_expr( A || B , AND ) -> [A || B] 6153 split_expr( A || B || (C && D) , OR ) -> [A, B, C && D] 6154 6155 # Second || is not at the top level 6156 split_expr( A || (B && (C || D)) , OR ) -> [A, B && (C || D)] 6157 6158 # Parentheses don't matter as long as we stay at the top level (don't 6159 # encounter any non-'op' nodes) 6160 split_expr( (A || B) || C , OR ) -> [A, B, C] 6161 split_expr( A || (B || C) , OR ) -> [A, B, C] 6162 """ 6163 res = [] 6164 6165 def rec(subexpr): 6166 if subexpr.__class__ is tuple and subexpr[0] is op: 6167 rec(subexpr[1]) 6168 rec(subexpr[2]) 6169 else: 6170 res.append(subexpr) 6171 6172 rec(expr) 6173 return res 6174 6175 6176def escape(s): 6177 r""" 6178 Escapes the string 's' in the same fashion as is done for display in 6179 Kconfig format and when writing strings to a .config file. " and \ are 6180 replaced by \" and \\, respectively. 6181 """ 6182 # \ must be escaped before " to avoid double escaping 6183 return s.replace("\\", r"\\").replace('"', r'\"') 6184 6185 6186def unescape(s): 6187 r""" 6188 Unescapes the string 's'. \ followed by any character is replaced with just 6189 that character. Used internally when reading .config files. 6190 """ 6191 return _unescape_sub(r"\1", s) 6192 6193# unescape() helper 6194_unescape_sub = re.compile(r"\\(.)").sub 6195 6196 6197def standard_kconfig(description=None): 6198 """ 6199 Argument parsing helper for tools that take a single optional Kconfig file 6200 argument (default: Kconfig). Returns the Kconfig instance for the parsed 6201 configuration. Uses argparse internally. 6202 6203 Exits with sys.exit() (which raises SystemExit) on errors. 6204 6205 description (default: None): 6206 The 'description' passed to argparse.ArgumentParser(). 6207 argparse.RawDescriptionHelpFormatter is used, so formatting is preserved. 6208 """ 6209 import argparse 6210 6211 parser = argparse.ArgumentParser( 6212 formatter_class=argparse.RawDescriptionHelpFormatter, 6213 description=description) 6214 6215 parser.add_argument( 6216 "kconfig", 6217 metavar="KCONFIG", 6218 default="Kconfig", 6219 nargs="?", 6220 help="Top-level Kconfig file (default: Kconfig)") 6221 6222 return Kconfig(parser.parse_args().kconfig, suppress_traceback=True) 6223 6224 6225def standard_config_filename(): 6226 """ 6227 Helper for tools. Returns the value of KCONFIG_CONFIG (which specifies the 6228 .config file to load/save) if it is set, and ".config" otherwise. 6229 6230 Calling load_config() with filename=None might give the behavior you want, 6231 without having to use this function. 6232 """ 6233 return os.getenv("KCONFIG_CONFIG", ".config") 6234 6235 6236def load_allconfig(kconf, filename): 6237 """ 6238 Use Kconfig.load_allconfig() instead, which was added in Kconfiglib 13.4.0. 6239 Supported for backwards compatibility. Might be removed at some point after 6240 a long period of deprecation warnings. 6241 """ 6242 allconfig = os.getenv("KCONFIG_ALLCONFIG") 6243 if allconfig is None: 6244 return 6245 6246 def std_msg(e): 6247 # "Upcasts" a _KconfigIOError to an IOError, removing the custom 6248 # __str__() message. The standard message is better here. 6249 # 6250 # This might also convert an OSError to an IOError in obscure cases, 6251 # but it's probably not a big deal. The distinction is shaky (see 6252 # PEP-3151). 6253 return IOError(e.errno, e.strerror, e.filename) 6254 6255 old_warn_assign_override = kconf.warn_assign_override 6256 old_warn_assign_redun = kconf.warn_assign_redun 6257 kconf.warn_assign_override = kconf.warn_assign_redun = False 6258 6259 if allconfig in ("", "1"): 6260 try: 6261 print(kconf.load_config(filename, False)) 6262 except EnvironmentError as e1: 6263 try: 6264 print(kconf.load_config("all.config", False)) 6265 except EnvironmentError as e2: 6266 sys.exit("error: KCONFIG_ALLCONFIG is set, but neither {} " 6267 "nor all.config could be opened: {}, {}" 6268 .format(filename, std_msg(e1), std_msg(e2))) 6269 else: 6270 try: 6271 print(kconf.load_config(allconfig, False)) 6272 except EnvironmentError as e: 6273 sys.exit("error: KCONFIG_ALLCONFIG is set to '{}', which " 6274 "could not be opened: {}" 6275 .format(allconfig, std_msg(e))) 6276 6277 kconf.warn_assign_override = old_warn_assign_override 6278 kconf.warn_assign_redun = old_warn_assign_redun 6279 6280 6281# 6282# Internal functions 6283# 6284 6285 6286def _visibility(sc): 6287 # Symbols and Choices have a "visibility" that acts as an upper bound on 6288 # the values a user can set for them, corresponding to the visibility in 6289 # e.g. 'make menuconfig'. This function calculates the visibility for the 6290 # Symbol or Choice 'sc' -- the logic is nearly identical. 6291 6292 vis = 0 6293 6294 for node in sc.nodes: 6295 if node.prompt: 6296 vis = max(vis, expr_value(node.prompt[1])) 6297 6298 if sc.__class__ is Symbol and sc.choice: 6299 if sc.choice.orig_type is TRISTATE and \ 6300 sc.orig_type is not TRISTATE and sc.choice.tri_value != 2: 6301 # Non-tristate choice symbols are only visible in y mode 6302 return 0 6303 6304 if sc.orig_type is TRISTATE and vis == 1 and sc.choice.tri_value == 2: 6305 # Choice symbols with m visibility are not visible in y mode 6306 return 0 6307 6308 # Promote m to y if we're dealing with a non-tristate (possibly due to 6309 # modules being disabled) 6310 if vis == 1 and sc.type is not TRISTATE: 6311 return 2 6312 6313 return vis 6314 6315 6316def _depend_on(sc, expr): 6317 # Adds 'sc' (symbol or choice) as a "dependee" to all symbols in 'expr'. 6318 # Constant symbols in 'expr' are skipped as they can never change value 6319 # anyway. 6320 6321 if expr.__class__ is tuple: 6322 # AND, OR, NOT, or relation 6323 6324 _depend_on(sc, expr[1]) 6325 6326 # NOTs only have a single operand 6327 if expr[0] is not NOT: 6328 _depend_on(sc, expr[2]) 6329 6330 elif not expr.is_constant: 6331 # Non-constant symbol, or choice 6332 expr._dependents.add(sc) 6333 6334 6335def _parenthesize(expr, type_, sc_expr_str_fn): 6336 # expr_str() helper. Adds parentheses around expressions of type 'type_'. 6337 6338 if expr.__class__ is tuple and expr[0] is type_: 6339 return "({})".format(expr_str(expr, sc_expr_str_fn)) 6340 return expr_str(expr, sc_expr_str_fn) 6341 6342 6343def _ordered_unique(lst): 6344 # Returns 'lst' with any duplicates removed, preserving order. This hacky 6345 # version seems to be a common idiom. It relies on short-circuit evaluation 6346 # and set.add() returning None, which is falsy. 6347 6348 seen = set() 6349 seen_add = seen.add 6350 return [x for x in lst if x not in seen and not seen_add(x)] 6351 6352 6353def _is_base_n(s, n): 6354 try: 6355 int(s, n) 6356 return True 6357 except ValueError: 6358 return False 6359 6360 6361def _strcmp(s1, s2): 6362 # strcmp()-alike that returns -1, 0, or 1 6363 6364 return (s1 > s2) - (s1 < s2) 6365 6366 6367def _sym_to_num(sym): 6368 # expr_value() helper for converting a symbol to a number. Raises 6369 # ValueError for symbols that can't be converted. 6370 6371 # For BOOL and TRISTATE, n/m/y count as 0/1/2. This mirrors 9059a3493ef 6372 # ("kconfig: fix relational operators for bool and tristate symbols") in 6373 # the C implementation. 6374 return sym.tri_value if sym.orig_type in _BOOL_TRISTATE else \ 6375 int(sym.str_value, _TYPE_TO_BASE[sym.orig_type]) 6376 6377 6378def _touch_dep_file(path, sym_name): 6379 # If sym_name is MY_SYM_NAME, touches my/sym/name.h. See the sync_deps() 6380 # docstring. 6381 6382 sym_path = path + os.sep + sym_name.lower().replace("_", os.sep) + ".h" 6383 sym_path_dir = dirname(sym_path) 6384 if not exists(sym_path_dir): 6385 os.makedirs(sym_path_dir, 0o755) 6386 6387 # A kind of truncating touch, mirroring the C tools 6388 os.close(os.open( 6389 sym_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)) 6390 6391 6392def _save_old(path): 6393 # See write_config() 6394 6395 def copy(src, dst): 6396 # Import as needed, to save some startup time 6397 import shutil 6398 shutil.copyfile(src, dst) 6399 6400 if islink(path): 6401 # Preserve symlinks 6402 copy_fn = copy 6403 elif hasattr(os, "replace"): 6404 # Python 3 (3.3+) only. Best choice when available, because it 6405 # removes <filename>.old on both *nix and Windows. 6406 copy_fn = os.replace 6407 elif os.name == "posix": 6408 # Removes <filename>.old on POSIX systems 6409 copy_fn = os.rename 6410 else: 6411 # Fall back on copying 6412 copy_fn = copy 6413 6414 try: 6415 copy_fn(path, path + ".old") 6416 except Exception: 6417 # Ignore errors from 'path' missing as well as other errors. 6418 # <filename>.old file is usually more of a nice-to-have, and not worth 6419 # erroring out over e.g. if <filename>.old happens to be a directory or 6420 # <filename> is something like /dev/null. 6421 pass 6422 6423 6424def _locs(sc): 6425 # Symbol/Choice.name_and_loc helper. Returns the "(defined at ...)" part of 6426 # the string. 'sc' is a Symbol or Choice. 6427 6428 if sc.nodes: 6429 return "(defined at {})".format( 6430 ", ".join("{0.filename}:{0.linenr}".format(node) 6431 for node in sc.nodes)) 6432 6433 return "(undefined)" 6434 6435 6436# Menu manipulation 6437 6438 6439def _expr_depends_on(expr, sym): 6440 # Reimplementation of expr_depends_symbol() from mconf.c. Used to determine 6441 # if a submenu should be implicitly created. This also influences which 6442 # items inside choice statements are considered choice items. 6443 6444 if expr.__class__ is not tuple: 6445 return expr is sym 6446 6447 if expr[0] in _EQUAL_UNEQUAL: 6448 # Check for one of the following: 6449 # sym = m/y, m/y = sym, sym != n, n != sym 6450 6451 left, right = expr[1:] 6452 6453 if right is sym: 6454 left, right = right, left 6455 elif left is not sym: 6456 return False 6457 6458 return (expr[0] is EQUAL and right is sym.kconfig.m or 6459 right is sym.kconfig.y) or \ 6460 (expr[0] is UNEQUAL and right is sym.kconfig.n) 6461 6462 return expr[0] is AND and \ 6463 (_expr_depends_on(expr[1], sym) or 6464 _expr_depends_on(expr[2], sym)) 6465 6466 6467def _auto_menu_dep(node1, node2): 6468 # Returns True if node2 has an "automatic menu dependency" on node1. If 6469 # node2 has a prompt, we check its condition. Otherwise, we look directly 6470 # at node2.dep. 6471 6472 return _expr_depends_on(node2.prompt[1] if node2.prompt else node2.dep, 6473 node1.item) 6474 6475 6476def _flatten(node): 6477 # "Flattens" menu nodes without prompts (e.g. 'if' nodes and non-visible 6478 # symbols with children from automatic menu creation) so that their 6479 # children appear after them instead. This gives a clean menu structure 6480 # with no unexpected "jumps" in the indentation. 6481 # 6482 # Do not flatten promptless choices (which can appear "legitimately" if a 6483 # named choice is defined in multiple locations to add on symbols). It 6484 # looks confusing, and the menuconfig already shows all choice symbols if 6485 # you enter the choice at some location with a prompt. 6486 6487 while node: 6488 if node.list and not node.prompt and \ 6489 node.item.__class__ is not Choice: 6490 6491 last_node = node.list 6492 while 1: 6493 last_node.parent = node.parent 6494 if not last_node.next: 6495 break 6496 last_node = last_node.next 6497 6498 last_node.next = node.next 6499 node.next = node.list 6500 node.list = None 6501 6502 node = node.next 6503 6504 6505def _remove_ifs(node): 6506 # Removes 'if' nodes (which can be recognized by MenuNode.item being None), 6507 # which are assumed to already have been flattened. The C implementation 6508 # doesn't bother to do this, but we expose the menu tree directly, and it 6509 # makes it nicer to work with. 6510 6511 cur = node.list 6512 while cur and not cur.item: 6513 cur = cur.next 6514 6515 node.list = cur 6516 6517 while cur: 6518 next = cur.next 6519 while next and not next.item: 6520 next = next.next 6521 6522 # Equivalent to 6523 # 6524 # cur.next = next 6525 # cur = next 6526 # 6527 # due to tricky Python semantics. The order matters. 6528 cur.next = cur = next 6529 6530 6531def _finalize_choice(node): 6532 # Finalizes a choice, marking each symbol whose menu node has the choice as 6533 # the parent as a choice symbol, and automatically determining types if not 6534 # specified. 6535 6536 choice = node.item 6537 6538 cur = node.list 6539 while cur: 6540 if cur.item.__class__ is Symbol: 6541 cur.item.choice = choice 6542 choice.syms.append(cur.item) 6543 cur = cur.next 6544 6545 # If no type is specified for the choice, its type is that of 6546 # the first choice item with a specified type 6547 if not choice.orig_type: 6548 for item in choice.syms: 6549 if item.orig_type: 6550 choice.orig_type = item.orig_type 6551 break 6552 6553 # Each choice item of UNKNOWN type gets the type of the choice 6554 for sym in choice.syms: 6555 if not sym.orig_type: 6556 sym.orig_type = choice.orig_type 6557 6558 6559def _check_dep_loop_sym(sym, ignore_choice): 6560 # Detects dependency loops using depth-first search on the dependency graph 6561 # (which is calculated earlier in Kconfig._build_dep()). 6562 # 6563 # Algorithm: 6564 # 6565 # 1. Symbols/choices start out with _visited = 0, meaning unvisited. 6566 # 6567 # 2. When a symbol/choice is first visited, _visited is set to 1, meaning 6568 # "visited, potentially part of a dependency loop". The recursive 6569 # search then continues from the symbol/choice. 6570 # 6571 # 3. If we run into a symbol/choice X with _visited already set to 1, 6572 # there's a dependency loop. The loop is found on the call stack by 6573 # recording symbols while returning ("on the way back") until X is seen 6574 # again. 6575 # 6576 # 4. Once a symbol/choice and all its dependencies (or dependents in this 6577 # case) have been checked recursively without detecting any loops, its 6578 # _visited is set to 2, meaning "visited, not part of a dependency 6579 # loop". 6580 # 6581 # This saves work if we run into the symbol/choice again in later calls 6582 # to _check_dep_loop_sym(). We just return immediately. 6583 # 6584 # Choices complicate things, as every choice symbol depends on every other 6585 # choice symbol in a sense. When a choice is "entered" via a choice symbol 6586 # X, we visit all choice symbols from the choice except X, and prevent 6587 # immediately revisiting the choice with a flag (ignore_choice). 6588 # 6589 # Maybe there's a better way to handle this (different flags or the 6590 # like...) 6591 6592 if not sym._visited: 6593 # sym._visited == 0, unvisited 6594 6595 sym._visited = 1 6596 6597 for dep in sym._dependents: 6598 # Choices show up in Symbol._dependents when the choice has the 6599 # symbol in a 'prompt' or 'default' condition (e.g. 6600 # 'default ... if SYM'). 6601 # 6602 # Since we aren't entering the choice via a choice symbol, all 6603 # choice symbols need to be checked, hence the None. 6604 loop = _check_dep_loop_choice(dep, None) \ 6605 if dep.__class__ is Choice \ 6606 else _check_dep_loop_sym(dep, False) 6607 6608 if loop: 6609 # Dependency loop found 6610 return _found_dep_loop(loop, sym) 6611 6612 if sym.choice and not ignore_choice: 6613 loop = _check_dep_loop_choice(sym.choice, sym) 6614 if loop: 6615 # Dependency loop found 6616 return _found_dep_loop(loop, sym) 6617 6618 # The symbol is not part of a dependency loop 6619 sym._visited = 2 6620 6621 # No dependency loop found 6622 return None 6623 6624 if sym._visited == 2: 6625 # The symbol was checked earlier and is already known to not be part of 6626 # a dependency loop 6627 return None 6628 6629 # sym._visited == 1, found a dependency loop. Return the symbol as the 6630 # first element in it. 6631 return (sym,) 6632 6633 6634def _check_dep_loop_choice(choice, skip): 6635 if not choice._visited: 6636 # choice._visited == 0, unvisited 6637 6638 choice._visited = 1 6639 6640 # Check for loops involving choice symbols. If we came here via a 6641 # choice symbol, skip that one, as we'd get a false positive 6642 # '<sym FOO> -> <choice> -> <sym FOO>' loop otherwise. 6643 for sym in choice.syms: 6644 if sym is not skip: 6645 # Prevent the choice from being immediately re-entered via the 6646 # "is a choice symbol" path by passing True 6647 loop = _check_dep_loop_sym(sym, True) 6648 if loop: 6649 # Dependency loop found 6650 return _found_dep_loop(loop, choice) 6651 6652 # The choice is not part of a dependency loop 6653 choice._visited = 2 6654 6655 # No dependency loop found 6656 return None 6657 6658 if choice._visited == 2: 6659 # The choice was checked earlier and is already known to not be part of 6660 # a dependency loop 6661 return None 6662 6663 # choice._visited == 1, found a dependency loop. Return the choice as the 6664 # first element in it. 6665 return (choice,) 6666 6667 6668def _found_dep_loop(loop, cur): 6669 # Called "on the way back" when we know we have a loop 6670 6671 # Is the symbol/choice 'cur' where the loop started? 6672 if cur is not loop[0]: 6673 # Nope, it's just a part of the loop 6674 return loop + (cur,) 6675 6676 # Yep, we have the entire loop. Throw an exception that shows it. 6677 6678 msg = "\nDependency loop\n" \ 6679 "===============\n\n" 6680 6681 for item in loop: 6682 if item is not loop[0]: 6683 msg += "...depends on " 6684 if item.__class__ is Symbol and item.choice: 6685 msg += "the choice symbol " 6686 6687 msg += "{}, with definition...\n\n{}\n\n" \ 6688 .format(item.name_and_loc, item) 6689 6690 # Small wart: Since we reuse the already calculated 6691 # Symbol/Choice._dependents sets for recursive dependency detection, we 6692 # lose information on whether a dependency came from a 'select'/'imply' 6693 # condition or e.g. a 'depends on'. 6694 # 6695 # This might cause selecting symbols to "disappear". For example, 6696 # a symbol B having 'select A if C' gives a direct dependency from A to 6697 # C, since it corresponds to a reverse dependency of B && C. 6698 # 6699 # Always print reverse dependencies for symbols that have them to make 6700 # sure information isn't lost. I wonder if there's some neat way to 6701 # improve this. 6702 6703 if item.__class__ is Symbol: 6704 if item.rev_dep is not item.kconfig.n: 6705 msg += "(select-related dependencies: {})\n\n" \ 6706 .format(expr_str(item.rev_dep)) 6707 6708 if item.weak_rev_dep is not item.kconfig.n: 6709 msg += "(imply-related dependencies: {})\n\n" \ 6710 .format(expr_str(item.rev_dep)) 6711 6712 msg += "...depends again on " + loop[0].name_and_loc 6713 6714 raise KconfigError(msg) 6715 6716 6717def _decoding_error(e, filename, macro_linenr=None): 6718 # Gives the filename and context for UnicodeDecodeError's, which are a pain 6719 # to debug otherwise. 'e' is the UnicodeDecodeError object. 6720 # 6721 # If the decoding error is for the output of a $(shell,...) command, 6722 # macro_linenr holds the line number where it was run (the exact line 6723 # number isn't available for decoding errors in files). 6724 6725 raise KconfigError( 6726 "\n" 6727 "Malformed {} in {}\n" 6728 "Context: {}\n" 6729 "Problematic data: {}\n" 6730 "Reason: {}".format( 6731 e.encoding, 6732 "'{}'".format(filename) if macro_linenr is None else 6733 "output from macro at {}:{}".format(filename, macro_linenr), 6734 e.object[max(e.start - 40, 0):e.end + 40], 6735 e.object[e.start:e.end], 6736 e.reason)) 6737 6738 6739def _warn_verbose_deprecated(fn_name): 6740 sys.stderr.write( 6741 "Deprecation warning: {0}()'s 'verbose' argument has no effect. Since " 6742 "Kconfiglib 12.0.0, the message is returned from {0}() instead, " 6743 "and is always generated. Do e.g. print(kconf.{0}()) if you want to " 6744 "want to show a message like \"Loaded configuration '.config'\" on " 6745 "stdout. The old API required ugly hacks to reuse messages in " 6746 "configuration interfaces.\n".format(fn_name)) 6747 6748 6749# Predefined preprocessor functions 6750 6751 6752def _filename_fn(kconf, _): 6753 return kconf.filename 6754 6755 6756def _lineno_fn(kconf, _): 6757 return str(kconf.linenr) 6758 6759 6760def _info_fn(kconf, _, msg): 6761 print("{}:{}: {}".format(kconf.filename, kconf.linenr, msg)) 6762 6763 return "" 6764 6765 6766def _warning_if_fn(kconf, _, cond, msg): 6767 if cond == "y": 6768 kconf._warn(msg, kconf.filename, kconf.linenr) 6769 6770 return "" 6771 6772 6773def _error_if_fn(kconf, _, cond, msg): 6774 if cond == "y": 6775 raise KconfigError("{}:{}: {}".format( 6776 kconf.filename, kconf.linenr, msg)) 6777 6778 return "" 6779 6780 6781def _shell_fn(kconf, _, command): 6782 import subprocess # Only import as needed, to save some startup time 6783 6784 stdout, stderr = subprocess.Popen( 6785 command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE 6786 ).communicate() 6787 6788 if not _IS_PY2: 6789 try: 6790 stdout = stdout.decode(kconf._encoding) 6791 stderr = stderr.decode(kconf._encoding) 6792 except UnicodeDecodeError as e: 6793 _decoding_error(e, kconf.filename, kconf.linenr) 6794 6795 if stderr: 6796 kconf._warn("'{}' wrote to stderr: {}".format( 6797 command, "\n".join(stderr.splitlines())), 6798 kconf.filename, kconf.linenr) 6799 6800 # Universal newlines with splitlines() (to prevent e.g. stray \r's in 6801 # command output on Windows), trailing newline removal, and 6802 # newline-to-space conversion. 6803 # 6804 # On Python 3 versions before 3.6, it's not possible to specify the 6805 # encoding when passing universal_newlines=True to Popen() (the 'encoding' 6806 # parameter was added in 3.6), so we do this manual version instead. 6807 return "\n".join(stdout.splitlines()).rstrip("\n").replace("\n", " ") 6808 6809# 6810# Global constants 6811# 6812 6813TRI_TO_STR = { 6814 0: "n", 6815 1: "m", 6816 2: "y", 6817} 6818 6819STR_TO_TRI = { 6820 "n": 0, 6821 "m": 1, 6822 "y": 2, 6823} 6824 6825# Constant representing that there's no cached choice selection. This is 6826# distinct from a cached None (no selection). Any object that's not None or a 6827# Symbol will do. We test this with 'is'. 6828_NO_CACHED_SELECTION = 0 6829 6830# Are we running on Python 2? 6831_IS_PY2 = sys.version_info[0] < 3 6832 6833try: 6834 _UNAME_RELEASE = os.uname()[2] 6835except AttributeError: 6836 # Only import as needed, to save some startup time 6837 import platform 6838 _UNAME_RELEASE = platform.uname()[2] 6839 6840# The token and type constants below are safe to test with 'is', which is a bit 6841# faster (~30% faster on my machine, and a few % faster for total parsing 6842# time), even without assuming Python's small integer optimization (which 6843# caches small integer objects). The constants end up pointing to unique 6844# integer objects, and since we consistently refer to them via the names below, 6845# we always get the same object. 6846# 6847# Client code should use == though. 6848 6849# Tokens, with values 1, 2, ... . Avoiding 0 simplifies some checks by making 6850# all tokens except empty strings truthy. 6851( 6852 _T_ALLNOCONFIG_Y, 6853 _T_AND, 6854 _T_BOOL, 6855 _T_CHOICE, 6856 _T_CLOSE_PAREN, 6857 _T_COMMENT, 6858 _T_CONFIG, 6859 _T_DEFAULT, 6860 _T_DEFCONFIG_LIST, 6861 _T_DEF_BOOL, 6862 _T_DEF_HEX, 6863 _T_DEF_INT, 6864 _T_DEF_STRING, 6865 _T_DEF_TRISTATE, 6866 _T_DEPENDS, 6867 _T_ENDCHOICE, 6868 _T_ENDIF, 6869 _T_ENDMENU, 6870 _T_ENV, 6871 _T_EQUAL, 6872 _T_GREATER, 6873 _T_GREATER_EQUAL, 6874 _T_HELP, 6875 _T_HEX, 6876 _T_IF, 6877 _T_IMPLY, 6878 _T_INT, 6879 _T_LESS, 6880 _T_LESS_EQUAL, 6881 _T_MAINMENU, 6882 _T_MENU, 6883 _T_MENUCONFIG, 6884 _T_MODULES, 6885 _T_NOT, 6886 _T_ON, 6887 _T_OPEN_PAREN, 6888 _T_OPTION, 6889 _T_OPTIONAL, 6890 _T_OR, 6891 _T_ORSOURCE, 6892 _T_OSOURCE, 6893 _T_PROMPT, 6894 _T_RANGE, 6895 _T_RSOURCE, 6896 _T_SELECT, 6897 _T_SOURCE, 6898 _T_STRING, 6899 _T_TRISTATE, 6900 _T_UNEQUAL, 6901 _T_VISIBLE, 6902) = range(1, 51) 6903 6904# Keyword to token map, with the get() method assigned directly as a small 6905# optimization 6906_get_keyword = { 6907 "---help---": _T_HELP, 6908 "allnoconfig_y": _T_ALLNOCONFIG_Y, 6909 "bool": _T_BOOL, 6910 "boolean": _T_BOOL, 6911 "choice": _T_CHOICE, 6912 "comment": _T_COMMENT, 6913 "config": _T_CONFIG, 6914 "def_bool": _T_DEF_BOOL, 6915 "def_hex": _T_DEF_HEX, 6916 "def_int": _T_DEF_INT, 6917 "def_string": _T_DEF_STRING, 6918 "def_tristate": _T_DEF_TRISTATE, 6919 "default": _T_DEFAULT, 6920 "defconfig_list": _T_DEFCONFIG_LIST, 6921 "depends": _T_DEPENDS, 6922 "endchoice": _T_ENDCHOICE, 6923 "endif": _T_ENDIF, 6924 "endmenu": _T_ENDMENU, 6925 "env": _T_ENV, 6926 "grsource": _T_ORSOURCE, # Backwards compatibility 6927 "gsource": _T_OSOURCE, # Backwards compatibility 6928 "help": _T_HELP, 6929 "hex": _T_HEX, 6930 "if": _T_IF, 6931 "imply": _T_IMPLY, 6932 "int": _T_INT, 6933 "mainmenu": _T_MAINMENU, 6934 "menu": _T_MENU, 6935 "menuconfig": _T_MENUCONFIG, 6936 "modules": _T_MODULES, 6937 "on": _T_ON, 6938 "option": _T_OPTION, 6939 "optional": _T_OPTIONAL, 6940 "orsource": _T_ORSOURCE, 6941 "osource": _T_OSOURCE, 6942 "prompt": _T_PROMPT, 6943 "range": _T_RANGE, 6944 "rsource": _T_RSOURCE, 6945 "select": _T_SELECT, 6946 "source": _T_SOURCE, 6947 "string": _T_STRING, 6948 "tristate": _T_TRISTATE, 6949 "visible": _T_VISIBLE, 6950}.get 6951 6952# The constants below match the value of the corresponding tokens to remove the 6953# need for conversion 6954 6955# Node types 6956MENU = _T_MENU 6957COMMENT = _T_COMMENT 6958 6959# Expression types 6960AND = _T_AND 6961OR = _T_OR 6962NOT = _T_NOT 6963EQUAL = _T_EQUAL 6964UNEQUAL = _T_UNEQUAL 6965LESS = _T_LESS 6966LESS_EQUAL = _T_LESS_EQUAL 6967GREATER = _T_GREATER 6968GREATER_EQUAL = _T_GREATER_EQUAL 6969 6970REL_TO_STR = { 6971 EQUAL: "=", 6972 UNEQUAL: "!=", 6973 LESS: "<", 6974 LESS_EQUAL: "<=", 6975 GREATER: ">", 6976 GREATER_EQUAL: ">=", 6977} 6978 6979# Symbol/choice types. UNKNOWN is 0 (falsy) to simplify some checks. 6980# Client code shouldn't rely on it though, as it was non-zero in 6981# older versions. 6982UNKNOWN = 0 6983BOOL = _T_BOOL 6984TRISTATE = _T_TRISTATE 6985STRING = _T_STRING 6986INT = _T_INT 6987HEX = _T_HEX 6988 6989TYPE_TO_STR = { 6990 UNKNOWN: "unknown", 6991 BOOL: "bool", 6992 TRISTATE: "tristate", 6993 STRING: "string", 6994 INT: "int", 6995 HEX: "hex", 6996} 6997 6998# Used in comparisons. 0 means the base is inferred from the format of the 6999# string. 7000_TYPE_TO_BASE = { 7001 HEX: 16, 7002 INT: 10, 7003 STRING: 0, 7004 UNKNOWN: 0, 7005} 7006 7007# def_bool -> BOOL, etc. 7008_DEF_TOKEN_TO_TYPE = { 7009 _T_DEF_BOOL: BOOL, 7010 _T_DEF_HEX: HEX, 7011 _T_DEF_INT: INT, 7012 _T_DEF_STRING: STRING, 7013 _T_DEF_TRISTATE: TRISTATE, 7014} 7015 7016# Tokens after which strings are expected. This is used to tell strings from 7017# constant symbol references during tokenization, both of which are enclosed in 7018# quotes. 7019# 7020# Identifier-like lexemes ("missing quotes") are also treated as strings after 7021# these tokens. _T_CHOICE is included to avoid symbols being registered for 7022# named choices. 7023_STRING_LEX = frozenset({ 7024 _T_BOOL, 7025 _T_CHOICE, 7026 _T_COMMENT, 7027 _T_HEX, 7028 _T_INT, 7029 _T_MAINMENU, 7030 _T_MENU, 7031 _T_ORSOURCE, 7032 _T_OSOURCE, 7033 _T_PROMPT, 7034 _T_RSOURCE, 7035 _T_SOURCE, 7036 _T_STRING, 7037 _T_TRISTATE, 7038}) 7039 7040# Various sets for quick membership tests. Gives a single global lookup and 7041# avoids creating temporary dicts/tuples. 7042 7043_TYPE_TOKENS = frozenset({ 7044 _T_BOOL, 7045 _T_TRISTATE, 7046 _T_INT, 7047 _T_HEX, 7048 _T_STRING, 7049}) 7050 7051_SOURCE_TOKENS = frozenset({ 7052 _T_SOURCE, 7053 _T_RSOURCE, 7054 _T_OSOURCE, 7055 _T_ORSOURCE, 7056}) 7057 7058_REL_SOURCE_TOKENS = frozenset({ 7059 _T_RSOURCE, 7060 _T_ORSOURCE, 7061}) 7062 7063# Obligatory (non-optional) sources 7064_OBL_SOURCE_TOKENS = frozenset({ 7065 _T_SOURCE, 7066 _T_RSOURCE, 7067}) 7068 7069_BOOL_TRISTATE = frozenset({ 7070 BOOL, 7071 TRISTATE, 7072}) 7073 7074_BOOL_TRISTATE_UNKNOWN = frozenset({ 7075 BOOL, 7076 TRISTATE, 7077 UNKNOWN, 7078}) 7079 7080_INT_HEX = frozenset({ 7081 INT, 7082 HEX, 7083}) 7084 7085_SYMBOL_CHOICE = frozenset({ 7086 Symbol, 7087 Choice, 7088}) 7089 7090_MENU_COMMENT = frozenset({ 7091 MENU, 7092 COMMENT, 7093}) 7094 7095_EQUAL_UNEQUAL = frozenset({ 7096 EQUAL, 7097 UNEQUAL, 7098}) 7099 7100_RELATIONS = frozenset({ 7101 EQUAL, 7102 UNEQUAL, 7103 LESS, 7104 LESS_EQUAL, 7105 GREATER, 7106 GREATER_EQUAL, 7107}) 7108 7109# Helper functions for getting compiled regular expressions, with the needed 7110# matching function returned directly as a small optimization. 7111# 7112# Use ASCII regex matching on Python 3. It's already the default on Python 2. 7113 7114 7115def _re_match(regex): 7116 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).match 7117 7118 7119def _re_search(regex): 7120 return re.compile(regex, 0 if _IS_PY2 else re.ASCII).search 7121 7122 7123# Various regular expressions used during parsing 7124 7125# The initial token on a line. Also eats leading and trailing whitespace, so 7126# that we can jump straight to the next token (or to the end of the line if 7127# there is only one token). 7128# 7129# This regex will also fail to match for empty lines and comment lines. 7130# 7131# '$' is included to detect preprocessor variable assignments with macro 7132# expansions in the left-hand side. 7133_command_match = _re_match(r"\s*([A-Za-z0-9_$-]+)\s*") 7134 7135# An identifier/keyword after the first token. Also eats trailing whitespace. 7136# '$' is included to detect identifiers containing macro expansions. 7137_id_keyword_match = _re_match(r"([A-Za-z0-9_$/.-]+)\s*") 7138 7139# A fragment in the left-hand side of a preprocessor variable assignment. These 7140# are the portions between macro expansions ($(foo)). Macros are supported in 7141# the LHS (variable name). 7142_assignment_lhs_fragment_match = _re_match("[A-Za-z0-9_-]*") 7143 7144# The assignment operator and value (right-hand side) in a preprocessor 7145# variable assignment 7146_assignment_rhs_match = _re_match(r"\s*(=|:=|\+=)\s*(.*)") 7147 7148# Special characters/strings while expanding a macro ('(', ')', ',', and '$(') 7149_macro_special_search = _re_search(r"\(|\)|,|\$\(") 7150 7151# Special characters/strings while expanding a string (quotes, '\', and '$(') 7152_string_special_search = _re_search(r'"|\'|\\|\$\(') 7153 7154# Special characters/strings while expanding a symbol name. Also includes 7155# end-of-line, in case the macro is the last thing on the line. 7156_name_special_search = _re_search(r'[^A-Za-z0-9_$/.-]|\$\(|$') 7157 7158# A valid right-hand side for an assignment to a string symbol in a .config 7159# file, including escaped characters. Extracts the contents. 7160_conf_string_match = _re_match(r'"((?:[^\\"]|\\.)*)"') 7161
