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