Constants

CON_PRINTBUFFER

Used by newly registered consoles to avoid duplicateoutput of messages that were already shown by bootconsoles or read by userspace viasyslog() syscall.

CON_CONSDEV

Indicates that the console driver is backing/dev/console.

CON_ENABLED

Indicates if a console is allowed to print records. Iffalse, the console also will not advance to laterrecords.

CON_BOOT

Marks the console driver as early console driver whichis used during boot before the real driver becomesavailable. It will be automatically unregisteredwhen the real console driver is registered unless“keep_bootcon” parameter is used.

CON_ANYTIME

A misnomed historical flag which tells the core codethat the legacyconsole::write callback can be invokedon a CPU which is marked OFFLINE. That is misleading asit suggests that there is no contextual limit forinvoking the callback. The original motivation wasreadiness of the per-CPU areas.

CON_BRL

Indicates a braille device which is exempt fromreceiving 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, theprinting callbacks must not be called.

CON_NBCON

Console can operate outside of the legacy style console_lockconstraints.

CON_NBCON_ATOMIC_UNSAFE

Thewrite_atomic() callback is not safe and istherefore only used bynbcon_atomic_flush_unsafe().

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 nbcon_state;    atomic_long_t nbcon_seq;    struct nbcon_context  nbcon_device_ctxt;    atomic_long_t 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. Seeenumcons_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 callnbcon_enter_unsafe() andnbcon_exit_unsafe()around any code where the takeover is not safe, for example, whenmanipulating the serial port registers.

nbcon_enter_unsafe() will fail if the context has lost the consoleownership in the meantime. In this case, the callback is no longerallowed to go forward. It must back out immediately and carefully.The buffer content is also no longer trusted since it no longerbelongs to the context.

The callback should allow the takeover whenever it is safe. Itincreases the chance to see messages when the system is in trouble.If the driver must reacquire ownership in order to finalize orrevert hardware changes,nbcon_reacquire_nobuf() can be used.However, on reacquire the buffer content is no longer available. Areacquire 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 relyon 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 bothdevice_lock() and the nbcon console acquired withNBCON_PRIO_NORMAL.

The same rules for console ownership verification and unsafesections handling applies as withwrite_atomic().

The console ownership handling is necessary for synchronizationagainstwrite_atomic() which is synchronized only via the context.

Thedevice_lock() provides the primary serialization for operationson the device. It might be as relaxed (mutex)[*] or as tight(disabled preemption and interrupts) as needed. It allowsthe kthread to operate in the least restrictive mode[**].

[*] Standalone nbcon_context_try_acquire() is not safe with

the preemption enabled, seenbcon_owner_matches(). But itcan be safe when always called in the preemptive contextunder thedevice_lock().

[**] The device_lock() makes sure that nbcon_context_try_acquire()

would never need to spin which is important especially withPREEMPT_RT.

device_lock

NBCON callback to begin synchronization with driver code.

Console drivers typically must deal with access to the hardwarevia user input/output (such as an interactive login shell) andoutput of kernel messages viaprintk() calls. This callback iscalled by the printk-subsystem whenever it needs to synchronizewith hardware access by the driver. It should be implemented touse whatever synchronization mechanism the driver is using foritself (for example, the port lock for uart serial consoles).

The callback is always called from task context. It may use anysynchronization method required by the driver.

IMPORTANT: The callback MUST disable migration. The console driver

may be using a synchronization mechanism that already takescare of this (such as spinlocks). Otherwise this function mustexplicitly callmigrate_disable().

The flags argument is provided as a convenience to the driver. Itwill be passed again todevice_unlock(). It can be ignored if thedriver does not need it.

device_unlock

NBCON callback to finish synchronization with driver code.

It is the counterpart todevice_lock().

This callback is always called from task context. It mustappropriately re-enable migration (depending on howdevice_lock()disabled migration).

The flags argument is the value of the same variable that waspassed todevice_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 forkthread waking

irq_work

Deferkthread waking to IRQ work context

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);};

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 onvc.init is true for the very firstcall on thisvc.

con_deinit

deinitialize the console fromvc.

con_clear

erasecount characters at [x,y] onvc.count >= 1.

