diff options
author | Demi Marie Obenour <demiobenour@gmail.com> | 2022-07-03 18:01:40 -0400 |
---|---|---|
committer | Demi Marie Obenour <demiobenour@gmail.com> | 2022-07-03 18:01:40 -0400 |
commit | 0fc6197034c49d9fdf5607cae201f1ac3270e7de (patch) | |
tree | 508a55f571552bd0ac9748666e0674fc3c352154 | |
parent | ed461f379b6cde5bea7bc99d253c270b37298401 (diff) |
Document the MIT-SHM extension
This adds documentation for the entire MIT-SHM extension.
Signed-off-by: Demi Marie Obenour <demiobenour@gmail.com>
-rw-r--r-- | src/shm.xml | 214 |
1 files changed, 214 insertions, 0 deletions
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> |