From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751642AbeDEN1k (ORCPT ); Thu, 5 Apr 2018 09:27:40 -0400 Received: from mail-wr0-f193.google.com ([209.85.128.193]:36704 "EHLO mail-wr0-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751277AbeDEN1i (ORCPT ); Thu, 5 Apr 2018 09:27:38 -0400 X-Google-Smtp-Source: AIpwx49ky3Kp0ztTWGAf/HLrl8VDSe+nGHxIII6CwrLQLcXyvD59L+j/Ww4c+/5deTFnigRPtyDJM4sWbkCGWYHkpYs= MIME-Version: 1.0 In-Reply-To: References: <20180404223251.28449-1-eric@anholt.net> From: Alex Deucher Date: Thu, 5 Apr 2018 09:27:36 -0400 Message-ID: Subject: Re: [PATCH] drm/sched: Extend the documentation. To: Daniel Vetter Cc: Eric Anholt , Alex Deucher , =?UTF-8?Q?Christian_K=C3=B6nig?= , dri-devel , Linux Kernel Mailing List Content-Type: text/plain; charset="UTF-8" Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, Apr 5, 2018 at 2:16 AM, Daniel Vetter wrote: > On Thu, Apr 5, 2018 at 12:32 AM, Eric Anholt wrote: >> These comments answer all the questions I had for myself when >> implementing a driver using the GPU scheduler. >> >> Signed-off-by: Eric Anholt > > Pulling all these comments into the generated kerneldoc would be > awesome, maybe as a new "GPU Scheduler" chapter at the end of > drm-mm.rst? Would mean a bit of busywork to convert the existing raw > comments into proper kerneldoc. Also has the benefit that 0day will > complain when you forget to update the comment when editing the > function prototype - kerneldoc which isn't included anywhere in .rst > won't be checked automatically. I was actually planning to do this myself, but Nayan wanted to do this a prep work for his proposed GSoC project so I was going to see how far he got first. Alex > -Daniel > >> --- >> include/drm/gpu_scheduler.h | 46 +++++++++++++++++++++++++++++++++---- >> 1 file changed, 42 insertions(+), 4 deletions(-) >> >> diff --git a/include/drm/gpu_scheduler.h b/include/drm/gpu_scheduler.h >> index dfd54fb94e10..c053a32341bf 100644 >> --- a/include/drm/gpu_scheduler.h >> +++ b/include/drm/gpu_scheduler.h >> @@ -43,10 +43,12 @@ enum drm_sched_priority { >> }; >> >> /** >> - * A scheduler entity is a wrapper around a job queue or a group >> - * of other entities. Entities take turns emitting jobs from their >> - * job queues to corresponding hardware ring based on scheduling >> - * policy. >> + * drm_sched_entity - A wrapper around a job queue (typically attached >> + * to the DRM file_priv). >> + * >> + * Entities will emit jobs in order to their corresponding hardware >> + * ring, and the scheduler will alternate between entities based on >> + * scheduling policy. >> */ >> struct drm_sched_entity { >> struct list_head list; >> @@ -78,7 +80,18 @@ struct drm_sched_rq { >> >> struct drm_sched_fence { >> struct dma_fence scheduled; >> + >> + /* This fence is what will be signaled by the scheduler when >> + * the job is completed. >> + * >> + * When setting up an out fence for the job, you should use >> + * this, since it's available immediately upon >> + * drm_sched_job_init(), and the fence returned by the driver >> + * from run_job() won't be created until the dependencies have >> + * resolved. >> + */ >> struct dma_fence finished; >> + >> struct dma_fence_cb cb; >> struct dma_fence *parent; >> struct drm_gpu_scheduler *sched; >> @@ -88,6 +101,13 @@ struct drm_sched_fence { >> >> struct drm_sched_fence *to_drm_sched_fence(struct dma_fence *f); >> >> +/** >> + * drm_sched_job - A job to be run by an entity. >> + * >> + * A job is created by the driver using drm_sched_job_init(), and >> + * should call drm_sched_entity_push_job() once it wants the scheduler >> + * to schedule the job. >> + */ >> struct drm_sched_job { >> struct spsc_node queue_node; >> struct drm_gpu_scheduler *sched; >> @@ -112,10 +132,28 @@ static inline bool drm_sched_invalidate_job(struct drm_sched_job *s_job, >> * these functions should be implemented in driver side >> */ >> struct drm_sched_backend_ops { >> + /* Called when the scheduler is considering scheduling this >> + * job next, to get another struct dma_fence for this job to >> + * block on. Once it returns NULL, run_job() may be called. >> + */ >> struct dma_fence *(*dependency)(struct drm_sched_job *sched_job, >> struct drm_sched_entity *s_entity); >> + >> + /* Called to execute the job once all of the dependencies have >> + * been resolved. This may be called multiple times, if >> + * timedout_job() has happened and drm_sched_job_recovery() >> + * decides to try it again. >> + */ >> struct dma_fence *(*run_job)(struct drm_sched_job *sched_job); >> + >> + /* Called when a job has taken too long to execute, to trigger >> + * GPU recovery. >> + */ >> void (*timedout_job)(struct drm_sched_job *sched_job); >> + >> + /* Called once the job's finished fence has been signaled and >> + * it's time to clean it up. >> + */ >> void (*free_job)(struct drm_sched_job *sched_job); >> }; >> >> -- >> 2.17.0 >> >> _______________________________________________ >> dri-devel mailing list >> dri-devel@lists.freedesktop.org >> https://lists.freedesktop.org/mailman/listinfo/dri-devel > > > > -- > Daniel Vetter > Software Engineer, Intel Corporation > +41 (0) 79 365 57 48 - http://blog.ffwll.ch > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alex Deucher Subject: Re: [PATCH] drm/sched: Extend the documentation. Date: Thu, 5 Apr 2018 09:27:36 -0400 Message-ID: References: <20180404223251.28449-1-eric@anholt.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-wr0-x241.google.com (mail-wr0-x241.google.com [IPv6:2a00:1450:400c:c0c::241]) by gabe.freedesktop.org (Postfix) with ESMTPS id 91CE56E0F6 for ; Thu, 5 Apr 2018 13:27:38 +0000 (UTC) Received: by mail-wr0-x241.google.com with SMTP id p53so28410025wrc.10 for ; Thu, 05 Apr 2018 06:27:38 -0700 (PDT) In-Reply-To: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Daniel Vetter Cc: Alex Deucher , =?UTF-8?Q?Christian_K=C3=B6nig?= , dri-devel , Linux Kernel Mailing List List-Id: dri-devel@lists.freedesktop.org T24gVGh1LCBBcHIgNSwgMjAxOCBhdCAyOjE2IEFNLCBEYW5pZWwgVmV0dGVyIDxkYW5pZWxAZmZ3 bGwuY2g+IHdyb3RlOgo+IE9uIFRodSwgQXByIDUsIDIwMTggYXQgMTI6MzIgQU0sIEVyaWMgQW5o b2x0IDxlcmljQGFuaG9sdC5uZXQ+IHdyb3RlOgo+PiBUaGVzZSBjb21tZW50cyBhbnN3ZXIgYWxs IHRoZSBxdWVzdGlvbnMgSSBoYWQgZm9yIG15c2VsZiB3aGVuCj4+IGltcGxlbWVudGluZyBhIGRy aXZlciB1c2luZyB0aGUgR1BVIHNjaGVkdWxlci4KPj4KPj4gU2lnbmVkLW9mZi1ieTogRXJpYyBB bmhvbHQgPGVyaWNAYW5ob2x0Lm5ldD4KPgo+IFB1bGxpbmcgYWxsIHRoZXNlIGNvbW1lbnRzIGlu dG8gdGhlIGdlbmVyYXRlZCBrZXJuZWxkb2Mgd291bGQgYmUKPiBhd2Vzb21lLCBtYXliZSBhcyBh IG5ldyAiR1BVIFNjaGVkdWxlciIgY2hhcHRlciBhdCB0aGUgZW5kIG9mCj4gZHJtLW1tLnJzdD8g V291bGQgbWVhbiBhIGJpdCBvZiBidXN5d29yayB0byBjb252ZXJ0IHRoZSBleGlzdGluZyByYXcK PiBjb21tZW50cyBpbnRvIHByb3BlciBrZXJuZWxkb2MuIEFsc28gaGFzIHRoZSBiZW5lZml0IHRo YXQgMGRheSB3aWxsCj4gY29tcGxhaW4gd2hlbiB5b3UgZm9yZ2V0IHRvIHVwZGF0ZSB0aGUgY29t bWVudCB3aGVuIGVkaXRpbmcgdGhlCj4gZnVuY3Rpb24gcHJvdG90eXBlIC0ga2VybmVsZG9jIHdo aWNoIGlzbid0IGluY2x1ZGVkIGFueXdoZXJlIGluIC5yc3QKPiB3b24ndCBiZSBjaGVja2VkIGF1 dG9tYXRpY2FsbHkuCgpJIHdhcyBhY3R1YWxseSBwbGFubmluZyB0byBkbyB0aGlzIG15c2VsZiwg YnV0IE5heWFuIHdhbnRlZCB0byBkbyB0aGlzCmEgcHJlcCB3b3JrIGZvciBoaXMgcHJvcG9zZWQg R1NvQyBwcm9qZWN0IHNvIEkgd2FzIGdvaW5nIHRvIHNlZSBob3cKZmFyIGhlIGdvdCBmaXJzdC4K CkFsZXgKCj4gLURhbmllbAo+Cj4+IC0tLQo+PiAgaW5jbHVkZS9kcm0vZ3B1X3NjaGVkdWxlci5o IHwgNDYgKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrLS0tLQo+PiAgMSBmaWxlIGNo YW5nZWQsIDQyIGluc2VydGlvbnMoKyksIDQgZGVsZXRpb25zKC0pCj4+Cj4+IGRpZmYgLS1naXQg YS9pbmNsdWRlL2RybS9ncHVfc2NoZWR1bGVyLmggYi9pbmNsdWRlL2RybS9ncHVfc2NoZWR1bGVy LmgKPj4gaW5kZXggZGZkNTRmYjk0ZTEwLi5jMDUzYTMyMzQxYmYgMTAwNjQ0Cj4+IC0tLSBhL2lu Y2x1ZGUvZHJtL2dwdV9zY2hlZHVsZXIuaAo+PiArKysgYi9pbmNsdWRlL2RybS9ncHVfc2NoZWR1 bGVyLmgKPj4gQEAgLTQzLDEwICs0MywxMiBAQCBlbnVtIGRybV9zY2hlZF9wcmlvcml0eSB7Cj4+ ICB9Owo+Pgo+PiAgLyoqCj4+IC0gKiBBIHNjaGVkdWxlciBlbnRpdHkgaXMgYSB3cmFwcGVyIGFy b3VuZCBhIGpvYiBxdWV1ZSBvciBhIGdyb3VwCj4+IC0gKiBvZiBvdGhlciBlbnRpdGllcy4gRW50 aXRpZXMgdGFrZSB0dXJucyBlbWl0dGluZyBqb2JzIGZyb20gdGhlaXIKPj4gLSAqIGpvYiBxdWV1 ZXMgdG8gY29ycmVzcG9uZGluZyBoYXJkd2FyZSByaW5nIGJhc2VkIG9uIHNjaGVkdWxpbmcKPj4g LSAqIHBvbGljeS4KPj4gKyAqIGRybV9zY2hlZF9lbnRpdHkgLSBBIHdyYXBwZXIgYXJvdW5kIGEg am9iIHF1ZXVlICh0eXBpY2FsbHkgYXR0YWNoZWQKPj4gKyAqIHRvIHRoZSBEUk0gZmlsZV9wcml2 KS4KPj4gKyAqCj4+ICsgKiBFbnRpdGllcyB3aWxsIGVtaXQgam9icyBpbiBvcmRlciB0byB0aGVp ciBjb3JyZXNwb25kaW5nIGhhcmR3YXJlCj4+ICsgKiByaW5nLCBhbmQgdGhlIHNjaGVkdWxlciB3 aWxsIGFsdGVybmF0ZSBiZXR3ZWVuIGVudGl0aWVzIGJhc2VkIG9uCj4+ICsgKiBzY2hlZHVsaW5n IHBvbGljeS4KPj4gICovCj4+ICBzdHJ1Y3QgZHJtX3NjaGVkX2VudGl0eSB7Cj4+ICAgICAgICAg c3RydWN0IGxpc3RfaGVhZCAgICAgICAgICAgICAgICBsaXN0Owo+PiBAQCAtNzgsNyArODAsMTgg QEAgc3RydWN0IGRybV9zY2hlZF9ycSB7Cj4+Cj4+ICBzdHJ1Y3QgZHJtX3NjaGVkX2ZlbmNlIHsK Pj4gICAgICAgICBzdHJ1Y3QgZG1hX2ZlbmNlICAgICAgICAgICAgICAgIHNjaGVkdWxlZDsKPj4g Kwo+PiArICAgICAgIC8qIFRoaXMgZmVuY2UgaXMgd2hhdCB3aWxsIGJlIHNpZ25hbGVkIGJ5IHRo ZSBzY2hlZHVsZXIgd2hlbgo+PiArICAgICAgICAqIHRoZSBqb2IgaXMgY29tcGxldGVkLgo+PiAr ICAgICAgICAqCj4+ICsgICAgICAgICogV2hlbiBzZXR0aW5nIHVwIGFuIG91dCBmZW5jZSBmb3Ig dGhlIGpvYiwgeW91IHNob3VsZCB1c2UKPj4gKyAgICAgICAgKiB0aGlzLCBzaW5jZSBpdCdzIGF2 YWlsYWJsZSBpbW1lZGlhdGVseSB1cG9uCj4+ICsgICAgICAgICogZHJtX3NjaGVkX2pvYl9pbml0 KCksIGFuZCB0aGUgZmVuY2UgcmV0dXJuZWQgYnkgdGhlIGRyaXZlcgo+PiArICAgICAgICAqIGZy b20gcnVuX2pvYigpIHdvbid0IGJlIGNyZWF0ZWQgdW50aWwgdGhlIGRlcGVuZGVuY2llcyBoYXZl Cj4+ICsgICAgICAgICogcmVzb2x2ZWQuCj4+ICsgICAgICAgICovCj4+ICAgICAgICAgc3RydWN0 IGRtYV9mZW5jZSAgICAgICAgICAgICAgICBmaW5pc2hlZDsKPj4gKwo+PiAgICAgICAgIHN0cnVj dCBkbWFfZmVuY2VfY2IgICAgICAgICAgICAgY2I7Cj4+ICAgICAgICAgc3RydWN0IGRtYV9mZW5j ZSAgICAgICAgICAgICAgICAqcGFyZW50Owo+PiAgICAgICAgIHN0cnVjdCBkcm1fZ3B1X3NjaGVk dWxlciAgICAgICAgKnNjaGVkOwo+PiBAQCAtODgsNiArMTAxLDEzIEBAIHN0cnVjdCBkcm1fc2No ZWRfZmVuY2Ugewo+Pgo+PiAgc3RydWN0IGRybV9zY2hlZF9mZW5jZSAqdG9fZHJtX3NjaGVkX2Zl bmNlKHN0cnVjdCBkbWFfZmVuY2UgKmYpOwo+Pgo+PiArLyoqCj4+ICsgKiBkcm1fc2NoZWRfam9i IC0gQSBqb2IgdG8gYmUgcnVuIGJ5IGFuIGVudGl0eS4KPj4gKyAqCj4+ICsgKiBBIGpvYiBpcyBj cmVhdGVkIGJ5IHRoZSBkcml2ZXIgdXNpbmcgZHJtX3NjaGVkX2pvYl9pbml0KCksIGFuZAo+PiAr ICogc2hvdWxkIGNhbGwgZHJtX3NjaGVkX2VudGl0eV9wdXNoX2pvYigpIG9uY2UgaXQgd2FudHMg dGhlIHNjaGVkdWxlcgo+PiArICogdG8gc2NoZWR1bGUgdGhlIGpvYi4KPj4gKyAqLwo+PiAgc3Ry dWN0IGRybV9zY2hlZF9qb2Igewo+PiAgICAgICAgIHN0cnVjdCBzcHNjX25vZGUgICAgICAgICAg ICAgICAgcXVldWVfbm9kZTsKPj4gICAgICAgICBzdHJ1Y3QgZHJtX2dwdV9zY2hlZHVsZXIgICAg ICAgICpzY2hlZDsKPj4gQEAgLTExMiwxMCArMTMyLDI4IEBAIHN0YXRpYyBpbmxpbmUgYm9vbCBk cm1fc2NoZWRfaW52YWxpZGF0ZV9qb2Ioc3RydWN0IGRybV9zY2hlZF9qb2IgKnNfam9iLAo+PiAg ICogdGhlc2UgZnVuY3Rpb25zIHNob3VsZCBiZSBpbXBsZW1lbnRlZCBpbiBkcml2ZXIgc2lkZQo+ PiAgKi8KPj4gIHN0cnVjdCBkcm1fc2NoZWRfYmFja2VuZF9vcHMgewo+PiArICAgICAgIC8qIENh bGxlZCB3aGVuIHRoZSBzY2hlZHVsZXIgaXMgY29uc2lkZXJpbmcgc2NoZWR1bGluZyB0aGlzCj4+ ICsgICAgICAgICogam9iIG5leHQsIHRvIGdldCBhbm90aGVyIHN0cnVjdCBkbWFfZmVuY2UgZm9y IHRoaXMgam9iIHRvCj4+ICsgICAgICAgICogYmxvY2sgb24uICBPbmNlIGl0IHJldHVybnMgTlVM TCwgcnVuX2pvYigpIG1heSBiZSBjYWxsZWQuCj4+ICsgICAgICAgICovCj4+ICAgICAgICAgc3Ry dWN0IGRtYV9mZW5jZSAqKCpkZXBlbmRlbmN5KShzdHJ1Y3QgZHJtX3NjaGVkX2pvYiAqc2NoZWRf am9iLAo+PiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc3RydWN0IGRy bV9zY2hlZF9lbnRpdHkgKnNfZW50aXR5KTsKPj4gKwo+PiArICAgICAgIC8qIENhbGxlZCB0byBl eGVjdXRlIHRoZSBqb2Igb25jZSBhbGwgb2YgdGhlIGRlcGVuZGVuY2llcyBoYXZlCj4+ICsgICAg ICAgICogYmVlbiByZXNvbHZlZC4gIFRoaXMgbWF5IGJlIGNhbGxlZCBtdWx0aXBsZSB0aW1lcywg aWYKPj4gKyAgICAgICAgKiB0aW1lZG91dF9qb2IoKSBoYXMgaGFwcGVuZWQgYW5kIGRybV9zY2hl ZF9qb2JfcmVjb3ZlcnkoKQo+PiArICAgICAgICAqIGRlY2lkZXMgdG8gdHJ5IGl0IGFnYWluLgo+ PiArICAgICAgICAqLwo+PiAgICAgICAgIHN0cnVjdCBkbWFfZmVuY2UgKigqcnVuX2pvYikoc3Ry dWN0IGRybV9zY2hlZF9qb2IgKnNjaGVkX2pvYik7Cj4+ICsKPj4gKyAgICAgICAvKiBDYWxsZWQg d2hlbiBhIGpvYiBoYXMgdGFrZW4gdG9vIGxvbmcgdG8gZXhlY3V0ZSwgdG8gdHJpZ2dlcgo+PiAr ICAgICAgICAqIEdQVSByZWNvdmVyeS4KPj4gKyAgICAgICAgKi8KPj4gICAgICAgICB2b2lkICgq dGltZWRvdXRfam9iKShzdHJ1Y3QgZHJtX3NjaGVkX2pvYiAqc2NoZWRfam9iKTsKPj4gKwo+PiAr ICAgICAgIC8qIENhbGxlZCBvbmNlIHRoZSBqb2IncyBmaW5pc2hlZCBmZW5jZSBoYXMgYmVlbiBz aWduYWxlZCBhbmQKPj4gKyAgICAgICAgKiBpdCdzIHRpbWUgdG8gY2xlYW4gaXQgdXAuCj4+ICsg ICAgICAgICovCj4+ICAgICAgICAgdm9pZCAoKmZyZWVfam9iKShzdHJ1Y3QgZHJtX3NjaGVkX2pv YiAqc2NoZWRfam9iKTsKPj4gIH07Cj4+Cj4+IC0tCj4+IDIuMTcuMAo+Pgo+PiBfX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXwo+PiBkcmktZGV2ZWwgbWFpbGlu ZyBsaXN0Cj4+IGRyaS1kZXZlbEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKPj4gaHR0cHM6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwKPgo+Cj4KPiAtLQo+ IERhbmllbCBWZXR0ZXIKPiBTb2Z0d2FyZSBFbmdpbmVlciwgSW50ZWwgQ29ycG9yYXRpb24KPiAr NDEgKDApIDc5IDM2NSA1NyA0OCAtIGh0dHA6Ly9ibG9nLmZmd2xsLmNoCj4gX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KPiBkcmktZGV2ZWwgbWFpbGluZyBs aXN0Cj4gZHJpLWRldmVsQGxpc3RzLmZyZWVkZXNrdG9wLm9yZwo+IGh0dHBzOi8vbGlzdHMuZnJl ZWRlc2t0b3Aub3JnL21haWxtYW4vbGlzdGluZm8vZHJpLWRldmVsCl9fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fCmRyaS1kZXZlbCBtYWlsaW5nIGxpc3QKZHJp LWRldmVsQGxpc3RzLmZyZWVkZXNrdG9wLm9yZwpodHRwczovL2xpc3RzLmZyZWVkZXNrdG9wLm9y Zy9tYWlsbWFuL2xpc3RpbmZvL2RyaS1kZXZlbAo=