[thirdparty/u-boot.git] / doc / README.console

SPDX-License-Identifier: GPL-2.0+
/*
 * (C) Copyright 2000
 * Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it
 */

U-Boot console handling
========================

HOW THE CONSOLE WORKS?
----------------------

At system startup U-Boot initializes a serial console. When U-Boot
relocates itself to RAM, all console drivers are initialized (they
will register all detected console devices to the system for further
use).

If not defined in the environment, the first input device is assigned
to the 'stdin' file, the first output one to 'stdout' and 'stderr'.

You can use the command "coninfo" to see all registered console
devices and their flags. You can assign a standard file (stdin,
stdout or stderr) to any device you see in that list simply by
assigning its name to the corresponding environment variable. For
example:

    setenv stdin serial		<- To use the serial input
    setenv stdout video		<- To use the video console

Do a simple "saveenv" to save the console settings in the environment
and get them working on the next startup, too.

HOW CAN I USE STANDARD FILE INTO THE SOURCES?
---------------------------------------------

You can use the following functions to access the console:

* STDOUT:
    putc	(to put a char to stdout)
    puts	(to put a string to stdout)
    printf	(to format and put a string to stdout)

* STDIN:
    tstc	(to test for the presence of a char in stdin)
    getc	(to get a char from stdin)

* STDERR:
    eputc	(to put a char to stderr)
    eputs	(to put a string to stderr)
    eprintf	(to format and put a string to stderr)

* FILE (can be 'stdin', 'stdout', 'stderr'):
    fputc	(like putc but redirected to a file)
    fputs	(like puts but redirected to a file)
    fprintf	(like printf but redirected to a file)
    ftstc	(like tstc but redirected to a file)
    fgetc	(like getc but redirected to a file)

Remember that all FILE-related functions CANNOT be used before
U-Boot relocation (done in 'board_init_r' in arch/*/lib/board.c).

HOW CAN I USE STANDARD FILE INTO APPLICATIONS?
----------------------------------------------

Use the 'bd_mon_fnc' field of the bd_t structure passed to the
application to do everything you want with the console.

But REMEMBER that that will work only if you have not overwritten any
U-Boot code while loading (or uncompressing) the image of your
application.

For example, you won't get the console stuff running in the Linux
kernel because the kernel overwrites U-Boot before running. Only
some parameters like the framebuffer descriptors are passed to the
kernel in the high memory area to let the applications (the kernel)
use the framebuffers initialized by U-Boot.

SUPPORTED DRIVERS
-----------------

Working drivers:

    serial	(architecture dependent serial stuff)
    video	(mpc8xx video controller)

Work in progress:

    wl_kbd	(Wireless 4PPM keyboard)

Waiting for volounteers:

    lcd	(mpc8xx lcd controller; to )

TESTED CONFIGURATIONS
---------------------

The driver has been tested with the following configurations (see
CREDITS for other contact informations):

- MPC823FADS with AD7176 on a PAL TV (YCbYCr)	- arsenio@tin.it
Commit	Line	Data
83d290c5	1	SPDX-License-Identifier: GPL-2.0+
cc1c8a13 WD	2	/*
	3	* (C) Copyright 2000
	4	* Paolo Scaffardi, AIRVENT SAM s.p.a - RIMINI(ITALY), arsenio@tin.it
cc1c8a13 WD	5	*/
	6
	7	U-Boot console handling
	8	========================
	9
	10	HOW THE CONSOLE WORKS?
	11	----------------------
	12
	13	At system startup U-Boot initializes a serial console. When U-Boot
	14	relocates itself to RAM, all console drivers are initialized (they
	15	will register all detected console devices to the system for further
	16	use).
	17
	18	If not defined in the environment, the first input device is assigned
	19	to the 'stdin' file, the first output one to 'stdout' and 'stderr'.
	20
	21	You can use the command "coninfo" to see all registered console
	22	devices and their flags. You can assign a standard file (stdin,
	23	stdout or stderr) to any device you see in that list simply by
	24	assigning its name to the corresponding environment variable. For
	25	example:
	26
dc2164da	27	setenv stdin serial <- To use the serial input
cc1c8a13 WD	28	setenv stdout video <- To use the video console
	29
	30	Do a simple "saveenv" to save the console settings in the environment
	31	and get them working on the next startup, too.
	32
	33	HOW CAN I USE STANDARD FILE INTO THE SOURCES?
	34	---------------------------------------------
	35
	36	You can use the following functions to access the console:
	37
	38	* STDOUT:
	39	putc (to put a char to stdout)
	40	puts (to put a string to stdout)
	41	printf (to format and put a string to stdout)
	42
	43	* STDIN:
	44	tstc (to test for the presence of a char in stdin)
	45	getc (to get a char from stdin)
	46
	47	* STDERR:
	48	eputc (to put a char to stderr)
	49	eputs (to put a string to stderr)
	50	eprintf (to format and put a string to stderr)
	51
	52	* FILE (can be 'stdin', 'stdout', 'stderr'):
	53	fputc (like putc but redirected to a file)
	54	fputs (like puts but redirected to a file)
	55	fprintf (like printf but redirected to a file)
	56	ftstc (like tstc but redirected to a file)
	57	fgetc (like getc but redirected to a file)
	58
	59	Remember that all FILE-related functions CANNOT be used before
7de17781	60	U-Boot relocation (done in 'board_init_r' in arch/*/lib/board.c).
cc1c8a13 WD	61
	62	HOW CAN I USE STANDARD FILE INTO APPLICATIONS?
	63	----------------------------------------------
	64
	65	Use the 'bd_mon_fnc' field of the bd_t structure passed to the
	66	application to do everything you want with the console.
	67
	68	But REMEMBER that that will work only if you have not overwritten any
	69	U-Boot code while loading (or uncompressing) the image of your
	70	application.
	71
	72	For example, you won't get the console stuff running in the Linux
	73	kernel because the kernel overwrites U-Boot before running. Only
	74	some parameters like the framebuffer descriptors are passed to the
	75	kernel in the high memory area to let the applications (the kernel)
	76	use the framebuffers initialized by U-Boot.
	77
	78	SUPPORTED DRIVERS
	79	-----------------
	80
	81	Working drivers:
	82
53677ef1 WD	83	serial (architecture dependent serial stuff)
53677ef1 WD	84	video (mpc8xx video controller)
cc1c8a13 WD	85
	86	Work in progress:
	87
	88	wl_kbd (Wireless 4PPM keyboard)
	89
	90	Waiting for volounteers:
	91
	92	lcd (mpc8xx lcd controller; to )
	93
	94	TESTED CONFIGURATIONS
	95	---------------------
	96
	97	The driver has been tested with the following configurations (see
	98	CREDITS for other contact informations):
	99
53677ef1	100	- MPC823FADS with AD7176 on a PAL TV (YCbYCr) - arsenio@tin.it