Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Hsia-Jun Li <randy.li@synaptics.com>
To:     dri-devel@lists.freedesktop.org
Cc:     airlied@linux.ie, ayaka@soulik.info, sakari.ailus@linux.intel.com,
        ezequiel@vanguardiasur.com.ar, tzimmermann@suse.de,
        linux-kernel@vger.kernel.org, laurent.pinchart@ideasonboard.com,
        mchehab@kernel.org, tfiga@chromium.org, mripard@kernel.org,
        ribalda@chromium.org, maarten.lankhorst@linux.intel.com,
        linux-media@vger.kernel.org, sebastian.hesselbarth@gmail.com,
        helen.koike@collabora.com, nicolas@ndufresne.ca,
        linux-arm-kernel@lists.infradead.org,
        Hsia-Jun Li <randy.li@synaptics.com>
Subject: [PATCH v5 2/2] Documentation/gpu: Add Synaptics tiling formats documentation
Date:   Wed, 30 Nov 2022 17:21:49 +0800
Message-Id: <20221130092149.102788-3-randy.li@synaptics.com>
In-Reply-To: <20221130092149.102788-1-randy.li@synaptics.com>
References: <20221130092149.102788-1-randy.li@synaptics.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?VUU4ovx2KNm9EgVfupMqICKyJgS0U+E/ZofofFPi5M6X+0vozMZwvUtojaSH?=
 =?us-ascii?Q?6n6zdaQYv3LfPKxxxLbD2uQTzsja9L0Wa02xeIbNBtxTbjkwDjf7uWjpUdK2?=
 =?us-ascii?Q?TW3iy2nynYb23/al9jlXspNbXZOKRrwwoRVi8dAQ5lNOFO/UzzU7yQ4lXSvh?=
 =?us-ascii?Q?2kcq7X4zV85g9FfTB11st3wv5uRylRUBgb4auusUYIBMIB37K9jurTOrKYSB?=
 =?us-ascii?Q?CNl8vNmCRDtK5uHZ/5JRI9ft6nSG4aRH6AkUnAN7dSHirAjwNo8hKC49eCqv?=
 =?us-ascii?Q?4BvsYF/NxW1GGEEgqxH1SgtsLUFK+ew7QdOHat3eVRZvY0//q8MP6329ii3A?=
 =?us-ascii?Q?DVAg51J6WEIKgqRB6QXf3s8YbB3x95meWNzunWDTliaOXkDL1M/5ANL8qae3?=
 =?us-ascii?Q?kazjTpytcuVa4MiYbHW9L/KdoGk6OkpDZ7p6OJIHYS94U6HVARld6WzCEav1?=
 =?us-ascii?Q?3TRhzfKUSmFoaqTwT36aCWG/bxNWMaMyvJqz0tyayGbJ7GTETuBd9e8Lvb2H?=
 =?us-ascii?Q?3gr2LOGabOGE4kdN4JUIGRYrdt1mrF/ivnSVnoOJF+L5T8fREaYaggSLhaQx?=
 =?us-ascii?Q?rMhf+zz8rHrSDZykpDW/i9gtw0aIRCK1RqltC14UW5qZG5BdqSyFG05K9Rwu?=
 =?us-ascii?Q?vOKavOvWRtztjPrU3oRPK2rrzw067ASJ4ARtR4zk1q62mvg/lVbryoSqHcJk?=
 =?us-ascii?Q?267iqvaSAtTR+LQr++OW0pxLCulCxqCjc+v0p2zloSMq2ZG8KoKvdlUjmQD1?=
 =?us-ascii?Q?I4gHdoiocSBKgLKnosV3qhzzKtbjEr7B9BDewjr+AsfkXC3cW/ddR7wKyd4V?=
 =?us-ascii?Q?V/fVDT6sXHjjFhrHlXCPxSXf7CtN1BhkiThuFqhwOkTBq/gum3pFgEYnU7Ds?=
 =?us-ascii?Q?VVJHRp3cCRmYgKPEoYrHpJhUVy1Q6dVbXgXDpQnLrzefKAQCh9WBleoXYTJB?=
 =?us-ascii?Q?3iNNpYZz8oCHokjpOof+t8wyigigOQxx0aJ2UuEs/PrpNF9y4OVczMI9+mIt?=
 =?us-ascii?Q?JRv3y3bS2HYDByi6f09CB54ecZOlVpys13irpt9nifvNQce3NVZg0icu/7TI?=
 =?us-ascii?Q?CxvOrQwzPuNbdcV/NxwlZmQy+N30hTFIbkWlL6bMq6iTqzcAxKIvfe0Tw+E/?=
 =?us-ascii?Q?4sHczkvh3pcdlVVKQcriN+K0qvVdr9KOpxWoLRQsHZJov9AlOrr9Eaq8wBZ4?=
 =?us-ascii?Q?0dBs5Ym8MSWfp5ClLheKTNAe2iehq5F2a9u7IGvgL8X9CYv+ExM7GbuFXpoJ?=
 =?us-ascii?Q?KxZl/bzHRYLpPNHH9mzgir4ifA6Dd1wkcWK449Vruc1lC3GYWn0D6O4Jvc7t?=
 =?us-ascii?Q?Tqqviqn8YicDoXJTyHzpvSwZuoJApsG8MZ0FTTMoD/nNlt751pYRZe3fSGYa?=
 =?us-ascii?Q?rxT2HbyQs9AZsjJ1ihKBTON+XvbJ81OZfPP4022btR38sgOfvEHlb0LueSqz?=
 =?us-ascii?Q?vlrqMWuSJTOvNaHEKM7jp399eaZTVCq8PqnJcQ7qoDvu+qhG1CO6pPMC1uVn?=
 =?us-ascii?Q?T6SZvjYlWTPItJ5sBEO894zsWZZoIqqqyXmUy6oYobmoJO6LSPZ3OrNm+TRD?=
 =?us-ascii?Q?h0nehVTtdW/1p2zeM8EcmGbF5koJV/7oGe32cyaq?=
