Documentation/video/tegra_dc_ext.txt

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.