Extended Module Support -- configuration file language
======================================================


-=> Initial note

Please make sure that you have read the file

       Documentation/badmem.txt
       
   
   
-=> The /etc/badmem.conf file

Almost every configuration of BadMEM is done in the file
      
       /etc/badmem.conf
       
if you have selected to install the Extended Module support during kernel
configuration. This is a plain text file like the one you are currently
reading. You can write it with your favourite text editor like vi, emacs,
joe, or whatever.
The length is not limited, although it is recommended that you take care
that it is below 128kb which is very very much!



-=> Commands

The configuration file consists of one or more commands. Here is an example
configuration file:


*** CUT ***

# /etc/badmem.conf
#
#
# This file contains all information about your BadMEM modules.
# It is needed at kernel compile time.
# Only change this file, if you have read the documentation of BadMEM!

module mod1
 size 64m
 base 128m
 0x80014f8,0xfe001ff8
 
module mod2
 size 64m
 base 256m
 0x10000004,0xfc0430004
 0x10000000,0xfd8000000
 
module good256
 size 256m
 base 0
 
mdf /proc/badmem/mdf/mdfmod1
 
*** CUT ***

For explaination: This configuration file defines four (or even more) modules:

1) called "mod1" which has 64MB. The calculation of bad areas was done
during the presence of 128MB below of this module (that means, there was a
128MB module in Memory Bank 0 and the faulty 64MB module was in Memory
Bank 1). Use "0x80014f8,0xfe001ff8" and pass these options to the main
BadMEM driver.

2) called "mod2" which has 64MB, too. Now there was one 256MB module below
(or two 128MB modules, or four 64MB modules or ...). Use the two lines above
to pass them to the main BadMEM driver.

3) called "good256". This just defines a good RAM module. BadMEM should not
lock any line. We need this if you have good RAM in your PC. See the
"GoodRAM" section below.

4) no name is given; the file /proc/badmem/mdf/mdfmod1 is looked up and all
the modules defined there will be included into the current setup.

Comments are either initiated by setting a # or a ; (semicolon) at the first
character in the line. 
I will now try to explain every single command.

-=> Command: module <modname>

Declares to define a new module with the name <modname>. Do *not* use " or
'. A module name must not contain white spaces ( ) but it may contain
underscores (_). Try to make your module names as short as possible, as you
will use them as short-cuts during kernel configuration in the LILO append
line.

-=> Command: mdf <path/filename>

Looks at the file path/filename and tries to open it according to the MDF
protocol. If successful, all the modules contained there is read and
included in the current configuration. 
Please note that you may not specify modules in a mdf file which are already
declared by a command 'module' (see above). This would double-define it
confusing the C-compiler.
Hint: In the directory /proc/badmem/mdf/ you will find all your current
compiled modules definitions as mdf files.

-=> Command: size <size>

Defines the size of the module which was defined before. You may use
abbrivations like

    m         for Megabytes (1048576 bytes)
    k         for Kilobytes (1024 bytes)
    g         for Gigabytes (well - something very huge...) ;-)
    t         for Terabytes (that's g * 1024)

Examples: 2m = 512p = 2048k = 4096b = 2097152

Note: This is similar to the dd command line.

You are not allowed to use the size command several times in one module. If
you still define it more than once, the last size command is used.

-=> Command: base <basemem>

To ensure that the driver blocks the right memory areas and the right module,
you must tell it with which how much memory you have measured the BadMEM
regions. This has one very big advantage: You may test a module (let's call
it the B module -- B like Bad) in Bank 1 while you have a good module (let's
call this one the G module -- G like Good) in Bank 0. Let's say B is 64m
sized an G is only 32m in size. Afterwards you remove the G module and put
in a (perhaps bad) 128m module. Then all your lock line would be foo bar. If
you set the <basemem>, then shifting the memory addresses are done
automatically according to your current configuration. For further
assistance to this issue, please read the HOWTO available at

	   http://webrum.uni-mannheim.de/math/schmoigl/linux
	   
which will be available in the very near future (2000/09/03).

You may use the abbrevations m, b, k, etc. as you know it from the "size"
command. You are allowed to use the base command several times in a 
module. If you do not select it at all, 0 is assumed.

-=> Command: <memaddr>,<memmask>

This is the locking combination which you know from the Rick-van-Rein-methode
described in the file Documentation/badmem.txt. 

Common trap: Do not forget to use "0x" at the beginning of a hexadecimal
number! Otherwise the number is interpreted as a decimal number.

IMPORTANT NOTE: Different from the Rick-van-Rein-methode you *MUST* select a
<memmask>. This parameter is therefore not optional.

Note: You may define as many <memaddr>,<memmask> combinations as you like!
There is no limit!


-=> Complex (or crazy?) definitions:

Have a short look on the following definition:

*** CUT ***

module test
 size 128m
 base 256m
 0x10000004,0xfc0430004
 0x10000000,0xfd8000000

 base 128m
 0x080014f8,0xfe001ff8

 size 64m

*** CUT ***

This will define a quite fuzzy module:

 * Its size is 64m.
 * Locking is done with the two lines above relative to a base of 256m
 * Locking is done with the "0x080014f8,0xfe001ff8" relative to the base of
   128m.
   
So, you can always add your knowledge to your latest configuration file.
Overlapping locking areas are ignored by the kernel driver. Please note that
no optimization is done during compile time, yet.



-=> Activating the modules

Up to now, there is no possibility to auto-detect which memory module is in
which bank. Theory defines one, but this is not implemented yet. So you must
tell the kernel, which module is next. This is done via the LILO kernel
command line (append or during boot time query). Example:

 append = "badmem=good256,mod1,mod2"
 
This means, that the first module (typically in Bank 0) is the module which
was defined with the name "good256". In Bank 1 there is the "mod1" module
and so on. There is no limitation to length of this command except the total
command line length of the LILO.

During boot up phase, all data you specified in the badmem.conf is used to
lock those areas which are marked as bad.



-=> GoodRAM

Please note that you must tell the driver all your RAM modules - those which
are good, too! Otherwise it is asyncronous with your Banks. Then, the wrong
areas will be marked as bad (well, this would not harm much) and the broken
onces are left ok (this is the real-bad-thing(tm) !)



-=> Final note

If you walk over the syntax definitions in the /etc/badmem.conf file, it is
very likely that kernel compilation will stop. So, if you suddenly do not
know why the kernel stops during badmem compilation, check the correct
syntax of your badmem.conf

If you find any typos or you want to send me some idea or suggestion, please
contact me via the email address below.



By(t)e
  Nico
  
  Germany, BW, (Uni-)Mannheim
  <nico@writemail.com>, http://badmem.sourceforge.net
  Last update: 2001/04/30
