Document the XML tags used to describe Wayland protocols. Previously we
only had the informal specification in the Protocol chapter, and the
DTD. Better late than never.
I have looked into wayland-scanner and libwayland for various
limitations documented here possibly for the first time. I have also
forbid things that are not in use or are known broken, including
unspecified interface for a new_id in an event, or an object argument
with an unspecified interface.
I did investigate writing a RELAX NG compact schema for Wayland and
documenting everything there, then generating DocBook XML from it.
However, it seems generating documentation from schema is actually
really complicated. I found these tools:
- xs3p stylesheet: website looks dead, though Sourceforge still
has it. Produces XHTML, not DocBook. Has an unfamiliar license.
- xsddoc: the authors wrote that XSLT is not really sufficient, so they
abandoned this approach and went for Java to create xnsdoc.
- xnsdoc: seems to be proprietary licensed, although one could ask for a
free license for a FLOSS project.
All in all, it seems to be much easier to just write the documentation
in DocBook, copying the strcture from the DTD manually, than to generate
it. It's not doing to change often, anyway. It also allowed me to
leverage DocBook syntax in full.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Once I got XML validation working in VSCode, it found an error:
Document root element "preface", must match DOCTYPE root "chapter".
I guess DOCTYPE declares which element is used as root in the
file.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
It's unlikely that protocols/wayland.xml sees much change anymore, but
files in doc/ might. To make writing documentation easier, stick to an
unsurprising indentation style that is already in use in
wayland-protocols and for the XSL files.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
The behavior of content updates, specifically in combination with sync
subsrufaces and constrains can become quite complicated. This introduces
a chapter in the wayland book which explains the behavior of the core
specification in this regard, and shows examples.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
The protocol currently is in a state where we define that commits create
content updates and they are queued up until they are applied, and the
old view that commit applies the state or caches it in the parent state.
This commit moves the protocol completely to the new model which retains
the old behavior when no constraints are being used but allows for
constraints to be used to hold back a group of synchronized content
updates.
To convince yourself that this indeed retains the original behavior I
suggest to play around with a few examples and look at the resulting
graphs, as is done here:
https://gitlab.freedesktop.org/wayland/wayland/-/issues/457#note_2403135
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
It seems these images were never in the repository. They might have
existed when the documentation was still built with Publican, but since
the migration to xmlto I think these have all been just 404.
Removing div.warning:before, div.note:before and div.important:before
would actually delete some unexpected empty space if the Docbook
<warning>, <note> or <important> elements were used. They are not used
now, but may be in the future.
.draft is never used, so I replaced the image with whatever.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Artifacts include the prefix directory, but it was empty: we
weren't running the install step. Run it to align Debian with
FreeBSD.
This allows reviewers to check the HTML documentation output.
Signed-off-by: Simon Ser <contact@emersion.fr>
The exact type behind these might depend on the architecture. For
instance, on ARMv7, struct timeval fields are long long int instead
of long int:
FAILED: tests/libtest-runner.a.p/test-compositor.c.o
cc -Itests/libtest-runner.a.p -Itests -I../tests -I. -I.. -Isrc -I../src -fdiagnostics-color=always -fsanitize=address,undefined -fno-omit-frame-pointer -D_FILE_OFFSET_BITS=64 -Wall -Winvalid-pch -Wextra -Werror -std=c99 -O0 -g -D_POSIX_C_SOURCE=200809L -Wno-unused-parameter -Wstrict-prototypes -Wmissing-prototypes -fvisibility=hidden -fPIC -pthread -MD -MQ tests/libtest-runner.a.p/test-compositor.c.o -MF tests/libtest-runner.a.p/test-compositor.c.o.d -o tests/libtest-runner.a.p/test-compositor.c.o -c ../tests/test-compositor.c
../tests/test-compositor.c: In function 'get_socket_name':
../tests/test-compositor.c:95:60: error: format '%ld' expects argument of type 'long int', but argument 5 has type '__time64_t' {aka 'long long int'} [-Werror=format=]
95 | snprintf(retval, sizeof retval, "wayland-test-%d-%ld%ld",
| ~~^
| |
| long int
| %lld
96 | getpid(), tv.tv_sec, tv.tv_usec);
| ~~~~~~~~~
| |
| __time64_t {aka long long int}
../tests/test-compositor.c:95:63: error: format '%ld' expects argument of type 'long int', but argument 6 has type '__suseconds64_t' {aka 'long long int'} [-Werror=format=]
95 | snprintf(retval, sizeof retval, "wayland-test-%d-%ld%ld",
| ~~^
| |
| long int
| %lld
96 | getpid(), tv.tv_sec, tv.tv_usec);
| ~~~~~~~~~~
| |
| __suseconds64_t {aka long long int}
Signed-off-by: Simon Ser <contact@emersion.fr>
This fixes a validation error in the documentation which are not fatal.
The idea is the same as in 12ec67a ("server: document listener fields
and a vfunc"), which seems to have missed the reference to the
wl_protocol_logger_func_t from the note in wl_log_func_t.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
Now that all XML validation errors have been fixed, it is time to turn
the validation back on to make sure the errors stay out.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Creating an empty <variablelist> is illegal. This can already be seen in
the XSL anywhere it is generated. The used XSL programming pattern
requires the look-up conditions to be repeated between the <xsl:if> and
<xsl:apply-templates> tags. Usually this is not a problem, but the
conditions for memberdef is too much to copy around.
The conditions between the if and the apply-templates have already
diverged, causing validation errors (that are currently suppressed).
Rearrange the XSL so that the applicable memberdef are stored in a
variable, so that both the if and the apply-templates operate on the
exact same set of matches. This avoids emitting empty <variablelist>.
As a result, the members of structures wl_argument, wl_interface,
wl_message, and wl_listener newly appear in the documentation.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Adding these simple documentation comments allows us to have meaningful
link targets in the generated API documentation. That will help getting
rid of broken links which cause XML validation to fail.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
Now that I figured out what these do, I might as well add comments about
it for others.
The target names are changed to be more descriptive of what the target
does.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
When generating documentation, xmllint complained:
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1afe73f44f7f1b517c9c0ba90829c93309"
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1afe73f44f7f1b517c9c0ba90829c93309"
element link: validity error : IDREF attribute linkend references an
unknown ID "Server-structwl__signal_1aa8bcd3b8e250cfe35ed064d5af589096"
These were referring to wl_signal_add() and wl_signal_emit() I think,
which are static inlines in a public header.
The XSLT ignored static functions, probably assuming that they cannot be
public API. Internal (static) functions are present in the Doxygen XML,
so they do need to be excluded. Now we include static functions if their
body is in a header. We de not scan private headers, so they must be
public API.
Comparing the final generated HTML documentation, these functions are
added to both Client and Server APIs:
wl_fixed_to_double
wl_fixed_from_double
wl_fixed_to_int
wl_fixed_from_int
These functions are added to the Server API:
wl_signal_init
wl_signal_add
wl_signal_get
wl_signal_emit
Signed-off-by: Pekka Paalanen <pq@iki.fi>
xmllint complained:
element imageobjectco: validity error : Element imageobjectco content
does not follow the DTD, expecting (areaspec , imageobject ,
calloutlist*), got (imageobject )
This image has no callouts (clickable items explained in the text), so
it must not use the tags that assume callouts.
I probably cargo-culted this from the X11 and Wayland diagrams which
have callouts when writing Xwayland.xml.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
$ meson compile -C build -v xml-Server-doc
INFO: autodetecting backend as ninja
INFO: calculating backend command to run: /usr/bin/ninja -C /home/pq/git/wayland/build -v doc/doxygen/xml/Server/combine.xslt doc/doxygen/xml/Server/index.xml
ninja: Entering directory `/home/pq/git/wayland/build'
[1/1] /home/pq/git/wayland/doc/doxygen/gen-doxygen.py --builddir=doc/doxygen/xml/Server --section=Server --output-format=xml doc/doxygen/wayland.doxygen ../doc/doxygen/../../src/wayland-util.h ../doc/doxygen/../../src/event-loop.c ../doc/doxygen/../../src/wayland-server.c ../doc/doxygen/../../src/wayland-server.h ../doc/doxygen/../../src/wayland-server-core.h ../doc/doxygen/../../src/wayland-shm.c
/home/pq/git/wayland/src/wayland-server-core.h:394: warning: explicit link request to 'wl_signal_add' could not be resolved
I don't know why, but the "explicit link" mark-up fails, while the
automatic link mark-up works. This warning disappears.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
This fixes the errors during the compilation of Architecture.xml that
the .map files cannot be found. As a result, the architure diagrams
become clickable in the HTML document once again.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
For all requests and events that do not have any arguments, enabling XML
validation would lead to many errors like this:
/home/pq/git/wayland/build/doc/publican/Wayland.xml:5287: element
variablelist: validity error : Element variablelist content does not
follow the DTD, expecting (blockinfo? , (title , titleabbrev?)? ,
(caution | important | note | tip | warning | literallayout |
programlisting | programlistingco | screen | screenco | screenshot |
synopsis | cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis |
constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara |
para | simpara | address | blockquote | graphic | graphicco |
mediaobject | mediaobjectco | informalequation | informalexample |
informalfigure | informaltable | anchor | bridgehead | remark |
highlights | abstract | authorblurb | epigraph | indexterm | beginpage)*
, varlistentry+), got
The reason is that a <variablelist> without any <varlistentry> inside it
is illegal.
If there are no <arg> at all, do not emit the list paragraph.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
to fix the Doxygen message:
warning: Tag 'HTML_TIMESTAMP' at line 8 of file '-' has become
obsolete. To avoid this warning please remove this line from your
configuration file or upgrade it using "doxygen -u"
Observed with Doxygen 1.9.8.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
The XSL files are mostly indented with 2 spaces. Using the default
editorconfig rules in VSCode constantly tries to mix in tabs. Add the
2-space rule for .xsl files to fix this.
The .xsl files, like .xml files, use a tab character in place of 8
spaces. This complicates things, and the new rule will prefer just
spaces. To keep the existing sometimes-tab-indented code looking right,
the tab width must be explicitly set to 8.
Signed-off-by: Pekka Paalanen <pq@iki.fi>
The event loop timer test has very precise sequencing and timing
constraints, which make it difficult to pass reliably on loaded systems.
Since this test isn't providing much value, remove it to prevent the
erroneous errors.
Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
By structuring things differently, it becomes possible to have a
complete build of the docs in the build dir, without having to install
anything.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
This version will be required in the next commit.
Bumps the CI image to get the required version from the debian package
instead of from pip.
Removes the bindir builtin directory from pkgconfig.generate() which is
deprecated since 0.62.0. It will be automatically included when
referenced.
Use `meson setup` everywhere instead of relying on deprecated automatic
detection of the setup command.
Signed-off-by: Sebastian Wick <sebastian.wick@redhat.com>
As well as wl_display_dispatch_queue_pending_single.
The motivation is writing libwayland bindings for a dynamic language
with exceptions/non-local returns. Since it is invalid for a
wl_dispatcher_func_t callback provided to libwayland to not return,
there is no way to prevent dispatching of further events in the case of
an exception in the dynamic language event handler.
Furthermore, since creating/destroying Wayland objects in an event
handler affects the dispatching of subsequent events by libwayland,
it is not possible to collect Wayland events in a queue outside
libwayland and dispatch them one-by-one after
wl_display_dispatch_pending() returns.
Adding libwayland API to dispatch at most one pending event solves this
problem cleanly. The bindings can have libwayland dispatch a single
event, wait for wl_display_dispatch_pending_single() to return, run the
dynamic language event handler (which may longjmp away), and continue
the loop for as long as there are more events to dispatch.
References: https://codeberg.org/ifreund/janet-wayland
Signed-off-by: Isaac Freund <mail@isaacfreund.com>
If WAYLAND_DEBUG contains the token "thread_id", and gettid() is
available, then include the current thread ID in the output from
wl_closure_print.
If multiple threads are sending requests, then those requests can get
interleaved. That's usually fine, but for wl_surface requests and
commits, that can cause problems ranging from incorrect behavior to
protocol errors.
Being able to see which requests are sent by different threads would
make such problems much easier to diagnose.
Signed-off-by: Kyle Brenneman <kbrenneman@nvidia.com>
Add a new function, wl_check_env_token, to scan for a token in a
comma-separated string.
Change wl_display_create in wayland-server.c and
wl_display_connect_to_fd in wayland-client.c to use that instead of a
simple substring search.
This means that WAYLAND_DEBUG will accept a value like "client,server"
but not "clientserver". But, this will make it easier to add other
tokens without worrying about overlap between them.
Signed-off-by: Kyle Brenneman <kbrenneman@nvidia.com>
If the length of a message exceeds the maximum length of the buffer, the
buffer size will reach its maximum value and stay there forever, with no
message ever being successfully processed. Since libwayland uses
level-triggered epoll, this will cause the compositor to loop forever
and consume CPU time. In libwayland 1.22 and below, there was an
explicit check that caused messages exceeding 4096 bytes to result in an
EOVERFLOW error, preventing the loop. However, this check was removed
between d074d52902 ("connection: Dynamically resize connection buffers").
To prevent this problem, always limit the size of messages to 4096 bytes.
Since the default and minimum buffer size is 4096 bytes, this ensures
that a single message will always fit in the buffer. It would be
possible to allow larger messages if the buffer size was larger, but the
maximum size of a message should not depend on the buffer size chosen by
the compositor.
Rejecting messages that exceed 4092 bytes seems to have the advantage of
reserving 4 bits, not 3, in the size field for future use. However,
message sizes in the range [0x0, 0x7] are invalid, so one can obtain a
fourth bit by negating the meaning of bit 12 if bits 0 through 11
(inclusive) are 0. Allowing 4096-byte messages provides the far more
important advantage that regressions compared to 1.22 are impossible
and regressions compared to 1.23 are extremely unlikely. The only case
where a regression is possible is:
- The receiving side is using libwayland 1.23.
- The sending side is either using libwayland 1.23 or is not using
libwayland.
- The sender sends a message exceeding 4096 bytes.
- If the sender of the large message is the client, the server has
increased the buffer size from the default value.
This combination is considered extremely unlikely, as libwayland 1.22
and below would disconnect upon receiving such a large message.
4096-byte messages, however, have always worked, so there was no reason
to avoid sending them.
Fixes: d074d52902 ("connection: Dynamically resize connection buffers").
Fixes: #494
Signed-off-by: Demi Marie Obenour <demi@invisiblethingslab.com>
I think the docbook deserves an introduction to how color management is
designed in Wayland, aimed at people who are familiar with pixels but
new to the topic.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Previously each value was a list of extra sources. The next commit will add an
additional field to each test, so they need to be dicts themselves.
Signed-off-by: Matt Turner <mattst88@gmail.com>
This change mentions the case where WAYLAND_SOCKET is used, which helps
people avoid just testing 'getenv(WAYLAND_DISPLAY)' to see if a
Wayland compositor is available;
Signed-off-by: Manuel Stoeckl <code@mstoeckl.com>
Do not override realloc's input pointer before checking for errors,
otherwise it's not possible to keep old value, as intended.
Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>
If cursor files require more than INT_MAX bytes, it is possible to
trigger out of boundary writes.
Since these sizes are most likely not desired anyway, gracefully
handle these situations like out of memory errors.
Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>
If the full path could not be constructed, avoid calling opendir(NULL)
which, depending on library, might trigger undefined behavior.
Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>
If an index.theme contains a theme name which gets close to INT_MAX,
then creation of full path can lead to a signed integer overflow,
which is undefined behavior.
Fix this by turning one of the values to size_t. Easy solution for a
probably never occurring issue.
Signed-off-by: Tobias Stoeckmann <tobias@stoeckmann.org>
