From a1f18fdc72a4dc7315f7bd14d6cb30dde42ce6eb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Dec 2017 10:42:26 -0500 Subject: media: dvb uAPI docs: document mmap-related ioctls 5 new ioctls were added to the DVB demux API, in order to handle memory maped I/O. Add documentation for them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dmx-expbuf.rst | 90 +++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 Documentation/media/uapi/dvb/dmx-expbuf.rst (limited to 'Documentation/media/uapi/dvb/dmx-expbuf.rst') diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst new file mode 100644 index 000000000000..51df34c6fb59 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -0,0 +1,90 @@ +.. _DMX_EXPBUF: + +**************** +ioctl DMX_EXPBUF +**************** + +Name +==== + +DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) + :name: DMX_EXPBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``argp`` + Pointer to struct :c:type:`dmx_exportbuffer`. + + +Description +=========== + +This ioctl is an extension to the memory mapping I/O method. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. + +The ``reserved`` array must be zeroed before calling it. + +To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. +Applications must set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dmx_requestbuffers` ``count``) minus one. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. +All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`DMX_EXPBUF` calls. + +After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a +driver, on success. This is a DMABUF file descriptor. The application may +pass it to other DMABUF-aware devices. It is recommended to close a DMABUF +file when it is no longer used to allow the associated memory to be reclaimed. + + +Examples +======== + + +.. code-block:: c + + int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) + { + struct dmx_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { + perror("DMX_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``index`` fields are invalid. -- cgit From a114a585be4f3173fe454921a0918fb7e71633b0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Dec 2017 10:57:13 -0500 Subject: media: dvb-core: get rid of mmap reserved field The "reserved" field was a way, used at V4L2 API, to add new data to existing structs without breaking userspace. However, there are now clever ways of doing that, without needing to add an uneeded overhead. So, get rid of them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dmx-expbuf.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'Documentation/media/uapi/dvb/dmx-expbuf.rst') diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst index 51df34c6fb59..2d96cfe891df 100644 --- a/Documentation/media/uapi/dvb/dmx-expbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -36,8 +36,6 @@ This ioctl is an extension to the memory mapping I/O method. It can be used to export a buffer as a DMABUF file at any time after buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. -The ``reserved`` array must be zeroed before calling it. - To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. Applications must set the ``index`` field. Valid index numbers range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` -- cgit