blob: 156627b515e69d19a85d79cb65a153a57128c481 [file] [log] [blame]
Marek Vasut15c69352012-08-08 01:42:17 +00001The U-Boot Driver Model Project
2===============================
3I/O system analysis
4===================
5Marek Vasut <marek.vasut@gmail.com>
62012-02-20
7
8I) Overview
9-----------
10
11The console input and output is currently done using the STDIO subsystem in
12U-Boot. The design of this subsystem is already flexible enough to be easily
13converted to new driver model approach. Minor changes will need to be done
14though.
15
16Each device that wants to register with STDIO subsystem has to define struct
17stdio_dev, defined in include/stdio_dev.h and containing the following fields:
18
19struct stdio_dev {
Wolfgang Denk93e14592013-10-04 17:43:24 +020020 int flags; /* Device flags: input/output/system */
21 int ext; /* Supported extensions */
22 char name[16]; /* Device name */
Marek Vasut15c69352012-08-08 01:42:17 +000023
24/* GENERAL functions */
25
Wolfgang Denk93e14592013-10-04 17:43:24 +020026 int (*start) (void); /* To start the device */
27 int (*stop) (void); /* To stop the device */
Marek Vasut15c69352012-08-08 01:42:17 +000028
29/* OUTPUT functions */
30
Wolfgang Denk93e14592013-10-04 17:43:24 +020031 void (*putc) (const char c); /* To put a char */
32 void (*puts) (const char *s); /* To put a string (accelerator) */
Marek Vasut15c69352012-08-08 01:42:17 +000033
34/* INPUT functions */
35
Wolfgang Denk93e14592013-10-04 17:43:24 +020036 int (*tstc) (void); /* To test if a char is ready... */
37 int (*getc) (void); /* To get that char */
Marek Vasut15c69352012-08-08 01:42:17 +000038
39/* Other functions */
40
Wolfgang Denk93e14592013-10-04 17:43:24 +020041 void *priv; /* Private extensions */
42 struct list_head list;
Marek Vasut15c69352012-08-08 01:42:17 +000043};
44
45Currently used flags are DEV_FLAGS_INPUT, DEV_FLAGS_OUTPUT and DEV_FLAGS_SYSTEM,
46extensions being only one, the DEV_EXT_VIDEO.
47
48The private extensions are now used as a per-device carrier of private data and
49finally list allows this structure to be a member of linked list of STDIO
50devices.
51
52The STDIN, STDOUT and STDERR routing is handled by environment variables
53"stdin", "stdout" and "stderr". By configuring the variable to the name of a
54driver, functions of such driver are called to execute that particular
55operation.
56
57II) Approach
58------------
59
60 1) Similarity of serial, video and keyboard drivers
61 ---------------------------------------------------
62
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.
69
70 2) Unification of serial, video and keyboard drivers
71 ----------------------------------------------------
72
73 Every STDIO device would register a structure containing operation it supports
74 with the STDIO core by calling:
75
76 int stdio_device_register(struct instance *i, struct stdio_device_ops *o);
77
78 The structure being defined as follows:
79
80 struct stdio_device_ops {
81 void (*putc)(struct instance *i, const char c);
82 void (*puts)(struct instance *i, const char *s); /* OPTIONAL */
83
84 int (*tstc)(struct instance *i);
85 int (*getc)(struct instance *i);
86
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);
90 };
91
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.
95
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.
99
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.
104
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
109 STDIO devices.
110
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
115 following options:
116
117 enum stdio_config {
118 STDIO_CONFIG_SERIAL_BAUDRATE,
119 };
120
121 3) Transformation of stdio routing
122 ----------------------------------
123
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:
128
129 struct stdio_device_node {
130 struct instance *i;
131 struct stdio_device_ops *ops;
132 uint8_t id;
133 uint8_t flags;
134 struct list_head list;
135 }
136
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:
140
141 STDIO_FLG_STDIN ..... This device will be used as an input device. All input
Wolfgang Denk93e14592013-10-04 17:43:24 +0200142 from all devices with this flag set will be received
Marek Vasut15c69352012-08-08 01:42:17 +0000143 and passed to the upper layers.
144 STDIO_FLG_STDOUT .... This device will be used as an output device. All
Wolfgang Denk93e14592013-10-04 17:43:24 +0200145 output sent to stdout will be routed to all devices
Marek Vasut15c69352012-08-08 01:42:17 +0000146 with this flag set.
147 STDIO_FLG_STDERR .... This device will be used as an standard error output
Wolfgang Denk93e14592013-10-04 17:43:24 +0200148 device. All output sent to stderr will be routed to
Marek Vasut15c69352012-08-08 01:42:17 +0000149 all devices with this flag set.
150
151 The "list" member of this structure allows to have a linked list of all
152 registered STDIO devices.
153
154III) Analysis of in-tree drivers
155--------------------------------
156
157For in-depth analysis of serial port drivers, refer to [ UDM-serial.txt ].
158For in-depth analysis of keyboard drivers, refer to [ UDM-keyboard.txt ].
159For in-depth analysis of video drivers, refer to [ UDM-video.txt ].
160
Masahiro Yamada566c6e42013-09-24 10:32:04 +0900161 arch/blackfin/cpu/jtag-console.c
162 --------------------------------
Marek Vasut15c69352012-08-08 01:42:17 +0000163 This driver is a classic STDIO driver, no problem with conversion is expected.
164
Masahiro Yamada566c6e42013-09-24 10:32:04 +0900165 board/mpl/pati/pati.c
166 ---------------------
Marek Vasut15c69352012-08-08 01:42:17 +0000167 This driver registers with the STDIO framework, though it uses a lot of ad-hoc
168 stuff which will need to be sorted out.
169
Masahiro Yamada566c6e42013-09-24 10:32:04 +0900170 board/netphone/phone_console.c
171 ------------------------------
Marek Vasut15c69352012-08-08 01:42:17 +0000172 This driver is a classic STDIO driver, no problem with conversion is expected.
173
Masahiro Yamada566c6e42013-09-24 10:32:04 +0900174 drivers/net/netconsole.c
175 ------------------------
Marek Vasut15c69352012-08-08 01:42:17 +0000176 This driver is a classic STDIO driver, no problem with conversion is expected.
177
178IV) Other involved files (To be removed)
179----------------------------------------
180
181common/cmd_console.c
182common/cmd_log.c
183common/cmd_terminal.c
184common/console.c
185common/fdt_support.c
186common/iomux.c
187common/lcd.c
188common/serial.c
189common/stdio.c
190common/usb_kbd.c
191doc/README.iomux