* [PATCH] wayland-drm: add a description for every item.
@ 2015-03-25 12:10 Emmanuel Gil Peyrot
[not found] ` <1427285424-12452-1-git-send-email-linkmauve-xNsE4SeuFpL985uAA1p3mw@public.gmane.org>
0 siblings, 1 reply; 2+ messages in thread
From: Emmanuel Gil Peyrot @ 2015-03-25 12:10 UTC (permalink / raw)
To: dri-devel
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>
--
2.3.4
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] wayland-drm: add a description for every item.
[not found] ` <1427285424-12452-1-git-send-email-linkmauve-xNsE4SeuFpL985uAA1p3mw@public.gmane.org>
@ 2015-04-06 7:37 ` Pekka Paalanen
0 siblings, 0 replies; 2+ messages in thread
From: Pekka Paalanen @ 2015-04-06 7:37 UTC (permalink / raw)
To: Emmanuel Gil Peyrot
Cc: mesa-dev-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW,
dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW,
wayland-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW
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 the
> + display'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 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>
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() 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"/>
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 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"/>
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 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>
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 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"/>
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.
_______________________________________________
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2015-04-06 7:37 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-03-25 12:10 [PATCH] wayland-drm: add a description for every item Emmanuel Gil Peyrot
[not found] ` <1427285424-12452-1-git-send-email-linkmauve-xNsE4SeuFpL985uAA1p3mw@public.gmane.org>
2015-04-06 7:37 ` Pekka Paalanen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.