[Xcb-commit] xcb/proto: src
GitLab Mirror
gitlab-mirror at kemper.freedesktop.org
Mon Jul 4 15:34:42 UTC 2022
src/shm.xml | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 214 insertions(+)
New commits:
commit 0fc6197034c49d9fdf5607cae201f1ac3270e7de
Author: Demi Marie Obenour <demiobenour at gmail.com>
Date: Sun Jul 3 18:01:40 2022 -0400
Document the MIT-SHM extension
This adds documentation for the entire MIT-SHM extension.
Signed-off-by: Demi Marie Obenour <demiobenour at gmail.com>
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>
More information about the xcb-commit
mailing list