include/media/videobuf-dma-sg.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * helper functions for SG DMA video4linux capture buffers
0004  *
0005  * The functions expect the hardware being able to scatter gather
0006  * (i.e. the buffers are not linear in physical memory, but fragmented
0007  * into PAGE_SIZE chunks).  They also assume the driver does not need
0008  * to touch the video data.
0009  *
0010  * (c) 2007 Mauro Carvalho Chehab, <mchehab@kernel.org>
0011  *
0012  * Highly based on video-buf written originally by:
0013  * (c) 2001,02 Gerd Knorr <kraxel@bytesex.org>
0014  * (c) 2006 Mauro Carvalho Chehab, <mchehab@kernel.org>
0015  * (c) 2006 Ted Walther and John Sokol
0016  */
0017 #ifndef _VIDEOBUF_DMA_SG_H
0018 #define _VIDEOBUF_DMA_SG_H
0019
0020 #include <media/videobuf-core.h>
0021
0022 /* --------------------------------------------------------------------- */
0023
0024 /*
0025  * A small set of helper functions to manage buffers (both userland
0026  * and kernel) for DMA.
0027  *
0028  * videobuf_dma_init_*()
0029  *  creates a buffer.  The userland version takes a userspace
0030  *  pointer + length.  The kernel version just wants the size and
0031  *  does memory allocation too using vmalloc_32().
0032  *
0033  * videobuf_dma_*()
0034  *  see Documentation/core-api/dma-api-howto.rst, these functions to
0035  *  basically the same.  The map function does also build a
0036  *  scatterlist for the buffer (and unmap frees it ...)
0037  *
0038  * videobuf_dma_free()
0039  *  no comment ...
0040  *
0041  */
0042
0043 struct videobuf_dmabuf {
0044     u32                 magic;
0045
0046     /* for userland buffer */
0047     int                 offset;
0048     size_t          size;
0049     struct page         **pages;
0050
0051     /* for kernel buffers */
0052     void                *vaddr;
0053     struct page         **vaddr_pages;
0054     dma_addr_t          *dma_addr;
0055     struct device       *dev;
0056
0057     /* for overlay buffers (pci-pci dma) */
0058     dma_addr_t          bus_addr;
0059
0060     /* common */
0061     struct scatterlist  *sglist;
0062     int                 sglen;
0063     unsigned long       nr_pages;
0064     int                 direction;
0065 };
0066
0067 struct videobuf_dma_sg_memory {
0068     u32                 magic;
0069
0070     /* for mmap'ed buffers */
0071     struct videobuf_dmabuf  dma;
0072 };
0073
0074 /*
0075  * Scatter-gather DMA buffer API.
0076  *
0077  * These functions provide a simple way to create a page list and a
0078  * scatter-gather list from a kernel, userspace of physical address and map the
0079  * memory for DMA operation.
0080  *
0081  * Despite the name, this is totally unrelated to videobuf, except that
0082  * videobuf-dma-sg uses the same API internally.
0083  */
0084 int videobuf_dma_free(struct videobuf_dmabuf *dma);
0085
0086 int videobuf_dma_unmap(struct device *dev, struct videobuf_dmabuf *dma);
0087 struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf);
0088
0089 void *videobuf_sg_alloc(size_t size);
0090
0091 void videobuf_queue_sg_init(struct videobuf_queue *q,
0092              const struct videobuf_queue_ops *ops,
0093              struct device *dev,
0094              spinlock_t *irqlock,
0095              enum v4l2_buf_type type,
0096              enum v4l2_field field,
0097              unsigned int msize,
0098              void *priv,
0099              struct mutex *ext_lock);
0100
0101 #endif /* _VIDEOBUF_DMA_SG_H */
0102