documentation/RFC/config.tex

   1                 New config language for LinuxBIOS
   2
   3 \begin{abstract}
   4 We describe the new configuration language for LinuxBIOS.
   5 \end{abstract}
   6
   7 \section{Scope}
   8 This document defines the new configuration language for LinuxBIOS.
   9
  10 \section{Goals}
  11 The goals of the new language are these:
  12 \begin{itemize}
  13 \item Simplified Makefiles so people can see what is set
  14 \item Move from the regular-expression-based language to something
  15 a bit more comprehensible and flexible
  16 \item make the specification easier for people to use and understand
  17 \item allow unique register-set-specifiers for each chip
  18 \item allow generic register-set-specifiers for each chip
  19 \item generate static initialization code, as needed, for the
  20 specifiers.
  21 \end{itemize}
  22
  23 \section{Language}
  24 Here is the new language. It is very similar to the old one, differing
  25 in only a few respects. It borrows heavily from Greg Watson's suggestions.
  26
  27 I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
  28 in '' are keywords; things in ``'' are strings in the actual text.
  29 \begin{verbatim}
  30 #exprs are composed of factor or factor + factor etc.
  31 expr ::= factor ( ``+'' factor | ``-'' factor | )*
  32 #factors are term or term * term or term / term or ...
  33 factor ::=  term ( ``*'' term | ``/'' term | ... )*
  34 #
  35 unary-op ::= ``!'' ID
  36 # term is a number, hexnumber, ID, unary-op, or a full-blown expression
  37 term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
  38
  39 # Option command. Can be an expression or quote-string.
  40 # Options are used in the config tool itself (in expressions and 'if')
  41 # and are also passed to the C compiler when building linuxbios.
  42 # It is an error to have two option commands in a file.
  43 # It is an error to have an option command after the ID has been used
  44 #   in an expression (i.e. 'set after used' is an error)
  45 option ::= 'option' ID '=' (``value'' | term)
  46
  47 # Default command. The ID is set to this value if no option command
  48 # is scanned.
  49 # Multiple defaults for an ID will produce warning, but not errors.
  50 # It is OK to scan a default command after use of an ID.
  51 # Options always over-ride defaults.
  52 default ::= 'default' ID '=' (``value'' | term)
  53
  54 # the mainboard, southbridge, northbridge commands
  55 # cause sourcing of Config.lb files as in the old config tool
  56 # as parts are sourced, a device tree is built. The structure
  57 # of the tree is determined by the structure of the components
  58 # as they are specified. To attach a superio to a southbridge, for
  59 # example, one would do this:
  60 # southbridge acer/5432
  61 #   superio nsc/123
  62 #   end
  63 # end
  64 # the tool generates static initializers for this hierarchy.
  65
  66 # add C code to the current component (motherboard, etc. )
  67 # to initialise the component-INDEPENDENT structure members
  68 init ::= 'init' ``CODE''
  69
  70 # add C code to the current component (motherboard, etc. )
  71 # to initialise the component-DEPENDENT structure members
  72 register ::= 'register' ``CODE''
  73
  74
  75 # mainboard command
  76 # statements in this block will set variables controlling the mainboard,
  77 # and will also place components (northbridge etc.) in the device tree
  78 # under this mainboard
  79 mainboard ::= 'mainboard' PATH (statements)* 'end'
  80
  81 # standard linuxbios commands
  82 southbridge ::= 'southbridge' PATH (statemnts)* 'end'
  83 northbridge ::= 'northbridge' PATH (statemnts)* 'end'
  84 superio ::= 'superio PATH (statemnts)* 'end'
  85 cpu ::= 'cpu' PATH (statemnts)* 'end'
  86 arch ::= 'arch' PATH (statemnts)* 'end'
  87
  88 # files for building linuxbios
  89 # include a file in crt0.S
  90 mainboardinit ::= 'mainboardinit' PATH
  91
  92 # object file
  93 object ::= 'object' PATH
  94 # driver objects are just built into the image in a different way
  95 driver ::= 'driver' PATH
  96
  97 # Use the Config.lb file in the PATH
  98 dir ::= 'dir' PATH
  99
 100 # add a file to the set of ldscript files
 101 ldscript ::= 'ldscript' PATH
 102
 103 # dependencies or actions for the makerule command
 104 dep ::= 'dep' ``dependency-string''
 105 act ::= 'act' ``actions''
 106 depsacts ::= (dep | act)*
 107 # set up a makerule
 108 #
 109 makerule ::= 'makerule' PATH depsacts
 110
 111 #defines for use in makefiles only
 112 # note usable in the config tool, not passed to cc
 113 makedefine ::= 'makedefine' ``RAWTEXT''
 114
 115 # add an action to an existing make rule
 116 addaction ::= 'addaction' PATH ``ACTION''
 117
 118 # statements
 119 statement ::=
 120                   option
 121                 | default
 122                 | cpu
 123                 | arch
 124                 | northbridge
 125                 | southbridge
 126                 | superio
 127                 | object
 128                 | driver
 129                 | mainboardinit
 130                 | makerule
 131                 | makedefine
 132                 | addaction
 133                 | init
 134                 | register
 135                 | iif
 136                 | dir
 137                 | ldscript
 138
 139 statements ::= (statement)*
 140
 141 # target directory specification
 142 target ::= 'target' PATH
 143
 144 # and the whole thing
 145 board ::= target (option)* mainboard
 146
 147 \end{verbatim}
 148
 149 \subsubsection{Command definitions}
 150 \subsubsubsection{option}
 151 \subsubsubsection{default}
 152 \subsubsubsection{cpu}
 153 \subsubsubsection{arch}
 154 \subsubsubsection{northbridge}
 155 \subsubsubsection{southbridge}
 156 \subsubsubsection{superio}
 157 \subsubsubsection{object}
 158 \subsubsubsection{driver}
 159 \subsubsubsection{mainboardinit}
 160 \subsubsubsection{makerule}
 161 \subsubsubsection{makedefine}
 162 \subsubsubsection{addaction}
 163 \subsubsubsection{init}
 164 \subsubsubsection{register}
 165 \subsubsubsection{iif}
 166 \subsubsubsection{dir}
 167 \subsubsubsection{ldscript}
 168
 169
 170 A sample file:
 171
 172 \begin{verbatim}
 173 target x
 174
 175 # over-ride the default rom size in the mainboard file
 176 option CONFIG_ROM_SIZE=1024*1024
 177 mainboard amd/solo
 178 end
 179
 180 \end{verbatim}
 181
 182 Sample mainboard file
 183 \begin{verbatim}
 184 #
 185 ###
 186 ### Set all of the defaults for an x86 architecture
 187 ###
 188 arch i386 end
 189 cpu k8 end
 190 #
 191 option CONFIG_DEBUG=1
 192 default CONFIG_USE_FALLBACK_IMAGE=1
 193 option A=(1+2)
 194 option B=0xa
 195 #
 196 ###
 197 ### Build our 16 bit and 32 bit linuxBIOS entry code
 198 ###
 199 mainboardinit cpu/i386/entry16.inc
 200 mainboardinit cpu/i386/entry32.inc
 201 ldscript cpu/i386/entry16.lds
 202 ldscript cpu/i386/entry32.lds
 203 #
 204 ###
 205 ### Build our reset vector (This is where linuxBIOS is entered)
 206 ###
 207 if CONFIG_USE_FALLBACK_IMAGE
 208         mainboardinit cpu/i386/reset16.inc
 209         ldscript cpu/i386/reset16.lds
 210 else
 211         mainboardinit cpu/i386/reset32.inc
 212         ldscript cpu/i386/reset32.lds
 213 end
 214 .
 215 .
 216 .
 217 if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc  end
 218 #
 219 ###
 220 ### Romcc output
 221 ###
 222 #makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
 223 #makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
 224 #mainboardinit ./failover.inc
 225 makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
 226 makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
 227 mainboardinit ./auto.inc
 228 #
 229 ###
 230 ### Include the secondary Configuration files
 231 ###
 232 northbridge amd/amdk8
 233 end
 234 southbridge amd/amd8111
 235 end
 236 #mainboardinit arch/i386/smp/secondary.inc
 237 superio nsc/pc87360
 238         register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
 239 end
 240 dir /pc80
 241 ##dir /src/superio/winbond/w83627hf
 242 cpu p5 end
 243 cpu p6 end
 244 cpu k7 end
 245 cpu k8 end
 246 #
 247 ###
 248 ### Build the objects we have code for in this directory.
 249 ###
 250 ##object mainboard.o
 251 driver mainboard.o
 252 object static_devices.o
 253 if CONFIG_HAVE_MP_TABLE object mptable.o end
 254 if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
 255 ### Location of the DIMM EEPROMS on the SMBUS
 256 ### This is fixed into a narrow range by the DIMM package standard.
 257 ###
 258 option SMBUS_MEM_DEVICE_START=(0xa << 3)
 259 option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
 260 option SMBUS_MEM_DEVICE_INC=1
 261 #
 262 ### The linuxBIOS bootloader.
 263 ###
 264 option CONFIG_PAYLOAD_SIZE            = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
 265 option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
 266 #
 267
 268 \end{verbatim}
 269
 270 I've found the output of the new tool to be easier to
 271 handle. Makefile.settings looks like this, for example:
 272 \begin{verbatim}
 273 TOP:=/home/rminnich/src/yapps2/freebios2
 274 TARGET_DIR:=x
 275 export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
 276 export CONFIG_ARCH:=i386
 277 export CONFIG_RAMBASE:=0x4000
 278 export CONFIG_ROM_IMAGE_SIZE:=65535
 279 export CONFIG_PAYLOAD_SIZE:=131073
 280 export CONFIG_MAX_CPUS:=1
 281 export CONFIG_HEAP_SIZE:=8192
 282 export CONFIG_STACK_SIZE:=8192
 283 export CONFIG_MEMORY_HOLE:=0
 284 export COREBOOT_VERSION:=1.1.0
 285 export CC:=$(CONFIG_CROSS_COMPILE)gcc
 286
 287 \end{verbatim}
 288
 289 In other words, instead of expressions, we see the values. It's easier to
 290 deal with.
 291