Linaro-mm-sig January 2024

linaro-mm-sig@lists.linaro.org

23 participants
27 discussions

Re: [PATCH 2/3] udmabuf: Sync buffer mappings for attached devices

by Andrew Davis

On 1/24/24 5:05 PM, Kasireddy, Vivek wrote: > Hi Andrew, > >> Currently this driver creates a SGT table using the CPU as the >> target device, then performs the dma_sync operations against >> that SGT. This is backwards to how DMA-BUFs are supposed to behave. >> This may have worked for the case where these buffers were given >> only back to the same CPU that produced them as in the QEMU case. >> And only then because the original author had the dma_sync >> operations also backwards, syncing for the "device" on begin_cpu. >> This was noticed and "fixed" in this patch[0]. >> >> That then meant we were sync'ing from the CPU to the CPU using >> a pseudo-device "miscdevice". Which then caused another issue >> due to the miscdevice not having a proper DMA mask (and why should >> it, the CPU is not a DMA device). The fix for that was an even >> more egregious hack[1] that declares the CPU is coherent with >> itself and can access its own memory space.. >> >> Unwind all this and perform the correct action by doing the dma_sync >> operations for each device currently attached to the backing buffer. > Makes sense. > >> >> [0] commit 1ffe09590121 ("udmabuf: fix dma-buf cpu access") >> [1] commit 9e9fa6a9198b ("udmabuf: Set the DMA mask for the udmabuf >> device (v2)") >> >> Signed-off-by: Andrew Davis <afd(a)ti.com> >> --- >> drivers/dma-buf/udmabuf.c | 41 +++++++++++++++------------------------ >> 1 file changed, 16 insertions(+), 25 deletions(-) >> >> diff --git a/drivers/dma-buf/udmabuf.c b/drivers/dma-buf/udmabuf.c >> index 3a23f0a7d112a..ab6764322523c 100644 >> --- a/drivers/dma-buf/udmabuf.c >> +++ b/drivers/dma-buf/udmabuf.c >> @@ -26,8 +26,6 @@ MODULE_PARM_DESC(size_limit_mb, "Max size of a >> dmabuf, in megabytes. Default is >> struct udmabuf { >> pgoff_t pagecount; >> struct page **pages; >> - struct sg_table *sg; >> - struct miscdevice *device; >> struct list_head attachments; >> struct mutex lock; >> }; >> @@ -169,12 +167,8 @@ static void unmap_udmabuf(struct >> dma_buf_attachment *at, >> static void release_udmabuf(struct dma_buf *buf) >> { >> struct udmabuf *ubuf = buf->priv; >> - struct device *dev = ubuf->device->this_device; >> pgoff_t pg; >> >> - if (ubuf->sg) >> - put_sg_table(dev, ubuf->sg, DMA_BIDIRECTIONAL); > What happens if the last importer maps the dmabuf but erroneously > closes it immediately? Would unmap somehow get called in this case? > Good question, had to scan the framework code a bit here. I thought closing a DMABUF handle would automatically unwind any current attachments/mappings, but it seems nothing in the framework does that. Looks like that is up to the importing drivers[0]: > Once a driver is done with a shared buffer it needs to call > dma_buf_detach() (after cleaning up any mappings) and then > release the reference acquired with dma_buf_get() by > calling dma_buf_put(). So closing a DMABUF after mapping without first unmapping it would be a bug in the importer, it is not the exporters problem to check for (although some more warnings in the framework checking for that might not be a bad idea..). Andrew [0] https://www.kernel.org/doc/html/v6.7/driver-api/dma-buf.html > Thanks, > Vivek > >> - >> for (pg = 0; pg < ubuf->pagecount; pg++) >> put_page(ubuf->pages[pg]); >> kfree(ubuf->pages); >> @@ -185,33 +179,31 @@ static int begin_cpu_udmabuf(struct dma_buf >> *buf, >> enum dma_data_direction direction) >> { >> struct udmabuf *ubuf = buf->priv; >> - struct device *dev = ubuf->device->this_device; >> - int ret = 0; >> - >> - if (!ubuf->sg) { >> - ubuf->sg = get_sg_table(dev, buf, direction); >> - if (IS_ERR(ubuf->sg)) { >> - ret = PTR_ERR(ubuf->sg); >> - ubuf->sg = NULL; >> - } >> - } else { >> - dma_sync_sg_for_cpu(dev, ubuf->sg->sgl, ubuf->sg->nents, >> - direction); >> - } >> + struct udmabuf_attachment *a; >> >> - return ret; >> + mutex_lock(&ubuf->lock); >> + >> + list_for_each_entry(a, &ubuf->attachments, list) >> + dma_sync_sgtable_for_cpu(a->dev, a->table, direction); >> + >> + mutex_unlock(&ubuf->lock); >> + >> + return 0; >> } >> >> static int end_cpu_udmabuf(struct dma_buf *buf, >> enum dma_data_direction direction) >> { >> struct udmabuf *ubuf = buf->priv; >> - struct device *dev = ubuf->device->this_device; >> + struct udmabuf_attachment *a; >> >> - if (!ubuf->sg) >> - return -EINVAL; >> + mutex_lock(&ubuf->lock); >> + >> + list_for_each_entry(a, &ubuf->attachments, list) >> + dma_sync_sgtable_for_device(a->dev, a->table, direction); >> + >> + mutex_unlock(&ubuf->lock); >> >> - dma_sync_sg_for_device(dev, ubuf->sg->sgl, ubuf->sg->nents, >> direction); >> return 0; >> } >> >> @@ -307,7 +299,6 @@ static long udmabuf_create(struct miscdevice >> *device, >> exp_info.priv = ubuf; >> exp_info.flags = O_RDWR; >> >> - ubuf->device = device; >> buf = dma_buf_export(&exp_info); >> if (IS_ERR(buf)) { >> ret = PTR_ERR(buf); >> -- >> 2.39.2 >

