[PATCH] linux-dmabuf: clarify DRM_FORMAT_MOD_INVALID

[Chia-I Wu]

DRM_FORMAT_MOD_INVALID means to derive the modifier from the dmabuf.

Signed-off-by: Chia-I Wu <olvaffe at gmail.com>
---
 .../linux-dmabuf/linux-dmabuf-unstable-v1.xml     | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
index 154afe2..7c76441 100644
--- a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
+++ b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml
@@ -28,6 +28,7 @@
     <description summary="factory for creating dmabuf-based wl_buffers">
       Following the interfaces from:
       https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt
+      https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt
       and the Linux DRM sub-system's AddFb2 ioctl.
 
       This interface offers ways to create generic dmabuf-based
@@ -129,8 +130,13 @@
         binds to this interface. A roundtrip after binding guarantees that
         the client has received all supported format-modifier pairs.
 
+        For each supported format, DRM_FORMAT_MOD_INVALID (that is,
+        modifier_hi == 0x00ffffff and modifier_lo == 0xffffffff) is implied
+        and may not be sent.
+
         For the definition of the format and modifier codes, see the
-        zwp_linux_buffer_params_v1::create request.
+        zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add
+        requests.
       </description>
       <arg name="format" type="uint" summary="DRM_FORMAT code"/>
       <arg name="modifier_hi" type="uint"
@@ -200,6 +206,13 @@
         This request raises the PLANE_IDX error if plane_idx is too large.
         The error PLANE_SET is raised if attempting to set a plane that
         was already set.
+
+        Note that DRM_FORMAT_MOD_INVALID (that is, modifier_hi == 0x00ffffff
+        and modifier_lo == 0xffffffff) is always allowed and has a special
+        meaning. It indicates that the modifier is derived from the dmabuf fd
+        rather than explicitly specified. This use is discouraged and may not
+        work if the dmabuf is imported to a different device than the device
+        that allocated it.
       </description>
       <arg name="fd" type="fd" summary="dmabuf fd"/>
       <arg name="plane_idx" type="uint" summary="plane index"/>
-- 
2.21.0.392.gf8f6787159e-goog