[PATCH 1/6] Add weston randr protocol

[Wang, Quanxian]

Hi, All

With the first version of randr protol, I got many useful idea and comments. Thanks.

Before I send the email, I have make it happen in real world but need more deep testing.

Here are new changes and idea for that protocol based on the idea and comments, welcome your input. 

1) Unique operation issue
Given that one client has two more threads to do mode setting on the same output at the same time, how to identify what response (done event) is belong to one or another request when they want to get response? 

This is a design flaw in the first version of randr protocol.

The solution is to use the wayland/weston mechanism, every request will generate a resource which be used to send done event to the owner who start it. Owner could set the listener on that and keep tuning on the response event.

For example
In client:
randr_transform = wl_randr_set_transform(randr.randr,wayland_output,argument.transform);

/* Here will will add listen callback to get the response for this unique request */
wl_randr_add_listener(randr_transform, &randr_transform_listener, &randr);

In compositor:
randr_resource = wl_resource_create(client,&wl_randr_interface,1, action);
wl_randr_send_action_done(randr_resource, 1<<WL_RANDR_ACTION_TRANSFORM, ret, action);
wl_resource_destroy(randr_resource);

2) Security and mess up issue
Will take randr protocol implementation as a module or plugin. This will keep compositor clear and avoid messing up in compositor.c. Also it is will be fine for compositor when this could be public.
The security should be a general issue for wayland instead of for randr protocol only. Take randr protocol as a module for user to determine if they want to public randr interface for their clients. Once security mechanism is built up in wayland, randr could adopt the mechanism to enhance the security of randr protocol.

weston --tty=1 --modules=wrandr.so
or set it in weston.ini like that
[core]
modules=wrandr.so

3) Group randr operations
After talking with PQ, in order to avoid glitches, group operation is needed. However, if operate on two outputs more at one time, it will bring more issues which could not control. In this randr design, will not provide group operation on multiple outputs. We provide atomic operation on one output, multi outputs operation logic are left to designer/developers. Group operation on one output will be designed. For example, you can set mode, scale, and transform at one time with one randr request.

4) Configuration interface
Weston randr protocol will be taken as configuration interface for output mode setting in wayland. So the permission for that will be strictly under the control. Before security mechanism is ready, randr module will be designed for compositor as a choice. It is just a loadable module or plugin for special compositors. User will take the decision if start it when boot up compositor as a module.

5) mode setting parameters control
Mode and output will be under the control. User could not randomly to set their mode. They have to select the available modes and outputs provided by compositor. Don't allow random mode setting. The mode and output information could be provided by weston-randr apps or wl_output interface.

6) Disconnected outputs
When user query output information, showing connected and disconnected output as a whole will be fine for user and QA people. Sometime, QA people or user like that information. It will be helpful for them to identify how many outputs are provided by their machine. Which is connected and which is not connected.

7) wl_output property event
Delete get_output_name request and event in protocol. wl_output name event will be added into wl_output protocol. This event will send the output name to user when they bind wl_output. For width and height of wl_output, I am not sure if it is should be sent out at the same time. My idea is it should be the same event to send name, width, height after output is changed. But currently I will not add that.

8) adding set_scale request
Mode, scale, transform is the basic property of output, I will add them as a whole.

Thanks

Regards

Quanxian Wang

-----Original Message-----
From: Pekka Paalanen [mailto:ppaalanen at gmail.com] 
Sent: Thursday, February 27, 2014 5:45 PM
To: Wang, Quanxian
Cc: wayland-devel at lists.freedesktop.org; Zhang, Xiong Y
Subject: Re: [PATCH 1/6] Add weston randr protocol

On Thu, 27 Feb 2014 09:15:55 +0000
"Wang, Quanxian" <quanxian.wang at intel.com> wrote:

