UDM-stdio.txt 7.1 KB

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