include/linux/console.h

   1 /*
   2  *  linux/include/linux/console.h
   3  *
   4  *  Copyright (C) 1993        Hamish Macdonald
   5  *
   6  * This file is subject to the terms and conditions of the GNU General Public
   7  * License.  See the file COPYING in the main directory of this archive
   8  * for more details.
   9  *
  10  * Changed:
  11  * 10-Mar-94: Arno Griffioen: Conversion for vt100 emulator port from PC LINUX
  12  */
  13
  14 #ifndef _LINUX_CONSOLE_H_
  15 #define _LINUX_CONSOLE_H_ 1
  16
  17 #include <linux/atomic.h>
  18 #include <linux/bits.h>
  19 #include <linux/rculist.h>
  20 #include <linux/types.h>
  21 #include <linux/vesa.h>
  22
  23 struct vc_data;
  24 struct console_font_op;
  25 struct console_font;
  26 struct module;
  27 struct tty_struct;
  28 struct notifier_block;
  29
  30 enum con_scroll {
  31         SM_UP,
  32         SM_DOWN,
  33 };
  34
  35 enum vc_intensity;
  36
  37 /**
  38  * struct consw - callbacks for consoles
  39  *
  40  * @owner:      the module to get references of when this console is used
  41  * @con_startup: set up the console and return its name (like VGA, EGA, ...)
  42  * @con_init:   initialize the console on @vc. @init is true for the very first
  43  *              call on this @vc.
  44  * @con_deinit: deinitialize the console from @vc.
  45  * @con_clear:  erase @count characters at [@x, @y] on @vc. @count >= 1.
  46  * @con_putc:   emit one character with attributes @ca to [@x, @y] on @vc.
  47  *              (optional -- @con_putcs would be called instead)
  48  * @con_putcs:  emit @count characters with attributes @s to [@x, @y] on @vc.
  49  * @con_cursor: enable/disable cursor depending on @enable
  50  * @con_scroll: move lines from @top to @bottom in direction @dir by @lines.
  51  *              Return true if no generic handling should be done.
  52  *              Invoked by csi_M and printing to the console.
  53  * @con_switch: notifier about the console switch; it is supposed to return
  54  *              true if a redraw is needed.
  55  * @con_blank:  blank/unblank the console. The target mode is passed in @blank.
  56  *              @mode_switch is set if changing from/to text/graphics. The hook
  57  *              is supposed to return true if a redraw is needed.
  58  * @con_font_set: set console @vc font to @font with height @vpitch. @flags can
  59  *              be %KD_FONT_FLAG_DONT_RECALC. (optional)
  60  * @con_font_get: fetch the current font on @vc of height @vpitch into @font.
  61  *              (optional)
  62  * @con_font_default: set default font on @vc. @name can be %NULL or font name
  63  *              to search for. @font can be filled back. (optional)
  64  * @con_resize: resize the @vc console to @width x @height. @from_user is true
  65  *              when this change comes from the user space.
  66  * @con_set_palette: sets the palette of the console @vc to @table (optional)
  67  * @con_scrolldelta: the contents of the console should be scrolled by @lines.
  68  *                   Invoked by user. (optional)
  69  * @con_set_origin: set origin (see &vc_data::vc_origin) of the @vc. If not
  70  *              provided or returns false, the origin is set to
  71  *              @vc->vc_screenbuf. (optional)
  72  * @con_save_screen: save screen content into @vc->vc_screenbuf. Called e.g.
  73  *              upon entering graphics. (optional)
  74  * @con_build_attr: build attributes based on @color, @intensity and other
  75  *              parameters. The result is used for both normal and erase
  76  *              characters. (optional)
  77  * @con_invert_region: invert a region of length @count on @vc starting at @p.
  78  *              (optional)
  79  * @con_debug_enter: prepare the console for the debugger. This includes, but
  80  *              is not limited to, unblanking the console, loading an
  81  *              appropriate palette, and allowing debugger generated output.
  82  *              (optional)
  83  * @con_debug_leave: restore the console to its pre-debug state as closely as
  84  *              possible. (optional)
  85  */
  86 struct consw {
  87         struct module *owner;
  88         const char *(*con_startup)(void);
  89         void    (*con_init)(struct vc_data *vc, bool init);
  90         void    (*con_deinit)(struct vc_data *vc);
  91         void    (*con_clear)(struct vc_data *vc, unsigned int y,
  92                              unsigned int x, unsigned int count);
  93         void    (*con_putc)(struct vc_data *vc, u16 ca, unsigned int y,
  94                             unsigned int x);
  95         void    (*con_putcs)(struct vc_data *vc, const u16 *s,
  96                              unsigned int count, unsigned int ypos,
  97                              unsigned int xpos);
  98         void    (*con_cursor)(struct vc_data *vc, bool enable);
  99         bool    (*con_scroll)(struct vc_data *vc, unsigned int top,
 100                         unsigned int bottom, enum con_scroll dir,
 101                         unsigned int lines);
 102         bool    (*con_switch)(struct vc_data *vc);
 103         bool    (*con_blank)(struct vc_data *vc, enum vesa_blank_mode blank,
 104                              bool mode_switch);
 105         int     (*con_font_set)(struct vc_data *vc,
 106                                 const struct console_font *font,
 107                                 unsigned int vpitch, unsigned int flags);
 108         int     (*con_font_get)(struct vc_data *vc, struct console_font *font,
 109                         unsigned int vpitch);
 110         int     (*con_font_default)(struct vc_data *vc,
 111                         struct console_font *font, const char *name);
 112         int     (*con_resize)(struct vc_data *vc, unsigned int width,
 113                               unsigned int height, bool from_user);
 114         void    (*con_set_palette)(struct vc_data *vc,
 115                         const unsigned char *table);
 116         void    (*con_scrolldelta)(struct vc_data *vc, int lines);
 117         bool    (*con_set_origin)(struct vc_data *vc);
 118         void    (*con_save_screen)(struct vc_data *vc);
 119         u8      (*con_build_attr)(struct vc_data *vc, u8 color,
 120                         enum vc_intensity intensity,
 121                         bool blink, bool underline, bool reverse, bool italic);
 122         void    (*con_invert_region)(struct vc_data *vc, u16 *p, int count);
 123         void    (*con_debug_enter)(struct vc_data *vc);
 124         void    (*con_debug_leave)(struct vc_data *vc);
 125 };
 126
 127 extern const struct consw *conswitchp;
 128
 129 extern const struct consw dummy_con;    /* dummy console buffer */
 130 extern const struct consw vga_con;      /* VGA text console */
 131 extern const struct consw newport_con;  /* SGI Newport console  */
 132
 133 struct screen_info;
 134 #ifdef CONFIG_VGA_CONSOLE
 135 void vgacon_register_screen(struct screen_info *si);
 136 #else
 137 static inline void vgacon_register_screen(struct screen_info *si) { }
 138 #endif
 139
 140 int con_is_bound(const struct consw *csw);
 141 int do_unregister_con_driver(const struct consw *csw);
 142 int do_take_over_console(const struct consw *sw, int first, int last, int deflt);
 143 void give_up_console(const struct consw *sw);
 144 #ifdef CONFIG_VT
 145 void con_debug_enter(struct vc_data *vc);
 146 void con_debug_leave(void);
 147 #else
 148 static inline void con_debug_enter(struct vc_data *vc) { }
 149 static inline void con_debug_leave(void) { }
 150 #endif
 151
 152 /*
 153  * The interface for a console, or any other device that wants to capture
 154  * console messages (printer driver?)
 155  */
 156
 157 /**
 158  * enum cons_flags - General console flags
 159  * @CON_PRINTBUFFER:    Used by newly registered consoles to avoid duplicate
 160  *                      output of messages that were already shown by boot
 161  *                      consoles or read by userspace via syslog() syscall.
 162  * @CON_CONSDEV:        Indicates that the console driver is backing
 163  *                      /dev/console.
 164  * @CON_ENABLED:        Indicates if a console is allowed to print records. If
 165  *                      false, the console also will not advance to later
 166  *                      records.
 167  * @CON_BOOT:           Marks the console driver as early console driver which
 168  *                      is used during boot before the real driver becomes
 169  *                      available. It will be automatically unregistered
 170  *                      when the real console driver is registered unless
 171  *                      "keep_bootcon" parameter is used.
 172  * @CON_ANYTIME:        A misnomed historical flag which tells the core code
 173  *                      that the legacy @console::write callback can be invoked
 174  *                      on a CPU which is marked OFFLINE. That is misleading as
 175  *                      it suggests that there is no contextual limit for
 176  *                      invoking the callback. The original motivation was
 177  *                      readiness of the per-CPU areas.
 178  * @CON_BRL:            Indicates a braille device which is exempt from
 179  *                      receiving the printk spam for obvious reasons.
 180  * @CON_EXTENDED:       The console supports the extended output format of
 181  *                      /dev/kmesg which requires a larger output buffer.
 182  * @CON_SUSPENDED:      Indicates if a console is suspended. If true, the
 183  *                      printing callbacks must not be called.
 184  * @CON_NBCON:          Console can operate outside of the legacy style console_lock
 185  *                      constraints.
 186  */
 187 enum cons_flags {
 188         CON_PRINTBUFFER         = BIT(0),
 189         CON_CONSDEV             = BIT(1),
 190         CON_ENABLED             = BIT(2),
 191         CON_BOOT                = BIT(3),
 192         CON_ANYTIME             = BIT(4),
 193         CON_BRL                 = BIT(5),
 194         CON_EXTENDED            = BIT(6),
 195         CON_SUSPENDED           = BIT(7),
 196         CON_NBCON               = BIT(8),
 197 };
 198
 199 /**
 200  * struct nbcon_state - console state for nbcon consoles
 201  * @atom:       Compound of the state fields for atomic operations
 202  *
 203  * @req_prio:           The priority of a handover request
 204  * @prio:               The priority of the current owner
 205  * @unsafe:             Console is busy in a non takeover region
 206  * @unsafe_takeover:    A hostile takeover in an unsafe state happened in the
 207  *                      past. The console cannot be safe until re-initialized.
 208  * @cpu:                The CPU on which the owner runs
 209  *
 210  * To be used for reading and preparing of the value stored in the nbcon
 211  * state variable @console::nbcon_state.
 212  *
 213  * The @prio and @req_prio fields are particularly important to allow
 214  * spin-waiting to timeout and give up without the risk of a waiter being
 215  * assigned the lock after giving up.
 216  */
 217 struct nbcon_state {
 218         union {
 219                 unsigned int    atom;
 220                 struct {
 221                         unsigned int prio               :  2;
 222                         unsigned int req_prio           :  2;
 223                         unsigned int unsafe             :  1;
 224                         unsigned int unsafe_takeover    :  1;
 225                         unsigned int cpu                : 24;
 226                 };
 227         };
 228 };
 229
 230 /*
 231  * The nbcon_state struct is used to easily create and interpret values that
 232  * are stored in the @console::nbcon_state variable. Ensure this struct stays
 233  * within the size boundaries of the atomic variable's underlying type in
 234  * order to avoid any accidental truncation.
 235  */
 236 static_assert(sizeof(struct nbcon_state) <= sizeof(int));
 237
 238 /**
 239  * enum nbcon_prio - console owner priority for nbcon consoles
 240  * @NBCON_PRIO_NONE:            Unused
 241  * @NBCON_PRIO_NORMAL:          Normal (non-emergency) usage
 242  * @NBCON_PRIO_EMERGENCY:       Emergency output (WARN/OOPS...)
 243  * @NBCON_PRIO_PANIC:           Panic output
 244  * @NBCON_PRIO_MAX:             The number of priority levels
 245  *
 246  * A higher priority context can takeover the console when it is
 247  * in the safe state. The final attempt to flush consoles in panic()
 248  * can be allowed to do so even in an unsafe state (Hope and pray).
 249  */
 250 enum nbcon_prio {
 251         NBCON_PRIO_NONE = 0,
 252         NBCON_PRIO_NORMAL,
 253         NBCON_PRIO_EMERGENCY,
 254         NBCON_PRIO_PANIC,
 255         NBCON_PRIO_MAX,
 256 };
 257
 258 struct console;
 259 struct printk_buffers;
 260
 261 /**
 262  * struct nbcon_context - Context for console acquire/release
 263  * @console:                    The associated console
 264  * @spinwait_max_us:            Limit for spin-wait acquire
 265  * @prio:                       Priority of the context
 266  * @allow_unsafe_takeover:      Allow performing takeover even if unsafe. Can
 267  *                              be used only with NBCON_PRIO_PANIC @prio. It
 268  *                              might cause a system freeze when the console
 269  *                              is used later.
 270  * @backlog:                    Ringbuffer has pending records
 271  * @pbufs:                      Pointer to the text buffer for this context
 272  * @seq:                        The sequence number to print for this context
 273  */
 274 struct nbcon_context {
 275         /* members set by caller */
 276         struct console          *console;
 277         unsigned int            spinwait_max_us;
 278         enum nbcon_prio         prio;
 279         unsigned int            allow_unsafe_takeover   : 1;
 280
 281         /* members set by emit */
 282         unsigned int            backlog                 : 1;
 283
 284         /* members set by acquire */
 285         struct printk_buffers   *pbufs;
 286         u64                     seq;
 287 };
 288
 289 /**
 290  * struct nbcon_write_context - Context handed to the nbcon write callbacks
 291  * @ctxt:               The core console context
 292  * @outbuf:             Pointer to the text buffer for output
 293  * @len:                Length to write
 294  * @unsafe_takeover:    If a hostile takeover in an unsafe state has occurred
 295  */
 296 struct nbcon_write_context {
 297         struct nbcon_context    __private ctxt;
 298         char                    *outbuf;
 299         unsigned int            len;
 300         bool                    unsafe_takeover;
 301 };
 302
 303 /**
 304  * struct console - The console descriptor structure
 305  * @name:               The name of the console driver
 306  * @write:              Write callback to output messages (Optional)
 307  * @read:               Read callback for console input (Optional)
 308  * @device:             The underlying TTY device driver (Optional)
 309  * @unblank:            Callback to unblank the console (Optional)
 310  * @setup:              Callback for initializing the console (Optional)
 311  * @exit:               Callback for teardown of the console (Optional)
 312  * @match:              Callback for matching a console (Optional)
 313  * @flags:              Console flags. See enum cons_flags
 314  * @index:              Console index, e.g. port number
 315  * @cflag:              TTY control mode flags
 316  * @ispeed:             TTY input speed
 317  * @ospeed:             TTY output speed
 318  * @seq:                Sequence number of the next ringbuffer record to print
 319  * @dropped:            Number of unreported dropped ringbuffer records
 320  * @data:               Driver private data
 321  * @node:               hlist node for the console list
 322  *
 323  * @write_atomic:       Write callback for atomic context
 324  * @nbcon_state:        State for nbcon consoles
 325  * @nbcon_seq:          Sequence number of the next record for nbcon to print
 326  * @pbufs:              Pointer to nbcon private buffer
 327  */
 328 struct console {
 329         char                    name[16];
 330         void                    (*write)(struct console *co, const char *s, unsigned int count);
 331         int                     (*read)(struct console *co, char *s, unsigned int count);
 332         struct tty_driver       *(*device)(struct console *co, int *index);
 333         void                    (*unblank)(void);
 334         int                     (*setup)(struct console *co, char *options);
 335         int                     (*exit)(struct console *co);
 336         int                     (*match)(struct console *co, char *name, int idx, char *options);
 337         short                   flags;
 338         short                   index;
 339         int                     cflag;
 340         uint                    ispeed;
 341         uint                    ospeed;
 342         u64                     seq;
 343         unsigned long           dropped;
 344         void                    *data;
 345         struct hlist_node       node;
 346
 347         /* nbcon console specific members */
 348         bool                    (*write_atomic)(struct console *con,
 349                                                 struct nbcon_write_context *wctxt);
 350         atomic_t                __private nbcon_state;
 351         atomic_long_t           __private nbcon_seq;
 352         struct printk_buffers   *pbufs;
 353 };
 354
 355 #ifdef CONFIG_LOCKDEP
 356 extern void lockdep_assert_console_list_lock_held(void);
 357 #else
 358 static inline void lockdep_assert_console_list_lock_held(void)
 359 {
 360 }
 361 #endif
 362
 363 #ifdef CONFIG_DEBUG_LOCK_ALLOC
 364 extern bool console_srcu_read_lock_is_held(void);
 365 #else
 366 static inline bool console_srcu_read_lock_is_held(void)
 367 {
 368         return 1;
 369 }
 370 #endif
 371
 372 extern int console_srcu_read_lock(void);
 373 extern void console_srcu_read_unlock(int cookie);
 374
 375 extern void console_list_lock(void) __acquires(console_mutex);
 376 extern void console_list_unlock(void) __releases(console_mutex);
 377
 378 extern struct hlist_head console_list;
 379
 380 /**
 381  * console_srcu_read_flags - Locklessly read the console flags
 382  * @con:        struct console pointer of console to read flags from
 383  *
 384  * This function provides the necessary READ_ONCE() and data_race()
 385  * notation for locklessly reading the console flags. The READ_ONCE()
 386  * in this function matches the WRITE_ONCE() when @flags are modified
 387  * for registered consoles with console_srcu_write_flags().
 388  *
 389  * Only use this function to read console flags when locklessly
 390  * iterating the console list via srcu.
 391  *
 392  * Context: Any context.
 393  */
 394 static inline short console_srcu_read_flags(const struct console *con)
 395 {
 396         WARN_ON_ONCE(!console_srcu_read_lock_is_held());
 397
 398         /*
 399          * Locklessly reading console->flags provides a consistent
 400          * read value because there is at most one CPU modifying
 401          * console->flags and that CPU is using only read-modify-write
 402          * operations to do so.
 403          */
 404         return data_race(READ_ONCE(con->flags));
 405 }
 406
 407 /**
 408  * console_srcu_write_flags - Write flags for a registered console
 409  * @con:        struct console pointer of console to write flags to
 410  * @flags:      new flags value to write
 411  *
 412  * Only use this function to write flags for registered consoles. It
 413  * requires holding the console_list_lock.
 414  *
 415  * Context: Any context.
 416  */
 417 static inline void console_srcu_write_flags(struct console *con, short flags)
 418 {
 419         lockdep_assert_console_list_lock_held();
 420
 421         /* This matches the READ_ONCE() in console_srcu_read_flags(). */
 422         WRITE_ONCE(con->flags, flags);
 423 }
 424
 425 /* Variant of console_is_registered() when the console_list_lock is held. */
 426 static inline bool console_is_registered_locked(const struct console *con)
 427 {
 428         lockdep_assert_console_list_lock_held();
 429         return !hlist_unhashed(&con->node);
 430 }
 431
 432 /*
 433  * console_is_registered - Check if the console is registered
 434  * @con:        struct console pointer of console to check
 435  *
 436  * Context: Process context. May sleep while acquiring console list lock.
 437  * Return: true if the console is in the console list, otherwise false.
 438  *
 439  * If false is returned for a console that was previously registered, it
 440  * can be assumed that the console's unregistration is fully completed,
 441  * including the exit() callback after console list removal.
 442  */
 443 static inline bool console_is_registered(const struct console *con)
 444 {
 445         bool ret;
 446
 447         console_list_lock();
 448         ret = console_is_registered_locked(con);
 449         console_list_unlock();
 450         return ret;
 451 }
 452
 453 /**
 454  * for_each_console_srcu() - Iterator over registered consoles
 455  * @con:        struct console pointer used as loop cursor
 456  *
 457  * Although SRCU guarantees the console list will be consistent, the
 458  * struct console fields may be updated by other CPUs while iterating.
 459  *
 460  * Requires console_srcu_read_lock to be held. Can be invoked from
 461  * any context.
 462  */
 463 #define for_each_console_srcu(con)                                      \
 464         hlist_for_each_entry_srcu(con, &console_list, node,             \
 465                                   console_srcu_read_lock_is_held())
 466
 467 /**
 468  * for_each_console() - Iterator over registered consoles
 469  * @con:        struct console pointer used as loop cursor
 470  *
 471  * The console list and the &console.flags are immutable while iterating.
 472  *
 473  * Requires console_list_lock to be held.
 474  */
 475 #define for_each_console(con)                                           \
 476         lockdep_assert_console_list_lock_held();                        \
 477         hlist_for_each_entry(con, &console_list, node)
 478
 479 #ifdef CONFIG_PRINTK
 480 extern bool nbcon_can_proceed(struct nbcon_write_context *wctxt);
 481 extern bool nbcon_enter_unsafe(struct nbcon_write_context *wctxt);
 482 extern bool nbcon_exit_unsafe(struct nbcon_write_context *wctxt);
 483 #else
 484 static inline bool nbcon_can_proceed(struct nbcon_write_context *wctxt) { return false; }
 485 static inline bool nbcon_enter_unsafe(struct nbcon_write_context *wctxt) { return false; }
 486 static inline bool nbcon_exit_unsafe(struct nbcon_write_context *wctxt) { return false; }
 487 #endif
 488
 489 extern int console_set_on_cmdline;
 490 extern struct console *early_console;
 491
 492 enum con_flush_mode {
 493         CONSOLE_FLUSH_PENDING,
 494         CONSOLE_REPLAY_ALL,
 495 };
 496
 497 extern int add_preferred_console(const char *name, const short idx, char *options);
 498 extern void console_force_preferred_locked(struct console *con);
 499 extern void register_console(struct console *);
 500 extern int unregister_console(struct console *);
 501 extern void console_lock(void);
 502 extern int console_trylock(void);
 503 extern void console_unlock(void);
 504 extern void console_conditional_schedule(void);
 505 extern void console_unblank(void);
 506 extern void console_flush_on_panic(enum con_flush_mode mode);
 507 extern struct tty_driver *console_device(int *);
 508 extern void console_stop(struct console *);
 509 extern void console_start(struct console *);
 510 extern int is_console_locked(void);
 511 extern int braille_register_console(struct console *, int index,
 512                 char *console_options, char *braille_options);
 513 extern int braille_unregister_console(struct console *);
 514 #ifdef CONFIG_TTY
 515 extern void console_sysfs_notify(void);
 516 #else
 517 static inline void console_sysfs_notify(void)
 518 { }
 519 #endif
 520 extern bool console_suspend_enabled;
 521
 522 /* Suspend and resume console messages over PM events */
 523 extern void suspend_console(void);
 524 extern void resume_console(void);
 525
 526 int mda_console_init(void);
 527
 528 void vcs_make_sysfs(int index);
 529 void vcs_remove_sysfs(int index);
 530
 531 /* Some debug stub to catch some of the obvious races in the VT code */
 532 #define WARN_CONSOLE_UNLOCKED()                                         \
 533         WARN_ON(!atomic_read(&ignore_console_lock_warning) &&           \
 534                 !is_console_locked() && !oops_in_progress)
 535 /*
 536  * Increment ignore_console_lock_warning if you need to quiet
 537  * WARN_CONSOLE_UNLOCKED() for debugging purposes.
 538  */
 539 extern atomic_t ignore_console_lock_warning;
 540
 541 extern void console_init(void);
 542
 543 /* For deferred console takeover */
 544 void dummycon_register_output_notifier(struct notifier_block *nb);
 545 void dummycon_unregister_output_notifier(struct notifier_block *nb);
 546
 547 #endif /* _LINUX_CONSOLE_H */