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