From mboxrd@z Thu Jan 1 00:00:00 1970 From: Daniel Vetter Subject: Re: [PATCH 12/12] Documentation: add Sync File doc Date: Wed, 27 Apr 2016 21:05:08 +0200 Message-ID: <20160427190508.GE2558@phenom.ffwll.local> References: <1461774439-11512-1-git-send-email-gustavo@padovan.org> <1461774439-11512-13-git-send-email-gustavo@padovan.org> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-wm0-x241.google.com (mail-wm0-x241.google.com [IPv6:2a00:1450:400c:c09::241]) by gabe.freedesktop.org (Postfix) with ESMTPS id 9192189097 for ; Wed, 27 Apr 2016 19:05:13 +0000 (UTC) Received: by mail-wm0-x241.google.com with SMTP id n129so6588720wmn.1 for ; Wed, 27 Apr 2016 12:05:13 -0700 (PDT) Content-Disposition: inline In-Reply-To: <1461774439-11512-13-git-send-email-gustavo@padovan.org> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Gustavo Padovan Cc: devel@driverdev.osuosl.org, Daniel Stone , Greg Kroah-Hartman , linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, Arve =?iso-8859-1?B?SGr4bm5lduVn?= , Daniel Vetter , Riley Andrews , Gustavo Padovan , John Harrison List-Id: dri-devel@lists.freedesktop.org T24gV2VkLCBBcHIgMjcsIDIwMTYgYXQgMDE6Mjc6MTlQTSAtMDMwMCwgR3VzdGF2byBQYWRvdmFu IHdyb3RlOgo+IEZyb206IEd1c3Rhdm8gUGFkb3ZhbiA8Z3VzdGF2by5wYWRvdmFuQGNvbGxhYm9y YS5jby51az4KPiAKPiBBZGQgc3luY19maWxlIGRvY3VtZW50YXRpb24gb24gZG1hLWJ1Zi1zeW5j X2ZpbGUudHh0Cj4gLS0tCj4gIERvY3VtZW50YXRpb24vZG1hLWJ1Zi1zeW5jX2ZpbGUudHh0IHwg NjUgKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKwo+ICAxIGZpbGUgY2hhbmdl ZCwgNjUgaW5zZXJ0aW9ucygrKQo+ICBjcmVhdGUgbW9kZSAxMDA2NDQgRG9jdW1lbnRhdGlvbi9k bWEtYnVmLXN5bmNfZmlsZS50eHQKPiAKPiBkaWZmIC0tZ2l0IGEvRG9jdW1lbnRhdGlvbi9kbWEt YnVmLXN5bmNfZmlsZS50eHQgYi9Eb2N1bWVudGF0aW9uL2RtYS1idWYtc3luY19maWxlLnR4dAo+ IG5ldyBmaWxlIG1vZGUgMTAwNjQ0Cj4gaW5kZXggMDAwMDAwMC4uYWE3MzIwZgo+IC0tLSAvZGV2 L251bGwKPiArKysgYi9Eb2N1bWVudGF0aW9uL2RtYS1idWYtc3luY19maWxlLnR4dAo+IEBAIC0w LDAgKzEsNjUgQEAKPiArCQkJIERNQSBCdWZmZXIgU3luYyBGaWxlIEFQSSBHdWlkZQo+ICsJCQkg fn5+fn5+fn5+fn5+fn5+fn5+fn5+fn5+fn5+fn5+CgpTdHJpY3RseSBzcGVha2luZyB5b3UgY2Fu IHVzZSBzeW5jX2ZpbGUgZmVuY2VzIHdpdGhvdXQgZG1hLWJ1ZnMuIEUuZy4gd2hlbgp5b3VyIGdw dSB1c2VzIHNvbWV0aGluZyBsaWtlIHNoYXJlZCB2aXJ0dWFsIG1lbW9yeSBhbmQgZGlyZWN0bHkg YWNjZXNzIHRoZQp1c2Vyc3BhY2UgYWRkcmVzcyBzcGFjZSB0aGVyZSdzIG5vdCBidWZmZXIgaGFu ZGxlcyBpbnZvbHZlZCwgYnV0IHlvdSBzdGlsbAptaWdodCB3YW50IHRvIHBhc3MgYXJvdW5kIGZl bmNlcyBiZXR3ZWVuIGRyaXZlcnMgYW5kL29yIHByb2Nlc3Nlcy4gU28KcGxlYXNlIGRyb3AgZG1h LWJ1ZiBmcm9tIHRoZSBmaWxlbmFtZSBhbmQgZXZlcnl0aGluZyBlbHNlIGluIGhlcmUuIEl0J3Mg b2sKdG8gbWVudGlvbiB0aGF0IHRoaXMgaXMgdXNlZCB0b2dldGhlciB3aXRoIGJ1ZmZlcnMvcHJv Y2Vzc2luZywganVzdCBhcyBhbgpleGFtcGxlLgoKPiArCj4gKwkJCQlHdXN0YXZvIFBhZG92YW4K PiArCQkJICA8Z3VzdGF2byBhdCBwYWRvdmFuIGRvdCBvcmc+Cj4gKwo+ICtUaGlzIGRvY3VtZW50 IHNlcnZlcyBhcyBhIGd1aWRlIGZvciBkZXZpY2UgZHJpdmVycyB3cml0ZXJzIG9uIHdoYXQgaXMg dGhlCj4gK2RtYS1idWYgc3luY19maWxlIEFQSSwgYW5kIGhvdyBkcml2ZXJzIGNhbiBzdXBwb3J0 IGl0LiBTeW5jIGZpbGUgaXMgdGhlCgoiLi4uIG9uIHdoYXQgdGhlIHN5bmNfZmlsZSBBUEkgX2lz XywgLi4uIgoKPiArY2FycmllciBvZiB0aGUgZmVuY2VzKHN0cnVjdCBmZW5jZSkgdGhhdCBuZWVk cyB0byBzeW5jaHJvbml6ZWQgYmV0d2VlbiBkcml2ZXJzLgoKIi4uLiBiZXR3ZWVuIGRyaXZlcnMg b3IgYWNyb3NzIHByb2Nlc3MgYm91bmRhcmllcy4iCgpBbmRyb2lkIHdhbnRzL25lZWRzIGJvdGgu Cgo+ICsKPiArVGhlIHN5bmNfZmlsZSBBUEkgaXMgbWVhbnQgdG8gYmUgdXNlZCB0byBzZW5kIGFu ZCByZWNlaXZlIGZlbmNlIGluZm9ybWF0aW9uCj4gK3RvL2Zyb20gdXNlcnNwYWNlLiBJdCBlbmFi bGVzIHVzZXJzcGFjZSB0byBkbyBleHBsaWNpdCBmZW5jaW5nLCB3aGVyZSBpbnN0ZWFkCj4gK29m IGF0dGFjaGluZyBhIGZlbmNlIHRvIHRoZSBidWZmZXIgYSBQcm9kdWNlciBkcml2ZXIgKHN1Y2gg YXMgR1BVIG9yIFY0TAoKX3Bfcm9kdWNlcgoKIihzdWNoIGFzIF9hXyBHUFUgLi4uKSIKCj4gK2Ry aXZlcikgaXQgc2VuZHMgdGhlIGZlbmNlIHJlbGF0ZWQgdG8gdGhlIGJ1ZmZlciB0byB1c2Vyc3Bh Y2UuIFRoZSBmZW5jZSB0aGVuCgpzL2l0Ly8KCj4gK2NhbiBiZSBzZW50IHRvIHRoZSBDb25zdW1l ciAoRFJNIGRyaXZlciBmb3IgZXhhbXBsZSksIHRoYXQgd2lsbCBub3QgdXNlIHRoZQoKX2Nfb25z dW1lcgoKPiArYnVmZmVyIGZvciBhbnl0aGluZyBiZWZvcmUgdGhlIGZlbmNlIHNpZ25hbHMsIGku ZS4sIHRoZSBkcml2ZXIgdGhhdCBpc3N1ZWQgdGhlCj4gK2ZlbmNlIGlzIG5vdCB1c2luZy9wcm9j ZXNzaW5nIHRoZSBidWZmZXIgYW55bW9yZSwgc28gaXQgc2lnbmFscyB0aGF0IHRoZSBidWZmZXIK PiAraXMgcmVhZHkgdG8gdXNlLiBBbmQgdmljZS12ZXJzYSBmb3IgdGhlIENvbnN1bWVyIC0+IFBy b2R1Y2VyIHBhcnQgb2YgdGhlIGN5Y2xlLgoKQSBiaXQgYSBydW4tb24gc2VudGVuY2UgYWJvdmUu IE1pZ2h0IHdhbnQgdG8gc3BsaXQgaXQuCgo+ICtTeW5jIGZpbGVzIGFsbG93cyB1c2Vyc3BhY2Ug YXdhcmVuZXNzIG9uIHRoZSBETUEgYnVmZmVyIHNoYXJpbmcgc3luY2hyb25pemF0aW9uCj4gK2Jl dHdlZW4gZHJpdmVycy4KPiArCj4gK1N5bmMgZmlsZSB3YXMgb3JpZ2luYWxseSBhZGRlZCBpbiB0 aGUgQW5kcm9pZCBrZXJuZWwgYnV0IGN1cnJlbnQgTGludXggRGVza3RvcAo+ICtjYW4gYmVuZWZp dCBhIGxvdCBmcm9tIGl0Lgo+ICsKPiAraW4tZmVuY2VzIGFuZCBvdXQtZmVuY2VzCj4gKy0tLS0t LS0tLS0tLS0tLS0tLS0tLS0tLQo+ICsKPiArU3luYyBmaWxlcyBjYW4gZ28gZWl0aGVyIHRvIG9y IGZyb20gdXNlcnNwYWNlLiBXaGVuIGEgc3luY19maWxlIGlzIHNlbnQgZnJvbQo+ICt0aGUgZHJp dmVyIHRvIHVzZXJzcGFjZSB3ZSBjYWxsIHRoZSBmZW5jZXMgaXQgY29udGFpbnMgJ291dC1mZW5j ZXMnLiBUaGV5IGFyZQo+ICtyZWxhdGVkIHRvIGEgYnVmZmVyIHRoYXQgdGhlIGRyaXZlciBpcyBw cm9jZXNzaW5nIG9yIGlzIGdvaW5nIHRvIHByb2Nlc3MsIHNvCj4gK3RoZSBkcml2ZXIgY3JlYXRl IG91dC1mZW5jZXMgdG8gYmUgYWJsZSB0byBub3RpZnksIHRocm91Z2ggZmVuY2Vfc2lnbmFsKCks IHdoZW4KCiIuLi4gY3JlYXRlX3NfIF9hbl8gb3V0IGZlbmNlIC4uLiIKCj4gK2l0IGhhcyBmaW5p c2hlZCB1c2luZyAob3IgcHJvY2Vzc2luZykgdGhhdCBidWZmZXIuIE91dC1mZW5jZXMgYXJlIGZl bmNlcyB0aGF0Cj4gK3RoZSBkcml2ZXIgY3JlYXRlcy4KPiArCj4gK09uIHRoZSBvdGhlciBoYW5k IGlmIHRoZSBkcml2ZXIgcmVjZWl2ZXMgZmVuY2UocykgdGhyb3VnaCBhIHN5bmNfZmlsZSBmcm9t Cj4gK3VzZXJzcGFjZSB3ZSBjYWxsIHRoZXNlIGZlbmNlKHMpICdpbi1mZW5jZXMnLiBSZWNlaXZl aW5nIGluLWZlbmNlcyBtZWFucyB0aGF0Cj4gK3dlIG5lZWQgdG8gd2FpdCBmb3IgdGhlIGZlbmNl KHMpIHRvIHNpZ25hbCBiZWZvcmUgdXNpbmcgYW55IGJ1ZmZlciByZWxhdGVkIHRvCj4gK3RoZSBp bi1mZW5jZXMuCj4gKwo+ICtDcmVhdGluZyBTeW5jIEZpbGVzCj4gKy0tLS0tLS0tLS0tLS0tLS0t LS0KPiArCj4gK1doZW4gYSBkcml2ZXIgbmVlZHMgdG8gc2VuZCBhbiBvdXQtZmVuY2UgdXNlcnNw YWNlIGl0IGNyZWF0ZXMgYSBzeW5jX2ZpbGUuCj4gKwo+ICtJbnRlcmZhY2U6Cj4gKwlzdHJ1Y3Qg c3luY19maWxlICpzeW5jX2ZpbGVfY3JlYXRlKGNvbnN0IGNoYXIgKm5hbWUsIHN0cnVjdCBmZW5j ZSAqZmVuY2UpOwo+ICsKPiArVGhlIGNhbGxlciBwYXNzIHRoZSBuYW1lIGFuZCB0aGUgb3V0LWZl bmNlIGFuZCBnZXRzIGJhY2sgdGhlIHN5bmNfZmlsZS4gVGhhdCBpcwo+ICtqdXN0IHRoZSBmaXJz dCBzdGVwLCBuZXh0IGl0IG5lZWRzIHRvIGluc3RhbGwgYW4gZmQgb24gc3luY19maWxlLT5maWxl LiBTbyBpdAo+ICtnZXRzIGFuIGZkOgo+ICsKPiArCWZkID0gZ2V0X3VudXNlZF9mZF9mbGFncyhP X0NMT0VYRUMpOwo+ICsKPiArYW5kIGluc3RhbGxzIGl0IG9uIHN5bmNfZmlsZS0+ZmlsZToKPiAr Cj4gKwlmZF9pbnN0YWxsKGZkLCBzeW5jX2ZpbGUtPmZpbGUpOwo+ICsKPiArVGhlIHN5bmNfZmls ZSBmZCBub3cgY2FuIGJlIHNlbnQgdG8gdXNlcnNwYWNlLgo+ICsKPiArSWYgdGhlIGNyZWF0aW9u IHByb2Nlc3MgZmFpbCwgb3IgdGhlIHN5bmNfZmlsZSBuZWVkcyB0byBiZSByZWxlYXNlZCBieSBh bnkKPiArb3RoZXIgcmVhc29uIGZwdXQoc3luY19maWxlLT5maWxlKSBzaG91bGQgYmUgdXNlZC4K CldpdGggdGhlIGFib3ZlIG5pdHBpY2tzIGZpeGVkOgoKUmV2aWV3ZWQtYnk6IERhbmllbCBWZXR0 ZXIgPGRhbmllbC52ZXR0ZXJAZmZ3bGwuY2g+Cj4gKwo+ICtSZWZlcmVuY2VzOgo+ICtbMV0gc3Ry dWN0IHN5bmNfZmlsZSBpbiBpbmNsdWRlL2xpbnV4L3N5bmNfZmlsZS5oCj4gK1syXSBBbGwgaW50 ZXJmYWNlcyBtZW50aW9uZWQgYWJvdmUgZGVmaW5lZCBpbiBpbmNsdWRlL2xpbnV4L3N5bmNfZmls ZS5oCj4gLS0gCj4gMi41LjUKPiAKCi0tIApEYW5pZWwgVmV0dGVyClNvZnR3YXJlIEVuZ2luZWVy LCBJbnRlbCBDb3Jwb3JhdGlvbgpodHRwOi8vYmxvZy5mZndsbC5jaApfX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXwpkcmktZGV2ZWwgbWFpbGluZyBsaXN0CmRy aS1kZXZlbEBsaXN0cy5mcmVlZGVza3RvcC5vcmcKaHR0cHM6Ly9saXN0cy5mcmVlZGVza3RvcC5v cmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752697AbcD0TFQ (ORCPT ); Wed, 27 Apr 2016 15:05:16 -0400 Received: from mail-wm0-f65.google.com ([74.125.82.65]:34611 "EHLO mail-wm0-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750753AbcD0TFN (ORCPT ); Wed, 27 Apr 2016 15:05:13 -0400 Date: Wed, 27 Apr 2016 21:05:08 +0200 From: Daniel Vetter To: Gustavo Padovan Cc: Greg Kroah-Hartman , linux-kernel@vger.kernel.org, devel@driverdev.osuosl.org, dri-devel@lists.freedesktop.org, Daniel Stone , Arve =?iso-8859-1?B?SGr4bm5lduVn?= , Riley Andrews , Daniel Vetter , Rob Clark , Greg Hackmann , John Harrison , Maarten Lankhorst , Sumit Semwal , Gustavo Padovan Subject: Re: [PATCH 12/12] Documentation: add Sync File doc Message-ID: <20160427190508.GE2558@phenom.ffwll.local> Mail-Followup-To: Gustavo Padovan , Greg Kroah-Hartman , linux-kernel@vger.kernel.org, devel@driverdev.osuosl.org, dri-devel@lists.freedesktop.org, Daniel Stone , Arve =?iso-8859-1?B?SGr4bm5lduVn?= , Riley Andrews , Rob Clark , Greg Hackmann , John Harrison , Maarten Lankhorst , Sumit Semwal , Gustavo Padovan References: <1461774439-11512-1-git-send-email-gustavo@padovan.org> <1461774439-11512-13-git-send-email-gustavo@padovan.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1461774439-11512-13-git-send-email-gustavo@padovan.org> X-Operating-System: Linux phenom 4.6.0-rc5+ User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, Apr 27, 2016 at 01:27:19PM -0300, Gustavo Padovan wrote: > From: Gustavo Padovan > > Add sync_file documentation on dma-buf-sync_file.txt > --- > Documentation/dma-buf-sync_file.txt | 65 +++++++++++++++++++++++++++++++++++++ > 1 file changed, 65 insertions(+) > create mode 100644 Documentation/dma-buf-sync_file.txt > > diff --git a/Documentation/dma-buf-sync_file.txt b/Documentation/dma-buf-sync_file.txt > new file mode 100644 > index 0000000..aa7320f > --- /dev/null > +++ b/Documentation/dma-buf-sync_file.txt > @@ -0,0 +1,65 @@ > + DMA Buffer Sync File API Guide > + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Strictly speaking you can use sync_file fences without dma-bufs. E.g. when your gpu uses something like shared virtual memory and directly access the userspace address space there's not buffer handles involved, but you still might want to pass around fences between drivers and/or processes. So please drop dma-buf from the filename and everything else in here. It's ok to mention that this is used together with buffers/processing, just as an example. > + > + Gustavo Padovan > + > + > +This document serves as a guide for device drivers writers on what is the > +dma-buf sync_file API, and how drivers can support it. Sync file is the "... on what the sync_file API _is_, ..." > +carrier of the fences(struct fence) that needs to synchronized between drivers. "... between drivers or across process boundaries." Android wants/needs both. > + > +The sync_file API is meant to be used to send and receive fence information > +to/from userspace. It enables userspace to do explicit fencing, where instead > +of attaching a fence to the buffer a Producer driver (such as GPU or V4L _p_roducer "(such as _a_ GPU ...)" > +driver) it sends the fence related to the buffer to userspace. The fence then s/it// > +can be sent to the Consumer (DRM driver for example), that will not use the _c_onsumer > +buffer for anything before the fence signals, i.e., the driver that issued the > +fence is not using/processing the buffer anymore, so it signals that the buffer > +is ready to use. And vice-versa for the Consumer -> Producer part of the cycle. A bit a run-on sentence above. Might want to split it. > +Sync files allows userspace awareness on the DMA buffer sharing synchronization > +between drivers. > + > +Sync file was originally added in the Android kernel but current Linux Desktop > +can benefit a lot from it. > + > +in-fences and out-fences > +------------------------ > + > +Sync files can go either to or from userspace. When a sync_file is sent from > +the driver to userspace we call the fences it contains 'out-fences'. They are > +related to a buffer that the driver is processing or is going to process, so > +the driver create out-fences to be able to notify, through fence_signal(), when "... create_s_ _an_ out fence ..." > +it has finished using (or processing) that buffer. Out-fences are fences that > +the driver creates. > + > +On the other hand if the driver receives fence(s) through a sync_file from > +userspace we call these fence(s) 'in-fences'. Receiveing in-fences means that > +we need to wait for the fence(s) to signal before using any buffer related to > +the in-fences. > + > +Creating Sync Files > +------------------- > + > +When a driver needs to send an out-fence userspace it creates a sync_file. > + > +Interface: > + struct sync_file *sync_file_create(const char *name, struct fence *fence); > + > +The caller pass the name and the out-fence and gets back the sync_file. That is > +just the first step, next it needs to install an fd on sync_file->file. So it > +gets an fd: > + > + fd = get_unused_fd_flags(O_CLOEXEC); > + > +and installs it on sync_file->file: > + > + fd_install(fd, sync_file->file); > + > +The sync_file fd now can be sent to userspace. > + > +If the creation process fail, or the sync_file needs to be released by any > +other reason fput(sync_file->file) should be used. With the above nitpicks fixed: Reviewed-by: Daniel Vetter > + > +References: > +[1] struct sync_file in include/linux/sync_file.h > +[2] All interfaces mentioned above defined in include/linux/sync_file.h > -- > 2.5.5 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch