Add documentation for the PipeWire backend.
Co-authored-by: Michael Tretter <m.tretter@pengutronix.de>
Signed-off-by: Philipp Zabel <philipp.zabel@gmail.com>
Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
Rather than reinventing --use-pixman and --use-gl throughout each
backend, just have a common --renderer=foo argument which can be used to
explicitly specify the renderer.
The old arguments are still handled for backwards compatibility.
Signed-off-by: Daniel Stone <daniels@collabora.com>
libweston contains weston_config and weston_shell_utils utilities
functions so include these in the sphinx documentation as well.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
While the --backend parameter looks like it takes a file name, it really
is selected from a list of supported strings that are then funneled
through a translation to enum weston_compositor_backend [1].
Because all backend parameters are of the form "...-backend.so", and
writing "--backend=...-backend.so" is boring, allow the --backend option
to match the backend name without "-backend.so" suffix instead.
For example, this allows to use "--backend=headless" instead of
"--backend=headless-backend.so".
Update help text and documentation. Keep the old way working for
backwards compatibility.
[1] 50dbf38514 ("libweston: use enum to choose the backend")
Signed-off-by: Philipp Zabel <philipp.zabel@gmail.com>
As seen previous times, with newer doxygen version we seem to be
generating warnings and with it to stop generating documentation
entirely as we have enabled warning as error in the doxygen
configuration file.
By default meson werror build option is not enabled, so users can still
generate documentation when building regularly, and when we'll update to
the same doxygen version we should be able to catch those errors up if
any of them will pile up in between.
Suggested-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
All these Doxygen configuration directives raise a deprecation warning
with Doxygen 1.9.5.
Since we have WARN_AS_ERROR = YES, this causes the build to fail.
Remove these deprecated directives.
I have checked the differences by first building from scratch without
this patch, and then building from scratch with this patch, and
in the latter builddir checking
$ diff -ru -x '*.md5' -x '*.pdf' ~/tmp/weston-doc-before doc
The only differences are the Doxygen config file and one .pickle file.
So it seems the generated docs are identical with Doxygen 1.9.1.
Fixes: https://gitlab.freedesktop.org/wayland/weston/-/issues/661
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The README for the IVI-shell is completely outdated.
Update the documentation, add some more information on the IVI-shell use cases
and explain how to use and customize the IVI-shell. Also convert the file to rst
and move it to doc directory next to the kiosk-shell documentation.
Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>
CLASS_DIAGRAM has been obsolete in newer version of doxygen, and
it's enabled if HAVE_DOT and CLASS_GRAPH are set.
This increase DOT_GRAPH_MAX_NODES to avoid dot complaning,
and include dot/graphviz for doxygen.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Same as LaTeX, RTF is being made obsolete in newer version of doxygen.
Also, we weren't really using it so there's no harm in removing it
entirely.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
LaTeX has become obsolete in newer doxygen version, and we weren't using
it at all so remove it entirely.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Add a struct weston_head parameter to weston_compositor_create_output()
and fold weston_compositor_create_output_with_head() into it.
See: https://gitlab.freedesktop.org/wayland/weston/-/issues/268
Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de>
This reverts commit 6914064066.
This is a follow-up change of b623fd2a ("drm-backend: stop parsing IN_FORMATS
blobs, use libdrm instead"). Weston now has a hard-requirement on libdrm
2.4.108, clean up remaining and unnecessary conditional code. Change 69140640
("backend-drm: add HDR_OUTPUT_METADATA definitions") is no longer needed
and stop including libdrm-updates.h from kms-color.c.
Signed-off-by: Luigi Santivetti <luigi.santivetti@imgtec.com>
These are fallback definitions in case libdrm is not new enough.
They are copied from libdrm 2.4.107.
struct hdr_output_metadata defines the contents of the blob to be used
with the connector property "HDR_OUTPUT_METADATA".
This is needed for programming a HDR mode in KMS.
This headers need to be excluded from Doxygen, because Doxygen chokes on
the kerneldoc markup.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Fbdev backend was deprecated in the Weston 10.0.0 release with
6338dbd581. Before that, I suggested
already in 2019 to remove it, but it was too soon then. Now it seems the
final voices asking for fbdev to be kept have been satisfied, see the
linked issue.
Fbdev-backend uses a kernel graphics UAPI (fbdev) which is sub-par for a
Wayland compositor: you cannot do GPU accelerated graphics in any
reasonable way, no hotplug support, multi-output support is tedious, and
so on. Most importantly, Linux has deprecated fbdev a long time ago due
to the UAPI fitting modern systems and use cases very poorly, but cannot
get rid of it if any users remain. Let's do here what we can to reduce
fbdev usage.
I am doing color management related additions to libweston which require
adding checks to every backend. One backend less is less churn to write
and review.
Libweston major version has already been bumped to 11, so the next
release will be Weston 11, without fbdev. enum weston_compositor_backend
entries change their numerical values.
Fixes: https://gitlab.freedesktop.org/wayland/weston/-/issues/581
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
When using the libseat launcher, there is one more detail to take care:
stop libseat from managing the VT.
A normal user does not have permissions to manage a VT, so launching
would just fail. In this use case you also do not want to be managing
the VT, because your normal desktop is already owning the seat
associated with the VT.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Give a little more details about how running Weston via ssh or serial
terminal is best done, now that launcher-direct and weston-launch are
gone.
Hopefully the removal of launcher-direct also makes less people run
Weston as root, when seatd is the privileged process. Running 'weston'
as root might still work through libseat's builtin backend without
seatd.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Moving forward we're going to be supporting libseat and logind as our
only launchers. We're doing this to reduce our maintenance burden,
and security impact.
Libseat supports all our existing use cases, and seatd can replace
weston-launch so we no longer have to carry a setuid-root program.
This patch removes weston-launch, and launcher-direct, leaving only
libseat and logind.
Signed-off-by: Derek Foreman <derek.foreman@collabora.com>
Add VGEM to the Linux image that runs in the CI. There are tests that we
plan to add in the future that need this.
This brings a complication, as we already have VKMS in the image. The
order in which DRM devices are loaded is not always the same, so the
node they receive is non-deterministic. Until now we were sure that VKMS
(the virtual device we use to run the DRM-backend tests in the CI) would
be in "/dev/dri/card0", but now we can't be sure. To deal with this
problem we find the node of each device using a one-liner shell script.
This commit also updates the documentation section that describes
specificities of DRM-backend tests in our test suite.
Signed-off-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
With the recent changes, weston could be started as user service. This
adds some examples and howtos one might do that. Includes some simple
systemd unit files.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
warning: Tag 'TCL_SUBST' at line 250 of file '/home/pq/build/weston-meson/doc/sphinx/doxygen.ini' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'COLS_IN_ALPHA_INDEX' at line 1094 of file '/home/pq/build/weston-meson/doc/sphinx/doxygen.ini' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'PERL_PATH' at line 2159 of file '/home/pq/build/weston-meson/doc/sphinx/doxygen.ini' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'MSCGEN_PATH' at line 2181 of file '/home/pq/build/weston-meson/doc/sphinx/doxygen.ini' 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.1 in Debian Bullseye.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
The standard style of LCOV HTML reports is a bit harsh to look at. This
commit replaces it with a new one.
The new CSS was written from scratch by looking at the HTML source code
of a generated LCOV report. The original gcov.css file was not used.
The color scheme is neutral, trying to avoid a Christmas tree effect.
The colors are intended to be calm while also distinguishable, and not
hamper text readability.
The font lists were taken from Gitlab with the hope that it will blend
in a little better when viewing from MR artifacts.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
This used a cargo-culted form of the ACTION check. Kernel is allowed to
invent new ACTIONs and IIRC there are already actions like bind and
unbind.
Udev events before rule processing always start with a clean property
list. This means that if you only match ACTION==add to add some value to
the event, then that value will not be present for ACTION==bind. Udev
event consumers do not accumulate values, so inconsistent value setting
may confuse them.
Therefore one needs to match ACTION!=remove, not ACTION==add|change, to
keep the device properties consistent for every event. It doesn't hurt
to set them on remove either, but it's a habit to try to avoid
processing when not strictly needed.
This issue came up in
https://gitlab.freedesktop.org/wayland/weston/-/issues/476#note_841430
For more information, see
https://lists.freedesktop.org/archives/systemd-devel/2020-November/045570.html
the part "KERNEL API INCOMPATIBILITY" near the beginning.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Documentation file for explaning in more detail how to run weston, using
launcher direct and specifying a non-default seat. This explains how to
create a udev file and assign a particular GPU card to it, and
potentially, other input devices. It also describes a bit additional
arguments that can be passed on, as an introduction to using the DRM
node for that particular seat.
Fixes#460
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
kiosk-shell is fullscreen shell for apps that use the xdg-shell
protocol. The goal is to make life easier for people shipping embedded
devices with simple fullscreen shell requirements, and reduce the
proliferation of desktop-shell hacks.
Top level surfaces are made fullscreen, whereas dialogs are placed on
top in the center of the output and retain their natural sizes. Dialogs
can be moved and (un)maximized, but resizing is currently not supported.
An app can be directed to a particular output by populating the
"app-ids" field with the app's XDG app id, in the relevant
"[output]" section in the weston config file.
Fixes: #277
Signed-off-by: Alexandros Frantzis <alexandros.frantzis@collabora.com>
With this patch we add support to run DRM-backend tests locally
in the test suite. For now this won't work in the CI, as there
are no cards available. But the plan is to achieve this by using
VKMS (virtual KMS) in the future.
To run DRM-backend tests locally, first of all the user has to
set the environment variable WESTON_TEST_SUITE_DRM_DEVICE to
'card0', 'card1' or any other device where he wants to run
the tests. Also, for now it only works if it is run as root,
but in the future this problem will be solved.
The tests will run on a non-default seat. The reason for that
is that we want to avoid opening input devices unnecessarily.
Also, since DRM-backend usage requires gaining DRM master status
on a DRM KMS device, nothing else must be using the device at
the same time. To achieve this we use a lock to run the
DRM-backend tests sequentially.
Signed-off-by: Leandro Ribeiro <leandro.ribeiro@collabora.com>
The only reason why we have both weston_compositor_tear_down() and
weston_compositor_destroy() is that the only we had to destroy
the log context was keeping weston_compositor alive and calling
weston_log_ctx_compositor_destroy().
After commit "weston-log: replace weston_log_ctx_compositor_destroy()
by weston_log_ctx_destroy()", it's not necessary to keep a zombie
weston_compositor just to be able to call
weston_log_ctx_compositor_destroy().
Fold weston_compositor_tear_down() into weston_compositor_destroy(),
as this split is useless now.
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
The function weston_log_ctx_compositor_destroy(), which destroys struct
weston_log_context, takes weston_compositor as argument. We may have a
weston_log_context unlinked from a weston_compositor and currently there
is no way to destroy it.
Add function weston_log_ctx_destroy(), what makes the destruction of
weston_log_context independent of weston_compositor.
With this change, one could destroy a weston_compositor and keep the
related weston_log_context (since now weston_log_context can be destroyed
without the need of a weston_compositor). But if weston_compositor gets
destroyed it's also necessary to destroy weston_log_context::global,
as the debug protocol depends on the compositor. So a listener has been
added to the destroy signal of weston_compositor.
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
Since weston_log_ctx_compositor_create() does not have any relation
with weston_compositor, rename it to weston_log_ctx_create().
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
If we use the function weston_log_context_add_log_scope()
in non-core code, it's necessary to access
weston_compositor::weston_log_ctx.
This is not ideal, since the goal is to make core structs
(weston_compositor, weston_surface, weston_output, etc)
opaque.
Add function weston_compositor_add_log_scope(), so non-core
users are able to pass weston_compositor as argument instead
of weston_compositor::weston_log_ctx.
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
There's a function named weston_compositor_log_scope_destroy()
but it doesn't take a struct weston_compositor argument.
Rename it to weston_log_scope_destroy(), as the argument is a
struct weston_log_scope.
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
There's a function named weston_compositor_add_log_scope()
but it doesn't take a struct weston_compositor argument.
Rename it to weston_log_ctx_add_log_scope(), as
the log_scope is being added to a log_context.
Also, bump libweston_major to 9.
Signed-off-by: Leandro Ribeiro <leandrohr@riseup.net>
When we were designing the libweston output API, I wrote a design document
as a Phabricator wiki page. Phabricator is no longer accessible so that
information needs to be migrated to a new place. Here I am converting most of
it into libweston Sphinx documentation, particularly pulling in the sequence
diagrams I drew. This should help people understand how libweston output
configuration works.
The diagrams are committed as both MSC source files and rendered PNG files. I
did not bother tinkering with the build to run mscgen automatically and then
with the CI images to install the tool.
The Sphinx configuration need numref explicitly enabled so that figures are
automatically numbered and can be referenced by their number rather than their
whole caption text(!).
The document structure is changed a little better flowing with Output
Management being the overview page and the Heads and Outputs being the API
pages.
First I wrote the struct weston_output and weston_head descriptions in Doxygen
comments in libweston.h, but then in the API page that text would have been
buried somewhere towards the end of the page. So I put that text in ReST
instead where it comes as first on the pages as it should. The doc for the
structs only contain a link to the top of the page. Yes, the comment style in
libweston.h is a little broken. If I left the asterisk there it would show up
as a bullet point in Sphinx. OTOH putting everything from \rst in a single line
did not produce anything.
Because Sphinx cannot look in two places, the images need to be copied into the
build dir too.
mscgen: http://www.mcternan.me.uk/mscgen/
Fixes: https://gitlab.freedesktop.org/wayland/weston/issues/25
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Mimics the C version that displays the contents of the flight recorder.
With a core-dump in place source the python file then call
'display_flight_rec' to dump the data.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Use doxygen ingroup command as to show the symbols in the sphinx
documentation.
Include some basic comments and document the exported functions from
timeline.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
This details the logging/debugging framework with the latest changes,
making use of the groups added by "weston-log: Start adding
documentation" and "libweston/log: Add 'wlog' group".
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Destroying the compositor after destroying the log scope will not print
out the messages in the tear down/clean-up phase of the compositor, so
add a new tear_down function which allows keeping a valid reference to
the compositor. This way we can destroy the compositor before destroying
the scope and keep the debug messages.
While at it remove the log context destroy part from the clean-up
of the compositor and make it stand on its own.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Unfortunate left over which was not removed once we had the script in
place to regenerate the documentation. A side-effect was the fact that
we still ran the script even if 'docs' target was called, effectively
nullifying the fact that 'docs' target was ran at all. For instance,
'install' would've been executing the script even if 'docs' target
was called before.
This removes the doxygen_target entirely and the depends of sphinx
target on it, makes building and installing docs a bit faster.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
With the introduction of the 'docs' target we make sure that we always
build the documentation, but currently breathe is unaware of the fact
that the doxygen XML database was changed in between runs. It is obvious
when changing only source code not rST bits.
This patch makes sphinx ignore the saved environment and always
rebuild the docs.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
These definitions were just set to the default (off), but their presence
causes Fedora's Doxygen to emit a warning as it is not compiled with
Clang support.
Remove them as they are no-ops anyway.
Signed-off-by: Daniel Stone <daniels@collabora.com>
Demonstrates how to call/use the 'doxygen*' breathe directives. Make
use of previous patches that tag symbols using 'ingroup' doxygen
command.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
With these aliases we can use rST directives inside comment blocks. This
adds also a doxygen command '\rststar' where ignores the asterisk --
typical to multi-line comment blocks.
While at it, add a simple example on how to use them.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Turn warnings into errors so we can spot them immediately.
While at it: no need to generate class graphs as we're not using it and
make doxygen run quieter.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
This is adds basic configuration files for doxygen and for breathe,
which is a doxygen-to-sphinx bridge that can document C symbols.
Breathe is configured with default project 'weston' and implicitly adds
:members: and :undoc-members: to breathe configuration options.
This allows a shorter way to call breathe directives without the need
specify the project and also to display implicitly all the members,
documented or not.
A 'docs' run_target to force the docs to be re-built has been added.
Initially (the first time the build system is ran) the documentation
will automatically be built, but later re-builds will require the use of
the 'docs' target. This avoid further delays in building weston but in
the same time allows the possiblity to update/improve the documentation
bits to those who want that.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
