Console¶
Struct Console¶
-
enum cons_flags¶
General console flags
Constants
CON_PRINTBUFFER
Used 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_CONSDEV
Indicates that the console driver is backing /dev/console.
CON_ENABLED
Indicates if a console is allowed to print records. If false, the console also will not advance to later records.
CON_BOOT
Marks 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_ANYTIME
A 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_BRL
Indicates a braille device which is exempt from receiving the printk spam for obvious reasons.
CON_EXTENDED
The console supports the extended output format of /dev/kmesg which requires a larger output buffer.
CON_SUSPENDED
Indicates if a console is suspended. If true, the printing callbacks must not be called.
CON_NBCON
Console 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
name
The name of the console driver
write
Legacy write callback to output messages (Optional)
read
Read callback for console input (Optional)
device
The underlying TTY device driver (Optional)
unblank
Callback to unblank the console (Optional)
setup
Callback for initializing the console (Optional)
exit
Callback for teardown of the console (Optional)
match
Callback for matching a console (Optional)
flags
Console flags. See
enum cons_flags
index
Console index, e.g. port number
cflag
TTY control mode flags
ispeed
TTY input speed
ospeed
TTY output speed
seq
Sequence number of the next ringbuffer record to print
dropped
Number of unreported dropped ringbuffer records
data
Driver private data
node
hlist node for the console list
write_atomic
NBCON 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_thread
NBCON 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_lock
NBCON 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_unlock
NBCON 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_state
State for nbcon consoles
nbcon_seq
Sequence number of the next record for nbcon to print
nbcon_device_ctxt
Context available for non-printing operations
nbcon_prev_seq
Seq num the previous nbcon owner was assigned to print
pbufs
Pointer to nbcon private buffer
kthread
Printer kthread for this console
rcuwait
RCU-safe wait object for kthread waking
irq_work
Defer 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
atom
Compound of the state fields for atomic operations
{unnamed_struct}
anonymous
prio
The priority of the current owner
req_prio
The priority of a handover request
unsafe
Console is busy in a non takeover region
unsafe_takeover
A hostile takeover in an unsafe state happened in the past. The console cannot be safe until re-initialized.
cpu
The 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_NONE
Unused
NBCON_PRIO_NORMAL
Normal (non-emergency) usage
NBCON_PRIO_EMERGENCY
Emergency output (WARN/OOPS...)
NBCON_PRIO_PANIC
Panic output
NBCON_PRIO_MAX
The 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
console
The associated console
spinwait_max_us
Limit for spin-wait acquire
prio
Priority of the context
allow_unsafe_takeover
Allow 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.
backlog
Ringbuffer has pending records
pbufs
Pointer to the text buffer for this context
seq
The 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
ctxt
The core console context
outbuf
Pointer to the text buffer for output
len
Length to write
unsafe_takeover
If 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
owner
the module to get references of when this console is used
con_startup
set up the console and return its name (like VGA, EGA, ...)
con_init
initialize the console on vc. init is true for the very first call on this vc.
con_deinit
deinitialize the console from vc.
con_clear
erase count characters at [x, y] on vc. count >= 1.
con_putc
emit one character with attributes ca to [x, y] on vc. (optional -- con_putcs would be called instead)
con_putcs
emit count characters with attributes s to [x, y] on vc.
con_cursor
enable/disable cursor depending on enable
con_scroll
move 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_switch
notifier about the console switch; it is supposed to return true if a redraw is needed.
con_blank
blank/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_set
set console vc font to font with height vpitch. flags can be
KD_FONT_FLAG_DONT_RECALC
. (optional)con_font_get
fetch the current font on vc of height vpitch into font. (optional)
con_font_default
set default font on vc. name can be
NULL
or font name to search for. font can be filled back. (optional)con_resize
resize the vc console to width x height. from_user is true when this change comes from the user space.
con_set_palette
sets the palette of the console vc to table (optional)
con_scrolldelta
the contents of the console should be scrolled by lines. Invoked by user. (optional)
con_set_origin
set 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_screen
save screen content into vc->vc_screenbuf. Called e.g. upon entering graphics. (optional)
con_build_attr
build attributes based on color, intensity and other parameters. The result is used for both normal and erase characters. (optional)
con_invert_region
invert a region of length count on vc starting at p. (optional)
con_debug_enter
prepare 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_leave
restore 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 *con
struct console
pointer 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 *con
struct console
pointer of console to write flags toshort flags
new 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
con
struct console
pointer 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
con
struct console
pointer 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
void
no 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 *vc
virtual console
unsigned int cols
columns
unsigned int rows
rows
bool from_user
invoked 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 *csw
console 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 *vc
virtual 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 *vc
virtual 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
void
no arguments
Description
Restore the console state to what it was before the kernel debugger was invoked.
Parameters
const struct consw *csw
console 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 *lut
user 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 *sel
user selection info
struct tty_struct *tty
the 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 *tty
tty being resized
struct vc_data *vc
virtual console private data
unsigned int cols
columns
unsigned int lines
lines
bool from_user
invoked 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 *tty
tty to resize
struct winsize *ws
winsize 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
ESnormal
initial state, no control characters parsed
ESesc
ESC parsed
ESsquare
CSI parsed -- modifiers/parameters/ctrl chars expected
ESgetpars
CSI parsed -- parameters/ctrl chars expected
ESfunckey
CSI [ parsed
EShash
ESC # parsed
ESsetG0
ESC ( parsed
ESsetG1
ESC ) parsed
ESpercent
ESC % parsed
EScsiignore
CSI [0x20-0x3f] parsed
ESnonstd
OSC parsed
ESpalette
OSC P parsed
ESosc
OSC [0-9] parsed
ESANSI_first
first state for ignoring ansi control sequences
ESapc
ESC _ parsed
ESpm
ESC ^ parsed
ESdcs
ESC P parsed
ESANSI_last
last state for ignoring ansi control sequences
-
int vc_sanitize_unicode(const int c)¶
Replace invalid Unicode code points with
U+FFFD
Parameters
const int c
the 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 *vc
virtual console
int c
UTF-8 byte to translate
bool *rescan
set to true iff c wasn’t consumed here and needs to be re-processed
Description
vc_data.vc_utf_char
is the being-constructed Unicode code point.vc_data.vc_utf_count
is the number of continuation bytes still expected to arrive.vc_data.vc_npar
is 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+FFFD
is the resulting code point.U+FFFD
is 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 new
the 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
.