Documentation/RFC/config.tex

		New config language for LinuxBIOS

\begin{abstract}
We describe the new configuration language for LinuxBIOS.
\end{abstract}

\section{Scope}
This document defines the new configuration language for LinuxBIOS.

\section{Goals}
The goals of the new language are these:
\begin{itemize}
\item Simplified Makefiles so people can see what is set
\item Move from the regular-expression-based language to something
a bit more comprehensible and flexible
\item make the specification easier for people to use and understand
\item allow unique register-set-specifiers for each chip
\item allow generic register-set-specifiers for each chip
\item generate static initialization code, as needed, for the
specifiers.
\end{itemize}

\section{Language}
Here is the new language. It is very similar to the old one, differing
in only a few respects. It borrows heavily from Greg Watson's suggestions.

I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
in '' are keywords; things in ``'' are strings in the actual text.
\begin{verbatim}
#exprs are composed of factor or factor + factor etc.
expr ::= factor ( ``+'' factor | ``-'' factor | )*
#factors are term or term * term or term / term or ...
factor ::=  term ( ``*'' term | ``/'' term | ... )*
#
unary-op ::= ``!'' ID
# term is a number, hexnumber, ID, unary-op, or a full-blown expression
term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''

# Option command. Can be an expression or quote-string.
# Options are used in the config tool itself (in expressions and 'if')
# and are also passed to the C compiler when building linuxbios.
# It is an error to have two option commands in a file.
# It is an error to have an option command after the ID has been used
#   in an expression (i.e. 'set after used' is an error)
option ::= 'option' ID '=' (``value'' | term)

# Default command. The ID is set to this value if no option command
# is scanned.
# Multiple defaults for an ID will produce warning, but not errors.
# It is OK to scan a default command after use of an ID.
# Options always over-ride defaults.
default ::= 'default' ID '=' (``value'' | term)

# the mainboard, southbridge, northbridge commands
# cause sourcing of Config.lb files as in the old config tool
# as parts are sourced, a device tree is built. The structure
# of the tree is determined by the structure of the components
# as they are specified. To attach a superio to a southbridge, for
# example, one would do this:
# southbridge acer/5432
#   superio nsc/123
#   end
# end
# the tool generates static initializers for this hierarchy.

# add C code to the current component (motherboard, etc. )
# to initialise the component-INDEPENDENT structure members
init ::= 'init' ``CODE''

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


# mainboard command
# statements in this block will set variables controlling the mainboard,
# and will also place components (northbridge etc.) in the device tree
# under this mainboard
mainboard ::= 'mainboard' PATH (statements)* 'end'

# standard linuxbios commands
southbridge ::= 'southbridge' PATH (statemnts)* 'end'
northbridge ::= 'northbridge' PATH (statemnts)* 'end'
superio ::= 'superio PATH (statemnts)* 'end'
cpu ::= 'cpu' PATH (statemnts)* 'end'
arch ::= 'arch' PATH (statemnts)* 'end'

# files for building linuxbios
# include a file in crt0.S
mainboardinit ::= 'mainboardinit' PATH

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

# Use the Config.lb file in the PATH
dir ::= 'dir' PATH

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

# dependencies or actions for the makerule command
dep ::= 'dep' ``dependency-string''
act ::= 'act' ``actions''
depsacts ::= (dep | act)*
# set up a makerule
#
makerule ::= 'makerule' PATH depsacts

#defines for use in makefiles only
# note usable in the config tool, not passed to cc
makedefine ::= 'makedefine' ``RAWTEXT''

# add an action to an existing make rule
addaction ::= 'addaction' PATH ``ACTION''

# statements
statement ::=
		  option
		| default
        	| cpu
        	| arch
		| northbridge
		| southbridge
		| superio
		| object
		| driver
		| mainboardinit
		| makerule
		| makedefine
		| addaction
		| init
		| register
		| iif
		| dir
		| ldscript

