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