blob: 6fc3394c6652f899633586202454292c378e3fbe [file] [log] [blame]
The Tegra display controller (dc) driver has two frontends that implement
different interfaces:
1. The traditional fbdev interface, implemented in drivers/video/tegra/fb.c
2. A new interface that exposes the unique capabilities of the controller,
implemented in drivers/video/tegra/dc/ext
The Tegra fbdev capabilities are documented in fb/tegrafb.c [TODO]. This
document will describe the new "extended" dc interface.
The extended interface is only available when its frontend has been compiled
in, i.e., CONFIG_TEGRA_DC_EXTENSIONS=y. The dc_ext frontend can coexist with
tegrafb, but takes precedence (more on that later).
The dc_ext frontend's interface to userspace is exposed through a set of
device nodes: one for each controller (generally /dev/tegra_dc_N), and one
"control" node (generally /dev/tegra_dc_ctrl). Communication through these
device nodes is done with special IOCTLs. There is also an event delivery
mechanism; userspace can wait for and receive events with read() or poll().
The tegra_dc_N interface is stateful; each fresh open() of the device node
creates a client instance. In order to prevent multiple processes from
"fighting" for the hardware, only one client instance is permitted to control
certain resources at a time, on a first-come, first-serve basis.
Overview of tegra_dc_N IOCTLs:
SET_NVMAP_FD: This is used to associate your nvmap client with this dc_ext
client instance. This is necessary so that the kernel can
appropriately enforce permissions on nvmap buffers.
GET_WINDOW: A dc_ext client must call this on each window that it wishes to
control. This strictly enforces a single dc_ext client on a
window at a time.
PUT_WINDOW: A dc_ext client may call this to release a window previously
reserved with GET_WINDOW.
FLIP: This ioctl is used to actually display an nvmap surface using one or
more window. Each time a dc_ext client performs a FLIP, the request is
put on a flip queue and executed asynchronously (the FLIP ioctl will
return immediately). Various parameters are available in the
tegra_dc_ext_flip structure.
A dc_ext client may only use this on windows that it has previously
reserved with a successful GET_WINDOW call.
GET_CURSOR: This is analogous to GET_WINDOW, but for the hardware cursor
instead of a window.
PUT_CURSOR: This is analogous to PUT_WINDOW, but for the hardware cursor
instead of a window.
SET_CURSOR_IMAGE: This is used to change the hardware cursor image. May only
be used by a client who has successfully performed a
GET_CURSOR call.
SET_CURSOR: This is used to actually place the hardware cursor on the screen.
May only be used by a client who has successfully performed a
GET_CURSOR call.
SET_CSC: This may be used to set a color space conversion matrix on a window.
A dc_ext client may only use this on windows that it has previously
reserved with a successful GET_WINDOW call.
GET_STATUS: This is used to retrieve general status about the dc.
GET_VBLANK_SYNCPT: This is used to retrieve the auto-incrementing vblank
syncpoint for the head associated with this dc.
Overview of tegra_dc_ctrl IOCTLs:
GET_NUM_OUTPUTS: This returns the number of available output devices on the
system, which may exceed the number of display controllers.
GET_OUTPUT_PROPERTIES: This returns data about the given output, such as what
kind of output it is, whether it's currently associated
with a head, etc.
GET_OUTPUT_EDID: This returns the binary EDID read from the device connected
to the given output, if any.
SET_EVENT_MASK: A dc_ext client may call this ioctl with a bitmask of events
that it wishes to receive. These events will then be
available to that client on a subsequent read() on the same
file descriptor.