[LinuxBIOS] New config language

Sat Oct 29 23:29:05 CEST 2005

It has come to the awareness of many (apparently *after* I did my talk
at the summit) that the mini-config-language is quite useful and indeed
necessary unless we want a bunch of really ugly, duplicated makefile
code scattered through our codebase, and (most) people have come to the
realization that they don't want to handwrite static C initialization
structures unnecessarily.

So, by request, I've modified the old pseudo-BNF for the config language
and appended it to this message with the (initial) changes to include in
the "new" language.
This is by no means complete nor formal (yet hopefully it is relatively
accurate ;).
Most of the language description matches what we currently have, but
I've also added many of the changes I deem necessary (mostly from common
sense).  There are a few notes and suggestions on which I'd like some
feedback.  Feel free to rant or rave on anything and furthermore share
your ideas.

Said changes are mostly small and include, but are not limited to:

- Removing unnecessary "end" statements to commands that needn't be
blocks (like 'arch')
- Combined the function of 'define' (as found in src/config/Options.lb)
as an optional part of the 'default' statement
- Limited the widespread used of 'default' for setting options
- Changed 'dir' to 'config' and 'config' to 'static' (maybe)
- Removing necessity of double-quotes surrounding strings (which may
happen to include double-quotes of their own)
- etc...

-------------------------------------------------------------------------------

		New config language for LinuxBIOS

This document defines the new configuration language for LinuxBIOS.

The goals of the new language are these: 

- Move from the python based configuration tool to something more
easily extensible and flexible
- Simplify parser so people can see and alter what is done
- Detail output so people can visualize the configuration tree
during the parsing process
- Implement capability for viewing and altering configuration with
Kconfig

Here is the new language.  It is very similar to the old one, differing
in only a few aspects.  Furthermore, effort has been put forth to make
the new configuration tool capable of parsing the syntax of the old
language.
This capability may be phased out in the near future, and replaced with
warning/error statements for configuration files not conforming to the
new language.

Pseudo-BNF extensions key:
Elements in angled brackets (<>) are nonterminal symbols; 
items within braces ({}) are for clarification and do not represent
grammar, double-quotes ("") denote literal strings required in the text,
elements in single-quotes ('') are keywords picked up by the parser,
and a postfixed asterisk (*) denotes optionally repeatable blocks.

# Expressions are composed of terms acted upon by operators
# (unary or binary).
# They may optionally be surrounded by parentheses.
# (Preferably, surrounding parentheses may soon be required syntax - ?)
expr ::= ["("] ( unary-op term ) |
                 ( term (binary-op term)* ) [")"]

# term is a number (dec or hex with '0x' notation), ID, or expression.
# An ID remains as an unexpanded reference until it is used or exported.
term ::= NUM | ID | expr

unary-op  ::= "+" | "-" | "!"
binary-op ::= "+" | "-" | "*" | "/" | "^" | "&&" | "||"

# Default command: Define and set an ID to its initial value.
# Defaults may only be set in Options.lb files.
# Attempts to assign defaults elsewhere are treated as like 'option'. 
# It is OK to set an ID's default value after it has already been set.
# Default assignments may optionally be followed on subsequent lines 
# with 'export', 'type', and/or 'comment' commands in any order.
# A comment will be displayed in generated Kconfig menus.
# Values are re-evaluated from component statements when referenced
# (ie, are delayed-evaluate, or recursively expanded variables).
default ::= 'default' ID "=" value
	[
	type	::= ("number" | "bool" | "string")  # (Hex vs. Dec ???)
	export	::= ("always" | "used" | "never")
	comment ::= 'comment' [<newline> <comment>]* "end"
	]

# Option command: Re-sets ID to new value.
# Options are used in Config files (in expressions and 'if' statements)
# and are also passed to the C compiler when building rom images.
# Options always over-ride defaults.
# It is an error to have an option command define the value of an ID
# after the ID has been referenced (i.e. 'set after used' is an error).
option	::= 'option' ID "=" value

# Values are treated differently depending on their declared type.
# A string is taken literally and doesn't need surrounding quotes.
# A numeric type is always evaluated mathematically, as an expression.
# An expr containing at least 1 one hex term results in a hex answer.
value ::= string | term

