doc/driver-model/UDM-serial.txt

   1 The U-Boot Driver Model Project
   2 ===============================
   3 Serial I/O analysis
   4 ===================
   5 Marek Vasut <marek.vasut@gmail.com>
   6 2012-02-20
   7
   8 I) Overview
   9 -----------
  10
  11 The serial port support currently requires the driver to export the following
  12 functions:
  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
  21 The simpliest implementation, supporting only one port, simply defines these six
  22 functions and calls them. Such calls are scattered all around U-Boot, especiall
  23 serial_putc(), serial_puts(), serial_tstc() and serial_getc(). The serial_init()
  24 and serial_setbrg() are often called from platform-dependent places.
  25
  26 It's important to consider current implementation of CONFIG_SERIAL_MULTI though.
  27 This resides in common/serial.c and behaves as a multiplexer for serial ports.
  28 This, by calling serial_assign(), allows user to switch I/O from one serial port
  29 to another. Though the environmental variables "stdin", "stdout", "stderr"
  30 remain set to "serial".
  31
  32 These variables are managed by the IOMUX. This resides in common/iomux.c and
  33 manages all console input/output from U-Boot. For serial port, only one IOMUX is
  34 always registered, called "serial" and the switching of different serial ports
  35 is done by code in common/serial.c.
  36
  37 On a final note, it's important to mention function default_serial_console(),
  38 which is platform specific and reports the default serial console for the
  39 platform, unless proper environment variable overrides this.
  40
  41 II) Approach
  42 ------------
  43
  44 Drivers not using CONFIG_SERIAL_MULTI already will have to be converted to
  45 similar approach. The probe() function of a driver will call a function
  46 registering the driver with a STDIO subsystem core, stdio_device_register().
  47
  48 The serial_init() function will now be replaced by probe() function of the
  49 driver, the rest of the components of the driver will be converted to standard
  50 STDIO driver calls. See [ UDM-stdio.txt ] for details.
  51
  52 The serial_setbrg() function depends on global data pointer. This is wrong,
  53 since there is likely to be user willing to configure different baudrate on two
  54 different serial ports. The function will be replaced with STDIO's "conf()"
  55 call, with STDIO_CONFIG_SERIAL_BAUDRATE argument.
  56
  57 III) 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   ------------------
  89   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
  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
  99   10) s3c64xx.c
 100   -------------
 101   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 102
 103   11) sandbox.c
 104   -------------
 105   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 106
 107   12) serial.c
 108   ------------
 109   This is a complementary part of NS16550 UART driver, see above.
 110
 111   13) serial_clps7111.c
 112   ---------------------
 113   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 114
 115   14) serial_imx.c
 116   ----------------
 117   No support for CONFIG_SERIAL_MULTI. Simple conversion possible. This driver
 118   might be removed in favor of serial_mxc.c .
 119
 120   15) serial_ixp.c
 121   ----------------
 122   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 123
 124   16) serial_ks8695.c
 125   -------------------
 126   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 127
 128   17) serial_lh7a40x.c
 129   --------------------
 130   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 131
 132   18) serial_lpc2292.c
 133   --------------------
 134   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 135
 136   19) serial_max3100.c
 137   --------------------
 138   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 139
 140   20) serial_mxc.c
 141   ----------------
 142   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 143
 144   21) serial_netarm.c
 145   -------------------
 146   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 147
 148   22) serial_pl01x.c
 149   ------------------
 150   No support for CONFIG_SERIAL_MULTI. Simple conversion possible, though this
 151   driver in fact contains two drivers in total.
 152
 153   23) serial_pxa.c
 154   ----------------
 155   This driver is a bit complicated, but due to clean support for
 156   CONFIG_SERIAL_MULTI, there are no expected obstructions throughout the
 157   conversion process.
 158
 159   24) serial_s3c24x0.c
 160   --------------------
 161   This driver, being quite ad-hoc might need some work to bring back to shape.
 162
 163   25) serial_s3c44b0.c
 164   --------------------
 165   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 166
 167   26) serial_s5p.c
 168   ----------------
 169   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 170
 171   27) serial_sa1100.c
 172   -------------------
 173   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 174
 175   28) serial_sh.c
 176   ---------------
 177   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 178
 179   29) serial_xuartlite.c
 180   ----------------------
 181   No support for CONFIG_SERIAL_MULTI. Simple conversion possible.
 182
 183   30) usbtty.c
 184   ------------
 185   This driver seems very complicated and entangled with USB framework. The
 186   conversion might be complicated here.
 187
 188   31) arch/powerpc/cpu/mpc512x/serial.c
 189   -------------------------------------
 190   This driver supports CONFIG_SERIAL_MULTI. This driver will need to be moved to
 191   proper place.