From 0fc6197034c49d9fdf5607cae201f1ac3270e7de Mon Sep 17 00:00:00 2001
From: Demi Marie Obenour <demiobenour@gmail.com>
Date: Sun, 3 Jul 2022 18:01:40 -0400
Subject: Document the MIT-SHM extension

This adds documentation for the entire MIT-SHM extension.

Signed-off-by: Demi Marie Obenour <demiobenour@gmail.com>
---
 src/shm.xml | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 214 insertions(+)

diff --git a/src/shm.xml b/src/shm.xml
index c2605da..41fb1c1 100644
--- a/src/shm.xml
+++ b/src/shm.xml
@@ -39,6 +39,29 @@ authorization from the authors.
     <pad bytes="1" />
     <field type="SEG" name="shmseg" />
     <field type="CARD32" name="offset" />
+    <doc>
+      <brief>Report that an XCB_SHM_PUT_IMAGE request has completed</brief>
+      <description><![CDATA[
+This is generated by the X server to report that an XCB_SHM_PUT_IMAGE request
+has been successfully processed.
+      ]]></description>
+      <field name="drawable"><![CDATA[
+The drawable used in the XCB_SHM_PUT_IMAGE request.
+      ]]></field>
+      <field name="minor_event"><![CDATA[
+The minor opcode used in the request.  Always XCB_SHM_PUT_IMAGE.
+      ]]></field>
+      <field name="major_event"><![CDATA[
+The major opcode used in the request.  Always the opcode of the MIT-SHM
+extension.
+      ]]></field>
+      <field name="shmseg"><![CDATA[
+The shared memory segment used in the request.
+      ]]></field>
+      <field name="offset"><![CDATA[
+The offset in the shared memory segment used in the request.
+      ]]></field>
+    </doc>
   </event>
 
   <errorcopy name="BadSeg" number="0" ref="Value" />
@@ -52,7 +75,39 @@ authorization from the authors.
       <field type="CARD16" name="gid" />
       <field type="CARD8" name="pixmap_format" />
       <pad bytes="15" />
+      <doc>
+	<brief>The version of the MIT-SHM extension supported by the server</brief>
+	<description><![CDATA[
+This contains the version of the MIT-SHM extension supported by the server, as
+well as the server’s UID and GID.  Clients MUST obtain the version supproted by
+the server before making other requests from this extension.  To prevent local
+privilege escalation and local information leak security vulnerabilities,
+clients MUST ensure that System V shared memory objects they use with this
+extension can only be accessed by the client and the X server.  If this is not
+possible, the requests in this extension that use System V shared memory MUST
+NOT be used.  The file descriptor-passing versions provide an alternative.
+	]]></description>
+	<field name="shared_pixmaps"><![CDATA[
+True if the server supports shared pixmaps, otherwise false.
+        ]]></field>
+	<field name="major_version"><![CDATA[
+The major version of the extension supported.
+        ]]></field>
+	<field name="minor_version"><![CDATA[
+The minor version of the extension supported.
+        ]]></field>
+	<field name="uid">The UID of the server.</field>
+	<field name="gid">The GID of the server.</field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Query the version of the MIT-SHM extension.</brief>
+      <description><![CDATA[
+This is used to determine the version of the MIT-SHM extension supported by the
+X server.  Clients MUST NOT make other requests in this extension until a reply
+to this requests indicates the X server supports them.
+      ]]></description>
+    </doc>
   </request>
 
   <request name="Attach" opcode="1">
@@ -60,10 +115,36 @@ authorization from the authors.
     <field type="CARD32" name="shmid" />
     <field type="BOOL" name="read_only" />
     <pad bytes="3" />