3 months, 2 weeks

Re: [PATCH 1/3] udmabuf: Keep track current device mappings

by Andrew Davis

On 1/24/24 4:36 PM, Kasireddy, Vivek wrote: > Hi Andrew, > >> When a device attaches to and maps our buffer we need to keep track >> of this mapping/device. This is needed for synchronization with these >> devices when beginning and ending CPU access for instance. Add a list >> that tracks device mappings as part of {map,unmap}_udmabuf(). >> >> Signed-off-by: Andrew Davis <afd(a)ti.com> >> --- >> drivers/dma-buf/udmabuf.c | 43 >> +++++++++++++++++++++++++++++++++++++-- >> 1 file changed, 41 insertions(+), 2 deletions(-) >> >> diff --git a/drivers/dma-buf/udmabuf.c b/drivers/dma-buf/udmabuf.c >> index c406459996489..3a23f0a7d112a 100644 >> --- a/drivers/dma-buf/udmabuf.c >> +++ b/drivers/dma-buf/udmabuf.c >> @@ -28,6 +28,14 @@ struct udmabuf { >> struct page **pages; >> struct sg_table *sg; >> struct miscdevice *device; >> + struct list_head attachments; >> + struct mutex lock; >> +}; >> + >> +struct udmabuf_attachment { >> + struct device *dev; >> + struct sg_table *table; >> + struct list_head list; >> }; >> >> static vm_fault_t udmabuf_vm_fault(struct vm_fault *vmf) >> @@ -120,14 +128,42 @@ static void put_sg_table(struct device *dev, struct >> sg_table *sg, >> static struct sg_table *map_udmabuf(struct dma_buf_attachment *at, >> enum dma_data_direction direction) >> { >> - return get_sg_table(at->dev, at->dmabuf, direction); >> + struct udmabuf *ubuf = at->dmabuf->priv; >> + struct udmabuf_attachment *a; >> + >> + a = kzalloc(sizeof(*a), GFP_KERNEL); >> + if (!a) >> + return ERR_PTR(-ENOMEM); >> + >> + a->table = get_sg_table(at->dev, at->dmabuf, direction); >> + if (IS_ERR(a->table)) { >> + kfree(a); >> + return a->table; > Isn't that a use-after-free bug? Indeed it is, will fix. Seems coccicheck also caught this but I missed it when reviewing its output, my bad :( Andrew > Rest of the patch lgtm. > > Thanks, > Vivek > >> + } >> + >> + a->dev = at->dev; >> + >> + mutex_lock(&ubuf->lock); >> + list_add(&a->list, &ubuf->attachments); >> + mutex_unlock(&ubuf->lock); >> + >> + return a->table; >> } >> >> static void unmap_udmabuf(struct dma_buf_attachment *at, >> struct sg_table *sg, >> enum dma_data_direction direction) >> { >> - return put_sg_table(at->dev, sg, direction); >> + struct udmabuf_attachment *a = at->priv; >> + struct udmabuf *ubuf = at->dmabuf->priv; >> + >> + mutex_lock(&ubuf->lock); >> + list_del(&a->list); >> + mutex_unlock(&ubuf->lock); >> + >> + put_sg_table(at->dev, sg, direction); >> + >> + kfree(a); >> } >> >> static void release_udmabuf(struct dma_buf *buf) >> @@ -263,6 +299,9 @@ static long udmabuf_create(struct miscdevice >> *device, >> memfd = NULL; >> } >> >> + INIT_LIST_HEAD(&ubuf->attachments); >> + mutex_init(&ubuf->lock); >> + >> exp_info.ops = &udmabuf_ops; >> exp_info.size = ubuf->pagecount << PAGE_SHIFT; >> exp_info.priv = ubuf; >> -- >> 2.39.2 >

3 months, 2 weeks

[PATCH v4 0/3] Add mediatek,gce-props.yaml for other bindings reference

by Jason-JH.Lin

From: Jason-jh Lin <jason-jh.lin(a)mediatek.corp-partner.google.com> The property "mediatek,gce-events" is used for GCE event ID corresponding to a hardware event signal sent by the hardware or a software driver. If the mailbox providers or consumers want to manipulate the value of the event ID, they need to know the specific event ID. Since mediatek,gce-events property is used for both mailbox producers and consumers, we add a mediatek,gce-props.yaml to place the common GCE properties like mediatek,gce-events. Change in v4: 1. Fix some typo. 2. Change maxItems of gce-events from 1024 to 32. Change in v3: 1. Add more description and fix typo and grammar. 2. Fix $ref as full path. Change in v2: 1. Add mediatek,gce-props.yaml for other binding reference. Jason-JH.Lin (3): dt-bindings: mailbox: Add mediatek,gce-props.yaml dt-bindings: media: mediatek: mdp: Change mediatek,gce-events to reference dt-bindings: soc: mediatek: Change mediatek,gce-events to refernece .../bindings/mailbox/mediatek,gce-props.yaml | 52 +++++++++++++++++++ .../bindings/media/mediatek,mdp3-rdma.yaml | 11 ++-- .../bindings/media/mediatek,mdp3-rsz.yaml | 12 ++--- .../bindings/media/mediatek,mdp3-wrot.yaml | 12 ++--- .../bindings/soc/mediatek/mediatek,ccorr.yaml | 12 ++--- .../bindings/soc/mediatek/mediatek,mutex.yaml | 11 ++-- .../bindings/soc/mediatek/mediatek,wdma.yaml | 12 ++--- 7 files changed, 74 insertions(+), 48 deletions(-) create mode 100644 Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml -- 2.18.0

3 months, 2 weeks

[bug report] drm/amdkfd: Export DMABufs from KFD using GEM handles

by Dan Carpenter

Hello Felix Kuehling, The patch 1819200166ce: "drm/amdkfd: Export DMABufs from KFD using GEM handles" from Aug 24, 2023 (linux-next), leads to the following Smatch static checker warning: drivers/dma-buf/dma-buf.c:729 dma_buf_get() warn: fd used after fd_install() 'fd' drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gpuvm.c 809 static int kfd_mem_export_dmabuf(struct kgd_mem *mem) 810 { 811 if (!mem->dmabuf) { 812 struct amdgpu_device *bo_adev; 813 struct dma_buf *dmabuf; 814 int r, fd; 815 816 bo_adev = amdgpu_ttm_adev(mem->bo->tbo.bdev); 817 r = drm_gem_prime_handle_to_fd(&bo_adev->ddev, bo_adev->kfd.client.file, 818 mem->gem_handle, 819 mem->alloc_flags & KFD_IOC_ALLOC_MEM_FLAGS_WRITABLE ? 820 DRM_RDWR : 0, &fd); ^^^ The drm_gem_prime_handle_to_fd() function does an fd_install() and returns the result as "fd". 821 if (r) 822 return r; 823 dmabuf = dma_buf_get(fd); ^^ Then we do another fget() inside dma_buf_get(). I'm not an expert, but this looks wrong. We can't assume that the dmabuf here is the same one from drm_gem_prime_handle_to_fd() because the user could change it after the fd_install(). I suspect drm_gem_prime_handle_to_fd() should pass the dmabuf back instead. We had several CVEs similar to this such as CVE-2022-1998. 824 close_fd(fd); 825 if (WARN_ON_ONCE(IS_ERR(dmabuf))) 826 return PTR_ERR(dmabuf); 827 mem->dmabuf = dmabuf; 828 } 829 830 return 0; 831 } regards, dan carpenter

3 months, 2 weeks

[PATCH v3 0/3] Add mediatek,gce-props.yaml for other bindings reference

by Jason-JH.Lin

From: Jason-jh Lin <jason-jh.lin(a)mediatek.corp-partner.google.com> The property "mediatek,gce-events" is used for GCE event ID corresponding to a hardware event signal sent by the hardware or a sofware driver. If the mailbox providers or consumers want to manipulate the value of the event ID, they need to know the specific event ID. Since mediatek,gce-events property is used for both mailbox producers and consumers, we add a mediatek,gce-props.yaml to place the common GCE properties like mediatek,gce-events. Change in v3: 1. Add more description and fix typo and grammar. 2. Fix $ref as full path. Change in v2: 1. Add mediatek,gce-props.yaml for other binding reference. Jason-JH.Lin (3): dt-bindings: mailbox: Add mediatek,gce-props.yaml dt-bindings: media: mediatek: mdp: Change mediatek,gce-events to reference dt-bindings: soc: mediatek: Change mediatek,gce-events to refernece .../bindings/mailbox/mediatek,gce-props.yaml | 52 +++++++++++++++++++ .../bindings/media/mediatek,mdp3-rdma.yaml | 11 ++-- .../bindings/media/mediatek,mdp3-rsz.yaml | 12 ++--- .../bindings/media/mediatek,mdp3-wrot.yaml | 12 ++--- .../bindings/soc/mediatek/mediatek,ccorr.yaml | 12 ++--- .../bindings/soc/mediatek/mediatek,mutex.yaml | 11 ++-- .../bindings/soc/mediatek/mediatek,wdma.yaml | 12 ++--- 7 files changed, 74 insertions(+), 48 deletions(-) create mode 100644 Documentation/devicetree/bindings/mailbox/mediatek,gce-props.yaml -- 2.18.0

3 months, 2 weeks

[PATCH 15/82] dma-buf: Refactor intentional wrap-around calculation

by Kees Cook

In an effort to separate intentional arithmetic wrap-around from unexpected wrap-around, we need to refactor places that depend on this kind of math. One of the most common code patterns of this is: VAR + value < VAR Notably, this is considered "undefined behavior" for signed and pointer types, which the kernel works around by using the -fno-strict-overflow option in the build[1] (which used to just be -fwrapv). Regardless, we want to get the kernel source to the position where we can meaningfully instrument arithmetic wrap-around conditions and catch them when they are unexpected, regardless of whether they are signed[2], unsigned[3], or pointer[4] types. Refactor open-coded unsigned wrap-around addition test to use check_add_overflow(), retaining the result for later usage (which removes the redundant open-coded addition). This paves the way to enabling the wrap-around sanitizers in the future. Link: https://git.kernel.org/linus/68df3755e383e6fecf2354a67b08f92f18536594 [1] Link: https://github.com/KSPP/linux/issues/26 [2] Link: https://github.com/KSPP/linux/issues/27 [3] Link: https://github.com/KSPP/linux/issues/344 [4] Cc: Sumit Semwal <sumit.semwal(a)linaro.org> Cc: Christian König <christian.koenig(a)amd.com> Cc: "Christian König" <christian.koenig(a)amd.com> Cc: linux-media(a)vger.kernel.org Cc: dri-devel(a)lists.freedesktop.org Cc: linaro-mm-sig(a)lists.linaro.org Signed-off-by: Kees Cook <keescook(a)chromium.org> --- drivers/dma-buf/dma-buf.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c index 8fe5aa67b167..3743c63a9b59 100644 --- a/drivers/dma-buf/dma-buf.c +++ b/drivers/dma-buf/dma-buf.c @@ -1458,6 +1458,8 @@ EXPORT_SYMBOL_NS_GPL(dma_buf_end_cpu_access, DMA_BUF); int dma_buf_mmap(struct dma_buf *dmabuf, struct vm_area_struct *vma, unsigned long pgoff) { + unsigned long sum; + if (WARN_ON(!dmabuf || !vma)) return -EINVAL; @@ -1466,12 +1468,11 @@ int dma_buf_mmap(struct dma_buf *dmabuf, struct vm_area_struct *vma, return -EINVAL; /* check for offset overflow */ - if (pgoff + vma_pages(vma) < pgoff) + if (check_add_overflow(pgoff, vma_pages(vma), &sum)) return -EOVERFLOW; /* check for overflowing the buffer's size */ - if (pgoff + vma_pages(vma) > - dmabuf->size >> PAGE_SHIFT) + if (sum > dmabuf->size >> PAGE_SHIFT) return -EINVAL; /* readjust the vma */ -- 2.34.1

3 months, 2 weeks

Re: [PATCH v4 1/4] usb: gadget: Support already-mapped DMA SGs

by Paul Cercueil

Hi Frank, Le vendredi 19 janvier 2024 à 16:49 -0500, Frank Li a écrit : > On Wed, Jan 17, 2024 at 01:26:43PM +0100, Paul Cercueil wrote: > > Add a new 'sg_was_mapped' field to the struct usb_request. This > > field > > can be used to indicate that the scatterlist associated to the USB > > transfer has already been mapped into the DMA space, and it does > > not > > have to be done internally. > > > > Signed-off-by: Paul Cercueil <paul(a)crapouillou.net> > > --- > > drivers/usb/gadget/udc/core.c | 7 ++++++- > > include/linux/usb/gadget.h | 2 ++ > > 2 files changed, 8 insertions(+), 1 deletion(-) > > > > diff --git a/drivers/usb/gadget/udc/core.c > > b/drivers/usb/gadget/udc/core.c > > index d59f94464b87..9d4150124fdb 100644 > > --- a/drivers/usb/gadget/udc/core.c > > +++ b/drivers/usb/gadget/udc/core.c > > @@ -903,6 +903,11 @@ int usb_gadget_map_request_by_dev(struct > > device *dev, > > if (req->length == 0) > > return 0; > > > > + if (req->sg_was_mapped) { > > + req->num_mapped_sgs = req->num_sgs; > > + return 0; > > + } > > + > > if (req->num_sgs) { > > int mapped; > > > > @@ -948,7 +953,7 @@ EXPORT_SYMBOL_GPL(usb_gadget_map_request); > > void usb_gadget_unmap_request_by_dev(struct device *dev, > > struct usb_request *req, int is_in) > > { > > - if (req->length == 0) > > + if (req->length == 0 || req->sg_was_mapped) > > return; > > > > if (req->num_mapped_sgs) { > > diff --git a/include/linux/usb/gadget.h > > b/include/linux/usb/gadget.h > > index a771ccc038ac..c529e4e06997 100644 > > --- a/include/linux/usb/gadget.h > > +++ b/include/linux/usb/gadget.h > > @@ -52,6 +52,7 @@ struct usb_ep; > > * @short_not_ok: When reading data, makes short packets be > > * treated as errors (queue stops advancing till cleanup). > > * @dma_mapped: Indicates if request has been mapped to DMA > > (internal) > > + * @sg_was_mapped: Set if the scatterlist has been mapped before > > the request > > * @complete: Function called when request completes, so this > > request and > > * its buffer may be re-used. The function will always be > > called with > > * interrupts disabled, and it must not sleep. > > @@ -111,6 +112,7 @@ struct usb_request { > > unsigned zero:1; > > unsigned short_not_ok:1; > > unsigned dma_mapped:1; > > + unsigned sg_was_mapped:1; > > why not use dma_mapped direclty? Because of the unmap case. We want to know whether we should unmap or not. > > Frank Cheers, -Paul > > > > > void (*complete)(struct usb_ep *ep, > > struct usb_request *req); > > -- > > 2.43.0 > >

3 months, 2 weeks

[PATCH v4 0/4] usb: gadget: functionfs: DMABUF import interface

by Paul Cercueil

Hi, This is the v4 of my patchset that adds a new DMABUF import interface to FunctionFS. It addresses the points that Daniel raised on the v3 - see changelog below. This interface is being used at Analog Devices, to transfer data from high-speed transceivers to USB in a zero-copy fashion, using also the DMABUF import interface to the IIO subsystem which is being upstreamed in parallel [1]. The two are used by the Libiio software [2]. On a ZCU102 board with a FMComms3 daughter board, using the combination of these two new interfaces yields a drastic improvement of the throughput, from about 127 MiB/s using IIO's buffer read/write interface + read/write to the FunctionFS endpoints, to about 274 MiB/s when passing around DMABUFs, for a lower CPU usage (0.85 load avg. before, vs. 0.65 after). Right now, *technically* there are no users of this interface, as Analog Devices wants to wait until both interfaces are accepted upstream to merge the DMABUF code in Libiio into the main branch, and Jonathan wants to wait and see if this patchset is accepted to greenlight the DMABUF interface in IIO as well. I think this isn't really a problem; once everybody is happy with its part of the cake, we can merge them all at once. This is obviously for 5.9, and based on next-20240117. Changelog: - [3/4]: - Protect the dmabufs list with a mutex - Use incremental sequence number for the dma_fences - Unref attachments and DMABUFs in workers - Remove dead code in ffs_dma_resv_lock() - Fix non-block actually blocking - Use dma_fence_begin/end_signalling() - Add comment about cache-management and dma_buf_unmap_attachment() - Make sure dma_buf_map_attachment() is called with the dma-resv locked Cheers, -Paul [1] https://lore.kernel.org/linux-iio/219abc43b4fdd4a13b307ed2efaa0e6869e68e3f.… [2] https://github.com/analogdevicesinc/libiio/tree/pcercuei/dev-new-dmabuf-api Paul Cercueil (4): usb: gadget: Support already-mapped DMA SGs usb: gadget: functionfs: Factorize wait-for-endpoint code usb: gadget: functionfs: Add DMABUF import interface Documentation: usb: Document FunctionFS DMABUF API Documentation/usb/functionfs.rst | 36 ++ drivers/usb/gadget/function/f_fs.c | 500 ++++++++++++++++++++++++++-- drivers/usb/gadget/udc/core.c | 7 +- include/linux/usb/gadget.h | 2 + include/uapi/linux/usb/functionfs.h | 41 +++ 5 files changed, 565 insertions(+), 21 deletions(-) -- 2.43.0

3 months, 2 weeks

[PATCH v3 0/4] usb: gadget: functionfs: DMABUF import interface

by Paul Cercueil

Hi, This small patchset adds three new IOCTLs that can be used to attach, detach, or transfer from/to a DMABUF object. This interface is being used at Analog Devices, to transfer data from high-speed transceivers to USB in a zero-copy fashion, using also the DMABUF import interface to the IIO subsystem which is being upstreamed in parallel [1] (and has high chances to be accepted for 5.9, I think Jonathan can confirm). The two are used by the Libiio software [2]. On a ZCU102 board with a FMComms3 daughter board, using the combination of these two new interfaces yields a drastic improvement of the throughput, from about 127 MiB/s using IIO's buffer read/write interface + read/write to the FunctionFS endpoints, to about 274 MiB/s when passing around DMABUFs, for a lower CPU usage (0.85 load avg. before, vs. 0.65 after). Right now, *technically* there are no users of this interface, as Analog Devices wants to wait until both interfaces are accepted upstream to merge the DMABUF code in Libiio into the main branch, and Jonathan wants to wait and see if this patchset is accepted to greenlight the DMABUF interface in IIO as well. I think this isn't really a problem; once everybody is happy with its part of the cake, we can merge them all at once. This is obviously for 5.9, and based on next-20240108. Changelog: - [3/4]: - Inline to_ffs_dma_fence() which was called only once. - Simplify ffs_dma_resv_lock() - Add comment explaining why we unref twice in ffs_dmabuf_detach() - Document uapi struct usb_ffs_dmabuf_transfer_req and IOCTLs - [4/4]: New patch, as I figured out having documentation wouldn't hurt. Cheers, -Paul [1] https://lore.kernel.org/linux-iio/219abc43b4fdd4a13b307ed2efaa0e6869e68e3f.… [2] https://github.com/analogdevicesinc/libiio/tree/pcercuei/dev-new-dmabuf-api Paul Cercueil (4): usb: gadget: Support already-mapped DMA SGs usb: gadget: functionfs: Factorize wait-for-endpoint code usb: gadget: functionfs: Add DMABUF import interface Documentation: usb: Document FunctionFS DMABUF API Documentation/usb/functionfs.rst | 36 +++ drivers/usb/gadget/function/f_fs.c | 463 ++++++++++++++++++++++++++-- drivers/usb/gadget/udc/core.c | 7 +- include/linux/usb/gadget.h | 2 + include/uapi/linux/usb/functionfs.h | 41 +++ 5 files changed, 528 insertions(+), 21 deletions(-) -- 2.43.0

3 months, 3 weeks

Re: [PATCH v3 4/4] Documentation: usb: Document FunctionFS DMABUF API

by Paul Cercueil

Hi Vegard, Le mardi 09 janvier 2024 à 14:08 +0100, Vegard Nossum a écrit : > On 08/01/2024 13:00, Paul Cercueil wrote: > > Add documentation for the three ioctls used to attach or detach > > externally-created DMABUFs, and to request transfers from/to > > previously > > attached DMABUFs. > > > > Signed-off-by: Paul Cercueil <paul(a)crapouillou.net> > > > > --- > > v3: New patch > > --- > > Documentation/usb/functionfs.rst | 36 > > ++++++++++++++++++++++++++++++++ > > 1 file changed, 36 insertions(+) > > Hi, > > I'd like to point out that this file (usb/functionfs.rst) is > currently > included by Documentation/subsystem-apis.rst, the top-level file for > the > "Kernel subsystem documentation" set of books, which describe > internal > APIs: "These books get into the details of how specific kernel > subsystems work from the point of view of a kernel developer". > > However, functionfs.rst (and especially your new additions) are > documenting a userspace API, so it really belongs somewhere in > Documentation/userspace-api/ -- that's where /proc, /sys, /dev and > ioctl > descriptions for userspace programmers belong. Agreed. Even the original content prior to my additions describe a userspace API. > > I'm not NAKing the patch -- I just want to draw attention to this > discrepancy. Maybe we can separate the kernel-implementation details > (stuff about __init sections and stuff) from the new ioctl() info? > > Looking at <https://docs.kernel.org/usb/> I see that there are many > other adjacent documents that are also not really documenting kernel > implementation details, rough categorization as follows: > > USB support > ----------- > > - Linux ACM driver v0.16 ==> admin/user info > - Authorizing (or not) your USB devices to connect to the system ==> > admin/user info > - ChipIdea Highspeed Dual Role Controller Driver => admin/user info > - DWC3 driver ==> driver TODOs (can be moved into source code?) > - EHCI driver ==> technical info + driver details > - How FunctionFS works > - Linux USB gadget configured through configfs ==> userspace API + > implementation > - Linux USB HID gadget driver ==> implementation + userspace API > - Multifunction Composite Gadget ==> technical + user info > - Linux USB Printer Gadget Driver ==> userspace API > - Linux Gadget Serial Driver v2.0 ==> user/admin + userspace API > - Linux UVC Gadget Driver ==> user/admin + userspace API > - Gadget Testing ==> user/admin + userspace API > - Infinity Usb Unlimited Readme ==> user/admin > - Mass Storage Gadget (MSG) ==> user/admin > - USB 7-Segment Numeric Display ==> user/admin > - mtouchusb driver ==> user/admin > - OHCI ==> technical info > - USB Raw Gadget ==> userspace API > - USB/IP protocol ==> technical info > - usbmon ==> user/admin + userspace API > - USB serial ==> user/admin + technical info > - USB references > - Linux CDC ACM inf > - Linux inf > - USB devfs drop permissions source > - Credits > > By "admin/user info", I mean things that a user would have to do or > run > (e.g. modprobe + flags) to make use of a driver; "technical info" is > more like device specifications (transfer speeds, modes of operation, > etc.); "userspace API" is stuff like configfs and ioctls; "driver > details" is really implementation details and internal > considerations. > > The last ones I don't even really know how to categorize. > > I'm guessing nobody is really enthralled by the idea of splitting > Documentation/usb/ up like this? > > Documentation/admin-guide/usb/ > Documentation/driver-api/usb/ (this one actually exists already) > Documentation/userspace-api/usb/ > > For the stuff that is _actually_ internal to a specific driver (so > not > useful for end users, not useful for admins, not generic USB info, > and > not useful for userspace programmers), I would honestly propose to > just > move it directly into the driver's source code, or, if the text is > obsolete, just get rid of it completely. > > The distinction between user/admin and userspace API is pretty clear > (one is for end users, the other is for userspace _programmers_), but > it > can sometimes be hard to determine whether something falls in one or > the > other category. > > In any case -- it looks like almost all of the usb/ directory does > not > document "how specific kernel subsystems work from the point of view > of > a kernel developer" so maybe we should just move the include to > userspace-api/ for now as an obvious improvement (if still not 100% > correct): > > diff --git a/Documentation/subsystem-apis.rst > b/Documentation/subsystem-apis.rst > index 2d353fb8ea26..fe972f57bf4c 100644 > --- a/Documentation/subsystem-apis.rst > +++ b/Documentation/subsystem-apis.rst > @@ -81,7 +81,6 @@ Storage interfaces > security/index > crypto/index > bpf/index > - usb/index > PCI/index > misc-devices/index > peci/index > diff --git a/Documentation/userspace-api/index.rst > b/Documentation/userspace-api/index.rst > index 82f9dbd228f5..e60cd9174ada 100644 > --- a/Documentation/userspace-api/index.rst > +++ b/Documentation/userspace-api/index.rst > @@ -41,6 +41,7 @@ Subsystem-specific documentation: > tee > isapnp > dcdbas > + ../usb/index > > Kernel ABIs: These documents describe the the ABI between the Linux > kernel and userspace, and the relative stability of these > interfaces. > > > Thoughts? Makes sense to me. There's definitely some cleanup to be done in the USB documentation. > Vegard Cheers, -Paul

3 months, 3 weeks

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

Linaro-mm-sig January 2024