started, among other things.
Management of applications, starting, running and stopping them is done in AGL
-with AFM [Application Framework Management](5_appfw.md),
+with AppFW [Application Framework Management](../3_Developer_Guides/1_Application_Framework/1_Introduction.md),
which is an umbrella name to denote the suite of tools and daemons that handle
-all of that. It is integrated with systemd and with the current security model,
-SMACK (Simplified Mandatory Access Control Kernel), a Linux kernel security
-module. Applications can use AFM to hang off data, and to pass it down to
-other services. Together with AFM, and with the help of a library,
-applications could tell the compositor which application to activate or to
-switch to.
+all of that. It is integrated with systemd and with the current security model.
+Applications can use AppFW to hang off data, and to pass it down to
+other services. Together with AppFW, applications could tell the compositor
+which application to activate or to switch to.
## Simplifying the graphical stack
environments. For AGL, the shell client can be represented under different
forms, as well as the fact that the process management has another layer
baked-in to handle MAC (Mandatory Access Control) labels and use the
-above-mentioned Application Framework Management. These are all tightly
+above-mentioned Application Framework. These are all tightly
integrated and therefore, the AGL compositor will not automatically start the
-shell client, although there's code to handle that. One can modify the
-configuration file, add the shell client path, and the compositor will attempt
-to start it.
+shell client, although there's code to handle that.
+
+## Specifying a shell client to be started by the compositor
+
+Nevertheless, one can modify the configuration file, add the shell client path, and the
+compositor will attempt to start it.
+
+```
+[shell-client]
+command=/path/to/your/client/shell
+```
+
+
## Private extensions
Please consult the [protocol file](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-compositor.git;a=blob_plain;f=protocol/agl-shell.xml;hb=refs/heads/master)
as that is the authoritative way of getting the latest version.
+#### V2 updates
+
+Version 2 of the agl-shell protocol, while it is is not obligatory to be
+supported by the shell client, it adds two new events: bound_ok and bound_fail
+events.
+
+It has been observed that in some cases where we do not explicitly have a knob
+in the toolkit to tell whether the application is a regular one (which doesn't
+need to bind to the agl-shell protocol) or a one that needs to implement
+agl-shell protocol might result in terminating the wayland connection.
+
+That happens because we can't have multiple clients bind to the agl-shell
+protocol interface and was particularly visible when using regular
+flutter applications with other shell clients (Qt homescreen, or WAM/chromum),
+basically mashing together different kind of toolkits in the same image. Once
+a client has already bound to the agl-shell protocol interface any other client
+that attempts to do same will get its wayland connection severed and the
+application will be terminated.
+
+These two events provide a race-free method in which the clients can tell if
+they're in charge (of being the shell client) or their just regular
+applications. Explicitly implementing this protocol if you have other means to
+specify which type of application it is running wouldn't be required nor
+necessary. But by using the protocol we can provide the same thing,
+programmatically, without fearing that the wayland connection might be
+severed, and implicitly taking down the application.
+
+#### V3 updates
+
+Version 3 of the agl-shell protocol adds 4 more events to signal out when the
+application state was changed: started, activated, deactivated and terminated.
+
+Version 3 update was mostly prompted by an issue with start-up of applications
+but also is part of the first steps to reduce and simplify a bit more
+activation handling in the compositor. Specifically with this protocol update,
+we can correctly orchestrate start-up and activation of applications.
+
+At the moment of adding this protocol update, the default compositor behaviour
+is to display/activate applications as soon they're started, a feature which
+we've called activate-by-default (and which is turned on by default).
+But users can choose to disable that in such a way that activation is entirely
+driven the shell client.
+
+Implicitly having this activate-by-default papered over various
+issue when don't have that activation by default turned on. Supporting both
+use-cases (activate-by-default, on and off) turned out to be cluster of
+problems and regression over time. Not only that the amount of complexity in
+the compositor is unwarranted and can simplified by telling the shell client
+handle any window management interaction on its own.
+
+Further more, with this protocol update we also includes some events already
+present in the agl-shell-desktop protocol like deactivate and terminate.
+
### agl-shell-desktop
This extension is targeted at keeping some of the functionally already
the current activate one, with each output having independently active
surfaces.
-#### Explicit output
+## Explicit output
The activation and setting surface roles requires passing a Wayland output
(wl_output). The output is the wayland interface representation of an output
* `hide-cursor=[false]` - do not advertise pointer/cursor to clients. Present
in the `[core]` section.
-### Running with software rendering
+## Running with software rendering
By default the compositor will attempt to use the GL-renderer, and implicitly
the GPU. One could instead use the CPU, by making use of the Pixman library. To
actually use the GL library and perform the operations in software, while the
former does not use any GL whatsover. All back-ends support disabling the
GL-render to make sure it does not interfere with the composing process.
+
+## Multiple output set-up and touch input devices
+
+There's no deterministic way in which the compositor enables the outputs and
+depending on the input devices, specifically touch input devices, and the way
+the connectors are wired, a touch input device might be associated with a
+different output than the one intended.
+
+A consistent way, that survives a reboot, is to use
+[udev rules](https://man7.org/linux/man-pages/man7/udev.7.html), which
+libweston would be able to use such that a particular output is tied/associated
+to a particular touch input device.
+
+For instance, assuming that you have a set-up consisting of 4 outputs, a 4
+touch input devices, when the outputs are being enabled the compositor
+front-end will associate all 4 touch input device -- if they haven't been
+previously being associated to a particular output, to the first enabled
+output.
+
+In order to avoid that, and associate each touch input device to
+their respective output an udev rule can be installed, for the default
+seat (named `seat0`).
+
+Example of a udev rule:
+
+```
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004a", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-1"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004b", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-2"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004c", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-3"
+SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-4"
+```
+
+Add the following under `/etc/udev/rules.d/91-output.rules` and reload udev
+rules for these changes to take effect:
+
+ $ udevadm control --reload-rules && udevadm trigger
+
+Note that in the above example, we use physical seat, named `seat0` which is
+the default physical seat. You can verify that these changes have been applied by
+checking the compositor logs (under `/run/platform/display/compositor.log` file)
+You should be seeing `CONNECTOR-NO by udev` message like the following:
+
+```
+associating input device event0 with output HDMI-A-1 (HDMI-A-1 by udev)
+```
+
+vs
+
+```
+associating input device event0 with output HDMI-A-2 (none by udev)
+```
+
+where the rules are either incorrect or badly written.
+
+Retrieving device attributes could be done archaically using `lsusb` or `lspci`
+or using `udevadm info -a /dev/input/event*` which can provide with a multitude
+of attributes to use. In our above example we only relied `idVendor` and
+`idProduct` but potentially other attributes might be used.
Code Review / AGL / documentation.git / blobdiff