+    <doc>
+      <brief>Attach a System V shared memory segment.</brief>
+      <description><![CDATA[
+Attach a System V shared memory segment to the server.  This will fail unless
+the server has permission to map the segment.  The client may destroy the segment
+as soon as it receives a XCB_SHM_COMPLETION event with the shmseg value in this
+request and with the appropriate serial number.
+      ]]></description>
+      <field name="shmseg"><![CDATA[
+A shared memory segment ID created with xcb_generate_id().
+      ]]></field>
+      <field name="shmid"><![CDATA[
+The System V shared memory segment the server should map.
+      ]]></field>
+      <field name="read_only"><![CDATA[
+True if the segment shall be mapped read only by the X11 server, otherwise false.
+      ]]></field>
+    </doc>
   </request>
 
   <request name="Detach" opcode="2">
     <field type="SEG" name="shmseg" />
+    <doc>
+      <brief>Destroys the specified shared memory segment.</brief>
+      <description><![CDATA[
+Destroys the specified shared memory segment.  This will never fail unless the
+segment number is incorrect.
+      ]]></description>
+      <field name="shmseg">The segment to be destroyed.</field>
+    </doc>
   </request>
 
   <request name="PutImage" opcode="3">
@@ -83,6 +164,49 @@ authorization from the authors.
     <pad bytes="1" />
     <field type="SEG" name="shmseg" />
     <field type="CARD32" name="offset" />
+    <doc>
+      <brief>Copy data from the shared memory to the specified drawable.</brief>
+      <description><![CDATA[
+Copy data from the shared memory to the specified drawable.  The amount of bytes
+written to the destination image is always equal to the number of bytes read
+from the shared memory segment.
+      ]]></description>
+      <field name="drawable">The drawable to draw to.</field>
+      <field name="gc">The graphics context to use.</field>
+      <field name="total_width">The total width of the source image.</field>
+      <field name="total_height">The total height of the source image.</field>
+      <field name="src_x">The source X coordinate of the sub-image to copy.</field>
+      <field name="src_y">The source Y coordinate of the sub-image to copy.</field>
+      <field name="src_width"><![CDATA[
+The width, in source image coordinates, of the data to copy from the source.
+The X server will use this to determine the amount of data to copy.  The amount
+of the destination image that is overwritten is determined automatically.
+      ]]></field>
+      <field name="src_height"><![CDATA[
+The height, in source image coordinates, of the data to copy from the source.
+The X server will use this to determine the amount of data to copy.  The amount
+of the destination image that is overwritten is determined automatically.
+      ]]></field>
+      <field name="dst_x"><![CDATA[
+The X coordinate on the destination drawable to copy to.
+      ]]></field>
+      <field name="dst_y"><![CDATA[
+The Y coordinate on the destination drawable to copy to.
+      ]]></field>
+      <field name="depth">The depth to use.</field>
+      <field name="format"><![CDATA[
+The format of the image being drawn.  If it is XYBitmap, depth must be 1, or a
+“BadMatch” error results.  The foreground pixel in the GC determines the source
+for the one bits in the image, and the background pixel determines the source
+for the zero bits.  For XYPixmap and ZPixmap, the depth must match the depth of
+the drawable, or a “BadMatch” error results.
+      ]]></field>
+      <field name="send_event"><![CDATA[
+True if the server should send an XCB_SHM_COMPLETION event when the blit
+completes.
+      ]]></field>
+      <field name="offset">The offset that the source image starts at.</field>
+    </doc>
   </request>
 
   <request name="GetImage" opcode="4">
@@ -100,7 +224,33 @@ authorization from the authors.
       <field type="CARD8" name="depth" />
       <field type="VISUALID" name="visual" />
       <field type="CARD32" name="size" />
+      <doc>
+	<brief>Indicates the result of the copy.</brief>
+	<description><![CDATA[
+The result of the copy.
+	]]></description>
+	<field name="depth">The depth of the source drawable.</field>
+	<field name="visual">The visual ID of the source drawable.</field>
+	<field name="size">The number of bytes copied.</field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Copies data from the specified drawable to the shared memory segment.</brief>
+      <description><![CDATA[
+Copy data from the specified drawable to the shared memory segment.  The amount
+of bytes written to the destination image is always equal to the number of bytes
+read from the shared memory segment.
+      ]]></description>
+      <field name="drawable">The drawable to copy the image out of.</field>
+      <field name="x">The X coordinate in the drawable to begin copying at.</field>
+      <field name="y">The Y coordinate in the drawable to begin copying at.</field>
+      <field name="width">The width of the image to copy.</field>
+      <field name="height">The height of the image to copy.</field>
+      <field name="plane_mask">A mask that determines which planes are used.</field>
+      <field name="format">The format to use for the copy (???).</field>
+      <field name="shmseg">The destination shared memory segment.</field>
+      <field name="offset">The offset in the shared memory segment to copy data to.</field>
+    </doc>
   </request>
 
   <request name="CreatePixmap" opcode="5">
