documentation/RFC/chip.tex

   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 initalized. 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 seperate 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 libary 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}