Console¶
Struct Console¶
-
enum cons_flags¶
General console flags
Constants
CON_PRINTBUFFERUsed by newly registered consoles to avoid duplicate output of messages that were already shown by boot consoles or read by userspace via syslog() syscall.
CON_CONSDEVIndicates that the console driver is backing /dev/console.
CON_ENABLEDIndicates if a console is allowed to print records. If false, the console also will not advance to later records.
CON_BOOTMarks the console driver as early console driver which is used during boot before the real driver becomes available. It will be automatically unregistered when the real console driver is registered unless “keep_bootcon” parameter is used.
CON_ANYTIMEA misnomed historical flag which tells the core code that the legacy console::write callback can be invoked on a CPU which is marked OFFLINE. That is misleading as it suggests that there is no contextual limit for invoking the callback. The original motivation was readiness of the per-CPU areas.
CON_BRLIndicates a braille device which is exempt from receiving the printk spam for obvious reasons.
CON_EXTENDEDThe console supports the extended output format of /dev/kmesg which requires a larger output buffer.
CON_SUSPENDEDIndicates if a console is suspended. If true, the printing callbacks must not be called.
CON_NBCONConsole can operate outside of the legacy style console_lock constraints.
-
struct console¶
The console descriptor structure
Definition:
struct console {
char name[16];
void (*write)(struct console *co, const char *s, unsigned int count);
int (*read)(struct console *co, char *s, unsigned int count);
struct tty_driver *(*device)(struct console *co, int *index);
void (*unblank)(void);
int (*setup)(struct console *co, char *options);
int (*exit)(struct console *co);
int (*match)(struct console *co, char *name, int idx, char *options);
short flags;
short index;
int cflag;
uint ispeed;
uint ospeed;
u64 seq;
unsigned long dropped;
void *data;
struct hlist_node node;
void (*write_atomic)(struct console *con, struct nbcon_write_context *wctxt);
void (*write_thread)(struct console *con, struct nbcon_write_context *wctxt);
void (*device_lock)(struct console *con, unsigned long *flags);
void (*device_unlock)(struct console *con, unsigned long flags);
atomic_t __private nbcon_state;
atomic_long_t __private nbcon_seq;
struct nbcon_context __private nbcon_device_ctxt;
atomic_long_t __private nbcon_prev_seq;
struct printk_buffers *pbufs;
struct task_struct *kthread;
struct rcuwait rcuwait;
struct irq_work irq_work;
};
Members
nameThe name of the console driver
writeLegacy write callback to output messages (Optional)
readRead callback for console input (Optional)
deviceThe underlying TTY device driver (Optional)
unblankCallback to unblank the console (Optional)
setupCallback for initializing the console (Optional)
exitCallback for teardown of the console (Optional)
matchCallback for matching a console (Optional)
flagsConsole flags. See
enum cons_flagsindexConsole index, e.g. port number
cflagTTY control mode flags
ispeedTTY input speed
ospeedTTY output speed
seqSequence number of the next ringbuffer record to print
droppedNumber of unreported dropped ringbuffer records
dataDriver private data
nodehlist node for the console list
write_atomicNBCON callback to write out text in any context. (Optional)
This callback is called with the console already acquired. However, a higher priority context is allowed to take it over by default.
The callback must call nbcon_enter_unsafe() and nbcon_exit_unsafe() around any code where the takeover is not safe, for example, when manipulating the serial port registers.
nbcon_enter_unsafe() will fail if the context has lost the console ownership in the meantime. In this case, the callback is no longer allowed to go forward. It must back out immediately and carefully. The buffer content is also no longer trusted since it no longer belongs to the context.
The callback should allow the takeover whenever it is safe. It increases the chance to see messages when the system is in trouble. If the driver must reacquire ownership in order to finalize or revert hardware changes, nbcon_reacquire_nobuf() can be used. However, on reacquire the buffer content is no longer available. A reacquire cannot be used to resume printing.
The callback can be called from any context (including NMI). Therefore it must avoid usage of any locking and instead rely on the console ownership for synchronization.
write_threadNBCON callback to write out text in task context.
This callback must be called only in task context with both device_lock() and the nbcon console acquired with NBCON_PRIO_NORMAL.
The same rules for console ownership verification and unsafe sections handling applies as with write_atomic().
The console ownership handling is necessary for synchronization against write_atomic() which is synchronized only via the context.
The device_lock() provides the primary serialization for operations on the device. It might be as relaxed (mutex)[*] or as tight (disabled preemption and interrupts) as needed. It allows the kthread to operate in the least restrictive mode[**].
- [*] Standalone nbcon_context_try_acquire() is not safe with
the preemption enabled, see nbcon_owner_matches(). But it can be safe when always called in the preemptive context under the device_lock().
- [**] The device_lock() makes sure that nbcon_context_try_acquire()
would never need to spin which is important especially with PREEMPT_RT.
device_lockNBCON callback to begin synchronization with driver code.
Console drivers typically must deal with access to the hardware via user input/output (such as an interactive login shell) and output of kernel messages via
printk()calls. This callback is called by the printk-subsystem whenever it needs to synchronize with hardware access by the driver. It should be implemented to use whatever synchronization mechanism the driver is using for itself (for example, the port lock for uart serial consoles).The callback is always called from task context. It may use any synchronization method required by the driver.
- IMPORTANT: The callback MUST disable migration. The console driver
may be using a synchronization mechanism that already takes care of this (such as spinlocks). Otherwise this function must explicitly call migrate_disable().
The flags argument is provided as a convenience to the driver. It will be passed again to device_unlock(). It can be ignored if the driver does not need it.
device_unlockNBCON callback to finish synchronization with driver code.
It is the counterpart to device_lock().
This callback is always called from task context. It must appropriately re-enable migration (depending on how device_lock() disabled migration).
The flags argument is the value of the same variable that was passed to device_lock().
nbcon_stateState for nbcon consoles
nbcon_seqSequence number of the next record for nbcon to print
nbcon_device_ctxtContext available for non-printing operations
nbcon_prev_seqSeq num the previous nbcon owner was assigned to print
pbufsPointer to nbcon private buffer
kthreadPrinter kthread for this console
rcuwaitRCU-safe wait object for kthread waking
irq_workDefer kthread waking to IRQ work context
Internals¶
-
struct nbcon_state¶
console state for nbcon consoles
Definition:
struct nbcon_state {
union {
unsigned int atom;
struct {
unsigned int prio : 2;
unsigned int req_prio : 2;
unsigned int unsafe : 1;
unsigned int unsafe_takeover : 1;
unsigned int cpu : 24;
};
};
};
Members
{unnamed_union}anonymous
atomCompound of the state fields for atomic operations
{unnamed_struct}anonymous
prioThe priority of the current owner
req_prioThe priority of a handover request
unsafeConsole is busy in a non takeover region
unsafe_takeoverA hostile takeover in an unsafe state happened in the past. The console cannot be safe until re-initialized.
cpuThe CPU on which the owner runs
Description
To be used for reading and preparing of the value stored in the nbcon state variable console::nbcon_state.
The prio and req_prio fields are particularly important to allow spin-waiting to timeout and give up without the risk of a waiter being assigned the lock after giving up.
-
enum nbcon_prio¶
console owner priority for nbcon consoles
Constants
NBCON_PRIO_NONEUnused
NBCON_PRIO_NORMALNormal (non-emergency) usage
NBCON_PRIO_EMERGENCYEmergency output (WARN/OOPS...)
NBCON_PRIO_PANICPanic output
NBCON_PRIO_MAXThe number of priority levels
Description
A higher priority context can takeover the console when it is
in the safe state. The final attempt to flush consoles in panic()
can be allowed to do so even in an unsafe state (Hope and pray).
-
struct nbcon_context¶
Context for console acquire/release
Definition:
struct nbcon_context {
struct console *console;
unsigned int spinwait_max_us;
enum nbcon_prio prio;
unsigned int allow_unsafe_takeover : 1;
unsigned int backlog : 1;
struct printk_buffers *pbufs;
u64 seq;
};
Members
consoleThe associated console
spinwait_max_usLimit for spin-wait acquire
prioPriority of the context
allow_unsafe_takeoverAllow performing takeover even if unsafe. Can be used only with NBCON_PRIO_PANIC prio. It might cause a system freeze when the console is used later.
backlogRingbuffer has pending records
pbufsPointer to the text buffer for this context
seqThe sequence number to print for this context
-
struct nbcon_write_context¶
Context handed to the nbcon write callbacks
Definition:
struct nbcon_write_context {
struct nbcon_context __private ctxt;
char *outbuf;
unsigned int len;
bool unsafe_takeover;
};
Members
ctxtThe core console context
outbufPointer to the text buffer for output
lenLength to write
unsafe_takeoverIf a hostile takeover in an unsafe state has occurred
Struct Consw¶
-
struct consw¶
callbacks for consoles
Definition:
struct consw {
struct module *owner;
const char *(*con_startup)(void);
void (*con_init)(struct vc_data *vc, bool init);
void (*con_deinit)(struct vc_data *vc);
void (*con_clear)(struct vc_data *vc, unsigned int y, unsigned int x, unsigned int count);
void (*con_putc)(struct vc_data *vc, u16 ca, unsigned int y, unsigned int x);
void (*con_putcs)(struct vc_data *vc, const u16 *s,unsigned int count, unsigned int ypos, unsigned int xpos);
void (*con_cursor)(struct vc_data *vc, bool enable);
bool (*con_scroll)(struct vc_data *vc, unsigned int top,unsigned int bottom, enum con_scroll dir, unsigned int lines);
bool (*con_switch)(struct vc_data *vc);
bool (*con_blank)(struct vc_data *vc, enum vesa_blank_mode blank, bool mode_switch);
int (*con_font_set)(struct vc_data *vc,const struct console_font *font, unsigned int vpitch, unsigned int flags);
int (*con_font_get)(struct vc_data *vc, struct console_font *font, unsigned int vpitch);
int (*con_font_default)(struct vc_data *vc, struct console_font *font, const char *name);
int (*con_resize)(struct vc_data *vc, unsigned int width, unsigned int height, bool from_user);
void (*con_set_palette)(struct vc_data *vc, const unsigned char *table);
void (*con_scrolldelta)(struct vc_data *vc, int lines);
bool (*con_set_origin)(struct vc_data *vc);
void (*con_save_screen)(struct vc_data *vc);
u8 (*con_build_attr)(struct vc_data *vc, u8 color,enum vc_intensity intensity, bool blink, bool underline, bool reverse, bool italic);
void (*con_invert_region)(struct vc_data *vc, u16 *p, int count);
void (*con_debug_enter)(struct vc_data *vc);
void (*con_debug_leave)(struct vc_data *vc);
};
Members
ownerthe module to get references of when this console is used
con_startupset up the console and return its name (like VGA, EGA, ...)
con_initinitialize the console on vc. init is true for the very first call on this vc.
con_deinitdeinitialize the console from vc.
con_clearerase count characters at [x, y] on vc. count >= 1.
con_putcemit one character with attributes ca to [x, y] on vc. (optional -- con_putcs would be called instead)
con_putcsemit count characters with attributes s to [x, y] on vc.
con_cursorenable/disable cursor depending on enable
con_scrollmove lines from top to bottom in direction dir by lines. Return true if no generic handling should be done. Invoked by csi_M and printing to the console.
con_switchnotifier about the console switch; it is supposed to return true if a redraw is needed.
con_blankblank/unblank the console. The target mode is passed in blank. mode_switch is set if changing from/to text/graphics. The hook is supposed to return true if a redraw is needed.
con_font_setset console vc font to font with height vpitch. flags can be
KD_FONT_FLAG_DONT_RECALC. (optional)con_font_getfetch the current font on vc of height vpitch into font. (optional)
con_font_defaultset default font on vc. name can be
NULLor font name to search for. font can be filled back. (optional)con_resizeresize the vc console to width x height. from_user is true when this change comes from the user space.
con_set_palettesets the palette of the console vc to table (optional)
con_scrolldeltathe contents of the console should be scrolled by lines. Invoked by user. (optional)
con_set_originset origin (see
vc_data::vc_origin) of the vc. If not provided or returns false, the origin is set to vc->vc_screenbuf. (optional)con_save_screensave screen content into vc->vc_screenbuf. Called e.g. upon entering graphics. (optional)
con_build_attrbuild attributes based on color, intensity and other parameters. The result is used for both normal and erase characters. (optional)
con_invert_regioninvert a region of length count on vc starting at p. (optional)
con_debug_enterprepare the console for the debugger. This includes, but is not limited to, unblanking the console, loading an appropriate palette, and allowing debugger generated output. (optional)
con_debug_leaverestore the console to its pre-debug state as closely as possible. (optional)
Console functions¶
-
short console_srcu_read_flags(const struct console *con)¶
Locklessly read flags of a possibly registered console
Parameters
const struct console *construct consolepointer of console to read flags from
Description
Locklessly reading con->flags provides a consistent read value because there is at most one CPU modifying con->flags and that CPU is using only read-modify-write operations to do so.
Requires console_srcu_read_lock to be held, which implies that con might be a registered console. The purpose of holding console_srcu_read_lock is to guarantee that the console state is valid (CON_SUSPENDED/CON_ENABLED) and that no exit/cleanup routines will run if the console is currently undergoing unregistration.
If the caller is holding the console_list_lock or it is _certain_ that con is not and will not become registered, the caller may read con->flags directly instead.
Context
Any context.
Return
The current value of the con->flags field.
-
void console_srcu_write_flags(struct console *con, short flags)¶
Write flags for a registered console
Parameters
struct console *construct consolepointer of console to write flags toshort flagsnew flags value to write
Description
Only use this function to write flags for registered consoles. It requires holding the console_list_lock.
Context
Any context.
-
for_each_console_srcu¶
for_each_console_srcu (con)
Iterator over registered consoles
Parameters
construct consolepointer used as loop cursor
Description
Although SRCU guarantees the console list will be consistent, the
struct console fields may be updated by other CPUs while iterating.
Requires console_srcu_read_lock to be held. Can be invoked from any context.
-
for_each_console¶
for_each_console (con)
Iterator over registered consoles
Parameters
construct consolepointer used as loop cursor
Description
The console list and the console.flags are immutable while iterating.
Requires console_list_lock to be held.
-
void clear_selection(void)¶
remove current selection
Parameters
voidno arguments
Description
Remove the current selection highlight, if any from the console holding the selection.
Locking: The caller must hold the console lock.
-
int __vc_resize(struct vc_data *vc, unsigned int cols, unsigned int rows, bool from_user)¶
resize a VT
Parameters
struct vc_data *vcvirtual console
unsigned int colscolumns
unsigned int rowsrows
bool from_userinvoked by a user?
Description
Resize a virtual console as seen from the console end of things. We use the
common vc_do_resize() method to update the structures.
Locking: The caller must hold the console sem to protect console internals and vc->port.tty.
Parameters
const struct consw *cswconsole driver
Return
zero if unbound, nonzero if bound
Description
Drivers can call this and if zero, they should release
all resources allocated on consw.con_startup()
-
bool con_is_visible(const struct vc_data *vc)¶
checks whether the current console is visible
Parameters
const struct vc_data *vcvirtual console
Return
zero if not visible, nonzero if visible
-
void con_debug_enter(struct vc_data *vc)¶
prepare the console for the kernel debugger
Parameters
struct vc_data *vcvirtual console
Description
Called when the console is taken over by the kernel debugger, this function needs to save the current console state, then put the console into a state suitable for the kernel debugger.
-
void con_debug_leave(void)¶
restore console state
Parameters
voidno arguments
Description
Restore the console state to what it was before the kernel debugger was invoked.
Parameters
const struct consw *cswconsole driver
Description
All drivers that registers to the console layer must call this function upon exit, or if the console driver is in a state where it won’t be able to handle console services, such as the framebuffer console without loaded framebuffer drivers.
The driver must unbind first prior to unregistration.
Internals¶
-
int sel_loadlut(u32 __user *lut)¶
load the LUT table
Parameters
u32 __user *lutuser table
Description
Load the LUT table from user space. Make a temporary copy so a partial update doesn’t make a mess.
Locking: The console lock is acquired.
-
int set_selection_user(const struct tiocl_selection __user *sel, struct tty_struct *tty)¶
set the current selection.
Parameters
const struct tiocl_selection __user *seluser selection info
struct tty_struct *ttythe console tty
Description
Invoked by the ioctl handle for the vt layer.
Locking: The entire selection process is managed under the console_lock. It’s a lot under the lock but its hardly a performance path.
-
int vc_do_resize(struct tty_struct *tty, struct vc_data *vc, unsigned int cols, unsigned int lines, bool from_user)¶
resizing method for the tty
Parameters
struct tty_struct *ttytty being resized
struct vc_data *vcvirtual console private data
unsigned int colscolumns
unsigned int lineslines
bool from_userinvoked by a user?
Description
Resize a virtual console, clipping according to the actual constraints. If the caller passes a tty structure then update the termios winsize information and perform any necessary signal handling.
Locking: Caller must hold the console semaphore. Takes the termios rwsem and ctrl.lock of the tty IFF a tty is passed.
-
int vt_resize(struct tty_struct *tty, struct winsize *ws)¶
resize a VT
Parameters
struct tty_struct *ttytty to resize
struct winsize *wswinsize attributes
Description
Resize a virtual terminal. This is called by the tty layer as we register our own handler for resizing. The mutual helper does all the actual work.
Locking: Takes the console sem and the called methods then take the tty termios_rwsem and the tty ctrl.lock in that order.
-
enum vc_ctl_state¶
control characters state of a vt
Constants
ESnormalinitial state, no control characters parsed
ESescESC parsed
ESsquareCSI parsed -- modifiers/parameters/ctrl chars expected
ESgetparsCSI parsed -- parameters/ctrl chars expected
ESfunckeyCSI [ parsed
EShashESC # parsed
ESsetG0ESC ( parsed
ESsetG1ESC ) parsed
ESpercentESC % parsed
EScsiignoreCSI [0x20-0x3f] parsed
ESnonstdOSC parsed
ESpaletteOSC P parsed
ESoscOSC [0-9] parsed
ESANSI_firstfirst state for ignoring ansi control sequences
ESapcESC _ parsed
ESpmESC ^ parsed
ESdcsESC P parsed
ESANSI_lastlast state for ignoring ansi control sequences
-
int vc_sanitize_unicode(const int c)¶
Replace invalid Unicode code points with
U+FFFD
Parameters
const int cthe received code point
-
int vc_translate_unicode(struct vc_data *vc, int c, bool *rescan)¶
Combine UTF-8 into Unicode in
vc_data.vc_utf_char
Parameters
struct vc_data *vcvirtual console
int cUTF-8 byte to translate
bool *rescanset to true iff c wasn’t consumed here and needs to be re-processed
Description
vc_data.vc_utf_charis the being-constructed Unicode code point.vc_data.vc_utf_countis the number of continuation bytes still expected to arrive.vc_data.vc_nparis the number of continuation bytes arrived so far.
Return
-1- Input OK so far, c consumed, further bytes expected.0xFFFD- Possibility 1: input invalid, c may have been consumed (seedesc. of rescan). Possibility 2: input OK, c consumed,
U+FFFDis the resulting code point.U+FFFDis valid,REPLACEMENT CHARACTER.
otherwise - Input OK, c consumed, resulting code point returned.
-
int vt_kmsg_redirect(int new)¶
sets/gets the kernel message console
Parameters
int newthe new virtual terminal number or -1 if the console should stay unchanged
Description
By default, the kernel messages are always printed on the current virtual
console. However, the user may modify that default with the
TIOCL_SETKMSGREDIRECT ioctl call.
This function sets the kernel message console to be new. It returns the old
virtual console number. The virtual terminal number 0 (both as parameter and
return value) means no redirection (i.e. always printed on the currently
active console).
The parameter -1 means that only the current console is returned, but the value is not modified. You may use the macro vt_get_kmsg_redirect() in that case to make the code more understandable.
When the kernel is compiled without CONFIG_VT_CONSOLE, this function ignores
the parameter and always returns 0.