coreboot_tables: Document coreboot framebuffer

A discussion around the `bytes_per_line` field (it was ignored in
CorebootPayloadPkg for some reason) made the lack of documentation
obvious.

Change-Id: I5e1343b5fe37ac106e61e6907fbcc1737ac56f8b
Signed-off-by: Nico Huber <nico.h@gmx.de>
Reviewed-on: https://review.coreboot.org/23466
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Reviewed-by: Patrick Rudolph <siro@das-labor.org>
This commit is contained in:
Nico Huber 2018-01-27 16:40:11 +01:00
parent 9d07910d24
commit 310abe0bde
1 changed files with 39 additions and 0 deletions

View File

@ -211,6 +211,45 @@ struct lb_forward {
uint64_t forward;
};
/**
* coreboot framebuffer
*
* The coreboot framebuffer uses a very common format usually referred
* to as "linear framebuffer":
*
* The first pixel of the framebuffer is the upper left corner, its
* address is given by `physical_address`.
*
* Each pixel is represented by exactly `bits_per_pixel` bits. If a
* pixel (or a color component therein) doesn't fill a whole byte or
* doesn't start on a byte boundary, it starts at the least signifi-
* cant bit not occupied by the previous pixel (or color component).
* Pixels (or color components) that span multiple bytes always start
* in the byte with the lowest address.
*
* The framebuffer provides a visible rectangle of `x_resolution` *
* `y_resolution` pixels. However, the lines always start at a byte
* boundary given by `bytes_per_line`, which may leave a gap after
* each line of pixels. Thus, the data for a pixel with the coordi-
* nates (x, y) from the upper left corner always starts at
*
* physical_address + y * bytes_per_line + x * bits_per_pixel / 8
*
* `bytes_per_line` is always big enough to hold `x_resolution`
* pixels. It can, however, be arbitrarily higher (e.g. to fulfill
* hardware constraints or for optimization purposes). The size of
* the framebuffer is always `y_resolution * bytes_per_line`.
*
* The coreboot framebuffer only supports RGB color formats. The
* position and size of each color component are specified indivi-
* dually by <color>_mask_pos and <color>_mask_size. To allow byte
* or word aligned pixels, a fourth (padding) component may be
* specified by `reserved_mask_pos` and `reserved_mask_size`.
*
* Software utilizing the coreboot framebuffer shall consider all
* fields described above. It may, however, only implement a subset
* of the possible color formats.
*/
#define LB_TAG_FRAMEBUFFER 0x0012
struct lb_framebuffer {
uint32_t tag;