Gitiles
Code Review Sign In
gerrit.devboardsforandroid.linaro.org / platform / external / u-boot / 49493cb7144f0c51a5aaecc75fcd1b3f157633ba / . / doc / driver-model / UDM-serial.txt
blob: 1011c32d18b914b66778a463c362eb04e737e102 [file] [log] [blame]
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]1The U-Boot Driver Model Project
2===============================
3Serial I/O analysis
4===================
5Marek Vasut <marek.vasut@gmail.com>
62012-02-20
7
8I) Overview
9-----------
10
11The serial port support currently requires the driver to export the following
12functions:
13
14 serial_putc() ...... Output a character
15 serial_puts() ...... Output string, often done using serial_putc()
16 serial_tstc() ...... Test if incoming character is in a buffer
17 serial_getc() ...... Retrieve incoming character
18 serial_setbrg() .... Configure port options
19 serial_init() ...... Initialize the hardware
20
21The simpliest implementation, supporting only one port, simply defines these six
22functions and calls them. Such calls are scattered all around U-Boot, especiall
23serial_putc(), serial_puts(), serial_tstc() and serial_getc(). The serial_init()
24and serial_setbrg() are often called from platform-dependent places.
25
26It's important to consider current implementation of CONFIG_SERIAL_MULTI though.
27This resides in common/serial.c and behaves as a multiplexer for serial ports.
28This, by calling serial_assign(), allows user to switch I/O from one serial port
29to another. Though the environmental variables "stdin", "stdout", "stderr"
30remain set to "serial".
31
32These variables are managed by the IOMUX. This resides in common/iomux.c and
33manages all console input/output from U-Boot. For serial port, only one IOMUX is
34always registered, called "serial" and the switching of different serial ports
35is done by code in common/serial.c.
36
37On a final note, it's important to mention function default_serial_console(),
38which is platform specific and reports the default serial console for the
39platform, unless proper environment variable overrides this.
40
41II) Approach
42------------
43
44Drivers not using CONFIG_SERIAL_MULTI already will have to be converted to
45similar approach. The probe() function of a driver will call a function
46registering the driver with a STDIO subsystem core, stdio_device_register().
47
48The serial_init() function will now be replaced by probe() function of the
49driver, the rest of the components of the driver will be converted to standard
50STDIO driver calls. See [ UDM-stdio.txt ] for details.
51
52The serial_setbrg() function depends on global data pointer. This is wrong,
53since there is likely to be user willing to configure different baudrate on two
54different serial ports. The function will be replaced with STDIO's "conf()"
55call, with STDIO_CONFIG_SERIAL_BAUDRATE argument.
56
57III) Analysis of in-tree drivers
58--------------------------------
59
60 1) altera_jtag_uart.c
61 ---------------------
62 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
63
64 2) altera_uart.c
65 ----------------
66 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
67
68 3) arm_dcc.c
69 ------------
70 No support for CONFIG_SERIAL_MULTI. Simple conversion possible, unless used
71 with CONFIG_ARM_DCC_MULTI. Then it registers another separate IOMUX.
72
73 4) atmel_usart.c
74 ----------------
75 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
76
77 5) mcfuart.c
78 ------------
79 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
80
81 6) ns16550.c
82 ------------
83 This driver seems complicated and certain consideration will need to be made
84 during conversion. This driver is implemented in very universal manner,
85 therefore it'll be necessary to properly design it's platform_data.
86
87 7) ns9750_serial.c
88 ------------------
Wolfgang Denk4cfc6112012-11-29 02:53:29 +0000[diff] [blame]89 Unmaintained port. Code got removed.
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]90
91 8) opencores_yanu.c
92 -------------------
93 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
94
95 9) s3c4510b_uart.c
96 ------------------
97 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
98
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]99 10) sandbox.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]100 -------------
101 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
102
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]103 11) serial.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]104 ------------
105 This is a complementary part of NS16550 UART driver, see above.
106
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]107 12) serial_clps7111.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]108 ---------------------
109 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
110
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]111 13) serial_imx.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]112 ----------------
113 No support for CONFIG_SERIAL_MULTI. Simple conversion possible. This driver
114 might be removed in favor of serial_mxc.c .
115
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]116 14) serial_ixp.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]117 ----------------
118 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
119
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]120 15) serial_ks8695.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]121 -------------------
122 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
123
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]124 16) serial_max3100.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]125 --------------------
126 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
127
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]128 17) serial_mxc.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]129 ----------------
130 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
131
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]132 18) serial_netarm.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]133 -------------------
134 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
135
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]136 19) serial_pl01x.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]137 ------------------
138 No support for CONFIG_SERIAL_MULTI. Simple conversion possible, though this
139 driver in fact contains two drivers in total.
140
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]141 20) serial_pxa.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]142 ----------------
143 This driver is a bit complicated, but due to clean support for
144 CONFIG_SERIAL_MULTI, there are no expected obstructions throughout the
145 conversion process.
146
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]147 21) serial_s3c24x0.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]148 --------------------
149 This driver, being quite ad-hoc might need some work to bring back to shape.
150
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]151 22) serial_s3c44b0.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]152 --------------------
153 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
154
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]155 23) serial_s5p.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]156 ----------------
157 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
158
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]159 24) serial_sa1100.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]160 -------------------
161 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
162
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]163 25) serial_sh.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]164 ---------------
165 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
166
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]167 26) serial_xuartlite.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]168 ----------------------
169 No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
170
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]171 27) usbtty.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]172 ------------
173 This driver seems very complicated and entangled with USB framework. The
174 conversion might be complicated here.
175
Benoît Thébaudeaue5323222013-04-11 09:36:00 +0000[diff] [blame]176 28) arch/powerpc/cpu/mpc512x/serial.c
Marek Vasut15c69352012-08-08 01:42:17 +0000[diff] [blame]177 -------------------------------------
178 This driver supports CONFIG_SERIAL_MULTI. This driver will need to be moved to
179 proper place.