Doxygenation
[people/xl0/gpxe.git] / src / include / console.h
1 #ifndef CONSOLE_H
2 #define CONSOLE_H
3
4 #include "stdint.h"
5 #include "vsprintf.h"
6 #include "tables.h"
7
8 /** @file
9  *
10  * User interaction.
11  *
12  * Various console devices can be selected via the build options
13  * CONSOLE_FIRMWARE, CONSOLE_SERIAL etc.  The console functions
14  * putchar(), getchar() and iskey() delegate to the individual console
15  * drivers.
16  *
17  */
18
19 /**
20  * A console driver
21  *
22  * Defines the functions that implement a particular console type.
23  * Must be made part of the console drivers table by using
24  * #__console_driver.
25  *
26  * @note Consoles that cannot be used before their INIT_FN() has
27  * completed should set #disabled=1 initially.  This allows other
28  * console devices to still be used to print out early debugging
29  * messages.
30  *
31  */
32 struct console_driver {
33         /** Console is disabled.
34          *
35          * The console's putchar(), getchar() and iskey() methods will
36          * not be called while #disabled==1.  Typically the
37          * console's initialisation functions (called via INIT_FN())
38          * will set #disabled=0 upon completion.
39          *
40          */
41         int disabled;
42
43         /** Write a character to the console.
44          *
45          * @v character         Character to be written
46          * @ret None
47          * @err None
48          *
49          */
50         void ( *putchar ) ( int character );
51
52         /** Read a character from the console.
53          *
54          * @v None
55          * @ret character       Character read
56          * @err None
57          *
58          * If no character is available to be read, this method will
59          * block.  The character read should not be echoed back to the
60          * console.
61          *
62          */
63         int ( *getchar ) ( void );
64
65         /** Check for available input.
66          *
67          * @v None
68          * @ret True            Input is available
69          * @ret False           Input is not available
70          * @err None
71          *
72          * This should return True if a subsequent call to getchar()
73          * will not block.
74          *
75          */
76         int ( *iskey ) ( void );
77 };
78
79 /**
80  * Mark a <tt> struct console_driver </tt> as being part of the
81  * console drivers table.
82  *
83  * Use as e.g.
84  *
85  * @code
86  *
87  *   struct console_driver my_console __console_driver = {
88  *      .putchar = my_putchar,
89  *      .getchar = my_getchar,
90  *      .iskey = my_iskey,
91  *   };
92  *
93  * @endcode
94  *
95  */
96 #define __console_driver __table ( console, 01 )
97
98 /* Function prototypes */
99
100 extern void putchar ( int character );
101 extern int getchar ( void );
102 extern int iskey ( void );
103
104 #endif /* CONSOLE_H */