include/video_console.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (c) 2015 Google, Inc
   4  */
   5
   6 #ifndef __video_console_h
   7 #define __video_console_h
   8
   9 #include <video.h>
  10
  11 struct abuf;
  12 struct video_priv;
  13
  14 #define VID_FRAC_DIV    256
  15
  16 #define VID_TO_PIXEL(x) ((x) / VID_FRAC_DIV)
  17 #define VID_TO_POS(x)   ((x) * VID_FRAC_DIV)
  18
  19 enum {
  20         /* cursor width in pixels */
  21         VIDCONSOLE_CURSOR_WIDTH         = 2,
  22 };
  23
  24 /**
  25  * struct vidconsole_priv - uclass-private data about a console device
  26  *
  27  * Drivers must set up @rows, @cols, @x_charsize, @y_charsize in their probe()
  28  * method. Drivers may set up @xstart_frac if desired.
  29  *
  30  * @sdev:               stdio device, acting as an output sink
  31  * @xcur_frac:          Current X position, in fractional units (VID_TO_POS(x))
  32  * @ycur:               Current Y position in pixels (0=top)
  33  * @rows:               Number of text rows
  34  * @cols:               Number of text columns
  35  * @x_charsize:         Character width in pixels
  36  * @y_charsize:         Character height in pixels
  37  * @tab_width_frac:     Tab width in fractional units
  38  * @xsize_frac:         Width of the display in fractional units
  39  * @xstart_frac:        Left margin for the text console in fractional units
  40  * @last_ch:            Last character written to the text console on this line
  41  * @escape:             TRUE if currently accumulating an ANSI escape sequence
  42  * @escape_len:         Length of accumulated escape sequence so far
  43  * @col_saved:          Saved X position, in fractional units (VID_TO_POS(x))
  44  * @row_saved:          Saved Y position in pixels (0=top)
  45  * @escape_buf:         Buffer to accumulate escape sequence
  46  */
  47 struct vidconsole_priv {
  48         struct stdio_dev sdev;
  49         int xcur_frac;
  50         int ycur;
  51         int rows;
  52         int cols;
  53         int x_charsize;
  54         int y_charsize;
  55         int tab_width_frac;
  56         int xsize_frac;
  57         int xstart_frac;
  58         int last_ch;
  59         /*
  60          * ANSI escape sequences are accumulated character by character,
  61          * starting after the ESC char (0x1b) until the entire sequence
  62          * is consumed at which point it is acted upon.
  63          */
  64         int escape;
  65         int escape_len;
  66         int row_saved;
  67         int col_saved;
  68         char escape_buf[32];
  69 };
  70
  71 /**
  72  * struct vidfont_info - information about a font
  73  *
  74  * @name: Font name, e.g. nimbus_sans_l_regular
  75  */
  76 struct vidfont_info {
  77         const char *name;
  78 };
  79
  80 /**
  81  * struct vidconsole_colour - Holds colour information
  82  *
  83  * @colour_fg:  Foreground colour (pixel value)
  84  * @colour_bg:  Background colour (pixel value)
  85  */
  86 struct vidconsole_colour {
  87         u32 colour_fg;
  88         u32 colour_bg;
  89 };
  90
  91 /**
  92  * struct vidconsole_bbox - Bounding box of text
  93  *
  94  * This describes the bounding box of something, measured in pixels. The x0/y0
  95  * pair is inclusive; the x1/y2 pair is exclusive, meaning that it is one pixel
  96  * beyond the extent of the object
  97  *
  98  * @valid: Values are valid (bounding box is known)
  99  * @x0: left x position, in pixels from left side
 100  * @y0: top y position, in pixels from top
 101  * @x1: right x position + 1
 102  * @y1: botton y position + 1
 103  */
 104 struct vidconsole_bbox {
 105         bool valid;
 106         int x0;
 107         int y0;
 108         int x1;
 109         int y1;
 110 };
 111
 112 /**
 113  * struct vidconsole_ops - Video console operations
 114  *
 115  * These operations work on either an absolute console position (measured
 116  * in pixels) or a text row number (measured in rows, where each row consists
 117  * of an entire line of text - typically 16 pixels).
 118  */
 119 struct vidconsole_ops {
 120         /**
 121          * putc_xy() - write a single character to a position
 122          *
 123          * @dev:        Device to write to
 124          * @x_frac:     Fractional pixel X position (0=left-most pixel) which
 125          *              is the X position multipled by VID_FRAC_DIV.
 126          * @y:          Pixel Y position (0=top-most pixel)
 127          * @ch:         Character to write
 128          * @return number of fractional pixels that the cursor should move,
 129          * if all is OK, -EAGAIN if we ran out of space on this line, other -ve
 130          * on error
 131          */
 132         int (*putc_xy)(struct udevice *dev, uint x_frac, uint y, char ch);
 133
 134         /**
 135          * move_rows() - Move text rows from one place to another
 136          *
 137          * @dev:        Device to adjust
 138          * @rowdst:     Destination text row (0=top)
 139          * @rowsrc:     Source start text row
 140          * @count:      Number of text rows to move
 141          * @return 0 if OK, -ve on error
 142          */
 143         int (*move_rows)(struct udevice *dev, uint rowdst, uint rowsrc,
 144                           uint count);
 145
 146         /**
 147          * set_row() - Set the colour of a text row
 148          *
 149          * Every pixel contained within the text row is adjusted
 150          *
 151          * @dev:        Device to adjust
 152          * @row:        Text row to adjust (0=top)
 153          * @clr:        Raw colour (pixel value) to write to each pixel
 154          * @return 0 if OK, -ve on error
 155          */
 156         int (*set_row)(struct udevice *dev, uint row, int clr);
 157
 158         /**
 159          * entry_start() - Indicate that text entry is starting afresh
 160          *
 161          * @dev:        Device to adjust
 162          * Returns: 0 on success, -ve on error
 163          *
 164          * Consoles which use proportional fonts need to track the position of
 165          * each character output so that backspace will return to the correct
 166          * place. This method signals to the console driver that a new entry
 167          * line is being start (e.g. the user pressed return to start a new
 168          * command). The driver can use this signal to empty its list of
 169          * positions.
 170          */
 171         int (*entry_start)(struct udevice *dev);
 172
 173         /**
 174          * backspace() - Handle erasing the last character
 175          *
 176          * @dev:        Device to adjust
 177          * Returns: 0 on success, -ve on error
 178          *
 179          * With proportional fonts the vidconsole uclass cannot itself erase
 180          * the previous character. This optional method will be called when
 181          * a backspace is needed. The driver should erase the previous
 182          * character and update the cursor position (xcur_frac, ycur) to the
 183          * start of the previous character.
 184          *
 185          * If not implement, default behaviour will work for fixed-width
 186          * characters.
 187          */
 188         int (*backspace)(struct udevice *dev);
 189
 190         /**
 191          * get_font() - Obtain information about a font (optional)
 192          *
 193          * @dev:        Device to check
 194          * @seq:        Font number to query (0=first, 1=second, etc.)
 195          * @info:       Returns font information on success
 196          * Returns: 0 on success, -ENOENT if no such font
 197          */
 198         int (*get_font)(struct udevice *dev, int seq,
 199                         struct vidfont_info *info);
 200
 201         /**
 202          * get_font_size() - get the current font name and size
 203          *
 204          * @dev: vidconsole device
 205          * @sizep: Place to put the font size (nominal height in pixels)
 206          * Returns: Current font name
 207          */
 208         const char *(*get_font_size)(struct udevice *dev, uint *sizep);
 209
 210         /**
 211          * select_font() - Select a particular font by name / size
 212          *
 213          * @dev:        Device to adjust
 214          * @name:       Font name to use (NULL to use default)
 215          * @size:       Font size to use (0 to use default)
 216          * Returns: 0 on success, -ENOENT if no such font
 217          */
 218         int (*select_font)(struct udevice *dev, const char *name, uint size);
 219
 220         /**
 221          * measure() - Measure the bounds of some text
 222          *
 223          * @dev:        Device to adjust
 224          * @name:       Font name to use (NULL to use default)
 225          * @size:       Font size to use (0 to use default)
 226          * @text:       Text to measure
 227          * @bbox:       Returns bounding box of text, assuming it is positioned
 228          *              at 0,0
 229          * Returns: 0 on success, -ENOENT if no such font
 230          */
 231         int (*measure)(struct udevice *dev, const char *name, uint size,
 232                        const char *text, struct vidconsole_bbox *bbox);
 233
 234         /**
 235          * nominal() - Measure the expected width of a line of text
 236          *
 237          * Uses an average font width and nominal height
 238          *
 239          * @dev: Console device to use
 240          * @name: Font name, NULL for default
 241          * @size: Font size, ignored if @name is NULL
 242          * @num_chars: Number of characters to use
 243          * @bbox: Returns nounding box of @num_chars characters
 244          * Returns: 0 if OK, -ve on error
 245          */
 246         int (*nominal)(struct udevice *dev, const char *name, uint size,
 247                        uint num_chars, struct vidconsole_bbox *bbox);
 248
 249         /**
 250          * entry_save() - Save any text-entry information for later use
 251          *
 252          * Saves text-entry context such as a list of positions for each
 253          * character in the string.
 254          *
 255          * @dev: Console device to use
 256          * @buf: Buffer to hold saved data
 257          * Return: 0 if OK, -ENOMEM if out of memory
 258          */
 259         int (*entry_save)(struct udevice *dev, struct abuf *buf);
 260
 261         /**
 262          * entry_restore() - Restore text-entry information for current use
 263          *
 264          * Restores text-entry context such as a list of positions for each
 265          * character in the string.
 266          *
 267          * @dev: Console device to use
 268          * @buf: Buffer containing data to restore
 269          * Return: 0 if OK, -ve on error
 270          */
 271         int (*entry_restore)(struct udevice *dev, struct abuf *buf);
 272
 273         /**
 274          * set_cursor_visible() - Show or hide the cursor
 275          *
 276          * Shows or hides a cursor at the current position
 277          *
 278          * @dev: Console device to use
 279          * @visible: true to show the cursor, false to hide it
 280          * @x: X position in pixels
 281          * @y: Y position in pixels
 282          * @index: Character position (0 = at start)
 283          * Return: 0 if OK, -ve on error
 284          */
 285         int (*set_cursor_visible)(struct udevice *dev, bool visible,
 286                                   uint x, uint y, uint index);
 287 };
 288
 289 /* Get a pointer to the driver operations for a video console device */
 290 #define vidconsole_get_ops(dev)  ((struct vidconsole_ops *)(dev)->driver->ops)
 291
 292 /**
 293  * vidconsole_get_font() - Obtain information about a font
 294  *
 295  * @dev:        Device to check
 296  * @seq:        Font number to query (0=first, 1=second, etc.)
 297  * @info:       Returns font information on success
 298  * Returns: 0 on success, -ENOENT if no such font, -ENOSYS if there is no such
 299  * method
 300  */
 301 int vidconsole_get_font(struct udevice *dev, int seq,
 302                         struct vidfont_info *info);
 303
 304 /**
 305  * vidconsole_select_font() - Select a particular font by name / size
 306  *
 307  * @dev:        Device to adjust
 308  * @name:       Font name to use (NULL to use default)
 309  * @size:       Font size to use (0 to use default)
 310  */
 311 int vidconsole_select_font(struct udevice *dev, const char *name, uint size);
 312
 313 /*
 314  * vidconsole_measure() - Measuring the bounding box of some text
 315  *
 316  * @dev: Console device to use
 317  * @name: Font name, NULL for default
 318  * @size: Font size, ignored if @name is NULL
 319  * @text: Text to measure
 320  * @bbox: Returns nounding box of text
 321  * Returns: 0 if OK, -ve on error
 322  */
 323 int vidconsole_measure(struct udevice *dev, const char *name, uint size,
 324                        const char *text, struct vidconsole_bbox *bbox);
 325
 326 /**
 327  * vidconsole_nominal() - Measure the expected width of a line of text
 328  *
 329  * Uses an average font width and nominal height
 330  *
 331  * @dev: Console device to use
 332  * @name: Font name, NULL for default
 333  * @size: Font size, ignored if @name is NULL
 334  * @num_chars: Number of characters to use
 335  * @bbox: Returns nounding box of @num_chars characters
 336  * Returns: 0 if OK, -ve on error
 337  */
 338 int vidconsole_nominal(struct udevice *dev, const char *name, uint size,
 339                        uint num_chars, struct vidconsole_bbox *bbox);
 340
 341 /**
 342  * vidconsole_entry_save() - Save any text-entry information for later use
 343  *
 344  * Saves text-entry context such as a list of positions for each
 345  * character in the string.
 346  *
 347  * @dev: Console device to use
 348  * @buf: Buffer to hold saved data
 349  * Return: 0 if OK, -ENOMEM if out of memory
 350  */
 351 int vidconsole_entry_save(struct udevice *dev, struct abuf *buf);
 352
 353 /**
 354  * entry_restore() - Restore text-entry information for current use
 355  *
 356  * Restores text-entry context such as a list of positions for each
 357  * character in the string.
 358  *
 359  * @dev: Console device to use
 360  * @buf: Buffer containing data to restore
 361  * Return: 0 if OK, -ve on error
 362  */
 363 int vidconsole_entry_restore(struct udevice *dev, struct abuf *buf);
 364
 365 /**
 366  * vidconsole_set_cursor_visible() - Show or hide the cursor
 367  *
 368  * Shows or hides a cursor at the current position
 369  *
 370  * @dev: Console device to use
 371  * @visible: true to show the cursor, false to hide it
 372  * @x: X position in pixels
 373  * @y: Y position in pixels
 374  * @index: Character position (0 = at start)
 375  * Return: 0 if OK, -ve on error
 376  */
 377 int vidconsole_set_cursor_visible(struct udevice *dev, bool visible,
 378                                   uint x, uint y, uint index);
 379
 380 /**
 381  * vidconsole_push_colour() - Temporarily change the font colour
 382  *
 383  * @dev:        Device to adjust
 384  * @fg:         Foreground colour to select
 385  * @bg:         Background colour to select
 386  * @old:        Place to store the current colour, so it can be restored
 387  */
 388 void vidconsole_push_colour(struct udevice *dev, enum colour_idx fg,
 389                             enum colour_idx bg, struct vidconsole_colour *old);
 390
 391 /**
 392  * vidconsole_pop_colour() - Restore the original colour
 393  *
 394  * @dev:        Device to adjust
 395  * @old:        Old colour to be restored
 396  */
 397 void vidconsole_pop_colour(struct udevice *dev, struct vidconsole_colour *old);
 398
 399 /**
 400  * vidconsole_putc_xy() - write a single character to a position
 401  *
 402  * @dev:        Device to write to
 403  * @x_frac:     Fractional pixel X position (0=left-most pixel) which
 404  *              is the X position multipled by VID_FRAC_DIV.
 405  * @y:          Pixel Y position (0=top-most pixel)
 406  * @ch:         Character to write
 407  * Return: number of fractional pixels that the cursor should move,
 408  * if all is OK, -EAGAIN if we ran out of space on this line, other -ve
 409  * on error
 410  */
 411 int vidconsole_putc_xy(struct udevice *dev, uint x, uint y, char ch);
 412
 413 /**
 414  * vidconsole_move_rows() - Move text rows from one place to another
 415  *
 416  * @dev:        Device to adjust
 417  * @rowdst:     Destination text row (0=top)
 418  * @rowsrc:     Source start text row
 419  * @count:      Number of text rows to move
 420  * Return: 0 if OK, -ve on error
 421  */
 422 int vidconsole_move_rows(struct udevice *dev, uint rowdst, uint rowsrc,
 423                          uint count);
 424
 425 /**
 426  * vidconsole_set_row() - Set the colour of a text row
 427  *
 428  * Every pixel contained within the text row is adjusted
 429  *
 430  * @dev:        Device to adjust
 431  * @row:        Text row to adjust (0=top)
 432  * @clr:        Raw colour (pixel value) to write to each pixel
 433  * Return: 0 if OK, -ve on error
 434  */
 435 int vidconsole_set_row(struct udevice *dev, uint row, int clr);
 436
 437 /**
 438  * vidconsole_entry_start() - Set the start position of a vidconsole line
 439  *
 440  * Marks the current cursor position as the start of a line
 441  *
 442  * @dev:        Device to adjust
 443  */
 444 int vidconsole_entry_start(struct udevice *dev);
 445
 446 /**
 447  * vidconsole_put_char() - Output a character to the current console position
 448  *
 449  * Outputs a character to the console and advances the cursor. This function
 450  * handles wrapping to new lines and scrolling the console. Special
 451  * characters are handled also: \n, \r, \b and \t.
 452  *
 453  * The device always starts with the cursor at position 0,0 (top left). It
 454  * can be adjusted manually using vidconsole_position_cursor().
 455  *
 456  * @dev:        Device to adjust
 457  * @ch:         Character to write
 458  * Return: 0 if OK, -ve on error
 459  */
 460 int vidconsole_put_char(struct udevice *dev, char ch);
 461
 462 /**
 463  * vidconsole_put_string() - Output a string to the current console position
 464  *
 465  * Outputs a string to the console and advances the cursor. This function
 466  * handles wrapping to new lines and scrolling the console. Special
 467  * characters are handled also: \n, \r, \b and \t.
 468  *
 469  * The device always starts with the cursor at position 0,0 (top left). It
 470  * can be adjusted manually using vidconsole_position_cursor().
 471  *
 472  * @dev:        Device to adjust
 473  * @str:        String to write
 474  * Return: 0 if OK, -ve on error
 475  */
 476 int vidconsole_put_string(struct udevice *dev, const char *str);
 477
 478 /**
 479  * vidconsole_position_cursor() - Move the text cursor
 480  *
 481  * @dev:        Device to adjust
 482  * @col:        New cursor text column
 483  * @row:        New cursor text row
 484  * Return: 0 if OK, -ve on error
 485  */
 486 void vidconsole_position_cursor(struct udevice *dev, unsigned col,
 487                                 unsigned row);
 488
 489 /**
 490  * vidconsole_clear_and_reset() - Clear the console and reset the cursor
 491  *
 492  * The cursor is placed at the start of the console
 493  *
 494  * @dev:        vidconsole device to adjust
 495  */
 496 int vidconsole_clear_and_reset(struct udevice *dev);
 497
 498 /**
 499  * vidconsole_set_cursor_pos() - set cursor position
 500  *
 501  * The cursor is set to the new position and the start-of-line information is
 502  * updated to the same position, so that a newline will return to @x
 503  *
 504  * @dev:        video console device to update
 505  * @x:          x position from left in pixels
 506  * @y:          y position from top in pixels
 507  */
 508 void vidconsole_set_cursor_pos(struct udevice *dev, int x, int y);
 509
 510 /**
 511  * vidconsole_list_fonts() - List the available fonts
 512  *
 513  * @dev: vidconsole device to check
 514  *
 515  * This shows a list of fonts known by this vidconsole. The list is displayed on
 516  * the console (not necessarily @dev but probably)
 517  */
 518 void vidconsole_list_fonts(struct udevice *dev);
 519
 520 /**
 521  * vidconsole_get_font_size() - get the current font name and size
 522  *
 523  * @dev: vidconsole device
 524  * @sizep: Place to put the font size (nominal height in pixels)
 525  * @name: pointer to font name, a placeholder for result
 526  * Return: 0 if OK, -ENOSYS if not implemented in driver
 527  */
 528 int vidconsole_get_font_size(struct udevice *dev, const char **name, uint *sizep);
 529
 530 #ifdef CONFIG_VIDEO_COPY
 531 /**
 532  * vidconsole_sync_copy() - Sync back to the copy framebuffer
 533  *
 534  * This ensures that the copy framebuffer has the same data as the framebuffer
 535  * for a particular region. It should be called after the framebuffer is updated
 536  *
 537  * @from and @to can be in either order. The region between them is synced.
 538  *
 539  * @dev: Vidconsole device being updated
 540  * @from: Start/end address within the framebuffer (->fb)
 541  * @to: Other address within the frame buffer
 542  * Return: 0 if OK, -EFAULT if the start address is before the start of the
 543  *      frame buffer start
 544  */
 545 int vidconsole_sync_copy(struct udevice *dev, void *from, void *to);
 546
 547 /**
 548  * vidconsole_memmove() - Perform a memmove() within the frame buffer
 549  *
 550  * This handles a memmove(), e.g. for scrolling. It also updates the copy
 551  * framebuffer.
 552  *
 553  * @dev: Vidconsole device being updated
 554  * @dst: Destination address within the framebuffer (->fb)
 555  * @src: Source address within the framebuffer (->fb)
 556  * @size: Number of bytes to transfer
 557  * Return: 0 if OK, -EFAULT if the start address is before the start of the
 558  *      frame buffer start
 559  */
 560 int vidconsole_memmove(struct udevice *dev, void *dst, const void *src,
 561                        int size);
 562 #else
 563
 564 #include <string.h>
 565
 566 static inline int vidconsole_sync_copy(struct udevice *dev, void *from,
 567                                        void *to)
 568 {
 569         return 0;
 570 }
 571
 572 static inline int vidconsole_memmove(struct udevice *dev, void *dst,
 573                                      const void *src, int size)
 574 {
 575         memmove(dst, src, size);
 576
 577         return 0;
 578 }
 579
 580 #endif
 581
 582 #endif