1  		RFC for the chip specification architecture
  2  
  3  \begin{abstract}
  4  At the end of this document is the original message that motivated the
  5  change.
  6  \end{abstract}
  7  
  8  \section{Scope}
  9  This document defines how LinuxBIOS programmers can specify chips that
 10  are used, specified, and initialized. The current scope is for superio
 11  chips, but the architecture should allow for specification of other chips such
 12  as southbridges. Multiple chips of same or different type are supported.
 13  
 14  \section{Goals}
 15  The goals of the new chip architecture are these:
 16  \begin{itemize}
 17  \item separate implementation details from specification in the Config file
 18  (translation: no more C code in Config files)
 19  \item make the specification easier for people to use and understand
 20  \item remove private details of a given chip to the chip file as much
 21  as possible
 22  \item allow unique register-set-specifiers for each chip
 23  \end{itemize}
 24  
 25  \section{Specification in the Config file}
 26  The specification looks like this:
 27  \begin{verbatim}
 28  chip <name> [path=<path>] ["<configuration>"]
 29  \end{verbatim}
 30  The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
 31  "southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
 32  chip is derived from the first pathname component of the name, and the chip
 33  configuration is derived from the following components.
 34  
 35  The path defines the access mechanism to the chip.
 36  It is optional. If present, it overrides the default path to the chip.
 37  
 38  The configuration defines chip-specific configuration details, and is also
 39  optional. Note that an empty configuration will leave the chip with
 40  no enabled resources. This may be desirable in some cases.
 41  
 42  \section{Results of specifying a chip}
 43  
 44  When one or more chips are specified, the data about the chips
 45  is saved until the entire file is parsed. At this point, the config tool
 46  creates a file in the build directory called chip.c This file contains
 47  a common struct containing information about
 48  each individual chip and an array of pointers to these structures.
 49  
 50  For each chip, there are two structures. The structures contain control
 51  information for the chip, and register initialization information. The
 52  names of the structures are derived by ``flattening'' the chip name,
 53  as in the current linuxbios. For example, superio/ite/xyz uses
 54  two structs, one called superio_ite_xyz_control and one called
 55  superio_ite_xyz_init. The control struct is initialized from the
 56  chip name and path information, and has a pointer to the
 57  config struct. The config struct is initialized from the quote string
 58  
 59  \begin{verbatim}
 60  From rminnich@lanl.gov Fri May 16 10:34:13 2003
 61  Date: Tue, 13 May 2003 08:11:46 -0600 (MDT)
 62  From: ron minnich <rminnich@lanl.gov>
 63  To: linuxbios@clustermatic.org
 64  Subject: RFC:new superio proposal
 65  
 66  Abstract:
 67  	The superio architecture for linuxbios has worked for the last 2
 68  years but is being stretched to the limit by the changes in superio chips.
 69  The architecture depended on superio resources being relatively constant
 70  between chips, but this assumption no longer holds. In this document we
 71  propose several alternatives and solicit comments.
 72  
 73  Overview:
 74  The superio architecture in linuxbios was developed over time, and
 75  modified as circumstances required. In the beginning it was relatively
 76  simple and assumed only one superio per mainboard. The latest version
 77  allows an arbitrary number of superios per mainboard, and allows complete
 78  specification of the superio base I/O address along with the specification
 79  of reasonable default valures for both the base I/O address and the
 80  superio parameters such as serial enable, baud rate, and so on.
 81  
 82  Specification of superio control parameters is done by a configuration
 83  line such as:
 84  
 85  nsuperio sis/950 com1={1} floppy=1  lpt=1
 86  
 87  This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
 88  to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
 89  default values.
 90  
 91  While it is not obvious, these configuration parameters are fragments of a
 92  C initializer. The initializers are used to build a statically initialized
 93  structure of this type:
 94  
 95  struct superio {
 96          struct superio_control *super; // the ops for the device.
 97          unsigned int port; // if non-zero, overrides the default port
 98          // com ports. This is not done as an array (yet).
 99          // We think it's easier to set up from python if it is not an
100  	// array.
101          struct com_ports com1, com2, com3, com4;
102          // DMA, if it exists.
103          struct lpt_ports lpt1, lpt2;
104          /* flags for each device type. Unsigned int. */
105          // low order bit ALWAYS means enable. Next bit means to enable
106          // LPT is in transition, so we leave this here for the moment.
107          // The winbond chips really stretched the way this works.
108          // so many functions!
109          unsigned int ide, floppy, lpt;
110          unsigned int keyboard, cir, game;
111          unsigned int gpio1, gpio2, gpio3;
112          unsigned int acpi,hwmonitor;
113  };
114  
115  These structures are, in turn, created and statically initialized by a
116  config-tool-generated structure that defines all the superios. This file
117  is called nsuperio.c, is created for each mainboard you build, only
118  appears in the build directory, and looks like this:
119  
120  ===
121  extern struct superio_control superio_winbond_w83627hf_control;
122  
123  struct superio superio_winbond_w83627hf= {
124    &superio_winbond_w83627hf_control,
125    .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
126  
127  struct superio *all_superio[] = {&superio_winbond_w83627hf,
128  };
129  
130  unsigned long nsuperio = 1;
131  ===
132  
133  This example shows a board with one superio (nsuperio). The superio
134  consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
135  and hwmonitor enabled. Note that this structure also allows for
136  over-riding the default superio base, although that capability is rarely
137  used.
138  
139  The control structure is used to define how to access the superio for
140  purposes of control. It looks like this:
141  ===
142  struct superio_control {
143    void (*pre_pci_init)(struct superio *s);
144    void (*init)(struct superio *s);
145    void (*finishup)(struct superio *s);
146    unsigned int defaultport;     /* the defaultport. Can be overridden
147                                   * by commands in config
148                                   */
149    // This is the print name for debugging
150    char *name;
151  };
152  ===
153  
154  There are three methods for stages of hardwaremain. First is pre_pci_init
155  (for chips like the acer southbridge that require you to enable some
156  resources BEFORE pci scan); init, called during the 'middle' phase of
157  hardwaremain; and finishup, called before the payload is loaded.
158  
159  This approach was inspired by and borrows heavily on the Plan 9 kernel
160  configuration tools.
161  
162  The problem:
163  
164  When the first version of the superio structure came out it was much
165  smaller. It has grown and in the limit this structure is the union of all
166  possibly superio chips. Obviously, in the long term, this is not
167  practical: we can not anticipate all possible superio chips for all time.
168  
169  The common PC BIOS solution to this type of problem is to continue with
170  binary structures but add version numbers to them, so that all code that
171  uses a given structure has to check the version number. Personally, I find
172  this grotesque and would rather not work this way.
173  
174  Using textual strings for configuration is something I find far more
175  attractive. Plan 9 has shown that this approach has no real limits and
176  suffices for configuration tasks. The Linux kernel does more limited use
177  of strings for configuration, but still depends on them. Strings are
178  easier to read and work with than binary structures, and more important, a
179  lot easier to deal with when things start going wrong.
180  
181  The proposed solution:
182  
183  What follows are three possible ideas for specifying superio resources and
184  their settings.
185  
186  A common part of the new idea is to eliminate the common superio
187  structure, due to the many variations in chips, and make it invisible
188  outside a given superio source file -- the superio structure is now
189  private to a given superio. Thus, sis/950/superio.c would contain its own
190  superio structure definitions, and also might contain more than once
191  instance of these structures (consider a board with 2 sis 950 chips).
192  
193  The control structure would change as follows:
194  struct superio_control {
195    int (*create)(struct superio *s);
196    void (*pre_pci_init)(struct superio *s);
197    void (*init)(struct superio *s);
198    void (*finishup)(struct superio *s);
199    unsigned int defaultport;     /* the defaultport. Can be overridden
200                                   * by commands in config
201                                   */
202    // This is the print name for debugging
203    char *name;
204  };
205  
206  I.e. we add a new function for creating the superio.
207  
208  Communication of superio settings from linuxbios to the superio would be
209  via textual strings. The superio structure becomes this:
210  
211  struct superio {
212          struct superio_control *super; // the ops for the device.
213          unsigned int port; // if non-zero, overrides the default port
214  	struct configuration *config;
215  };
216  
217  
218  So now the question becomes, what is the configuration structure?
219  There are several choices. The simplest, from my point of view, are
220  keyword-value pairs:
221  struct configuration {
222  	const char *keyword;
223  	const char *value;
224  };
225  
226  These get filled in by the config tool as before. The linuxbios library can
227  then provide a generic parsing function for the superios to use.
228  
229  The remaining question is how should the superio command look in
230  freebios2?
231  
232  superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
233  
234  or
235  
236  superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1"
237  
238  or
239  
240  superio sis/950 ((com1 115200 8n1) (lpt 1))
241  
242  So,  my questions:
243  
244  1. Does this new scheme look workable. If not, what needs to change?
245  2. What should the 'struct configuration' be? does keyword/value work?
246  3. what should the superio command look like?
247  
248  Comments welcome.
249  
250  I'd like to adopt this "RFC" approach for freebios2 as much as we can.
251  There was a lot of give-and-take in the early days of linuxbios about
252  structure and it proved useful. There's a lot that will start happening in
253  freebios2 now, and we need to try to make sure it will work for everyone.
254  
255  Those of you who are doing mainboards, please look at freebios2 and see
256  how it looks for you. There's a lot of good work that has been done (not
257  by me so far, thanks Eric and Stefan), and more that needs to be done.
258  Consider trying out romcc as an "assembly code killer". See how it fits
259  together and if you can work with it or need changes. Bring comments back
260  to this list.
261  
262  thanks
263  
264  ron
265  
266  \end{verbatim}