statements ::= (statement)*

# target directory specification
target ::= 'target' PATH

# and the whole thing
board ::= target (option)* mainboard

\end{verbatim}

\subsubsection{Command definitions}
\subsubsubsection{option}
\subsubsubsection{default}
\subsubsubsection{cpu}
\subsubsubsection{arch}
\subsubsubsection{northbridge}
\subsubsubsection{southbridge}
\subsubsubsection{superio}
\subsubsubsection{object}
\subsubsubsection{driver}
\subsubsubsection{mainboardinit}
\subsubsubsection{makerule}
\subsubsubsection{makedefine}
\subsubsubsection{addaction}
\subsubsubsection{init}
\subsubsubsection{register}
\subsubsubsection{iif}
\subsubsubsection{dir}
\subsubsubsection{ldscript}


A sample file:

\begin{verbatim}
target x

# over-ride the default rom size in the mainboard file
option CONFIG_ROM_SIZE=1024*1024
mainboard amd/solo
end

\end{verbatim}

Sample mainboard file
\begin{verbatim}
#
###
### Set all of the defaults for an x86 architecture
###
arch i386 end
cpu k8 end
#
option CONFIG_DEBUG=1
default CONFIG_USE_FALLBACK_IMAGE=1
option A=(1+2)
option B=0xa
#
###
### Build our 16 bit and 32 bit linuxBIOS entry code
###
mainboardinit cpu/i386/entry16.inc
mainboardinit cpu/i386/entry32.inc
ldscript cpu/i386/entry16.lds
ldscript cpu/i386/entry32.lds
#
###
### Build our reset vector (This is where linuxBIOS is entered)
###
if CONFIG_USE_FALLBACK_IMAGE
	mainboardinit cpu/i386/reset16.inc
	ldscript cpu/i386/reset16.lds
else
	mainboardinit cpu/i386/reset32.inc
	ldscript cpu/i386/reset32.lds
end
.
.
.
if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc  end
#
###
### Romcc output
###
#makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
#makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
#mainboardinit ./failover.inc
makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
mainboardinit ./auto.inc
#
###
### Include the secondary Configuration files
###
northbridge amd/amdk8
end
southbridge amd/amd8111
end
#mainboardinit arch/i386/smp/secondary.inc
superio nsc/pc87360
	register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
end
dir /pc80
##dir /src/superio/winbond/w83627hf
cpu p5 end
cpu p6 end
cpu k7 end
cpu k8 end
#
###
### Build the objects we have code for in this directory.
###
##object mainboard.o
driver mainboard.o
object static_devices.o
if CONFIG_HAVE_MP_TABLE object mptable.o end
if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
### Location of the DIMM EEPROMS on the SMBUS
### This is fixed into a narrow range by the DIMM package standard.
###
option SMBUS_MEM_DEVICE_START=(0xa << 3)
option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
option SMBUS_MEM_DEVICE_INC=1
#
### The linuxBIOS bootloader.
###
option CONFIG_PAYLOAD_SIZE            = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
#

\end{verbatim}

I've found the output of the new tool to be easier to
handle. Makefile.settings looks like this, for example:
\begin{verbatim}
TOP:=/home/rminnich/src/yapps2/freebios2
TARGET_DIR:=x
export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
export CONFIG_ARCH:=i386
export CONFIG_RAMBASE:=0x4000
export CONFIG_ROM_IMAGE_SIZE:=65535
export CONFIG_PAYLOAD_SIZE:=131073
export CONFIG_MAX_CPUS:=1
export CONFIG_HEAP_SIZE:=8192
export CONFIG_STACK_SIZE:=8192
export CONFIG_MEMORY_HOLE:=0
export COREBOOT_VERSION:=1.1.0
export CC:=$(CONFIG_CROSS_COMPILE)gcc

\end{verbatim}

In other words, instead of expressions, we see the values. It's easier to
deal with.