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:     ayaka@soulik.info, maarten.lankhorst@linux.intel.com,
        mripard@kernel.org, tzimmermann@suse.de, airlied@gmail.com,
        daniel@ffwll.ch, linux-kernel@vger.kernel.org, tfiga@chromium.org,
        nicolas@ndufresne.ca, laurent.pinchart@ideasonboard.com,
        ribalda@chromium.org, Hsia-Jun Li <randy.li@synaptics.com>
Subject: [PATCH v6 2/2] Documentation/gpu: Add Synaptics tiling formats documentation
Date:   Wed, 22 Mar 2023 16:29:10 +0800
Message-Id: <20230322082910.115371-3-randy.li@synaptics.com>
In-Reply-To: <20230322082910.115371-1-randy.li@synaptics.com>
References: <20230322082910.115371-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?ySPm9j83rj6H3/u5iACPKuF35cUr6mTPzOr2lMeAe/MTN8ULV4IV9746/cBy?=
 =?us-ascii?Q?gY/bXzXI5j01hYFduyTuIXYb6sjtuyamR0VzJe4J7LRsslw0yHGl2zL9+yEU?=
 =?us-ascii?Q?LfXhG/yK2kdwi72UVTZK4QHc/A3fssTXwdfYGLFxsGkOOR6btOdNsYcsoS2P?=
 =?us-ascii?Q?bZ9UAgMDSEeJH7OWTXGiuHYduXWP06xmJPI9ZuzGYN1Ff72w7LFuPS5a3Q+W?=
 =?us-ascii?Q?ZuiknKoDy5rgEC6yECp8971NnOm5CabxoE8hgZ0mWxAVGrD6TY3q2txTEZs8?=
 =?us-ascii?Q?yltvW/CwQngbmbF8FTdYc6VaD66SjjmwkxfkPESigJHWPFQojQwrs4LTtD6K?=
 =?us-ascii?Q?cqUUejXbh8WQs7fI0eWpsZxBDnVOzSsu+xP9yQ9bTwAd7iY92ht+1amjI7SE?=
 =?us-ascii?Q?W5+3ZNCRoFYg7dzGwN2ZwdtJ/CcMAgqiBZA+fUTezithD7ndtX/TPQ0AO/b8?=
 =?us-ascii?Q?jjld8o93d03gmf4lLZFwssK+gALLxgGuVnsBU7f2w7k6b591cfLne7BZdyOS?=
 =?us-ascii?Q?j0LblOonueuhQEBKqAj5JrRQTiFFxZysd6eFaI8DJeLuJX1CC2UYVKto8Vvj?=
 =?us-ascii?Q?plrAxYmiZWgtVESDDsOyr07ulCP79VPXSbbgR1t1RGGppXvAiT7uvY1XU8lS?=
 =?us-ascii?Q?7Q+axeHasb/KC1eKNfkdPBz9k0ONWPmQf8V7U2mJPl2/DdnM2BqZ51glBgly?=
 =?us-ascii?Q?bEtGSFWUga3M3ciA3dFR9GVSQLnm2qiGwiprxVdWiKETzcj6CXkIE3WSid/q?=
 =?us-ascii?Q?gV7pvJWygv9VlhdC+vJ6smLxAL/2kBMZZD+pGzzEo5ir9xgyN8WTAaHzs1KH?=
 =?us-ascii?Q?RHIW6UgL/Abi81IK4PNNMG+AwcQ7D6ZiRUtiPQSi7RFnnUWtI3kH3mr3t2Vv?=
 =?us-ascii?Q?bGVVBk0fygJg64F1As3FToEd0ndPf9Udd9/c0e0aZUbAUoyfVYbRxzwVAnIa?=
 =?us-ascii?Q?mWVvMsmEJsd8cIIS9piVM1urfN1/s77afejsCIXm8iyBCRitjZHyzKwCheUr?=
 =?us-ascii?Q?O/OphJaYYQ+1BhgfwvbziW7sMXR03hZ7sxfhB2DAU74qYawwOjFgwtgiVRDQ?=
 =?us-ascii?Q?HBw7Khf9VM2KiG4LtN3JuoWLW/ua3Q4ZiMBWGSIhRdiADpe5XUntH8doslhv?=
 =?us-ascii?Q?Q54lVLxTm+32+LidoC3+8RaZCjpPIxLZ9KO/DIy9/TYcvK/HSm0o1kDQ/01/?=
 =?us-ascii?Q?8dDnJFUTeAK+BYiyRGFpyzdTyEYm6JhweJpnK4k9T5GZu0pczG642381SVEF?=
 =?us-ascii?Q?vSjDaJ6fjlyPaQ95YBB3thncc6TI+8SiIgyDuTcW/UhiZuV2lFvr3m4Rh6vq?=
 =?us-ascii?Q?BVFN4H0BoY2KIQvYAXtQvViH6P8AtR0eu86W5YnylbXP9O/J5Fv4hHDel0s0?=
 =?us-ascii?Q?ZhETFN1wrZ9aWnVqtiCogshzUCvWNu6ucuxoqN97zrFukutbXSryB8iHYvUw?=
 =?us-ascii?Q?sEX7n3cFq1bRO6qCioXGj7lPgEfdTq5K5wYfvrlagVPW5BTxzvBq380ha8lx?=
 =?us-ascii?Q?JP9bwIla3lw9gWFBlYnsn/qGdTmd7X0lXlKaJt/oEAvvB1Yl+M4Ar2Bthuhj?=
 =?us-ascii?Q?M+FVsX3GDXa90MYBTneXm6sQ2v6urFYwz7BF5nxl?=
X-OriginatorOrg: synaptics.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 680d1211-6e80-4f0c-9f86-08db2aafbcf5
X-MS-Exchange-CrossTenant-AuthSource: DM6PR03MB5196.namprd03.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Mar 2023 08:30:48.3570
 (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: n4d5/9pVdffmpsWKvE3JQTmcdihcdPs36ZEwmSJRklwew+JzL8P2YaXL1pCUSgESwhwx5KFiboneF02pxfLYiw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR03MB4944
X-Spam-Status: No, score=-0.0 required=5.0 tests=DKIM_SIGNED,DKIM_VALID,
        SPF_HELO_PASS,SPF_PASS autolearn=unavailable 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/synaptics.rst | 81 +++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 Documentation/gpu/synaptics.rst

diff --git a/Documentation/gpu/synaptics.rst b/Documentation/gpu/synaptics.rst
new file mode 100644
index 000000000000..4185ca536bf1
--- /dev/null
+++ b/Documentation/gpu/synaptics.rst
@@ -0,0 +1,81 @@
+.. 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, pixels within
+the group (nearest) width and height are stored into tile.
+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 still would 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.
+
+.. flat-table:: Synpatics Image Format Modifiers
+
+	* - Identifier
+	  - Fourcc
+	  - Details
+
+	* - 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_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_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_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_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_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.
-- 
2.17.1