@@ -112,6 +262,31 @@ authorization from the authors.
     <pad bytes="3" />
     <field type="SEG" name="shmseg" />
     <field type="CARD32" name="offset" />
+    <doc>
+      <brief>Create a pixmap backed by shared memory.</brief>
+      <description>
+Create a pixmap backed by shared memory.  Writes to the shared memory will be
+reflected in the contents of the pixmap, and writes to the pixmap will be
+reflected in the contents of the shared memory.
+      </description>
+      <field name="pid">A pixmap ID created with xcb_generate_id().</field>
+      <field name="drawable">The drawable to create the pixmap in.</field>
+      <field name="width"><![CDATA[
+The width of the pixmap to create.  Must be nonzero, or a Value error results.
+      ]]></field>
+      <field name="height"><![CDATA[
+The height of the pixmap to create.  Must be nonzero, or a Value error results.
+      ]]></field>
+      <field name="depth"><![CDATA[
+The depth of the pixmap to create.  Must be nonzero, or a Value error results.
+      ]]></field>
+      <field name="shmseg"><![CDATA[
+The shared memory segment to use to create the pixmap.
+      ]]></field>
+      <field name="offset"><![CDATA[
+The offset in the segment to create the pixmap at.
+      ]]></field>
+    </doc>
   </request>
 
   <request name="AttachFd" opcode="6">
@@ -119,6 +294,21 @@ authorization from the authors.
     <fd name="shm_fd" />
     <field type="BOOL" name="read_only" />
     <pad bytes="3" />
+    <doc>
+      <brief>Create a shared memory segment</brief>
+      <description><![CDATA[
+Create a shared memory segment.  The file descriptor will be mapped at offset
+zero, and the size will be obtained using fstat().  A zero size will result in a
+Value error.
+      ]]></description>
+      <field name="shmseg"><![CDATA[
+A shared memory segment ID created with xcb_generate_id().
+      ]]></field>
+      <field name="shm_fd">The file descriptor the server should mmap().</field>
+      <field name="read_only"><![CDATA[
+True if the segment shall be mapped read only by the X11 server, otherwise false.
+      ]]></field>
+    </doc>
   </request>
 
   <request name="CreateSegment" opcode="7">
@@ -130,6 +320,30 @@ authorization from the authors.
       <field type="CARD8" name="nfd" />
       <fd name="shm_fd" />
       <pad bytes="24" />
+      <doc>
+	<brief>The returned file descriptor.</brief>
+	<description><![CDATA[
+The file descriptor returned by the server.  The client may call mmap() on it to
+map the memory allocated by the server.
+	]]></description>
+	<field name="nfd"><![CDATA[
+The number of file descriptors sent by the server.  Will always be 1.
+	]]></field>
+      </doc>
     </reply>
+    <doc>
+      <brief>Asks the server to allocate a shared memory segment.</brief>
+      <description><![CDATA[
+Asks the server to allocate a shared memory segment.  The server’s reply will
+include a file descriptor for the client to pass to mmap().
+      ]]></description>
+      <field name="shmseg"><![CDATA[
+A shared memory segment ID created with xcb_generate_id().
+      ]]></field>
+      <field name="size">The size of the segment to create.</field>
+      <field name="read_only"><![CDATA[
+True if the server should map the segment read-only; otherwise false.
+      ]]></field>
+    </doc>
   </request>
 </xcb>
-- 
cgit v1.2.3