# Before any option may be referenced in a Config, it must be "used".
uses ::= 'uses' ID

# The 'chip' command causes sourcing of Config files as in the old
# config tool.  As parts are sourced, a device tree is built.
# The 'device' command also works just as it has in the past.
# Note that the 'device' command is used exclusively for describing the
# device tree and it does not source any configuration files.
# The structure of the tree is determined by the structure of the 
# components.
# Example of structure:
...
chip southbridge/via/vt8231
	register "enable_native_ide" = "0"
	device pci 11.0 on			# Southbrdge
		chip superio/winbond/w83627hf
			device pnp 2e.0 on	#  Floppy
				io 0x60 = 0x3f0
			end
...
# Static initializers are auto-generated from this hierarchy (static.c).
# Order does not matter for statements in the same block (for instance,
# in the above example, the device block may go before 'register' as
# long as it ends).
chip ::= 'chip' PATH
	['register' """<register_name>""" "=" """<register_value>"""]*
	[<embedded_chip_or_device_statement>]*
	"end"
# NOTE: Quotes may (preferably) become unneccessary in 'register' 
# clause.

device ::= 'device' device_path_type device_path ("on" | "off")
	[device_resource <resource_index> "=" <resource_base>]*

device_path_type ::= ("pci_domain" | "pci" | "pnp" | "apic" |
"apic_cluster"
	 | "i2c")

device_path ::= <port_on_path_type>"."<device_number_on_path_type>
# NOTE: The two numbers composing the path are implied hex (without the
"0x")

device_resource ::= "io" | "irq" | "drq" | "mem"

# Except as otherwise noted (in 'mainboard' and 'arch'),
# PATH is to a file's location in relation to the LinuxBIOS src dir.
PATH ::= {path_to_Config_file/}<filename>

# Files to include in static.c (Can this command have a better name?)
static ::= 'static' PATH

# Add C code to the current component (motherboard, etc.)
# to initialise the component-INDEPENDENT structure members.
# (Only used for src/arch/<arch>/init/crt0.S, so may become implicit)
init ::= 'init' PATH

# Add C code to the current component (motherboard, etc.)
# to initialise the component-DEPENDENT structure members.
register ::= 'register' <CODE>

# mainboard command specifies where (from src/mainboard directory)
# to find the board's root-level Config file with device tree.
mainboard ::= 'mainboard' {src/mainboard/}PATH

# Specify where (from within src/arch directory) to find the 
# architecture-specific Config file.
arch ::= 'arch' {src/arch/}PATH

# Target build directory
target ::= 'target' PATH

# Payload to include in image; existence is checked before compilation
payload ::= 'payload' PATH

# Files for building linuxbios:

# Include a file in crt0.S
mainboardinit ::= 'mainboardinit' PATH

# Include an object for initialization
initobject ::= 'initobject' PATH

# Object file 
object ::= 'object' PATH

# Driver objects are built into the image in a different way
driver ::= 'driver' PATH

# Use the Config file in the PATH
config ::= 'config' PATH

# Add a file to the set of ldscript files.
ldscript ::= 'ldscript' PATH

# Set up a makerule
makerule ::= 'makerule' "<rule_name>"
	("""[depends]""")*
	("""[action]""")*
	"end"
# NOTE: Again, quotes may become unneccessary

# Dependencies or actions for the makerule command
depends ::= 'depends' <raw_make_syntax(prerequisites)>
action ::= 'action' <raw_make_syntax(commands)>

# Add an action to an existing make rule.
addaction ::= 'addaction' "<rule_name>" <raw_make_syntax(commands)>

# Addition definitions used in generated image makefiles.
makedefine ::= 'makedefine' <raw_make_syntax>

# statements
statement ::= 
		  option
		| default
		| uses
        	| arch
		| target
		| chip
		| device
		| driver
		| object
		| makerule
		| makedefine
		| addaction
		| init
		| mainboardinit
		| initobject
		| if
		| config
		| static
		| ldscript

statements ::= (statement)*