con_putc

emit one character with attributesca to [x,y] onvc.(optional --con_putcs would be called instead)

con_putcs

emitcount characters with attributess to [x,y] onvc.

con_cursor

enable/disable cursor depending onenable

con_scroll

move lines fromtop tobottom in directiondir bylines.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 returntrue if a redraw is needed.

con_blank

blank/unblank the console. The target mode is passed inblank.mode_switch is set if changing from/to text/graphics. The hookis supposed to return true if a redraw is needed.

con_font_set

set consolevc font tofont with heightvpitch.flags canbeKD_FONT_FLAG_DONT_RECALC. (optional)

con_font_get

fetch the current font onvc of heightvpitch intofont.(optional)

con_font_default

set default font onvc.name can beNULL or font nameto search for.font can be filled back. (optional)

con_resize

resize thevc console towidth xheight.from_user is truewhen this change comes from the user space.

con_set_palette

sets the palette of the consolevc totable (optional)

con_scrolldelta

the contents of the console should be scrolled bylines.Invoked by user. (optional)

con_set_origin

set origin (seevc_data::vc_origin) of thevc. If notprovided or returns false, the origin is set tovc->vc_screenbuf. (optional)

con_save_screen

save screen content intovc->vc_screenbuf. Called e.g.upon entering graphics. (optional)

con_build_attr

build attributes based oncolor,intensity and otherparameters. The result is used for both normal and erasecharacters. (optional)

con_invert_region

invert a region of lengthcount onvc starting atp.(optional)

Parameters

conststructconsole*con

structconsole pointer of console to read flags from

Description

Locklessly readingcon->flags provides a consistent read value becausethere is at most one CPU modifyingcon->flags and that CPU is using onlyread-modify-write operations to do so.

Requires console_srcu_read_lock to be held, which implies thatcon mightbe a registered console. The purpose of holding console_srcu_read_lock isto guarantee that the console state is valid (CON_SUSPENDED/CON_ENABLED)and that no exit/cleanup routines will run if the console is currentlyundergoing unregistration.

If the caller is holding the console_list_lock or it is _certain_ thatcon is not and will not become registered, the caller may readcon->flags directly instead.

Context

Any context.

Return

The current value of thecon->flags field.

Parameters

structconsole*con

structconsole pointer of console to write flags to

shortflags

new flags value to write

Description

Only use this function to write flags for registered consoles. Itrequires holding the console_list_lock.

Context

Any context.

Parameters

con

structconsole pointer used as loop cursor

Description

Although SRCU guarantees the console list will be consistent, thestructconsole fields may be updated by other CPUs while iterating.

Requires console_srcu_read_lock to be held. Can be invoked fromany context.

Parameters

con

structconsole pointer used as loop cursor

Description

The console list and theconsole.flags are immutable while iterating.

Requires console_list_lock to be held.

Parameters

void

no arguments

Description

Remove the current selection highlight, if any from the console holding theselection.

Locking: The caller must hold the console lock.

Parameters

structvc_data*vc

virtual console

unsignedintcols

columns

unsignedintrows

rows

boolfrom_user

invoked by a user?

Description

Resize a virtual console as seen from the console end of things. We use thecommonvc_do_resize() method to update the structures.

Locking: The caller must hold the console sem to protect console internalsandvc->port.tty.

Parameters

conststructconsw*csw

console driver

Return

zero if unbound, nonzero if bound

Description

Drivers can call this and if zero, they should releaseall resources allocated onconsw.con_startup()

Parameters

conststructvc_data*vc

virtual console

Return

zero if not visible, nonzero if visible

Parameters

structvc_data*vc

virtual console

Description

Called when the console is taken over by the kernel debugger, thisfunction needs to save the current console state, then put the consoleinto a state suitable for the kernel debugger.

Parameters

void

no arguments

Description

Restore the console state to what it was before the kernel debuggerwas invoked.

Parameters

conststructconsw*csw

console driver

Description

All drivers that registers to the console layer mustcall this function upon exit, or if the console driver is in a statewhere it won’t be able to handle console services, such as theframebuffer console without loaded framebuffer drivers.

The driver must unbind first prior to unregistration.