iPXE
console.h
Go to the documentation of this file.
00001 #ifndef _IPXE_CONSOLE_H
00002 #define _IPXE_CONSOLE_H
00003 
00004 #include <stddef.h>
00005 #include <stdio.h>
00006 #include <ipxe/tables.h>
00007 
00008 /** @file
00009  *
00010  * User interaction.
00011  *
00012  * Various console devices can be selected via the build options
00013  * CONSOLE_FIRMWARE, CONSOLE_SERIAL etc.  The console functions
00014  * putchar(), getchar() and iskey() delegate to the individual console
00015  * drivers.
00016  *
00017  */
00018 
00019 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00020 
00021 struct pixel_buffer;
00022 
00023 /** A console configuration */
00024 struct console_configuration {
00025         /** Width */
00026         unsigned int width;
00027         /** Height */
00028         unsigned int height;
00029         /** Colour depth */
00030         unsigned int depth;
00031         /** Left margin */
00032         unsigned int left;
00033         /** Right margin */
00034         unsigned int right;
00035         /** Top margin */
00036         unsigned int top;
00037         /** Bottom margin */
00038         unsigned int bottom;
00039         /** Background picture, if any */
00040         struct pixel_buffer *pixbuf;
00041 };
00042 
00043 /**
00044  * A console driver
00045  *
00046  * Defines the functions that implement a particular console type.
00047  * Must be made part of the console drivers table by using
00048  * #__console_driver.
00049  *
00050  * @note Consoles that cannot be used before their initialisation
00051  * function has completed should set #disabled initially.  This allows
00052  * other console devices to still be used to print out early debugging
00053  * messages.
00054  */
00055 struct console_driver {
00056         /**
00057          * Console disabled flags
00058          *
00059          * This is the bitwise OR of zero or more console disabled
00060          * flags.
00061          */
00062         int disabled;
00063         /**
00064          * Write a character to the console
00065          *
00066          * @v character         Character to be written
00067          */
00068         void ( * putchar ) ( int character );
00069         /**
00070          * Read a character from the console
00071          *
00072          * @ret character       Character read
00073          *
00074          * If no character is available to be read, this method will
00075          * block.  The character read should not be echoed back to the
00076          * console.
00077          */
00078         int ( * getchar ) ( void );
00079         /**
00080          * Check for available input
00081          *
00082          * @ret is_available    Input is available
00083          *
00084          * This should return true if a subsequent call to getchar()
00085          * will not block.
00086          */
00087         int ( * iskey ) ( void );
00088         /**
00089          * Configure console
00090          *
00091          * @v config            Console configuration, or NULL to reset
00092          * @ret rc              Return status code
00093          */
00094         int ( * configure ) ( struct console_configuration *config );
00095         /**
00096          * Console usage bitmask
00097          *
00098          * This is the bitwise OR of zero or more @c CONSOLE_USAGE_XXX
00099          * values.
00100          */
00101         int usage;
00102 };
00103 
00104 /** Console is disabled for input */
00105 #define CONSOLE_DISABLED_INPUT 0x0001
00106 
00107 /** Console is disabled for output */
00108 #define CONSOLE_DISABLED_OUTPUT 0x0002
00109 
00110 /** Console is disabled for all uses */
00111 #define CONSOLE_DISABLED ( CONSOLE_DISABLED_INPUT | CONSOLE_DISABLED_OUTPUT )
00112 
00113 /** Console driver table */
00114 #define CONSOLES __table ( struct console_driver, "consoles" )
00115 
00116 /**
00117  * Mark a <tt> struct console_driver </tt> as being part of the
00118  * console drivers table.
00119  *
00120  * Use as e.g.
00121  *
00122  * @code
00123  *
00124  *   struct console_driver my_console __console_driver = {
00125  *      .putchar = my_putchar,
00126  *      .getchar = my_getchar,
00127  *      .iskey = my_iskey,
00128  *   };
00129  *
00130  * @endcode
00131  *
00132  */
00133 #define __console_driver __table_entry ( CONSOLES, 01 )
00134 
00135 /**
00136  * @defgroup consoleusage Console usages
00137  * @{
00138  */
00139 
00140 /** Standard output */
00141 #define CONSOLE_USAGE_STDOUT 0x0001
00142 
00143 /** Debug messages */
00144 #define CONSOLE_USAGE_DEBUG 0x0002
00145 
00146 /** Text-based user interface */
00147 #define CONSOLE_USAGE_TUI 0x0004
00148 
00149 /** Log messages */
00150 #define CONSOLE_USAGE_LOG 0x0008
00151 
00152 /** All console usages */
00153 #define CONSOLE_USAGE_ALL ( CONSOLE_USAGE_STDOUT | CONSOLE_USAGE_DEBUG | \
00154                             CONSOLE_USAGE_TUI | CONSOLE_USAGE_LOG )
00155 
00156 /** @} */
00157 
00158 /**
00159  * Test to see if console has an explicit usage
00160  *
00161  * @v console           Console definition (e.g. CONSOLE_PCBIOS)
00162  * @ret explicit        Console has an explicit usage
00163  *
00164  * This relies upon the trick that the expression ( 2 * N + 1 ) will
00165  * be valid even if N is defined to be empty, since it will then
00166  * evaluate to give ( 2 * + 1 ) == ( 2 * +1 ) == 2.
00167  */
00168 #define CONSOLE_EXPLICIT( console ) ( ( 2 * console + 1 ) != 2 )
00169 
00170 /** Default console width */
00171 #define CONSOLE_DEFAULT_WIDTH 80
00172 
00173 /** Default console height */
00174 #define CONSOLE_DEFAULT_HEIGHT 25
00175 
00176 extern int console_usage;
00177 extern unsigned int console_width;
00178 extern unsigned int console_height;
00179 
00180 /**
00181  * Set console usage
00182  *
00183  * @v usage             New console usage
00184  * @ret old_usage       Previous console usage
00185  */
00186 static inline __attribute__ (( always_inline )) int
00187 console_set_usage ( int usage ) {
00188         int old_usage = console_usage;
00189 
00190         console_usage = usage;
00191         return old_usage;
00192 }
00193 
00194 /**
00195  * Set console size
00196  *
00197  * @v width             Width, in characters
00198  * @v height            Height, in characters
00199  */
00200 static inline __attribute__ (( always_inline )) void
00201 console_set_size ( unsigned int width, unsigned int height ) {
00202         console_width = width;
00203         console_height = height;
00204 }
00205 
00206 extern int iskey ( void );
00207 extern int getkey ( unsigned long timeout );
00208 extern int console_configure ( struct console_configuration *config );
00209 
00210 /**
00211  * Reset console
00212  *
00213  */
00214 static inline __attribute__ (( always_inline )) void console_reset ( void ) {
00215 
00216         console_configure ( NULL );
00217 }
00218 
00219 #endif /* _IPXE_CONSOLE_H */