Rename documentation -> Documentation

In order to be closer to the Linux kernel source tree
structure, rename documentation to Documentation.

Change-Id: I8690f666638ef352d201bd3c3dc1923b0d24cb12
Signed-off-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
Reviewed-on: http://review.coreboot.org/10110
Tested-by: build bot (Jenkins)
Reviewed-by: Patrick Georgi <pgeorgi@google.com>

2 files changed, 0 insertions, 557 deletions

diff --git a/documentation/RFC/chip.tex b/documentation/RFC/chip.tex
deleted file mode 100644
index 5e366b8461..0000000000
--- a/documentation/RFC/chip.tex
+++ /dev/null
@@ -1,266 +0,0 @@
-		RFC for the chip specification architecture
-
-\begin{abstract}
-At the end of this document is the original message that motivated the
-change.
-\end{abstract}
-
-\section{Scope}
-This document defines how LinuxBIOS programmers can specify chips that
-are used, specified, and initalized. The current scope is for superio
-chips, but the architecture should allow for specification of other chips such
-as southbridges. Multiple chips of same or different type are supported.
-
-\section{Goals}
-The goals of the new chip architecture are these:
-\begin{itemize}
-\item seperate implementation details from specification in the Config file
-(translation: no more C code in Config files)
-\item make the specification easier for people to use and understand
-\item remove private details of a given chip to the chip file as much
-as possible
-\item allow unique register-set-specifiers for each chip
-\end{itemize}
-
-\section{Specification in the Config file}
-The specification looks like this:
-\begin{verbatim}
-chip <name> [path=<path>] ["<configuration>"]
-\end{verbatim}
-The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
-"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
-chip is derived from the first pathname component of the name, and the chip
-configuration is derived from the following components.
-
-The path defines the access mechanism to the chip.
-It is optional. If present, it overrides the default path to the chip.
-
-The configuration defines chip-specific configuration details, and is also
-optional. Note that an empty configuration will leave the chip with
-no enabled resources. This may be desirable in some cases.
-
-\section{Results of specifying a chip}
-
-When one or more chips are specified, the data about the chips
-is saved until the entire file is parsed. At this point, the config tool
-creates a file in the build directory called chip.c This file contains
-a common struct containing information about
-each individual chip and an array of pointers to these structures.
-
-For each chip, there are two structures. The structures contain control
-information for the chip, and register initialization information. The
-names of the structures are derived by ``flattening'' the chip name,
-as in the current linuxbios. For example, superio/ite/xyz uses
-two structs, one called superio_ite_xyz_control and one called
-superio_ite_xyz_init. The control struct is initialized from the
-chip name and path information, and has a pointer to the
-config struct. The config struct is initialized from the quote string
-
-\begin{verbatim}
-From rminnich@lanl.gov Fri May 16 10:34:13 2003
-Date: Tue, 13 May 2003 08:11:46 -0600 (MDT)
-From: ron minnich <rminnich@lanl.gov>
-To: linuxbios@clustermatic.org
-Subject: RFC:new superio proposal
-
-Abstract:
-	The superio architecture for linuxbios has worked for the last 2
-years but is being stretched to the limit by the changes in superio chips.
-The architecture depended on superio resources being relatively constant
-between chips, but this assumption no longer holds. In this document we
-propose several alternatives and solicit comments.
-
-Overview:
-The superio architecture in linuxbios was developed over time, and
-modified as circumstances required. In the beginning it was relatively
-simple and assumed only one superio per mainboard. The latest version
-allows an arbitrary number of superios per mainboard, and allows complete
-specification of the superio base I/O address along with the specification
-of reasonable default valures for both the base I/O address and the
-superio parameters such as serial enable, baud rate, and so on.
-
-Specification of superio control parameters is done by a configuration
-line such as:
-
-nsuperio sis/950 com1={1} floppy=1  lpt=1
-
-This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
-to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
-default values.
-
-While it is not obvious, these configuration parameters are fragments of a
-C initializer. The initializers are used to build a statically initialized
-structure of this type:
-
-struct superio {
-        struct superio_control *super; // the ops for the device.
-        unsigned int port; // if non-zero, overrides the default port
-        // com ports. This is not done as an array (yet).
-        // We think it's easier to set up from python if it is not an
-	// array.
-        struct com_ports com1, com2, com3, com4;
-        // DMA, if it exists.
-        struct lpt_ports lpt1, lpt2;
-        /* flags for each device type. Unsigned int. */
-        // low order bit ALWAYS means enable. Next bit means to enable
-        // LPT is in transition, so we leave this here for the moment.
-        // The winbond chips really stretched the way this works.
-        // so many functions!
-        unsigned int ide, floppy, lpt;
-        unsigned int keyboard, cir, game;
-        unsigned int gpio1, gpio2, gpio3;
-        unsigned int acpi,hwmonitor;
-};
-
-These structures are, in turn, created and statically initialized by a
-config-tool-generated structure that defines all the superios. This file
-is called nsuperio.c, is created for each mainboard you build, only
-appears in the build directory, and looks like this:
-
-===
-extern struct superio_control superio_winbond_w83627hf_control;
-
-struct superio superio_winbond_w83627hf= {
-  &superio_winbond_w83627hf_control,
-  .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
-
-struct superio *all_superio[] = {&superio_winbond_w83627hf,
-};
-
-unsigned long nsuperio = 1;
-===
-
-This example shows a board with one superio (nsuperio). The superio
-consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
-and hwmonitor enabled. Note that this structure also allows for
-over-riding the default superio base, although that capability is rarely
-used.
-
-The control structure is used to define how to access the superio for
-purposes of control. It looks like this:
-===
-struct superio_control {
-  void (*pre_pci_init)(struct superio *s);
-  void (*init)(struct superio *s);
-  void (*finishup)(struct superio *s);
-  unsigned int defaultport;     /* the defaultport. Can be overridden
-                                 * by commands in config
-                                 */
-  // This is the print name for debugging
-  char *name;
-};
-===
-
-There are three methods for stages of hardwaremain. First is pre_pci_init
-(for chips like the acer southbridge that require you to enable some
-resources BEFORE pci scan); init, called during the 'middle' phase of
-hardwaremain; and finishup, called before the payload is loaded.
-
-This approach was inspired by and borrows heavily on the Plan 9 kernel
-configuration tools.
-
-The problem:
-
-When the first version of the superio structure came out it was much
-smaller. It has grown and in the limit this structure is the union of all
-possibly superio chips. Obviously, in the long term, this is not
-practical: we can not anticipate all possible superio chips for all time.
-
-The common PC BIOS solution to this type of problem is to continue with
-binary structures but add version numbers to them, so that all code that
-uses a given structure has to check the version number. Personally, I find
-this grotesque and would rather not work this way.
-
-Using textual strings for configuration is something I find far more
-attractive. Plan 9 has shown that this approach has no real limits and
-suffices for configuration tasks. The Linux kernel does more limited use
-of strings for configuration, but still depends on them. Strings are
-easier to read and work with than binary structures, and more important, a
-lot easier to deal with when things start going wrong.
-
-The proposed solution:
-
-What follows are three possible ideas for specifying superio resources and
-their settings.
-
-A common part of the new idea is to eliminate the common superio
-structure, due to the many variations in chips, and make it invisible
-outside a given superio source file -- the superio structure is now
-private to a given superio. Thus, sis/950/superio.c would contain its own
-superio structure definitions, and also might contain more than once
-instance of these structures (consider a board with 2 sis 950 chips).
-
-The control structure would change as follows:
-struct superio_control {
-  int (*create)(struct superio *s);
-  void (*pre_pci_init)(struct superio *s);
-  void (*init)(struct superio *s);
-  void (*finishup)(struct superio *s);
-  unsigned int defaultport;     /* the defaultport. Can be overridden
-                                 * by commands in config
-                                 */
-  // This is the print name for debugging
-  char *name;
-};
-
-I.e. we add a new function for creating the superio.
-
-Communication of superio settings from linuxbios to the superio would be
-via textual strings. The superio structure becomes this:
-
-struct superio {
-        struct superio_control *super; // the ops for the device.
-        unsigned int port; // if non-zero, overrides the default port
-	struct configuration *config;
-};
-
-
-So now the question becomes, what is the configuration structure?
-There are several choices. The simplest, from my point of view, are
-keyword-value pairs:
-struct configuration {
-	const char *keyword;
-	const char *value;
-};
-
-These get filled in by the config tool as before. The linuxbios libary can
-then provide a generic parsing function for the superios to use.
-
-The remaining question is how should the superio command look in
-freebios2?
-
-superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
-
-or
-
-superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1"
-
-or
-
-superio sis/950 ((com1 115200 8n1) (lpt 1))
-
-So,  my questions:
-
-1. Does this new scheme look workable. If not, what needs to change?
-2. What should the 'struct configuration' be? does keyword/value work?
-3. what should the superio command look like?
-
-Comments welcome.
-
-I'd like to adopt this "RFC" approach for freebios2 as much as we can.
-There was a lot of give-and-take in the early days of linuxbios about
-structure and it proved useful. There's a lot that will start happening in
-freebios2 now, and we need to try to make sure it will work for everyone.
-
-Those of you who are doing mainboards, please look at freebios2 and see
-how it looks for you. There's a lot of good work that has been done (not
-by me so far, thanks Eric and Stefan), and more that needs to be done.
-Consider trying out romcc as an "assembly code killer". See how it fits
-together and if you can work with it or need changes. Bring comments back
-to this list.
-
-thanks
-
-ron
-
-\end{verbatim}
diff --git a/documentation/RFC/config.tex b/documentation/RFC/config.tex
deleted file mode 100644
index 6d6c433025..0000000000
--- a/documentation/RFC/config.tex
+++ /dev/null
@@ -1,291 +0,0 @@
-		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.
-