[PATCH weston-ivi-shell v2 02/15] ivi application protocol:
Nobuhiko Tanibata
nobuhiko_tanibata at xddp.denso.co.jp
Mon Mar 10 03:26:10 PDT 2014
2014-03-10 17:41 に Pekka Paalanen さんは書きました:
> On Fri, 7 Mar 2014 10:39:44 -0600
> Jason Ekstrand <jason at jlekstrand.net> wrote:
>
>> On Mar 7, 2014 7:56 AM, "Nobuhiko Tanibata" <
>> NOBUHIKO_TANIBATA at xddp.denso.co.jp> wrote:
>> >
>> > Add interface ivi_application, which creates ivi_surface objects
>> > tied to a given wl_surface with a given id. The given id can be
>> > used in a shell to identify which application is assigned to a
>> > wl_surface and layout the surface wherever the shell wants.
>> > ivi_surface objects can be used to receive status of wl_surface in
>> > the scenegraph of the compositor.
>> >
>> > Signed-off-by: Nobuhiko Tanibata
>> > <NOBUHIKO_TANIBATA at xddp.denso.co.jp> ---
>> >
>> > Changes for v2:
>> > - Rename "error" to "warning" because meaning of "error" in
>> > wayland is
>> fatal.
>> >
>> > protocol/ivi-application.xml | 88
>> ++++++++++++++++++++++++++++++++++++++++++++
>> > 1 file changed, 88 insertions(+)
>> > create mode 100755 protocol/ivi-application.xml
>> >
>> > diff --git a/protocol/ivi-application.xml
>> > b/protocol/ivi-application.xml new file mode 100755
>> > index 0000000..8659ec6
>> > --- /dev/null
>> > +++ b/protocol/ivi-application.xml
>> > @@ -0,0 +1,88 @@
>> > +<?xml version="1.0" encoding="UTF-8"?>
>> > +<protocol name="ivi_application">
>> > +
>> > + <copyright>
>> > + Copyright (C) 2013 DENSO CORPORATION
>> > + Copyright (c) 2013 BMW Car IT GmbH
>> > +
>> > + Permission is hereby granted, free of charge, to any person
>> obtaining a copy
>> > + of this software and associated documentation files (the
>> "Software"), to deal
>> > + in the Software without restriction, including without
>> > limitation
>> the rights
>> > + to use, copy, modify, merge, publish, distribute, sublicense,
>> > and/or
>> sell
>> > + copies of the Software, and to permit persons to whom the
>> > Software is
>> > + furnished to do so, subject to the following conditions:
>> > +
>> > + The above copyright notice and this permission notice shall be
>> included in
>> > + all copies or substantial portions of the Software.
>> > +
>> > + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
>> EXPRESS OR
>> > + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
>> MERCHANTABILITY,
>> > + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
>> > EVENT
>> SHALL THE
>> > + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
>> > OR
>> OTHER
>> > + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
>> ARISING FROM,
>> > + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
>> DEALINGS IN
>> > + THE SOFTWARE.
>> > + </copyright>
>> > +
>> > + <interface name="ivi_surface" version="1">
>> > + <description summary="application interface to surface in
>> > ivi
>> compositor"/>
>> > +
>> > + <request name="destroy" type="destructor">
>> > + <description summary="destroy ivi_surface"/>
>> > + </request>
>> > +
>> > + <event name="visibility">
>> > + <description summary="visibility of surface in ivi
>> compositor has changed">
>> > + The new visibility state is provided in argument
>> visibility.
>> > + If visibility is 0, the surface has become
>> > invisible.
>> > + If visibility is not 0, the surface has become
>> > visible.
>> > + </description>
>> > + <arg name="visibility" type="int"/>
>> > + </event>
>> > +
>> > + </interface>
>> > +
>> > + <interface name="ivi_application" version="1">
>> > + <description summary="interface for ivi applications to
>> > use ivi
>> compositor features"/>
>> > +
>> > + <request name="surface_create">
>> > + <description summary="create surface in ivi
>> > compositor">
>> > + surface_create will create a new surface with
>> > surface_id
>> in ivi compositor,
>> > + if it does not yet exists. If the surface with
>> surface_id already exists in
>> > + ivi compositor, the application content provided in
>> argument surface will
>> > + be used as surface content. If an other ivi
>> > application
>> already registered
>> > + content for surface with surface_id, an warning
>> > event
>> will indicate the problem.
>> > + </description>
>> > + <arg name="id_surface" type="uint"/>
>> > + <arg name="surface" type="object"
>> > interface="wl_surface"/>
>> > + <arg name="id" type="new_id" interface="ivi_surface"/>
>> > + </request>
>> > +
>> > + <enum name="warning_code">
>> > + <description summary="possible warning codes returned
>> > by ivi
>> compositor">
>> > + These warning codes define all possible warning
>> > codes
>> returned by ivi compositor
>> > + on server-side warnings.
>> > + </description>
>> > + <entry name="invalid_wl_surface" value="1"
>> summary="wl_surface is invalid"/>
>> > + <entry name="surface_id_in_use" value="2"
>> summary="surface_id is in use and can not be shared"/>
>> > + </enum>
>>
>> I have a couple more thoughts about these errors/warnings. For one, I
>> think some of these should be errors. For instance, there is no way
>> that the given wl_surface will be invalid unless the client has
>> destroyed it. Honestly, I'm not even sure if it's possible, given how
>> libwayland is written, to get a truely invalid wl_surface. From what
>> you've written in previous e-mails, I can't quite tell but it sounds
>> like you want to prevent a client from attaaching multiple
>> ivi_surface objects (and IVI ID's) to the same surface. If this is
>> the case then doing so should probably also be a fatal error because
>> that means the client was written wrong.
>>
>> With regards to what happens if a client tries to use an ID that's
>> already in use, I'm not 100% sure what to do there. You know IVI
>> systems better than I do. Is this something that happens with some
>> degree of regularity? Or is this something that only happens if the
>> there is a mistake in the client code? I'll leave that up to you.
>>
Hi Jason and pq,
- invalid_wl_surface
In the automotive use case, the worst case may need to be taken account.
In this use case, One application, e.g. Car navigation, will create
several ivi_surfaces in one process, its means one connection. These
surfaces for Map, traffic info, corner view, and so on. If it is
disconnected when something happen on creation of only ivi_surface, All
surfaces of car navigation will not work. Ideally, we shall remove all
bugs and release well-tested application to prevent it. However its
application required to work partially as fault tolerant. That's way, I
propose it as warnings and it is really fatal to the system, the Car
navigation application will notify it to the central controller to
decide whether the Car navigation application shall be restarted or not.
>> That said, if there is an issue, you need to explicitly say what
>> happens to the newly created ivi_surface object. The Wayland
>> protocol has no concept of returning NULL. Whenever a request or
>> event is fired which has a new_id parameter, both client and
>> server-side objects always get created. If surface_create can throw
>> a non-fatal error, we need to decide what happens to the new
>> ivi_surface object. One way to do this would be to have the
>> error/warning event on the ivi_surface itself instead of on
>> ivi_application. Then the client would know that if it recieves the
>> error/warning, that it needs to destroy the corresponding
>> ivi_surface. Otherwise, like you note below, they have to roundtrip
>> after every call to ivi_application.surface_create.
>
In case of that I have to do it, I will follow your suggested way. Thank
you for good ideas.
> Hi Nobuhiko,
>
> Jason pretty much covered everything that came to my mind, too.
>
> I just want to stress, that if a problem is caused by e.g. bad
> IVI-system configuration done by the system manufacturer rather than
> something the end user did, then I think you should keep to fatal
> errors. If a car manufacturer or a software vendor configures or codes
> something wrong, you really want to catch all those errors ASAP.
> Killing the whole client is a good way to point out such error
> conditions that really should never happen at runtime. Conflicting
> surface ID thing sounds like it is the system maker's fault, not an end
> user mistake.
>
Thank you for comment as well. As I mention it in the above, I want to
suggest the above mentioned use case.
> OTOH, if these problem cases can happen when the end user does
> something wrong, e.g. tries to open an application twice or whatever,
> the first thing would be to make sure the UI prevents such things from
> occurring in the first place.
I agree with you. UI shall prevent it.
> If you still need non-fatal errors in the
> protocol, then you have to have a solid plan on what happens with the
> request that caused it. Jason explained it well, you have to define how
> the already created protocol object works after the error has occurred
> in the compositor, i.e. even before the client receives the error
> event. The client might send requests to or requests referring the
> failed object before it processes the error event. You also should say
> something about how the client is expected to recover from this error.
> If the client is not disconnected, there must be a way to recover
> smoothly.
>
Yes, you are right. I will add clear comment in ivi_application.xml to
say how to
follow such a error.
> Jason's point about avoiding the roundtrip is a very good one.
>
> I haven't read the rest of the patches yet, but if you have error
> events defined in other protocol parts, the same comments apply.
>
> Personally I would hope for some more explanations on what the "ID" is,
> and how it is used, or at least a pointer in the .xml to more extensive
> documentation. It is quite odd to see numeric IDs passed manually in
> Wayland protocol.
>
Traditionally, automotive system list up all applications which will be
installed to the application with numeric IDs. The text might be OK to
manage them. Additionally, in the future, certified download
applications are also manged by IDs. This might be easier way then using
just a text. I will add such description to protocol summary.
Thank you,
Nobuhiko
>
> Thanks,
> pq
>
>> > +
>> > + <event name="warning">
>> > + <description summary="server-side warning detected">
>> > + The ivi compositor encountered warning while
>> > processing
>> a request by this
>> > + application. The warning is defined by argument
>> warning_code and optional
>> > + warning_text.
>> > + If the application requires to associate this
>> > warning
>> event to a request,
>> > + it can
>> > + 1. send request
>> > + 2. force display roundtrip
>> > + 3. check, if warning event was received
>> > + but this restricts the application to have only
>> > one
>> open request at a time.
>> > + </description>
>> > + <arg name="warning_code" type="int"/>
>> > + <arg name="warning_text" type="string"
>> > allow-null="true"/>
>> > + </event>
>> > +
>> > + </interface>
>> > +
>> > +</protocol>
>> > --
>> > 1.8.3.1
>> >
>> > _______________________________________________
>> > wayland-devel mailing list
>> > wayland-devel at lists.freedesktop.org
>> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list