1 The U-Boot Driver Model Project
2 ===============================
5 Marek Vasut <marek.vasut@gmail.com>
11 The console input and output is currently done using the STDIO subsystem in
12 U-Boot. The design of this subsystem is already flexible enough to be easily
13 converted to new driver model approach. Minor changes will need to be done
16 Each device that wants to register with STDIO subsystem has to define struct
17 stdio_dev, defined in include/stdio_dev.h and containing the following fields:
20 int flags; /* Device flags: input/output/system */
21 int ext; /* Supported extensions */
22 char name[16]; /* Device name */
24 /* GENERAL functions */
26 int (*start) (void); /* To start the device */
27 int (*stop) (void); /* To stop the device */
29 /* OUTPUT functions */
31 void (*putc) (const char c); /* To put a char */
32 void (*puts) (const char *s); /* To put a string (accelerator) */
36 int (*tstc) (void); /* To test if a char is ready... */
37 int (*getc) (void); /* To get that char */
41 void *priv; /* Private extensions */
42 struct list_head list;
45 Currently used flags are DEV_FLAGS_INPUT, DEV_FLAGS_OUTPUT and DEV_FLAGS_SYSTEM,
46 extensions being only one, the DEV_EXT_VIDEO.
48 The private extensions are now used as a per-device carrier of private data and
49 finally list allows this structure to be a member of linked list of STDIO
52 The STDIN, STDOUT and STDERR routing is handled by environment variables
53 "stdin", "stdout" and "stderr". By configuring the variable to the name of a
54 driver, functions of such driver are called to execute that particular
60 1) Similarity of serial, video and keyboard drivers
61 ---------------------------------------------------
63 All of these drivers can be unified under the STDIO subsystem if modified
64 slightly. The serial drivers basically define both input and output functions
65 and need function to configure baudrate. The keyboard drivers provide only
66 input. On the other hand, video drivers provide output, but need to be
67 configured in certain way. This configuration might be dynamic, therefore the
68 STDIO has to be modified to provide such flexibility.
70 2) Unification of serial, video and keyboard drivers
71 ----------------------------------------------------
73 Every STDIO device would register a structure containing operation it supports
74 with the STDIO core by calling:
76 int stdio_device_register(struct instance *i, struct stdio_device_ops *o);
78 The structure being defined as follows:
80 struct stdio_device_ops {
81 void (*putc)(struct instance *i, const char c);
82 void (*puts)(struct instance *i, const char *s); /* OPTIONAL */
84 int (*tstc)(struct instance *i);
85 int (*getc)(struct instance *i);
87 int (*init)(struct instance *i);
88 int (*exit)(struct instance *i);
89 int (*conf)(struct instance *i, enum stdio_config c, const void *data);
92 The "putc()" function will emit a character, the "puts()" function will emit a
93 string. If both of these are set to NULL, the device is considered STDIN only,
94 aka input only device.
96 The "getc()" retrieves a character from a STDIN device, while "tstc()" tests
97 if there is a character in the buffer of STDIN device. In case these two are
98 set to NULL, this device is STDOUT / STDERR device.
100 Setting all "putc()", "puts()", "getc()" and "tstc()" calls to NULL isn't an
101 error condition, though such device does nothing. By instroducing tests for
102 these functions being NULL, the "flags" and "ext" fields from original struct
103 stdio_dev can be eliminated.
105 The "init()" and "exit()" calls are replacement for "start()" and "exit()"
106 calls in the old approach. The "priv" part of the old struct stdio_dev will be
107 replaced by common private data in the driver model and the struct list_head
108 list will be eliminated by introducing common STDIO core, that tracks all the
111 Lastly, the "conf()" call will allow the user to configure various options of
112 the driver. The enum stdio_config contains all possible configuration options
113 available to the STDIO devices, const void *data being the argument to be
114 configured. Currently, the enum stdio_config will contain at least the
118 STDIO_CONFIG_SERIAL_BAUDRATE,
121 3) Transformation of stdio routing
122 ----------------------------------
124 By allowing multiple instances of drivers, the environment variables "stdin",
125 "stdout" and "stderr" can no longer be set to the name of the driver.
126 Therefore the STDIO core, tracking all of the STDIO devices in the system will
127 need to have a small amount of internal data for each device:
129 struct stdio_device_node {
131 struct stdio_device_ops *ops;
134 struct list_head list;
137 The "id" is the order of the instance of the same driver. The "flags" variable
138 allows multiple drivers to be used at the same time and even for different
139 purpose. The following flags will be defined:
141 STDIO_FLG_STDIN ..... This device will be used as an input device. All input
142 from all devices with this flag set will be received
143 and passed to the upper layers.
144 STDIO_FLG_STDOUT .... This device will be used as an output device. All
145 output sent to stdout will be routed to all devices
147 STDIO_FLG_STDERR .... This device will be used as an standard error output
148 device. All output sent to stderr will be routed to
149 all devices with this flag set.
151 The "list" member of this structure allows to have a linked list of all
152 registered STDIO devices.
154 III) Analysis of in-tree drivers
155 --------------------------------
157 For in-depth analysis of serial port drivers, refer to [ UDM-serial.txt ].
158 For in-depth analysis of keyboard drivers, refer to [ UDM-keyboard.txt ].
159 For in-depth analysis of video drivers, refer to [ UDM-video.txt ].
161 1) arch/blackfin/cpu/jtag-console.c
162 -----------------------------------
163 This driver is a classic STDIO driver, no problem with conversion is expected.
165 2) board/mpl/pati/pati.c
166 ------------------------
167 This driver registers with the STDIO framework, though it uses a lot of ad-hoc
168 stuff which will need to be sorted out.
170 3) board/netphone/phone_console.c
171 ---------------------------------
172 This driver is a classic STDIO driver, no problem with conversion is expected.
174 4) drivers/net/netconsole.c
175 ---------------------------
176 This driver is a classic STDIO driver, no problem with conversion is expected.
178 IV) Other involved files (To be removed)
179 ----------------------------------------
183 common/cmd_terminal.c