> 
> 
> -----Original Message-----
> From: Pekka Paalanen [mailto:ppaalanen at gmail.com]
> Sent: Thursday, February 27, 2014 4:36 PM
> To: Wang, Quanxian
> Cc: wayland-devel at lists.freedesktop.org; Zhang, Xiong Y
> Subject: Re: [PATCH 1/6] Add weston randr protocol
> 
> On Thu, 27 Feb 2014 08:06:23 +0000
> "Wang, Quanxian" <quanxian.wang at intel.com> wrote:
> 
> > 
> > 
> > -----Original Message-----
> > From: Pekka Paalanen [mailto:ppaalanen at gmail.com]
> > Sent: Thursday, February 27, 2014 3:28 PM
> > To: Wang, Quanxian
> > Cc: wayland-devel at lists.freedesktop.org; Zhang, Xiong Y
> > Subject: Re: [PATCH 1/6] Add weston randr protocol
> > 
> > On Thu, 27 Feb 2014 11:28:00 +0800
> > Quanxian Wang <quanxian.wang at intel.com> wrote:
> > 
> > > Weston protocol wrandr will provide interface to
> > > 1) set output mode
> > > 2) set output transform
> > > 3) move output to relative position
> > > 4) provide disconnected display port information
> > > 
> > > *Dynamic* mode setting is the main objective of this protocol.
> > > Remember, it is one shot operation. For example, if setting the 
> > > mode, just call one request wl_randr_set_mode without any other 
> > > operation.
> > 
> > Hi,
> > 
> > like I said in my other reply, this is a configuration interface, 
> > not something for all applications to use. Protocol comments below 
> > assuming, that this will be a configuration interface and that the 
> > generic idea is acceptable.
...
> > If I change the mode on two different outputs, how do I know which 
> > action_done corresponds to which request? [Wang, Quanxian] right, 
> > add wl_output parameter.
> 
> No. If I do two mode set operations on the same wl_output, then again 
> I would not know which answer was for which. [Wang, Quanxian] I know 
> you mean. Yes, if the same client has more threads which send mode 
> change at the same time, we have to use unique number to stand for 
> every operation.

That unique number could be a serial, but here more appropriate is a unique number for each request. You can let Wayland do all the unique number management for you by using the feedback object design I referred to below. After all, a Wayland protocol object is essentially just a unique number. They are very cheap.

That is why you almost never need to manually fiddle with "unique numbers" in the protocol.

> Instead, a generic pattern for this kind of "return data" is to let 
> the original request also create a feedback protocol object. This 
> object is unique to the request that was sent, and can deliver any 
> return data without any ambiguity. An example of a feedback object is 
> wl_callback, except it can only deliver "done", not "yes"/"no"; not 
> delivering anything will cause problems. [Wang, Quanxian] Good, 
> thanks.
> 
> > 
> > What if move succeeds but mode change fails? Wouldn't that leave the 
> > output in an unwanted state which is neither the original nor the 
> > wanted setting? [Wang, Quanxian] one by one. Not support complex. If 
> > you have such case, have to turn back. Call another move back. But 
> > firstly make sure the previous is successful.
> 
> That will require a lot of roundtrips, and it essentially forces the 
> compositor to show all the intermediate steps on the monitors. IOW, 
> that is designed to be both slow and glitchy. That's not how you 
> should do dynamic mode setting. I think you are going to need atomic 
> group operations. [Wang, Quanxian] Yes, we could provide a request 
> with more parameters setting(group operations). Just like many 
> parameters in weston_output_switch_mode.

Except you would need to let it cover an arbitrary number of outputs in one go. That means that you will need something like what wl_surface.commit does. Having a request with a huge number of arguments is not only ugly but inflexible, and cannot be extended in the future.

> > The solution to this would tie in with the solution to take changes 
> > atomic. For instance, to prepare for a configuration change, one 
> > might create a change object in the protocol, store all changes in 
> > that object, and then commit that set of changes atomically. Then 
> > have one return value: the whole set either succeeds or fails.
> > 
> > I guess you could look for inspiration in the DRM atomic mode 
> > setting API. I don't know how the RandR X11 protocol works, if that 
> > would be a good example also.

Thanks,
pq