X-OriginatorOrg: synaptics.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 3d5819fc-b07b-4ddf-9669-08dad2b46ba5
X-MS-Exchange-CrossTenant-AuthSource: DM6PR03MB5196.namprd03.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Nov 2022 09:22:37.0962
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 335d1fbc-2124-4173-9863-17e7051a2a0e
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: MHOBV/e7NS3elbLarza+sGNZspRTyLHLkh6yU1+cEZGkL1DxM3lg/QOxBPRpP4GcLl9NCOqBuFXNE6FO/fdFCw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR03MB5799
X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS
        autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

From: Randy Li <ayaka@soulik.info>

Signed-off-by: Randy Li <ayaka@soulik.info>
Signed-off-by: Hsia-Jun(Randy) Li <randy.li@synaptics.com>
---
 Documentation/gpu/drivers.rst   |   1 +
 Documentation/gpu/synaptics.rst | 104 ++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 Documentation/gpu/synaptics.rst

diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index 3a52f48215a3..7e820c93d994 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -18,6 +18,7 @@ GPU Driver Documentation
    xen-front
    afbc
    komeda-kms
+   synaptics
 
 .. only::  subproject and html
 
diff --git a/Documentation/gpu/synaptics.rst b/Documentation/gpu/synaptics.rst
new file mode 100644
index 000000000000..b0564d2fe3ce
--- /dev/null
+++ b/Documentation/gpu/synaptics.rst
@@ -0,0 +1,104 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+================
+Synaptics Tiling
+================
+
+The tiling pixel formats in Synpatics Video Smart platform have
+many variants. Tiles could form the group of tiles(GOT), pixels
+within a group rectangle are stored into tile.
+There are two parameters which consist a modifier described
+the (nearest) width and height pixels in a group.
+
+Meanwhile, the tile in a group may not follow dimension
+layout, tile could form a small group of tiles, then that (sub)group
+of tiles would form a bigger group. We won't describe the dimension
+layout inside the group of tiles here. The layout of the group
+of tiles is fixed with the group width and height parameters
+in the same generation of the platform.
+
+Compression
+===========
+The proprietary lossless image compression protocol in Synaptics
+could minimizes the amount of data transferred (less memory bandwidth
+consumption) between devices. It would usually apply to the tiling
+pixel format.
+
+Each component would request an extra page aligned length buffer
+for storing the compression meta data. Also a 32 bytes parameters
+set would come with a compression meta data buffer.
+
+The component here corresponds to a signal type (i.e. Luma, Chroma).
+They could be encoded into one or multiple metadata planes, but
+their compression parameters would still be individual.
+
+Pixel format modifiers
+======================
+Addition alignment requirement for stride and size of a memory plane
+could apply beyond what has been mentioned below. Remember always
+negotiating with all the devices in pipeline before allocation.
+
+.. raw:: latex
+
+    \small
+
+.. tabularcolumns:: |p{5.8cm}|p{1.2cm}|p{10.3cm}|
+
+.. cssclass:: longtable
+
+.. flat-table:: Synpatics Image Format Modifiers
+    :header-rows:  1
+    :stub-columns: 0
+    :widths:       3 1 8
+
+    * - Identifier
+      - Fourcc
+      - Details
+    * .. _DRM-FORMAT-MOD-SYNA-V4H1
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H1``
+      - ``DRM_FORMAT_NV12``
+      - The plain uncompressed 8 bits tile format. It sounds similar to
+	Intel's Y-tile. but it won't take any pixel from the next X direction
+	in a tile group. The line stride and image height must be aligned to
+	a multiple of 16. The height of chrominance plane would plus 8.
+    * .. _DRM-FORMAT-MOD-SYNA-V4H3P8
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H3P8``
+      - ``DRM_FORMAT_NV15``
+      - The plain uncompressed 10 bits tile format. It stores pixel in 2D
+	3x4 tiles with a 8bits padding to each of tile. Then a tile is in a
+	128 bits cache line.
+    * .. _DRM-FORMAT-MOD-SYNA-V4H1-64L4-COMPRESSED
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H1_64L4_COMPRESSED``
+      - ``DRM_FORMAT_NV12``
+      - Group of tiles and compressed variant of ``DRM_FORMAT_MOD_SYNA_V4H1``.
+	A group of tiles would contain 64x4 pixels, where a tile has 1x4
+	pixel.
+    * .. _DRM-FORMAT-MOD-SYNA-V4H3P8-64L4-COMPRESSED
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H3P8_64L4_COMPRESSED``
+      - ``DRM_FORMAT_NV15``
+      - Group of tiles and compressed variant of ``DRM_FORMAT_MOD_SYNA_V4H3P8``.
+	A group of tiles would contains 48x4 pixels, where a tile has 3x4 pixels
+	and a 8 bits padding in the end of a tile. A group of tiles would
+	be 256 bytes.
+    * .. _DRM-FORMAT-MOD-SYNA-V4H1-128L128-COMPRESSED
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H1_128L128_COMPRESSED``
+      - ``DRM_FORMAT_NV12``
+      - Group of tiles and compressed variant of ``DRM_FORMAT_MOD_SYNA_V4H1``.
+	A group of tiles would contain 128x32 pixels, where a tile has 1x4 pixel.
+    * .. _DRM-FORMAT-MOD-SYNA-V4H3P8-128L128-COMPRESSED
+
+      - ``DRM_FORMAT_MOD_SYNA_V4H3P8_128L128_COMPRESSED``
+      - ``DRM_FORMAT_NV15``
+      - Group of tiles and compressed variant of ``DRM_FORMAT_MOD_SYNA_V4H3P8``.
+	A group of tiles would contains 96x128 pixels, where a tile has 3x4 pixels
+	and a 8 bits padding in the end of a tile. A group of tiles would 
+	be 16 KiB.
+
+.. raw:: latex
+
+    \normalsize
-- 
2.37.3