more specs.

git-svn-id: svn://svn.coreboot.org/coreboot/trunk@846 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

1 files changed, 276 insertions, 0 deletions

diff --git a/documentation/RFC/config.tex b/documentation/RFC/config.tex
new file mode 100644
index 0000000000..1190c8daa9
--- /dev/null
+++ b/documentation/RFC/config.tex
@@ -0,0 +1,276 @@
+		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
+\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}
+
+A sample file:
+
+\begin{verbatim}
+target x
+
+# over-ride the default rom size in the mainboard file
+option ROM_SIZE=0x100000
+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 DEBUG=1
+default 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 USE_FALLBACK_IMAGE 
+  mainboardinit cpu/i386/reset16.inc 
+  ldscript cpu/i386/reset16.lds 
+end
+
+if USE_NORMAL_IMAGE
+  mainboardinit cpu/i386/reset32.inc 
+  ldscript cpu/i386/reset32.lds 
+end
+.
+.
+.
+if USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc  end
+#
+###
+### Romcc output
+###
+#makerule ./failover.E dep "$(MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(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 "$(MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(MAINBOARD)/auto.c > ./auto.E"
+makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
+mainboardinit ./auto.inc
+#
+###
+### Setup RAM
+###
+mainboardinit ram/ramtest.inc
+mainboardinit southbridge/amd/amd8111/smbus.inc
+mainboardinit sdram/generic_dump_spd.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 HAVE_MP_TABLE object mptable.o end
+if 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 PAYLOAD_SIZE            = (ROM_SECTION_SIZE - ROM_IMAGE_SIZE)
+option CONFIG_ROM_STREAM_START = (0xffffffff - ROM_SIZE + 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 MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
+export ARCH:=i386
+export _RAMBASE:=0x4000
+export ROM_IMAGE_SIZE:=65535
+export PAYLOAD_SIZE:=131073
+export MAX_CPUS:=1
+export HEAP_SIZE:=8192
+export STACK_SIZE:=8192
+export MEMORY_HOLE:=0
+export LINUXBIOS_VERSION:=1.1.0
+export CC:=$(CROSS_COMPILE)gcc
+
+\end{verbatim}
+
+In other words, instead of expressions, we see the values. It's easier to 
+deal with. 
+