doc/driver-model/UDM-stdio.txt - uboot/armada - Git at Google

 The U-Boot Driver Model Project
 ===============================
 I/O system analysis
 ===================
 Marek Vasut <marek.vasut@gmail.com>
 2012-02-20

 I) Overview
 -----------

 The console input and output is currently done using the STDIO subsystem in
 U-Boot. The design of this subsystem is already flexible enough to be easily
 converted to new driver model approach. Minor changes will need to be done
 though.

 Each device that wants to register with STDIO subsystem has to define struct
 stdio_dev, defined in include/stdio_dev.h and containing the following fields:

 struct stdio_dev {
         int     flags;                  /* Device flags: input/output/system */
         int     ext;                    /* Supported extensions              */
         char    name[16];               /* Device name                       */

 /* GENERAL functions */

         int (*start) (void);            /* To start the device               */
         int (*stop) (void);             /* To stop the device                */

 /* OUTPUT functions */

         void (*putc) (const char c);    /* To put a char                     */
         void (*puts) (const char *s);   /* To put a string (accelerator)     */

 /* INPUT functions */

         int (*tstc) (void);             /* To test if a char is ready...     */
         int (*getc) (void);             /* To get that char                  */

 /* Other functions */

         void *priv;                     /* Private extensions                */
         struct list_head list;
 };

 Currently used flags are DEV_FLAGS_INPUT, DEV_FLAGS_OUTPUT and DEV_FLAGS_SYSTEM,
 extensions being only one, the DEV_EXT_VIDEO.

 The private extensions are now used as a per-device carrier of private data and
 finally list allows this structure to be a member of linked list of STDIO
 devices.

 The STDIN, STDOUT and STDERR routing is handled by environment variables
 "stdin", "stdout" and "stderr". By configuring the variable to the name of a
 driver, functions of such driver are called to execute that particular
 operation.

 II) Approach
 ------------

   1) Similarity of serial, video and keyboard drivers
   ---------------------------------------------------

   All of these drivers can be unified under the STDIO subsystem if modified
   slightly. The serial drivers basically define both input and output functions
   and need function to configure baudrate. The keyboard drivers provide only
   input. On the other hand, video drivers provide output, but need to be
   configured in certain way. This configuration might be dynamic, therefore the
   STDIO has to be modified to provide such flexibility.

   2) Unification of serial, video and keyboard drivers
   ----------------------------------------------------

   Every STDIO device would register a structure containing operation it supports
   with the STDIO core by calling:

     int stdio_device_register(struct instance *i, struct stdio_device_ops *o);

   The structure being defined as follows:

   struct stdio_device_ops {
     void (*putc)(struct instance *i, const char c);
     void (*puts)(struct instance *i, const char *s);    /* OPTIONAL */

     int  (*tstc)(struct instance *i);
     int  (*getc)(struct instance *i);

     int  (*init)(struct instance *i);
     int  (*exit)(struct instance *i);
     int  (*conf)(struct instance *i, enum stdio_config c, const void *data);
   };

   The "putc()" function will emit a character, the "puts()" function will emit a
   string. If both of these are set to NULL, the device is considered STDIN only,
   aka input only device.

   The "getc()" retrieves a character from a STDIN device, while "tstc()" tests
   if there is a character in the buffer of STDIN device. In case these two are
   set to NULL, this device is STDOUT / STDERR device.

   Setting all "putc()", "puts()", "getc()" and "tstc()" calls to NULL isn't an
   error condition, though such device does nothing. By instroducing tests for
   these functions being NULL, the "flags" and "ext" fields from original struct
   stdio_dev can be eliminated.

   The "init()" and "exit()" calls are replacement for "start()" and "exit()"
   calls in the old approach. The "priv" part of the old struct stdio_dev will be
   replaced by common private data in the driver model and the struct list_head
   list will be eliminated by introducing common STDIO core, that tracks all the
   STDIO devices.

   Lastly, the "conf()" call will allow the user to configure various options of
   the driver. The enum stdio_config contains all possible configuration options
   available to the STDIO devices, const void *data being the argument to be
   configured. Currently, the enum stdio_config will contain at least the
   following options:

   enum stdio_config {
     STDIO_CONFIG_SERIAL_BAUDRATE,
   };

   3) Transformation of stdio routing
   ----------------------------------

   By allowing multiple instances of drivers, the environment variables "stdin",
   "stdout" and "stderr" can no longer be set to the name of the driver.
   Therefore the STDIO core, tracking all of the STDIO devices in the system will
   need to have a small amount of internal data for each device:

   struct stdio_device_node {
     struct instance          *i;
     struct stdio_device_ops  *ops;
     uint8_t                  id;
     uint8_t                  flags;
     struct list_head         list;
   }

   The "id" is the order of the instance of the same driver. The "flags" variable
   allows multiple drivers to be used at the same time and even for different
   purpose. The following flags will be defined:

     STDIO_FLG_STDIN ..... This device will be used as an input device. All input
                           from all devices with this flag set will be received
 			  and passed to the upper layers.
     STDIO_FLG_STDOUT .... This device will be used as an output device. All
                           output sent to stdout will be routed to all devices
 			  with this flag set.
     STDIO_FLG_STDERR .... This device will be used as an standard error output
                           device. All output sent to stderr will be routed to
 			  all devices with this flag set.

   The "list" member of this structure allows to have a linked list of all
   registered STDIO devices.

 III) Analysis of in-tree drivers
 --------------------------------

 For in-depth analysis of serial port drivers, refer to [ UDM-serial.txt ].
 For in-depth analysis of keyboard drivers, refer to [ UDM-keyboard.txt ].
 For in-depth analysis of video drivers, refer to [ UDM-video.txt ].

   1) arch/blackfin/cpu/jtag-console.c
   -----------------------------------
   This driver is a classic STDIO driver, no problem with conversion is expected.

   2) board/mpl/pati/pati.c
   ------------------------
   This driver registers with the STDIO framework, though it uses a lot of ad-hoc
   stuff which will need to be sorted out.

   3) board/netphone/phone_console.c
   ---------------------------------
   This driver is a classic STDIO driver, no problem with conversion is expected.

   4) drivers/net/netconsole.c
   ---------------------------
   This driver is a classic STDIO driver, no problem with conversion is expected.

 IV) Other involved files (To be removed)
 ----------------------------------------

 common/cmd_console.c
 common/cmd_log.c
 common/cmd_terminal.c
 common/console.c
 common/fdt_support.c
 common/iomux.c
 common/lcd.c
 common/serial.c
 common/stdio.c
 common/usb_kbd.c
 doc/README.iomux
	The U-Boot Driver Model Project
	===============================
	I/O system analysis
	===================
	Marek Vasut <marek.vasut@gmail.com>
	2012-02-20

	I) Overview
	-----------

	The console input and output is currently done using the STDIO subsystem in
	U-Boot. The design of this subsystem is already flexible enough to be easily
	converted to new driver model approach. Minor changes will need to be done
	though.

	Each device that wants to register with STDIO subsystem has to define struct
	stdio_dev, defined in include/stdio_dev.h and containing the following fields:

	struct stdio_dev {
	int flags; /* Device flags: input/output/system */
	int ext; /* Supported extensions */
	char name[16]; /* Device name */

	/* GENERAL functions */

	int (start) (void); / To start the device */
	int (stop) (void); / To stop the device */

	/* OUTPUT functions */

	void (putc) (const char c); / To put a char */
	void (puts) (const char s); /* To put a string (accelerator) */

	/* INPUT functions */

	int (tstc) (void); / To test if a char is ready... */
	int (getc) (void); / To get that char */

	/* Other functions */

	void priv; / Private extensions */
	struct list_head list;
	};

	Currently used flags are DEV_FLAGS_INPUT, DEV_FLAGS_OUTPUT and DEV_FLAGS_SYSTEM,
	extensions being only one, the DEV_EXT_VIDEO.

	The private extensions are now used as a per-device carrier of private data and
	finally list allows this structure to be a member of linked list of STDIO
	devices.

	The STDIN, STDOUT and STDERR routing is handled by environment variables
	"stdin", "stdout" and "stderr". By configuring the variable to the name of a
	driver, functions of such driver are called to execute that particular
	operation.

	II) Approach
	------------

	1) Similarity of serial, video and keyboard drivers
	---------------------------------------------------

	All of these drivers can be unified under the STDIO subsystem if modified
	slightly. The serial drivers basically define both input and output functions
	and need function to configure baudrate. The keyboard drivers provide only
	input. On the other hand, video drivers provide output, but need to be
	configured in certain way. This configuration might be dynamic, therefore the
	STDIO has to be modified to provide such flexibility.

	2) Unification of serial, video and keyboard drivers
	----------------------------------------------------

	Every STDIO device would register a structure containing operation it supports
	with the STDIO core by calling:

	int stdio_device_register(struct instance i, struct stdio_device_ops o);

	The structure being defined as follows:

	struct stdio_device_ops {
	void (putc)(struct instance i, const char c);
	void (puts)(struct instance i, const char s); / OPTIONAL */

	int (tstc)(struct instance i);
	int (getc)(struct instance i);

	int (init)(struct instance i);
	int (exit)(struct instance i);
	int (conf)(struct instance i, enum stdio_config c, const void *data);
	};

	The "putc()" function will emit a character, the "puts()" function will emit a
	string. If both of these are set to NULL, the device is considered STDIN only,
	aka input only device.

	The "getc()" retrieves a character from a STDIN device, while "tstc()" tests
	if there is a character in the buffer of STDIN device. In case these two are
	set to NULL, this device is STDOUT / STDERR device.

	Setting all "putc()", "puts()", "getc()" and "tstc()" calls to NULL isn't an
	error condition, though such device does nothing. By instroducing tests for
	these functions being NULL, the "flags" and "ext" fields from original struct
	stdio_dev can be eliminated.

	The "init()" and "exit()" calls are replacement for "start()" and "exit()"
	calls in the old approach. The "priv" part of the old struct stdio_dev will be
	replaced by common private data in the driver model and the struct list_head
	list will be eliminated by introducing common STDIO core, that tracks all the
	STDIO devices.

	Lastly, the "conf()" call will allow the user to configure various options of
	the driver. The enum stdio_config contains all possible configuration options
	available to the STDIO devices, const void *data being the argument to be
	configured. Currently, the enum stdio_config will contain at least the
	following options:

	enum stdio_config {
	STDIO_CONFIG_SERIAL_BAUDRATE,
	};

	3) Transformation of stdio routing
	----------------------------------

	By allowing multiple instances of drivers, the environment variables "stdin",
	"stdout" and "stderr" can no longer be set to the name of the driver.
	Therefore the STDIO core, tracking all of the STDIO devices in the system will
	need to have a small amount of internal data for each device:

	struct stdio_device_node {
	struct instance *i;
	struct stdio_device_ops *ops;
	uint8_t id;
	uint8_t flags;
	struct list_head list;
	}

	The "id" is the order of the instance of the same driver. The "flags" variable
	allows multiple drivers to be used at the same time and even for different
	purpose. The following flags will be defined:

	STDIO_FLG_STDIN ..... This device will be used as an input device. All input
	from all devices with this flag set will be received
	and passed to the upper layers.
	STDIO_FLG_STDOUT .... This device will be used as an output device. All
	output sent to stdout will be routed to all devices
	with this flag set.
	STDIO_FLG_STDERR .... This device will be used as an standard error output
	device. All output sent to stderr will be routed to
	all devices with this flag set.

	The "list" member of this structure allows to have a linked list of all
	registered STDIO devices.

	III) Analysis of in-tree drivers
	--------------------------------

	For in-depth analysis of serial port drivers, refer to [ UDM-serial.txt ].
	For in-depth analysis of keyboard drivers, refer to [ UDM-keyboard.txt ].
	For in-depth analysis of video drivers, refer to [ UDM-video.txt ].

	1) arch/blackfin/cpu/jtag-console.c
	-----------------------------------
	This driver is a classic STDIO driver, no problem with conversion is expected.

	2) board/mpl/pati/pati.c
	------------------------
	This driver registers with the STDIO framework, though it uses a lot of ad-hoc
	stuff which will need to be sorted out.

	3) board/netphone/phone_console.c
	---------------------------------
	This driver is a classic STDIO driver, no problem with conversion is expected.

	4) drivers/net/netconsole.c
	---------------------------
	This driver is a classic STDIO driver, no problem with conversion is expected.

	IV) Other involved files (To be removed)
	----------------------------------------

	common/cmd_console.c
	common/cmd_log.c
	common/cmd_terminal.c
	common/console.c
	common/fdt_support.c
	common/iomux.c
	common/lcd.c
	common/serial.c
	common/stdio.c
	common/usb_kbd.c
	doc/README.iomux