This makes the generated protocol headers a lot more readable. --- src/egl/wayland/wayland-drm/wayland-drm.xml | 159 +++++++++++++++++----------- 1 file changed, 100 insertions(+), 59 deletions(-)
diff --git a/src/egl/wayland/wayland-drm/wayland-drm.xml b/src/egl/wayland/wayland-drm/wayland-drm.xml index 5e64622..7cf06d9 100644 --- a/src/egl/wayland/wayland-drm/wayland-drm.xml +++ b/src/egl/wayland/wayland-drm/wayland-drm.xml @@ -27,19 +27,31 @@ THIS SOFTWARE. </copyright>
- <!-- drm support. This object is created by the server and published - using the display's global event. --> <interface name="wl_drm" version="2"> + <description summary="drm support"> + This object is created by the server and published using the + display's global event. + </description> + <enum name="error"> - <entry name="authenticate_fail" value="0"/> - <entry name="invalid_format" value="1"/> - <entry name="invalid_name" value="2"/> + <description summary="error values"> + These errors can be emitted in response to wl_drm requests. + </description> + <entry name="authenticate_fail" value="0" + summary="authentication failure"/> + <entry name="invalid_format" value="1" + summary="buffer format is not supported"/> + <entry name="invalid_name" value="2" + summary="invalid name for buffer creation"/> </enum>
<enum name="format"> - <!-- The drm format codes match the #defines in drm_fourcc.h. - The formats actually supported by the compositor will be - reported by the format event. --> + <description summary="pixel formats"> + The drm format codes match the #defines in drm_fourcc.h. + + The formats actually supported by the compositor will be + reported by the format event. + </description> <entry name="c8" value="0x20203843"/> <entry name="rgb332" value="0x38424752"/> <entry name="bgr233" value="0x38524742"/> @@ -100,84 +112,113 @@ <entry name="yvu444" value="0x34325659"/> </enum>
- <!-- Call this request with the magic received from drmGetMagic(). - It will be passed on to the drmAuthMagic() or - DRIAuthConnection() call. This authentication must be - completed before create_buffer could be used. --> <request name="authenticate"> - <arg name="id" type="uint"/> + <description summary="authentication request"> + Call this request with the magic received from drmGetMagic(). + + It will be passed on to the drmAuthMagic() or + DRIAuthConnection() call. This authentication must be + completed before create_buffer could be used. + </description> + <arg name="id" type="uint" summary="drm magic identifier"/> </request>
- <!-- Create a wayland buffer for the named DRM buffer. The DRM - surface must have a name using the flink ioctl --> <request name="create_buffer"> - <arg name="id" type="new_id" interface="wl_buffer"/> - <arg name="name" type="uint"/> - <arg name="width" type="int"/> - <arg name="height" type="int"/> - <arg name="stride" type="uint"/> - <arg name="format" type="uint"/> + <description summary="create drm buffer"> + Create a wayland buffer for the named DRM buffer. + + The DRM surface must have a name using the flink ioctl. + </description> + <arg name="id" type="new_id" interface="wl_buffer" + summary="wl_buffer assigned to this drm buffer"/> + <arg name="name" type="uint" summary="unique buffer name"/> + <arg name="width" type="int" summary="buffer width"/> + <arg name="height" type="int" summary="buffer height"/> + <arg name="stride" type="uint" summary="stride of a line"/> + <arg name="format" type="uint" summary="see wl_drm_format"/> </request>
- <!-- Create a wayland buffer for the named DRM buffer. The DRM - surface must have a name using the flink ioctl --> <request name="create_planar_buffer"> - <arg name="id" type="new_id" interface="wl_buffer"/> - <arg name="name" type="uint"/> - <arg name="width" type="int"/> - <arg name="height" type="int"/> - <arg name="format" type="uint"/> - <arg name="offset0" type="int"/> - <arg name="stride0" type="int"/> - <arg name="offset1" type="int"/> - <arg name="stride1" type="int"/> - <arg name="offset2" type="int"/> - <arg name="stride2" type="int"/> + <description summary="create planar drm buffer"> + Create a wayland buffer for the named planar DRM buffer. + + The DRM surface must have a name using the flink ioctl. + </description> + <arg name="id" type="new_id" interface="wl_buffer" + summary="wl_buffer assigned to this drm buffer"/> + <arg name="name" type="uint" summary="unique buffer name"/> + <arg name="width" type="int" summary="buffer width"/> + <arg name="height" type="int" summary="buffer height"/> + <arg name="format" type="uint" summary="see wl_drm_format"/> + <arg name="offset0" type="int" summary="first plane offset"/> + <arg name="stride0" type="int" summary="first plane stride"/> + <arg name="offset1" type="int" summary="second plane offset"/> + <arg name="stride1" type="int" summary="second plane stride"/> + <arg name="offset2" type="int" summary="third plane offset"/> + <arg name="stride2" type="int" summary="third plane stride"/> </request>
- <!-- Notification of the path of the drm device which is used by - the server. The client should use this device for creating - local buffers. Only buffers created from this device should - be be passed to the server using this drm object's - create_buffer request. --> <event name="device"> - <arg name="name" type="string"/> + <description summary="drm device of the server"> + Notification of the path of the drm device which is used by the + server. + + The client should use this device for creating local buffers. + Only buffers created from this device should be be passed to + the server using this drm object's create_buffer request. + </description> + <arg name="name" type="string" summary="path of the drm device"/> </event>
<event name="format"> - <arg name="format" type="uint"/> + <description summary="pixel format description"> + Informs the client about a valid pixel format that can be used + for buffers. + </description> + <arg name="format" type="uint" summary="pixel format"/> </event>
- <!-- Raised if the authenticate request succeeded --> - <event name="authenticated"/> + <event name="authenticated"> + <description summary="successful authentication"> + Raised if the authenticate request succeeded. + </description> + </event>
<enum name="capability" since="2"> - <description summary="wl_drm capability bitmask"> - Bitmask of capabilities. + <description summary="capability description"> + Lists the available capabilities the server can expose. </description> <entry name="prime" value="1" summary="wl_drm prime available"/> </enum>
<event name="capabilities"> - <arg name="value" type="uint"/> + <description summary="capabilities bitmask"> + Bitmask of capabilities supported by the server. + </description> + <arg name="value" type="uint" summary="capabilities"/> </event>
<!-- Version 2 additions -->
- <!-- Create a wayland buffer for the prime fd. Use for regular and planar - buffers. Pass 0 for offset and stride for unused planes. --> <request name="create_prime_buffer" since="2"> - <arg name="id" type="new_id" interface="wl_buffer"/> - <arg name="name" type="fd"/> - <arg name="width" type="int"/> - <arg name="height" type="int"/> - <arg name="format" type="uint"/> - <arg name="offset0" type="int"/> - <arg name="stride0" type="int"/> - <arg name="offset1" type="int"/> - <arg name="stride1" type="int"/> - <arg name="offset2" type="int"/> - <arg name="stride2" type="int"/> + <description summary="create prime drm buffer"> + Create a wayland buffer for the prime fd. + + Use for regular and planar buffers. Pass 0 for offset and + stride for unused planes. + </description> + <arg name="id" type="new_id" interface="wl_buffer" + summary="wl_buffer assigned to this drm buffer"/> + <arg name="name" type="fd" summary="prime fd"/> + <arg name="width" type="int" summary="buffer width"/> + <arg name="height" type="int" summary="buffer height"/> + <arg name="format" type="uint" summary="see wl_drm_format"/> + <arg name="offset0" type="int" summary="first plane offset"/> + <arg name="stride0" type="int" summary="first plane stride"/> + <arg name="offset1" type="int" summary="second plane offset"/> + <arg name="stride1" type="int" summary="second plane stride"/> + <arg name="offset2" type="int" summary="third plane offset"/> + <arg name="stride2" type="int" summary="third plane stride"/> </request>
</interface>
On Wed, 25 Mar 2015 13:10:24 +0100 Emmanuel Gil Peyrot linkmauve@linkmauve.fr wrote:
This makes the generated protocol headers a lot more readable.
src/egl/wayland/wayland-drm/wayland-drm.xml | 159 +++++++++++++++++----------- 1 file changed, 100 insertions(+), 59 deletions(-)
diff --git a/src/egl/wayland/wayland-drm/wayland-drm.xml b/src/egl/wayland/wayland-drm/wayland-drm.xml index 5e64622..7cf06d9 100644 --- a/src/egl/wayland/wayland-drm/wayland-drm.xml +++ b/src/egl/wayland/wayland-drm/wayland-drm.xml @@ -27,19 +27,31 @@ THIS SOFTWARE.
</copyright>
- <!-- drm support. This object is created by the server and published
using the display's global event. --><interface name="wl_drm" version="2">
<description summary="drm support">
This object is created by the server and published using thedisplay's global event.
Hi,
you can say that a lot shorter: "This is a global object interface." But you could also say more: - is this a singleton? - this is a detail of an EGL implementation - this is specific to Mesa, an internal implementation detail that no-one outside Mesa is supposed to access.
</description>
<enum name="error">
<entry name="authenticate_fail" value="0"/><entry name="invalid_format" value="1"/><entry name="invalid_name" value="2"/>
<description summary="error values">These errors can be emitted in response to wl_drm requests.
That's obvious, isn't it?
</description><entry name="authenticate_fail" value="0"summary="authentication failure"/><entry name="invalid_format" value="1"summary="buffer format is not supported"/><entry name="invalid_name" value="2"summary="invalid name for buffer creation"/>
Ok.
</enum> <enum name="format">
<!-- The drm format codes match the #defines in drm_fourcc.h.The formats actually supported by the compositor will bereported by the format event. -->
<description summary="pixel formats">The drm format codes match the #defines in drm_fourcc.h.The formats actually supported by the compositor will bereported by the format event.</description>
Ok.
<entry name="c8" value="0x20203843"/> <entry name="rgb332" value="0x38424752"/> <entry name="bgr233" value="0x38524742"/>@@ -100,84 +112,113 @@ <entry name="yvu444" value="0x34325659"/> </enum>
- <!-- Call this request with the magic received from drmGetMagic().
It will be passed on to the drmAuthMagic() orDRIAuthConnection() call. This authentication must becompleted before create_buffer could be used. --><request name="authenticate">
<arg name="id" type="uint"/>
<description summary="authentication request">Call this request with the magic received from drmGetMagic().It will be passed on to the drmAuthMagic() orDRIAuthConnection() call. This authentication must becompleted before create_buffer could be used.</description><arg name="id" type="uint" summary="drm magic identifier"/>
Ok.
</request>
- <!-- Create a wayland buffer for the named DRM buffer. The DRM
surface must have a name using the flink ioctl --><request name="create_buffer">
<arg name="id" type="new_id" interface="wl_buffer"/><arg name="name" type="uint"/><arg name="width" type="int"/><arg name="height" type="int"/><arg name="stride" type="uint"/><arg name="format" type="uint"/>
<description summary="create drm buffer">Create a wayland buffer for the named DRM buffer.The DRM surface must have a name using the flink ioctl.</description><arg name="id" type="new_id" interface="wl_buffer"summary="wl_buffer assigned to this drm buffer"/><arg name="name" type="uint" summary="unique buffer name"/>
Would be much more explicit to say that is a flink name, not just any freely chosen unique number.
<arg name="width" type="int" summary="buffer width"/><arg name="height" type="int" summary="buffer height"/>
Units?
<arg name="stride" type="uint" summary="stride of a line"/>
Units?
Without specifying the units, you are not really adding any information here.
<arg name="format" type="uint" summary="see wl_drm_format"/></request>
- <!-- Create a wayland buffer for the named DRM buffer. The DRM
surface must have a name using the flink ioctl --><request name="create_planar_buffer">
<arg name="id" type="new_id" interface="wl_buffer"/><arg name="name" type="uint"/><arg name="width" type="int"/><arg name="height" type="int"/><arg name="format" type="uint"/><arg name="offset0" type="int"/><arg name="stride0" type="int"/><arg name="offset1" type="int"/><arg name="stride1" type="int"/><arg name="offset2" type="int"/><arg name="stride2" type="int"/>
<description summary="create planar drm buffer">Create a wayland buffer for the named planar DRM buffer.The DRM surface must have a name using the flink ioctl.</description><arg name="id" type="new_id" interface="wl_buffer"summary="wl_buffer assigned to this drm buffer"/><arg name="name" type="uint" summary="unique buffer name"/>
Flink name.
<arg name="width" type="int" summary="buffer width"/><arg name="height" type="int" summary="buffer height"/><arg name="format" type="uint" summary="see wl_drm_format"/><arg name="offset0" type="int" summary="first plane offset"/><arg name="stride0" type="int" summary="first plane stride"/><arg name="offset1" type="int" summary="second plane offset"/><arg name="stride1" type="int" summary="second plane stride"/><arg name="offset2" type="int" summary="third plane offset"/><arg name="stride2" type="int" summary="third plane stride"/>
Units?
</request>
- <!-- Notification of the path of the drm device which is used by
the server. The client should use this device for creatinglocal buffers. Only buffers created from this device shouldbe be passed to the server using this drm object'screate_buffer request. --><event name="device">
<arg name="name" type="string"/>
<description summary="drm device of the server">Notification of the path of the drm device which is used by theserver.The client should use this device for creating local buffers.Only buffers created from this device should be be passed tothe server using this drm object's create_buffer request.</description><arg name="name" type="string" summary="path of the drm device"/>
Ok.
</event> <event name="format">
<arg name="format" type="uint"/>
<description summary="pixel format description">Informs the client about a valid pixel format that can be usedfor buffers.</description><arg name="format" type="uint" summary="pixel format"/></event>
<!-- Raised if the authenticate request succeeded -->
<event name="authenticated"/>
<event name="authenticated">
<description summary="successful authentication">Raised if the authenticate request succeeded.</description></event>
Ok.
<enum name="capability" since="2">
<description summary="wl_drm capability bitmask">Bitmask of capabilities.
<description summary="capability description">Lists the available capabilities the server can expose.
You lost the most important word of the description: "bitmask". It tells how to add new values to this enum.
</description> <entry name="prime" value="1" summary="wl_drm prime available"/> </enum> <event name="capabilities">
<arg name="value" type="uint"/>
<description summary="capabilities bitmask">Bitmask of capabilities supported by the server.</description><arg name="value" type="uint" summary="capabilities"/>
Ok. Might add "see wl_drm_capability".
</event> <!-- Version 2 additions -->
- <!-- Create a wayland buffer for the prime fd. Use for regular and planar
buffers. Pass 0 for offset and stride for unused planes. --><request name="create_prime_buffer" since="2">
<arg name="id" type="new_id" interface="wl_buffer"/><arg name="name" type="fd"/><arg name="width" type="int"/><arg name="height" type="int"/><arg name="format" type="uint"/><arg name="offset0" type="int"/><arg name="stride0" type="int"/><arg name="offset1" type="int"/><arg name="stride1" type="int"/><arg name="offset2" type="int"/><arg name="stride2" type="int"/>
<description summary="create prime drm buffer">Create a wayland buffer for the prime fd.Use for regular and planar buffers. Pass 0 for offset andstride for unused planes.</description><arg name="id" type="new_id" interface="wl_buffer"summary="wl_buffer assigned to this drm buffer"/><arg name="name" type="fd" summary="prime fd"/>
I'm not really sure what a "prime fd" is, care to explain it in the description? Is it a dmabuf fd? Any additional semantics or constraints?
<arg name="width" type="int" summary="buffer width"/><arg name="height" type="int" summary="buffer height"/><arg name="format" type="uint" summary="see wl_drm_format"/><arg name="offset0" type="int" summary="first plane offset"/><arg name="stride0" type="int" summary="first plane stride"/><arg name="offset1" type="int" summary="second plane offset"/><arg name="stride1" type="int" summary="second plane stride"/><arg name="offset2" type="int" summary="third plane offset"/><arg name="stride2" type="int" summary="third plane stride"/></request>
</interface>
I don't mind if you don't add the extra information I asked for. So, if you put the "bitmask" back, then this would be: Revieved-by: Pekka Paalanen ppaalanen@gmail.com
Thanks, pq
PS. the proper mailing lists would be mesa-dev and wayland-devel. dri-devel is more for the kernel stuff.
dri-devel@lists.freedesktop.org
-
Emmanuel Gil Peyrot -
Pekka Paalanen