gpu: omap_hwc: Describe the api agreement with omaplfb

Change-Id: I8b5173b6b89388cbb0185f5a2576893699268143
Signed-off-by: Tony Lofthouse <a0741364@ti.com>
Signed-off-by: Sundar Raman <sunds@ti.com>

diff --git a/include/video/omap_hwc.h b/include/video/omap_hwc.h
index 0fb31f10c5b1634eda57f1992159711ecbbac98f..cea2d73b8847432dd9bf04c0aa83d9209c8f1c65 100644 (file)
--- a/include/video/omap_hwc.h
+++ b/include/video/omap_hwc.h
@@ -20,6 +20,73 @@
 #ifndef _LINUX_OMAP_HWC_H
 #define _LINUX_OMAP_HWC_H
 
+/*
+ * Client of the omap_hwc_data API
+ * -------------------------------
+ * This is really a kernel to kernel API (not an ioctl interface) but most of
+ * the values are populated in user space by a single client, specifically the
+ * Android hardware composer HAL (HWC) which is a library loaded by the
+ * SurfaceFlinger composition process.
+ *
+ * Implementation details
+ * ----------------------
+ * The SGX display driver (called OMAPLFB) will obtain this data structure
+ * from the GPU driver (aka PVR kernel services) as well as an array of
+ * memory descriptors managed by PVR services. OMAPLFB is responsible
+ * for fixing up the buffer data within the omap_hwc_data data structure
+ * before calling the DSSCOMP module and (optionally) the Bltsville kernel
+ * API/implementation.
+ *
+ * Buffer referencing
+ * ------------------
+ * When calling from the HWC (via PVR services) the actual address of buffers
+ * involved in composition are typically unknown. It is a convention to store
+ * an index in the appropriate field of the sub-structures in omap_hwc_data.
+ * PVR services also passes an array of memory data structures that these
+ * indexes (commonly) refer to.
+ *
+ * The dsscomp API fully describes how it manages buffering when called
+ * from a kernel client context. The simplest scenario is that individual
+ * overlays carry the buffer index in the overlay structure base address.
+ *
+ * For Bltsville kernel mode support, buffers are identified by storing the
+ * buffer index in the virtaddr of the various bvbuffdesc entries. Some
+ * exceptions are described below.
+ *
+ * Blitting
+ * --------
+ * Blit source buffers are managed in the same way as Post2 layers in the
+ * dsscomp API. The Android HWC constructs the blits using the Bltsville
+ * API but the actual blits are issued to Bltsville kernel mode implementation
+ * from OMAPLFB. Destination buffers are allocated and managed by OMAPLFB.
+ *
+ * When blitting it is expected that HWC will construct the overlay information
+ * appropriately in "dsscomp_data"
+ */
+
+/*
+ * Alternate blit descriptor information.
+ *
+ * As mentioned above buffers are refers to by index, alternate buffers
+ * can be refered to by the following
+ */
+#define HWC_BLT_DESC_FLAG 0x80000000
+
+/*
+ * With this value the descriptor refers to an available framebuffer. It
+ * is up to the client and OMAPLFB to track and manage the state of these
+ * buffers. The caller can also specify an overlay index that OMAPLFB will
+ * use when programming dsscomp with the result of the blit.
+ */
+#define HWC_BLT_DESC_FB   0x40000000
+
+#define HWC_BLT_DESC_FB_FN(ovlno) \
+       (HWC_BLT_DESC_FLAG | HWC_BLT_DESC_FB | (ovlno))
+
+
+/*****************************************************************************/
+/* WARNING - These structs must keep in sync with user space code            */
+/*****************************************************************************/
 struct rgz_blt_entry {
        struct bvbltparams bp;
        struct bvsurfgeom dstgeom;