blob: 01f40c1e803a2e19c905dd4e29dc7a2e1eae0129 [file] [log] [blame]
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +00001 RFC for the chip specification architecture
2
3\begin{abstract}
4At the end of this document is the original message that motivated the
Stefan Reinauer14e22772010-04-27 06:56:47 +00005change.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +00006\end{abstract}
7
8\section{Scope}
9This document defines how LinuxBIOS programmers can specify chips that
Stefan Reinauer14e22772010-04-27 06:56:47 +000010are used, specified, and initalized. The current scope is for superio
11chips, but the architecture should allow for specification of other chips such
12as southbridges. Multiple chips of same or different type are supported.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000013
14\section{Goals}
Stefan Reinauer14e22772010-04-27 06:56:47 +000015The goals of the new chip architecture are these:
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000016\begin{itemize}
Jonathan Neuschäfer8ee93ae262018-04-09 13:05:29 +020017\item separate implementation details from specification in the Config file
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000018(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
21as possible
22\item allow unique register-set-specifiers for each chip
23\end{itemize}
24
25\section{Specification in the Config file}
26The specification looks like this:
27\begin{verbatim}
28chip <name> [path=<path>] ["<configuration>"]
29\end{verbatim}
Stefan Reinauer14e22772010-04-27 06:56:47 +000030The 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
32chip is derived from the first pathname component of the name, and the chip
33configuration is derived from the following components.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000034
Stefan Reinauer14e22772010-04-27 06:56:47 +000035The path defines the access mechanism to the chip.
36It is optional. If present, it overrides the default path to the chip.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000037
38The configuration defines chip-specific configuration details, and is also
Stefan Reinauer14e22772010-04-27 06:56:47 +000039optional. Note that an empty configuration will leave the chip with
40no enabled resources. This may be desirable in some cases.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000041
42\section{Results of specifying a chip}
43
44When one or more chips are specified, the data about the chips
45is saved until the entire file is parsed. At this point, the config tool
46creates a file in the build directory called chip.c This file contains
Stefan Reinauer14e22772010-04-27 06:56:47 +000047a common struct containing information about
48each individual chip and an array of pointers to these structures.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000049
Stefan Reinauer14e22772010-04-27 06:56:47 +000050For each chip, there are two structures. The structures contain control
51information for the chip, and register initialization information. The
52names of the structures are derived by ``flattening'' the chip name,
53as in the current linuxbios. For example, superio/ite/xyz uses
Uwe Hermannf28674e2006-11-01 12:52:49 +000054two structs, one called superio_ite_xyz_control and one called
Stefan Reinauer14e22772010-04-27 06:56:47 +000055superio_ite_xyz_init. The control struct is initialized from the
56chip name and path information, and has a pointer to the
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000057config struct. The config struct is initialized from the quote string
58
59\begin{verbatim}
60From rminnich@lanl.gov Fri May 16 10:34:13 2003
61Date: Tue, 13 May 2003 08:11:46 -0600 (MDT)
62From: ron minnich <rminnich@lanl.gov>
63To: linuxbios@clustermatic.org
64Subject: RFC:new superio proposal
65
66Abstract:
Stefan Reinauer14e22772010-04-27 06:56:47 +000067 The superio architecture for linuxbios has worked for the last 2
68years but is being stretched to the limit by the changes in superio chips.
69The architecture depended on superio resources being relatively constant
70between chips, but this assumption no longer holds. In this document we
71propose several alternatives and solicit comments.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000072
73Overview:
Stefan Reinauer14e22772010-04-27 06:56:47 +000074The superio architecture in linuxbios was developed over time, and
75modified as circumstances required. In the beginning it was relatively
76simple and assumed only one superio per mainboard. The latest version
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000077allows an arbitrary number of superios per mainboard, and allows complete
78specification of the superio base I/O address along with the specification
Stefan Reinauer14e22772010-04-27 06:56:47 +000079of reasonable default valures for both the base I/O address and the
80superio parameters such as serial enable, baud rate, and so on.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000081
Stefan Reinauer14e22772010-04-27 06:56:47 +000082Specification of superio control parameters is done by a configuration
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000083line such as:
84
85nsuperio sis/950 com1={1} floppy=1 lpt=1
86
Stefan Reinauer14e22772010-04-27 06:56:47 +000087This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
88to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
89default values.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +000090
91While it is not obvious, these configuration parameters are fragments of a
92C initializer. The initializers are used to build a statically initialized
93structure of this type:
94
95struct 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 Reinauer14e22772010-04-27 06:56:47 +000099 // We think it's easier to set up from python if it is not an
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000100 // 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
115These structures are, in turn, created and statically initialized by a
116config-tool-generated structure that defines all the superios. This file
Stefan Reinauer14e22772010-04-27 06:56:47 +0000117is called nsuperio.c, is created for each mainboard you build, only
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000118appears in the build directory, and looks like this:
119
120===
Stefan Reinauer14e22772010-04-27 06:56:47 +0000121extern struct superio_control superio_winbond_w83627hf_control;
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000122
Stefan Reinauer14e22772010-04-27 06:56:47 +0000123struct superio superio_winbond_w83627hf= {
124 &superio_winbond_w83627hf_control,
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000125 .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
126
127struct superio *all_superio[] = {&superio_winbond_w83627hf,
128};
129
130unsigned long nsuperio = 1;
131===
132
133This example shows a board with one superio (nsuperio). The superio
Stefan Reinauer14e22772010-04-27 06:56:47 +0000134consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
135and hwmonitor enabled. Note that this structure also allows for
136over-riding the default superio base, although that capability is rarely
137used.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000138
Stefan Reinauer14e22772010-04-27 06:56:47 +0000139The control structure is used to define how to access the superio for
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000140purposes of control. It looks like this:
141===
142struct 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 Reinauer14e22772010-04-27 06:56:47 +0000154There 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
156resources BEFORE pci scan); init, called during the 'middle' phase of
157hardwaremain; and finishup, called before the payload is loaded.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000158
Stefan Reinauer14e22772010-04-27 06:56:47 +0000159This approach was inspired by and borrows heavily on the Plan 9 kernel
160configuration tools.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000161
162The problem:
163
164When the first version of the superio structure came out it was much
165smaller. It has grown and in the limit this structure is the union of all
166possibly superio chips. Obviously, in the long term, this is not
167practical: we can not anticipate all possible superio chips for all time.
168
Stefan Reinauer14e22772010-04-27 06:56:47 +0000169The common PC BIOS solution to this type of problem is to continue with
170binary structures but add version numbers to them, so that all code that
171uses a given structure has to check the version number. Personally, I find
172this grotesque and would rather not work this way.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000173
Stefan Reinauer14e22772010-04-27 06:56:47 +0000174Using textual strings for configuration is something I find far more
175attractive. Plan 9 has shown that this approach has no real limits and
176suffices for configuration tasks. The Linux kernel does more limited use
177of strings for configuration, but still depends on them. Strings are
178easier to read and work with than binary structures, and more important, a
179lot easier to deal with when things start going wrong.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000180
181The proposed solution:
182
Stefan Reinauer14e22772010-04-27 06:56:47 +0000183What follows are three possible ideas for specifying superio resources and
184their settings.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000185
186A common part of the new idea is to eliminate the common superio
187structure, due to the many variations in chips, and make it invisible
188outside a given superio source file -- the superio structure is now
189private to a given superio. Thus, sis/950/superio.c would contain its own
190superio structure definitions, and also might contain more than once
191instance of these structures (consider a board with 2 sis 950 chips).
192
193The control structure would change as follows:
194struct 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 Reinauer14e22772010-04-27 06:56:47 +0000206I.e. we add a new function for creating the superio.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000207
Stefan Reinauer14e22772010-04-27 06:56:47 +0000208Communication of superio settings from linuxbios to the superio would be
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000209via textual strings. The superio structure becomes this:
210
211struct 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 Reinauer14e22772010-04-27 06:56:47 +0000218So now the question becomes, what is the configuration structure?
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000219There are several choices. The simplest, from my point of view, are
220keyword-value pairs:
221struct configuration {
222 const char *keyword;
223 const char *value;
224};
225
Jonathan Neuschäfer8ee93ae262018-04-09 13:05:29 +0200226These get filled in by the config tool as before. The linuxbios library can
Stefan Reinauer14e22772010-04-27 06:56:47 +0000227then provide a generic parsing function for the superios to use.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000228
Stefan Reinauer14e22772010-04-27 06:56:47 +0000229The remaining question is how should the superio command look in
230freebios2?
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000231
232superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
233
234or
235
236superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1"
237
238or
239
240superio sis/950 ((com1 115200 8n1) (lpt 1))
241
242So, my questions:
243
2441. Does this new scheme look workable. If not, what needs to change?
Stefan Reinauer14e22772010-04-27 06:56:47 +00002452. What should the 'struct configuration' be? does keyword/value work?
2463. what should the superio command look like?
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000247
248Comments welcome.
249
Stefan Reinauer14e22772010-04-27 06:56:47 +0000250I'd like to adopt this "RFC" approach for freebios2 as much as we can.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000251There was a lot of give-and-take in the early days of linuxbios about
252structure and it proved useful. There's a lot that will start happening in
253freebios2 now, and we need to try to make sure it will work for everyone.
254
255Those of you who are doing mainboards, please look at freebios2 and see
256how it looks for you. There's a lot of good work that has been done (not
Stefan Reinauer14e22772010-04-27 06:56:47 +0000257by me so far, thanks Eric and Stefan), and more that needs to be done.
258Consider trying out romcc as an "assembly code killer". See how it fits
259together and if you can work with it or need changes. Bring comments back
260to this list.
Ronald G. Minnichfd958ce2003-06-06 14:35:36 +0000261
262thanks
263
264ron
265
266\end{verbatim}