Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 5 | change. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 6 | \end{abstract} |
| 7 | |
| 8 | \section{Scope} |
| 9 | This document defines how LinuxBIOS programmers can specify chips that |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 13 | |
| 14 | \section{Goals} |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 15 | The goals of the new chip architecture are these: |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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} |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 34 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 35 | The path defines the access mechanism to the chip. |
| 36 | It is optional. If present, it overrides the default path to the chip. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 37 | |
| 38 | The configuration defines chip-specific configuration details, and is also |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 39 | optional. Note that an empty configuration will leave the chip with |
| 40 | no enabled resources. This may be desirable in some cases. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 47 | a common struct containing information about |
| 48 | each individual chip and an array of pointers to these structures. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 49 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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 |
Uwe Hermann | f28674e | 2006-11-01 12:52:49 +0000 | [diff] [blame] | 54 | two structs, one called superio_ite_xyz_control and one called |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 55 | superio_ite_xyz_init. The control struct is initialized from the |
| 56 | chip name and path information, and has a pointer to the |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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: |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 72 | |
| 73 | Overview: |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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 |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 81 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 82 | Specification of superio control parameters is done by a configuration |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 83 | line such as: |
| 84 | |
| 85 | nsuperio sis/950 com1={1} floppy=1 lpt=1 |
| 86 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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). |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 99 | // We think it's easier to set up from python if it is not an |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 117 | is called nsuperio.c, is created for each mainboard you build, only |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 118 | appears in the build directory, and looks like this: |
| 119 | |
| 120 | === |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 121 | extern struct superio_control superio_winbond_w83627hf_control; |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 122 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 123 | struct superio superio_winbond_w83627hf= { |
| 124 | &superio_winbond_w83627hf_control, |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 138 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 139 | The control structure is used to define how to access the superio for |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 158 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 159 | This approach was inspired by and borrows heavily on the Plan 9 kernel |
| 160 | configuration tools. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 173 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 180 | |
| 181 | The proposed solution: |
| 182 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 183 | What follows are three possible ideas for specifying superio resources and |
| 184 | their settings. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 206 | I.e. we add a new function for creating the superio. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 207 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 208 | Communication of superio settings from linuxbios to the superio would be |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 218 | So now the question becomes, what is the configuration structure? |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 228 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 229 | The remaining question is how should the superio command look in |
| 230 | freebios2? |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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? |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 245 | 2. What should the 'struct configuration' be? does keyword/value work? |
| 246 | 3. what should the superio command look like? |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 247 | |
| 248 | Comments welcome. |
| 249 | |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 250 | I'd like to adopt this "RFC" approach for freebios2 as much as we can. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 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 |
Stefan Reinauer | 14e2277 | 2010-04-27 06:56:47 +0000 | [diff] [blame] | 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. |
Ronald G. Minnich | fd958ce | 2003-06-06 14:35:36 +0000 | [diff] [blame] | 261 | |
| 262 | thanks |
| 263 | |
| 264 | ron |
| 265 | |
| 266 | \end{verbatim} |