296 lines
12 KiB
Diff
296 lines
12 KiB
Diff
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: [PATCH] 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>
|
||
--
|
||
2.39.0.windows.2
|
||
|