From mboxrd@z Thu Jan 1 00:00:00 1970 From: mturquette@linaro.org (Michael Turquette) Date: Thu, 30 Jul 2015 15:47:20 -0700 Subject: [PATCH v7 3/5] clk: Supply the critical clock {init, enable, disable} framework In-Reply-To: <20150730095014.GD14642@x1> References: <1437570255-21049-1-git-send-email-lee.jones@linaro.org> <1437570255-21049-4-git-send-email-lee.jones@linaro.org> <20150727072549.GP2564@lukather> <20150727085338.GW3436@x1> <20150728114022.GW2564@lukather> <20150728130055.GV14943@x1> <20150730011932.642.85168@quantum> <20150730095014.GD14642@x1> Message-ID: <20150730224720.23791.6722@quantum> To: linux-arm-kernel@lists.infradead.org List-Id: linux-arm-kernel.lists.infradead.org Quoting Lee Jones (2015-07-30 02:50:14) > On Wed, 29 Jul 2015, Michael Turquette wrote: > > Quoting Lee Jones (2015-07-28 06:00:55) > > > On Tue, 28 Jul 2015, Maxime Ripard wrote: > > > > > > > On Mon, Jul 27, 2015 at 09:53:38AM +0100, Lee Jones wrote: > > > > > On Mon, 27 Jul 2015, Maxime Ripard wrote: > > > > > > > > > > > On Wed, Jul 22, 2015 at 02:04:13PM +0100, Lee Jones wrote: > > > > > > > These new API calls will firstly provide a mechanisms to tag a clock as > > > > > > > critical and secondly allow any knowledgeable driver to (un)gate clocks, > > > > > > > even if they are marked as critical. > > > > > > > > > > > > > > Suggested-by: Maxime Ripard > > > > > > > Signed-off-by: Lee Jones > > > > > > > --- > > > > > > > drivers/clk/clk.c | 45 ++++++++++++++++++++++++++++++++++++++++++++ > > > > > > > include/linux/clk-provider.h | 2 ++ > > > > > > > include/linux/clk.h | 30 +++++++++++++++++++++++++++++ > > > > > > > 3 files changed, 77 insertions(+) > > > > > > > > > > > > > > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c > > > > > > > index 61c3fc5..486b1da 100644 > > > > > > > --- a/drivers/clk/clk.c > > > > > > > +++ b/drivers/clk/clk.c > > > > > > > @@ -46,6 +46,21 @@ static struct clk_core *clk_core_lookup(const char *name); > > > > > > > > > > > > > > /*** private data structures ***/ > > > > > > > > > > > > > > +/** > > > > > > > + * struct critical - Provides 'play' over critical clocks. A clock can be > > > > > > > + * marked as critical, meaning that it should not be > > > > > > > + * disabled. However, if a driver which is aware of the > > > > > > > + * critical behaviour wants to control it, it can do so > > > > > > > + * using clk_enable_critical() and clk_disable_critical(). > > > > > > > + * > > > > > > > + * @enabled Is clock critical? Once set, doesn't change > > > > > > > + * @leave_on Self explanatory. Can be disabled by knowledgeable drivers > > > > > > > + */ > > > > > > > +struct critical { > > > > > > > + bool enabled; > > > > > > > + bool leave_on; > > > > > > > +}; > > > > > > > + > > > > > > > struct clk_core { > > > > > > > const char *name; > > > > > > > const struct clk_ops *ops; > > > > > > > @@ -75,6 +90,7 @@ struct clk_core { > > > > > > > struct dentry *dentry; > > > > > > > #endif > > > > > > > struct kref ref; > > > > > > > + struct critical critical; > > > > > > > }; > > > > > > > > > > > > > > struct clk { > > > > > > > @@ -995,6 +1011,10 @@ static void clk_core_disable(struct clk_core *clk) > > > > > > > if (WARN_ON(clk->enable_count == 0)) > > > > > > > return; > > > > > > > > > > > > > > + /* Refuse to turn off a critical clock */ > > > > > > > + if (clk->enable_count == 1 && clk->critical.leave_on) > > > > > > > + return; > > > > > > > + > > > > > > > > > > > > I think it should be handled by a separate counting. Otherwise, if you > > > > > > have two users that marked the clock as critical, and then one of them > > > > > > disable it... > > > > > > > > > > > > > if (--clk->enable_count > 0) > > > > > > > return; > > > > > > > > > > > > > > @@ -1037,6 +1057,13 @@ void clk_disable(struct clk *clk) > > > > > > > } > > > > > > > EXPORT_SYMBOL_GPL(clk_disable); > > > > > > > > > > > > > > +void clk_disable_critical(struct clk *clk) > > > > > > > +{ > > > > > > > + clk->core->critical.leave_on = false; > > > > > > > > > > > > .. you just lost the fact that it was critical in the first place. > > > > > > > > > > I thought about both of these points, which is why I came up with this > > > > > strategy. > > > > > > > > > > Any device which uses the *_critical() API should a) have knowledge of > > > > > what happens when a particular critical clock is gated and b) have > > > > > thought about the consequences. > > > > > > > > Indeed. > > > > > > > > > I don't think we can use reference counting, because we'd need as > > > > > many critical clock owners as there are critical clocks. > > > > > > > > Which we can have if we replace the call to clk_prepare_enable you add > > > > in your fourth patch in __set_critical_clocks. > > > > > > What should it be replaced with? > > > > > > > > Cast your mind back to the reasons for this critical clock API. One > > > > > of the most important intentions of this API is the requirement > > > > > mitigation for each of the critical clocks to have an owner > > > > > (driver). > > > > > > > > > > With regards to your second point, that's what 'critical.enabled' > > > > > is for. Take a look at clk_enable_critical(). > > > > > > > > I don't think this addresses the issue, if you just throw more > > > > customers at it, the issue remain with your implementation. > > > > > > > > If you have three customers that used the critical API, and if on of > > > > these calls clk_disable_critical, you're losing leave_on. > > > > > > That's the idea. See my point above, the one you replied "Indeed" > > > to. So when a driver uses clk_disable_critical() it's saying, "I know > > > why this clock is a critical clock, and I know that nothing terrible > > > will happen if I disable it, as I have that covered". So then if it's > > > not the last user to call clk_disable(), the last one out the door > > > will be allowed to finally gate the clock, regardless whether it's > > > critical aware or not. > > > > > > Then, when we come to enable the clock again, the critical aware user > > > then re-marks the clock as leave_on, so not critical un-aware user can > > > take the final reference and disable the clock. > > > > > > > Which means that if there's one of the two users left that calls > > > > clk_disable on it, the clock will actually be disabled, which is > > > > clearly not what we want to do, as we have still a user that want the > > > > clock to be enabled. > > > > > > That's not what happens (at least it shouldn't if I've coded it up > > > right). The API _still_ requires all of the users to give-up their > > > reference. > > > > > > > It would be much more robust to have another count for the critical > > > > stuff, initialised to one by the __set_critical_clocks function. > > > > > > If I understand you correctly, we already have a count. We use the > > > original reference count. No need for one of our own. > > > > > > Using your RAM Clock (Clock 4) as an example > > > -------------------------------------------- > > > > > > Early start-up: > > > Clock 4 is marked as critical and a reference is taken (ref == 1) > > > > > > Driver probe: > > > SPI enables Clock 4 (ref == 2) > > > I2C enables Clock 4 (ref == 3) > > > > > > Suspend (without RAM driver's permission): > > > SPI disables Clock 4 (ref == 2) > > > I2C disables Clock 4 (ref == 1) > > > /* > > > * Clock won't be gated because: > > > * .leave_on is True - can't dec final reference > > > > I am clearly missing the point. The clock won't be gated because the > > enable_count is still 1! What does .leave_on do here? > > The point of _this_ (the extended) part of the API is so that the > clock _can_ be turned off. Without the possibility to disable > .leave_on and the logic with accompanies it (i.e. > clk_disable_critical()) the clock will _never_ be gated. > > > > */ > > > > > > Suspend (with RAM driver's permission): > > > /* Order is unimportant */ > > > SPI disables Clock 4 (ref == 2) > > > RAM disables Clock 4 (ref == 1) /* Won't turn off here (ref > 0) > > > I2C disables Clock 4 (ref == 0) /* (.leave_on == False) last ref can be taken */ > > > /* > > > * Clock will be gated because: > > > * .leave_on is False, so (ref == 0) > > > > Again, .leave_on does nothing new here. We gate the clock because the > > reference count is 0. > > It's the fact that .leave_on has been disabled in > clk_disable_critical() that allows the final reference to be taken. > > > > */ > > > > > > Resume: > > > /* Order is unimportant */ > > > SPI enables Clock 4 (ref == 1) > > > RAM enables Clock 4 and re-enables .leave_on (ref == 2) > > > I2C enables Clock 4 (ref == 3) > > > > Same again. As soon as RAM calls clk_enable_critical the ref count goes > > up. .leave_on does nothing as far as I can tell. The all works because > > of the reference counting, which already exists before this patch > > series. > > So fundamentally you're right in what you say. All you really need to > disable a critical clock is write a knowledgeable driver, which is > intentionally unbalanced i.e. just calls clk_disable(). All this OK, the line above is helpful. What you really want is a formalized hand-off mechanism, whereby the clock is enabled at registration-time and it cannot be turned off until the right driver claims it and decides turning it off is OK (with a priori knowledge that the clock is already enabled). Note that I don't think this implementation can really work in the near future. Today we do not catch unbalanced calls to clk_enable and clk_disable, but I have a patch that catches this and WARNs loudly in my private tree. More on that in the next stanza. What I don't understand is if there is ever a case for a clock consumer driver to ever call clk_enable_critical... I do not think there is. What you're trying to protect against is having the clock disabled BEFORE that "knowledgeable driver" has a chance to enable it. Let me know if I've got that right. The only user of this function in your series is the clk-conf.c stuff, which matches my summary above. > extended API really does is makes the process more official and > ensures that an unintentionally unbalanced driver doesn't bugger up > the running platform. We could also add a new WARN() to say that said > driver is unbalanced, as it just tried to turn off a critical clock. As I mentioned up above I am working on this right now. Our per-user struct clk stuff makes it trivial to track prepare_count and enable_count values on a per-user basis. Consequently a naive approach that simply calls clk_disable an extra time will not work once this code is merged. This is because the struct clk used in clk-conf.c and in your knowledgeable driver will be two distinct instances. Regards, Mike > > What do you think is best? > > -- > Lee Jones > Linaro STMicroelectronics Landing Team Lead > Linaro.org ? Open source software for ARM SoCs > Follow Linaro: Facebook | Twitter | Blog From mboxrd@z Thu Jan 1 00:00:00 1970 From: Michael Turquette Subject: Re: [PATCH v7 3/5] clk: Supply the critical clock {init, enable, disable} framework Date: Thu, 30 Jul 2015 15:47:20 -0700 Message-ID: <20150730224720.23791.6722@quantum> References: <1437570255-21049-1-git-send-email-lee.jones@linaro.org> <1437570255-21049-4-git-send-email-lee.jones@linaro.org> <20150727072549.GP2564@lukather> <20150727085338.GW3436@x1> <20150728114022.GW2564@lukather> <20150728130055.GV14943@x1> <20150730011932.642.85168@quantum> <20150730095014.GD14642@x1> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: In-Reply-To: <20150730095014.GD14642@x1> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=m.gmane.org@lists.infradead.org To: Lee Jones Cc: devicetree@vger.kernel.org, kernel@stlinux.com, s.hauer@pengutronix.de, sboyd@codeaurora.org, linux-kernel@vger.kernel.org, geert@linux-m68k.org, Maxime Ripard , linux-arm-kernel@lists.infradead.org List-Id: devicetree@vger.kernel.org UXVvdGluZyBMZWUgSm9uZXMgKDIwMTUtMDctMzAgMDI6NTA6MTQpCj4gT24gV2VkLCAyOSBKdWwg MjAxNSwgTWljaGFlbCBUdXJxdWV0dGUgd3JvdGU6Cj4gPiBRdW90aW5nIExlZSBKb25lcyAoMjAx NS0wNy0yOCAwNjowMDo1NSkKPiA+ID4gT24gVHVlLCAyOCBKdWwgMjAxNSwgTWF4aW1lIFJpcGFy ZCB3cm90ZToKPiA+ID4gCj4gPiA+ID4gT24gTW9uLCBKdWwgMjcsIDIwMTUgYXQgMDk6NTM6MzhB TSArMDEwMCwgTGVlIEpvbmVzIHdyb3RlOgo+ID4gPiA+ID4gT24gTW9uLCAyNyBKdWwgMjAxNSwg TWF4aW1lIFJpcGFyZCB3cm90ZToKPiA+ID4gPiA+IAo+ID4gPiA+ID4gPiBPbiBXZWQsIEp1bCAy MiwgMjAxNSBhdCAwMjowNDoxM1BNICswMTAwLCBMZWUgSm9uZXMgd3JvdGU6Cj4gPiA+ID4gPiA+ ID4gVGhlc2UgbmV3IEFQSSBjYWxscyB3aWxsIGZpcnN0bHkgcHJvdmlkZSBhIG1lY2hhbmlzbXMg dG8gdGFnIGEgY2xvY2sgYXMKPiA+ID4gPiA+ID4gPiBjcml0aWNhbCBhbmQgc2Vjb25kbHkgYWxs b3cgYW55IGtub3dsZWRnZWFibGUgZHJpdmVyIHRvICh1bilnYXRlIGNsb2NrcywKPiA+ID4gPiA+ ID4gPiBldmVuIGlmIHRoZXkgYXJlIG1hcmtlZCBhcyBjcml0aWNhbC4KPiA+ID4gPiA+ID4gPiAK PiA+ID4gPiA+ID4gPiBTdWdnZXN0ZWQtYnk6IE1heGltZSBSaXBhcmQgPG1heGltZS5yaXBhcmRA ZnJlZS1lbGVjdHJvbnMuY29tPgo+ID4gPiA+ID4gPiA+IFNpZ25lZC1vZmYtYnk6IExlZSBKb25l cyA8bGVlLmpvbmVzQGxpbmFyby5vcmc+Cj4gPiA+ID4gPiA+ID4gLS0tCj4gPiA+ID4gPiA+ID4g IGRyaXZlcnMvY2xrL2Nsay5jICAgICAgICAgICAgfCA0NSArKysrKysrKysrKysrKysrKysrKysr KysrKysrKysrKysrKysrKysrKysrKwo+ID4gPiA+ID4gPiA+ICBpbmNsdWRlL2xpbnV4L2Nsay1w cm92aWRlci5oIHwgIDIgKysKPiA+ID4gPiA+ID4gPiAgaW5jbHVkZS9saW51eC9jbGsuaCAgICAg ICAgICB8IDMwICsrKysrKysrKysrKysrKysrKysrKysrKysrKysrCj4gPiA+ID4gPiA+ID4gIDMg ZmlsZXMgY2hhbmdlZCwgNzcgaW5zZXJ0aW9ucygrKQo+ID4gPiA+ID4gPiA+IAo+ID4gPiA+ID4g PiA+IGRpZmYgLS1naXQgYS9kcml2ZXJzL2Nsay9jbGsuYyBiL2RyaXZlcnMvY2xrL2Nsay5jCj4g PiA+ID4gPiA+ID4gaW5kZXggNjFjM2ZjNS4uNDg2YjFkYSAxMDA2NDQKPiA+ID4gPiA+ID4gPiAt LS0gYS9kcml2ZXJzL2Nsay9jbGsuYwo+ID4gPiA+ID4gPiA+ICsrKyBiL2RyaXZlcnMvY2xrL2Ns ay5jCj4gPiA+ID4gPiA+ID4gQEAgLTQ2LDYgKzQ2LDIxIEBAIHN0YXRpYyBzdHJ1Y3QgY2xrX2Nv cmUgKmNsa19jb3JlX2xvb2t1cChjb25zdCBjaGFyICpuYW1lKTsKPiA+ID4gPiA+ID4gPiAgCj4g PiA+ID4gPiA+ID4gIC8qKiogICAgcHJpdmF0ZSBkYXRhIHN0cnVjdHVyZXMgICAgKioqLwo+ID4g PiA+ID4gPiA+ICAKPiA+ID4gPiA+ID4gPiArLyoqCj4gPiA+ID4gPiA+ID4gKyAqIHN0cnVjdCBj cml0aWNhbCAtICAgUHJvdmlkZXMgJ3BsYXknIG92ZXIgY3JpdGljYWwgY2xvY2tzLiAgQSBjbG9j ayBjYW4gYmUKPiA+ID4gPiA+ID4gPiArICogICAgICAgICAgICAgICAgICAgICBtYXJrZWQgYXMg Y3JpdGljYWwsIG1lYW5pbmcgdGhhdCBpdCBzaG91bGQgbm90IGJlCj4gPiA+ID4gPiA+ID4gKyAq ICAgICAgICAgICAgICAgICAgICAgZGlzYWJsZWQuICBIb3dldmVyLCBpZiBhIGRyaXZlciB3aGlj aCBpcyBhd2FyZSBvZiB0aGUKPiA+ID4gPiA+ID4gPiArICogICAgICAgICAgICAgICAgICAgICBj cml0aWNhbCBiZWhhdmlvdXIgd2FudHMgdG8gY29udHJvbCBpdCwgaXQgY2FuIGRvIHNvCj4gPiA+ ID4gPiA+ID4gKyAqICAgICAgICAgICAgICAgICAgICAgdXNpbmcgY2xrX2VuYWJsZV9jcml0aWNh bCgpIGFuZCBjbGtfZGlzYWJsZV9jcml0aWNhbCgpLgo+ID4gPiA+ID4gPiA+ICsgKgo+ID4gPiA+ ID4gPiA+ICsgKiBAZW5hYmxlZCAgICBJcyBjbG9jayBjcml0aWNhbD8gIE9uY2Ugc2V0LCBkb2Vz bid0IGNoYW5nZQo+ID4gPiA+ID4gPiA+ICsgKiBAbGVhdmVfb24gICBTZWxmIGV4cGxhbmF0b3J5 LiAgQ2FuIGJlIGRpc2FibGVkIGJ5IGtub3dsZWRnZWFibGUgZHJpdmVycwo+ID4gPiA+ID4gPiA+ ICsgKi8KPiA+ID4gPiA+ID4gPiArc3RydWN0IGNyaXRpY2FsIHsKPiA+ID4gPiA+ID4gPiArICAg ICAgIGJvb2wgZW5hYmxlZDsKPiA+ID4gPiA+ID4gPiArICAgICAgIGJvb2wgbGVhdmVfb247Cj4g PiA+ID4gPiA+ID4gK307Cj4gPiA+ID4gPiA+ID4gKwo+ID4gPiA+ID4gPiA+ICBzdHJ1Y3QgY2xr X2NvcmUgewo+ID4gPiA+ID4gPiA+ICAgICAgICAgY29uc3QgY2hhciAgICAgICAgICAgICAgKm5h bWU7Cj4gPiA+ID4gPiA+ID4gICAgICAgICBjb25zdCBzdHJ1Y3QgY2xrX29wcyAgICAqb3BzOwo+ ID4gPiA+ID4gPiA+IEBAIC03NSw2ICs5MCw3IEBAIHN0cnVjdCBjbGtfY29yZSB7Cj4gPiA+ID4g PiA+ID4gICAgICAgICBzdHJ1Y3QgZGVudHJ5ICAgICAgICAgICAqZGVudHJ5Owo+ID4gPiA+ID4g PiA+ICAjZW5kaWYKPiA+ID4gPiA+ID4gPiAgICAgICAgIHN0cnVjdCBrcmVmICAgICAgICAgICAg IHJlZjsKPiA+ID4gPiA+ID4gPiArICAgICAgIHN0cnVjdCBjcml0aWNhbCAgICAgICAgIGNyaXRp Y2FsOwo+ID4gPiA+ID4gPiA+ICB9Owo+ID4gPiA+ID4gPiA+ICAKPiA+ID4gPiA+ID4gPiAgc3Ry dWN0IGNsayB7Cj4gPiA+ID4gPiA+ID4gQEAgLTk5NSw2ICsxMDExLDEwIEBAIHN0YXRpYyB2b2lk IGNsa19jb3JlX2Rpc2FibGUoc3RydWN0IGNsa19jb3JlICpjbGspCj4gPiA+ID4gPiA+ID4gICAg ICAgICBpZiAoV0FSTl9PTihjbGstPmVuYWJsZV9jb3VudCA9PSAwKSkKPiA+ID4gPiA+ID4gPiAg ICAgICAgICAgICAgICAgcmV0dXJuOwo+ID4gPiA+ID4gPiA+ICAKPiA+ID4gPiA+ID4gPiArICAg ICAgIC8qIFJlZnVzZSB0byB0dXJuIG9mZiBhIGNyaXRpY2FsIGNsb2NrICovCj4gPiA+ID4gPiA+ ID4gKyAgICAgICBpZiAoY2xrLT5lbmFibGVfY291bnQgPT0gMSAmJiBjbGstPmNyaXRpY2FsLmxl YXZlX29uKQo+ID4gPiA+ID4gPiA+ICsgICAgICAgICAgICAgICByZXR1cm47Cj4gPiA+ID4gPiA+ ID4gKwo+ID4gPiA+ID4gPiAKPiA+ID4gPiA+ID4gSSB0aGluayBpdCBzaG91bGQgYmUgaGFuZGxl ZCBieSBhIHNlcGFyYXRlIGNvdW50aW5nLiBPdGhlcndpc2UsIGlmIHlvdQo+ID4gPiA+ID4gPiBo YXZlIHR3byB1c2VycyB0aGF0IG1hcmtlZCB0aGUgY2xvY2sgYXMgY3JpdGljYWwsIGFuZCB0aGVu IG9uZSBvZiB0aGVtCj4gPiA+ID4gPiA+IGRpc2FibGUgaXQuLi4KPiA+ID4gPiA+ID4gCj4gPiA+ ID4gPiA+ID4gICAgICAgICBpZiAoLS1jbGstPmVuYWJsZV9jb3VudCA+IDApCj4gPiA+ID4gPiA+ ID4gICAgICAgICAgICAgICAgIHJldHVybjsKPiA+ID4gPiA+ID4gPiAgCj4gPiA+ID4gPiA+ID4g QEAgLTEwMzcsNiArMTA1NywxMyBAQCB2b2lkIGNsa19kaXNhYmxlKHN0cnVjdCBjbGsgKmNsaykK PiA+ID4gPiA+ID4gPiAgfQo+ID4gPiA+ID4gPiA+ICBFWFBPUlRfU1lNQk9MX0dQTChjbGtfZGlz YWJsZSk7Cj4gPiA+ID4gPiA+ID4gIAo+ID4gPiA+ID4gPiA+ICt2b2lkIGNsa19kaXNhYmxlX2Ny aXRpY2FsKHN0cnVjdCBjbGsgKmNsaykKPiA+ID4gPiA+ID4gPiArewo+ID4gPiA+ID4gPiA+ICsg ICAgICAgY2xrLT5jb3JlLT5jcml0aWNhbC5sZWF2ZV9vbiA9IGZhbHNlOwo+ID4gPiA+ID4gPiAK PiA+ID4gPiA+ID4gLi4geW91IGp1c3QgbG9zdCB0aGUgZmFjdCB0aGF0IGl0IHdhcyBjcml0aWNh bCBpbiB0aGUgZmlyc3QgcGxhY2UuCj4gPiA+ID4gPiAKPiA+ID4gPiA+IEkgdGhvdWdodCBhYm91 dCBib3RoIG9mIHRoZXNlIHBvaW50cywgd2hpY2ggaXMgd2h5IEkgY2FtZSB1cCB3aXRoIHRoaXMK PiA+ID4gPiA+IHN0cmF0ZWd5Lgo+ID4gPiA+ID4gCj4gPiA+ID4gPiBBbnkgZGV2aWNlIHdoaWNo IHVzZXMgdGhlICpfY3JpdGljYWwoKSBBUEkgc2hvdWxkIGEpIGhhdmUga25vd2xlZGdlIG9mCj4g PiA+ID4gPiB3aGF0IGhhcHBlbnMgd2hlbiBhIHBhcnRpY3VsYXIgY3JpdGljYWwgY2xvY2sgaXMg Z2F0ZWQgYW5kIGIpIGhhdmUKPiA+ID4gPiA+IHRob3VnaHQgYWJvdXQgdGhlIGNvbnNlcXVlbmNl cy4KPiA+ID4gPiAKPiA+ID4gPiBJbmRlZWQuCj4gPiA+ID4gCj4gPiA+ID4gPiBJIGRvbid0IHRo aW5rIHdlIGNhbiB1c2UgcmVmZXJlbmNlIGNvdW50aW5nLCBiZWNhdXNlIHdlJ2QgbmVlZCBhcwo+ ID4gPiA+ID4gbWFueSBjcml0aWNhbCBjbG9jayBvd25lcnMgYXMgdGhlcmUgYXJlIGNyaXRpY2Fs IGNsb2Nrcy4KPiA+ID4gPiAKPiA+ID4gPiBXaGljaCB3ZSBjYW4gaGF2ZSBpZiB3ZSByZXBsYWNl IHRoZSBjYWxsIHRvIGNsa19wcmVwYXJlX2VuYWJsZSB5b3UgYWRkCj4gPiA+ID4gaW4geW91ciBm b3VydGggcGF0Y2ggaW4gX19zZXRfY3JpdGljYWxfY2xvY2tzLgo+ID4gPiAKPiA+ID4gV2hhdCBz aG91bGQgaXQgYmUgcmVwbGFjZWQgd2l0aD8KPiA+ID4gCj4gPiA+ID4gPiBDYXN0IHlvdXIgbWlu ZCBiYWNrIHRvIHRoZSByZWFzb25zIGZvciB0aGlzIGNyaXRpY2FsIGNsb2NrIEFQSS4gIE9uZQo+ ID4gPiA+ID4gb2YgdGhlIG1vc3QgaW1wb3J0YW50IGludGVudGlvbnMgb2YgdGhpcyBBUEkgaXMg dGhlIHJlcXVpcmVtZW50Cj4gPiA+ID4gPiBtaXRpZ2F0aW9uIGZvciBlYWNoIG9mIHRoZSBjcml0 aWNhbCBjbG9ja3MgdG8gaGF2ZSBhbiBvd25lcgo+ID4gPiA+ID4gKGRyaXZlcikuCj4gPiA+ID4g PiAKPiA+ID4gPiA+IFdpdGggcmVnYXJkcyB0byB5b3VyIHNlY29uZCBwb2ludCwgdGhhdCdzIHdo YXQgJ2NyaXRpY2FsLmVuYWJsZWQnCj4gPiA+ID4gPiBpcyBmb3IuICBUYWtlIGEgbG9vayBhdCBj bGtfZW5hYmxlX2NyaXRpY2FsKCkuCj4gPiA+ID4gCj4gPiA+ID4gSSBkb24ndCB0aGluayB0aGlz IGFkZHJlc3NlcyB0aGUgaXNzdWUsIGlmIHlvdSBqdXN0IHRocm93IG1vcmUKPiA+ID4gPiBjdXN0 b21lcnMgYXQgaXQsIHRoZSBpc3N1ZSByZW1haW4gd2l0aCB5b3VyIGltcGxlbWVudGF0aW9uLgo+ ID4gPiA+IAo+ID4gPiA+IElmIHlvdSBoYXZlIHRocmVlIGN1c3RvbWVycyB0aGF0IHVzZWQgdGhl IGNyaXRpY2FsIEFQSSwgYW5kIGlmIG9uIG9mCj4gPiA+ID4gdGhlc2UgY2FsbHMgY2xrX2Rpc2Fi bGVfY3JpdGljYWwsIHlvdSdyZSBsb3NpbmcgbGVhdmVfb24uCj4gPiA+IAo+ID4gPiBUaGF0J3Mg dGhlIGlkZWEuICBTZWUgbXkgcG9pbnQgYWJvdmUsIHRoZSBvbmUgeW91IHJlcGxpZWQgIkluZGVl ZCIKPiA+ID4gdG8uICBTbyB3aGVuIGEgZHJpdmVyIHVzZXMgY2xrX2Rpc2FibGVfY3JpdGljYWwo KSBpdCdzIHNheWluZywgIkkga25vdwo+ID4gPiB3aHkgdGhpcyBjbG9jayBpcyBhIGNyaXRpY2Fs IGNsb2NrLCBhbmQgSSBrbm93IHRoYXQgbm90aGluZyB0ZXJyaWJsZQo+ID4gPiB3aWxsIGhhcHBl biBpZiBJIGRpc2FibGUgaXQsIGFzIEkgaGF2ZSB0aGF0IGNvdmVyZWQiLiAgU28gdGhlbiBpZiBp dCdzCj4gPiA+IG5vdCB0aGUgbGFzdCB1c2VyIHRvIGNhbGwgY2xrX2Rpc2FibGUoKSwgdGhlIGxh c3Qgb25lIG91dCB0aGUgZG9vcgo+ID4gPiB3aWxsIGJlIGFsbG93ZWQgdG8gZmluYWxseSBnYXRl IHRoZSBjbG9jaywgcmVnYXJkbGVzcyB3aGV0aGVyIGl0J3MKPiA+ID4gY3JpdGljYWwgYXdhcmUg b3Igbm90Lgo+ID4gPiAKPiA+ID4gVGhlbiwgd2hlbiB3ZSBjb21lIHRvIGVuYWJsZSB0aGUgY2xv Y2sgYWdhaW4sIHRoZSBjcml0aWNhbCBhd2FyZSB1c2VyCj4gPiA+IHRoZW4gcmUtbWFya3MgdGhl IGNsb2NrIGFzIGxlYXZlX29uLCBzbyBub3QgY3JpdGljYWwgdW4tYXdhcmUgdXNlciBjYW4KPiA+ ID4gdGFrZSB0aGUgZmluYWwgcmVmZXJlbmNlIGFuZCBkaXNhYmxlIHRoZSBjbG9jay4KPiA+ID4g Cj4gPiA+ID4gV2hpY2ggbWVhbnMgdGhhdCBpZiB0aGVyZSdzIG9uZSBvZiB0aGUgdHdvIHVzZXJz IGxlZnQgdGhhdCBjYWxscwo+ID4gPiA+IGNsa19kaXNhYmxlIG9uIGl0LCB0aGUgY2xvY2sgd2ls bCBhY3R1YWxseSBiZSBkaXNhYmxlZCwgd2hpY2ggaXMKPiA+ID4gPiBjbGVhcmx5IG5vdCB3aGF0 IHdlIHdhbnQgdG8gZG8sIGFzIHdlIGhhdmUgc3RpbGwgYSB1c2VyIHRoYXQgd2FudCB0aGUKPiA+ ID4gPiBjbG9jayB0byBiZSBlbmFibGVkLgo+ID4gPiAKPiA+ID4gVGhhdCdzIG5vdCB3aGF0IGhh cHBlbnMgKGF0IGxlYXN0IGl0IHNob3VsZG4ndCBpZiBJJ3ZlIGNvZGVkIGl0IHVwCj4gPiA+IHJp Z2h0KS4gIFRoZSBBUEkgX3N0aWxsXyByZXF1aXJlcyBhbGwgb2YgdGhlIHVzZXJzIHRvIGdpdmUt dXAgdGhlaXIKPiA+ID4gcmVmZXJlbmNlLgo+ID4gPiAKPiA+ID4gPiBJdCB3b3VsZCBiZSBtdWNo IG1vcmUgcm9idXN0IHRvIGhhdmUgYW5vdGhlciBjb3VudCBmb3IgdGhlIGNyaXRpY2FsCj4gPiA+ ID4gc3R1ZmYsIGluaXRpYWxpc2VkIHRvIG9uZSBieSB0aGUgX19zZXRfY3JpdGljYWxfY2xvY2tz IGZ1bmN0aW9uLgo+ID4gPiAKPiA+ID4gSWYgSSB1bmRlcnN0YW5kIHlvdSBjb3JyZWN0bHksIHdl IGFscmVhZHkgaGF2ZSBhIGNvdW50LiAgV2UgdXNlIHRoZQo+ID4gPiBvcmlnaW5hbCByZWZlcmVu Y2UgY291bnQuICBObyBuZWVkIGZvciBvbmUgb2Ygb3VyIG93bi4KPiA+ID4gCj4gPiA+IFVzaW5n IHlvdXIgUkFNIENsb2NrIChDbG9jayA0KSBhcyBhbiBleGFtcGxlCj4gPiA+IC0tLS0tLS0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tCj4gPiA+IAo+ID4gPiBFYXJseSBzdGFy dC11cDoKPiA+ID4gICBDbG9jayA0IGlzIG1hcmtlZCBhcyBjcml0aWNhbCBhbmQgYSByZWZlcmVu Y2UgaXMgdGFrZW4gKHJlZiA9PSAxKQo+ID4gPiAKPiA+ID4gRHJpdmVyIHByb2JlOgo+ID4gPiAg IFNQSSBlbmFibGVzIENsb2NrIDQgKHJlZiA9PSAyKQo+ID4gPiAgIEkyQyBlbmFibGVzIENsb2Nr IDQgKHJlZiA9PSAzKQo+ID4gPiAKPiA+ID4gU3VzcGVuZCAod2l0aG91dCBSQU0gZHJpdmVyJ3Mg cGVybWlzc2lvbik6Cj4gPiA+ICAgU1BJIGRpc2FibGVzIENsb2NrIDQgKHJlZiA9PSAyKQo+ID4g PiAgIEkyQyBkaXNhYmxlcyBDbG9jayA0IChyZWYgPT0gMSkKPiA+ID4gICAvKgo+ID4gPiAgICAq IENsb2NrIHdvbid0IGJlIGdhdGVkIGJlY2F1c2U6Cj4gPiA+ICAgICogICAubGVhdmVfb24gaXMg VHJ1ZSAtIGNhbid0IGRlYyBmaW5hbCByZWZlcmVuY2UKPiA+IAo+ID4gSSBhbSBjbGVhcmx5IG1p c3NpbmcgdGhlIHBvaW50LiBUaGUgY2xvY2sgd29uJ3QgYmUgZ2F0ZWQgYmVjYXVzZSB0aGUKPiA+ IGVuYWJsZV9jb3VudCBpcyBzdGlsbCAxISBXaGF0IGRvZXMgLmxlYXZlX29uIGRvIGhlcmU/Cj4g Cj4gVGhlIHBvaW50IG9mIF90aGlzXyAodGhlIGV4dGVuZGVkKSBwYXJ0IG9mIHRoZSBBUEkgaXMg c28gdGhhdCB0aGUKPiBjbG9jayBfY2FuXyBiZSB0dXJuZWQgb2ZmLiAgV2l0aG91dCB0aGUgcG9z c2liaWxpdHkgdG8gZGlzYWJsZQo+IC5sZWF2ZV9vbiBhbmQgdGhlIGxvZ2ljIHdpdGggYWNjb21w YW5pZXMgaXQgKGkuZS4KPiBjbGtfZGlzYWJsZV9jcml0aWNhbCgpKSB0aGUgY2xvY2sgd2lsbCBf bmV2ZXJfIGJlIGdhdGVkLgo+IAo+ID4gPiAgICAqLwo+ID4gPiAKPiA+ID4gU3VzcGVuZCAod2l0 aCBSQU0gZHJpdmVyJ3MgcGVybWlzc2lvbik6Cj4gPiA+ICAgLyogT3JkZXIgaXMgdW5pbXBvcnRh bnQgKi8KPiA+ID4gICBTUEkgZGlzYWJsZXMgQ2xvY2sgNCAocmVmID09IDIpCj4gPiA+ICAgUkFN IGRpc2FibGVzIENsb2NrIDQgKHJlZiA9PSAxKSAvKiBXb24ndCB0dXJuIG9mZiBoZXJlIChyZWYg PiAwKQo+ID4gPiAgIEkyQyBkaXNhYmxlcyBDbG9jayA0IChyZWYgPT0gMCkgLyogKC5sZWF2ZV9v biA9PSBGYWxzZSkgbGFzdCByZWYgY2FuIGJlIHRha2VuICovCj4gPiA+ICAgLyoKPiA+ID4gICAg KiBDbG9jayB3aWxsIGJlIGdhdGVkIGJlY2F1c2U6Cj4gPiA+ICAgICogICAubGVhdmVfb24gaXMg RmFsc2UsIHNvIChyZWYgPT0gMCkKPiA+IAo+ID4gQWdhaW4sIC5sZWF2ZV9vbiBkb2VzIG5vdGhp bmcgbmV3IGhlcmUuIFdlIGdhdGUgdGhlIGNsb2NrIGJlY2F1c2UgdGhlCj4gPiByZWZlcmVuY2Ug Y291bnQgaXMgMC4KPiAKPiBJdCdzIHRoZSBmYWN0IHRoYXQgLmxlYXZlX29uIGhhcyBiZWVuIGRp c2FibGVkIGluCj4gY2xrX2Rpc2FibGVfY3JpdGljYWwoKSB0aGF0IGFsbG93cyB0aGUgZmluYWwg cmVmZXJlbmNlIHRvIGJlIHRha2VuLgo+IAo+ID4gPiAgICAqLwo+ID4gPiAKPiA+ID4gUmVzdW1l Ogo+ID4gPiAgIC8qIE9yZGVyIGlzIHVuaW1wb3J0YW50ICovCj4gPiA+ICAgU1BJIGVuYWJsZXMg Q2xvY2sgNCAocmVmID09IDEpCj4gPiA+ICAgUkFNIGVuYWJsZXMgQ2xvY2sgNCBhbmQgcmUtZW5h YmxlcyAubGVhdmVfb24gKHJlZiA9PSAyKQo+ID4gPiAgIEkyQyBlbmFibGVzIENsb2NrIDQgKHJl ZiA9PSAzKQo+ID4gCj4gPiBTYW1lIGFnYWluLiBBcyBzb29uIGFzIFJBTSBjYWxscyBjbGtfZW5h YmxlX2NyaXRpY2FsIHRoZSByZWYgY291bnQgZ29lcwo+ID4gdXAuIC5sZWF2ZV9vbiBkb2VzIG5v dGhpbmcgYXMgZmFyIGFzIEkgY2FuIHRlbGwuIFRoZSBhbGwgd29ya3MgYmVjYXVzZQo+ID4gb2Yg dGhlIHJlZmVyZW5jZSBjb3VudGluZywgd2hpY2ggYWxyZWFkeSBleGlzdHMgYmVmb3JlIHRoaXMg cGF0Y2gKPiA+IHNlcmllcy4KPiAKPiBTbyBmdW5kYW1lbnRhbGx5IHlvdSdyZSByaWdodCBpbiB3 aGF0IHlvdSBzYXkuICBBbGwgeW91IHJlYWxseSBuZWVkIHRvCj4gZGlzYWJsZSBhIGNyaXRpY2Fs IGNsb2NrIGlzIHdyaXRlIGEga25vd2xlZGdlYWJsZSBkcml2ZXIsIHdoaWNoIGlzCj4gaW50ZW50 aW9uYWxseSB1bmJhbGFuY2VkIGkuZS4ganVzdCBjYWxscyBjbGtfZGlzYWJsZSgpLiAgQWxsIHRo aXMKCk9LLCB0aGUgbGluZSBhYm92ZSBpcyBoZWxwZnVsLiBXaGF0IHlvdSByZWFsbHkgd2FudCBp cyBhIGZvcm1hbGl6ZWQKaGFuZC1vZmYgbWVjaGFuaXNtLCB3aGVyZWJ5IHRoZSBjbG9jayBpcyBl bmFibGVkIGF0IHJlZ2lzdHJhdGlvbi10aW1lCmFuZCBpdCBjYW5ub3QgYmUgdHVybmVkIG9mZiB1 bnRpbCB0aGUgcmlnaHQgZHJpdmVyIGNsYWltcyBpdCBhbmQgZGVjaWRlcwp0dXJuaW5nIGl0IG9m ZiBpcyBPSyAod2l0aCBhIHByaW9yaSBrbm93bGVkZ2UgdGhhdCB0aGUgY2xvY2sgaXMgYWxyZWFk eQplbmFibGVkKS4KCk5vdGUgdGhhdCBJIGRvbid0IHRoaW5rIHRoaXMgaW1wbGVtZW50YXRpb24g Y2FuIHJlYWxseSB3b3JrIGluIHRoZSBuZWFyCmZ1dHVyZS4gVG9kYXkgd2UgZG8gbm90IGNhdGNo IHVuYmFsYW5jZWQgY2FsbHMgdG8gY2xrX2VuYWJsZSBhbmQKY2xrX2Rpc2FibGUsIGJ1dCBJIGhh dmUgYSBwYXRjaCB0aGF0IGNhdGNoZXMgdGhpcyBhbmQgV0FSTnMgbG91ZGx5IGluIG15CnByaXZh dGUgdHJlZS4gTW9yZSBvbiB0aGF0IGluIHRoZSBuZXh0IHN0YW56YS4KCldoYXQgSSBkb24ndCB1 bmRlcnN0YW5kIGlzIGlmIHRoZXJlIGlzIGV2ZXIgYSBjYXNlIGZvciBhIGNsb2NrIGNvbnN1bWVy CmRyaXZlciB0byBldmVyIGNhbGwgY2xrX2VuYWJsZV9jcml0aWNhbC4uLiBJIGRvIG5vdCB0aGlu ayB0aGVyZSBpcy4gV2hhdAp5b3UncmUgdHJ5aW5nIHRvIHByb3RlY3QgYWdhaW5zdCBpcyBoYXZp bmcgdGhlIGNsb2NrIGRpc2FibGVkIEJFRk9SRQp0aGF0ICJrbm93bGVkZ2VhYmxlIGRyaXZlciIg aGFzIGEgY2hhbmNlIHRvIGVuYWJsZSBpdC4KCkxldCBtZSBrbm93IGlmIEkndmUgZ290IHRoYXQg cmlnaHQuIFRoZSBvbmx5IHVzZXIgb2YgdGhpcyBmdW5jdGlvbiBpbgp5b3VyIHNlcmllcyBpcyB0 aGUgY2xrLWNvbmYuYyBzdHVmZiwgd2hpY2ggbWF0Y2hlcyBteSBzdW1tYXJ5IGFib3ZlLgoKPiBl eHRlbmRlZCBBUEkgcmVhbGx5IGRvZXMgaXMgbWFrZXMgdGhlIHByb2Nlc3MgbW9yZSBvZmZpY2lh bCBhbmQKPiBlbnN1cmVzIHRoYXQgYW4gdW5pbnRlbnRpb25hbGx5IHVuYmFsYW5jZWQgZHJpdmVy IGRvZXNuJ3QgYnVnZ2VyIHVwCj4gdGhlIHJ1bm5pbmcgcGxhdGZvcm0uICBXZSBjb3VsZCBhbHNv IGFkZCBhIG5ldyBXQVJOKCkgdG8gc2F5IHRoYXQgc2FpZAo+IGRyaXZlciBpcyB1bmJhbGFuY2Vk LCBhcyBpdCBqdXN0IHRyaWVkIHRvIHR1cm4gb2ZmIGEgY3JpdGljYWwgY2xvY2suCgpBcyBJIG1l bnRpb25lZCB1cCBhYm92ZSBJIGFtIHdvcmtpbmcgb24gdGhpcyByaWdodCBub3cuIE91ciBwZXIt dXNlcgpzdHJ1Y3QgY2xrIHN0dWZmIG1ha2VzIGl0IHRyaXZpYWwgdG8gdHJhY2sgcHJlcGFyZV9j b3VudCBhbmQKZW5hYmxlX2NvdW50IHZhbHVlcyBvbiBhIHBlci11c2VyIGJhc2lzLiBDb25zZXF1 ZW50bHkgYSBuYWl2ZSBhcHByb2FjaAp0aGF0IHNpbXBseSBjYWxscyBjbGtfZGlzYWJsZSBhbiBl eHRyYSB0aW1lIHdpbGwgbm90IHdvcmsgb25jZSB0aGlzIGNvZGUKaXMgbWVyZ2VkLiBUaGlzIGlz IGJlY2F1c2UgdGhlIHN0cnVjdCBjbGsgdXNlZCBpbiBjbGstY29uZi5jIGFuZCBpbiB5b3VyCmtu b3dsZWRnZWFibGUgZHJpdmVyIHdpbGwgYmUgdHdvIGRpc3RpbmN0IGluc3RhbmNlcy4KClJlZ2Fy ZHMsCk1pa2UKCj4gCj4gV2hhdCBkbyB5b3UgdGhpbmsgaXMgYmVzdD8KPiAKPiAtLSAKPiBMZWUg Sm9uZXMKPiBMaW5hcm8gU1RNaWNyb2VsZWN0cm9uaWNzIExhbmRpbmcgVGVhbSBMZWFkCj4gTGlu YXJvLm9yZyDilIIgT3BlbiBzb3VyY2Ugc29mdHdhcmUgZm9yIEFSTSBTb0NzCj4gRm9sbG93IExp bmFybzogRmFjZWJvb2sgfCBUd2l0dGVyIHwgQmxvZwoKX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX18KbGludXgtYXJtLWtlcm5lbCBtYWlsaW5nIGxpc3QKbGlu dXgtYXJtLWtlcm5lbEBsaXN0cy5pbmZyYWRlYWQub3JnCmh0dHA6Ly9saXN0cy5pbmZyYWRlYWQu b3JnL21haWxtYW4vbGlzdGluZm8vbGludXgtYXJtLWtlcm5lbAo=