diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-12-21 10:42:26 -0500 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-12-28 11:17:30 -0500 |
commit | a1f18fdc72a4dc7315f7bd14d6cb30dde42ce6eb (patch) | |
tree | e4ef97beb644e712af58a7b168f3a529799f2e79 /Documentation/media/uapi/dvb/dmx-qbuf.rst | |
parent | f8aaf487712be2529f0e757643e04edf0aa9d5cb (diff) |
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 <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/dvb/dmx-qbuf.rst')
-rw-r--r-- | Documentation/media/uapi/dvb/dmx-qbuf.rst | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst new file mode 100644 index 000000000000..b20b8153d48d --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -0,0 +1,85 @@ +.. _DMX_QBUF: + +************************* +ioctl DMX_QBUF, DMX_DQBUF +************************* + +Name +==== + +DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver + +.. warning:: this API is still experimental + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) + :name: DMX_QBUF + +.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) + :name: DMX_DQBUF + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <dmx_fopen>`. + +``argp`` + Pointer to struct :c:type:`dmx_buffer`. + + +Description +=========== + +Applications call the ``DMX_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications 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. The contents of the struct :c:type:`dmx_buffer` returned +by a :ref:`DMX_QUERYBUF` ioctl will do as well. + +The and ``reserved`` field must be set to 0. + +When ``DMX_QBUF`` is called with a pointer to this structure, it locks the +memory pages of the buffer in physical memory, so they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +the device is closed. + +Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled +(capturing) buffer from the driver's outgoing queue. They just set the ``reserved`` field array to zero. When ``DMX_DQBUF`` is called with a +pointer to this structure, the driver fills the remaining fields or +returns an error code. + +By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:ref:`open() <dmx_fopen>` function, ``DMX_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The struct :c:type:`dmx_buffer` structure is specified in +:ref:`buffer`. + + +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 <gen-errors>` chapter. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The ``index`` is out of bounds, or no buffers have been allocated yet. + +EIO + ``DMX_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss or CRC errors. |