[media] videobuf2-core.h: improve documentation

Document that drivers can access/modify the buffer contents in buf_prepare
and buf_finish. That was not clearly stated before.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Pawel Osciak <pawel@osciak.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 6ef2d01197da95db59aea39eddc1d0b80592b0b6..70ace7cc6087151dc18c4ec3d3aba1091f5cc870 100644 (file)
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -270,22 +270,24 @@ struct vb2_buffer {
  *                     queue setup from completing successfully; optional.
  * @buf_prepare:       called every time the buffer is queued from userspace
  *                     and from the VIDIOC_PREPARE_BUF ioctl; drivers may
- *                     perform any initialization required before each hardware
- *                     operation in this callback; drivers that support
- *                     VIDIOC_CREATE_BUFS must also validate the buffer size;
- *                     if an error is returned, the buffer will not be queued
- *                     in driver; optional.
+ *                     perform any initialization required before each
+ *                     hardware operation in this callback; drivers can
+ *                     access/modify the buffer here as it is still synced for
+ *                     the CPU; drivers that support VIDIOC_CREATE_BUFS must
+ *                     also validate the buffer size; if an error is returned,
+ *                     the buffer will not be queued in driver; optional.
  * @buf_finish:                called before every dequeue of the buffer back to
- *                     userspace; drivers may perform any operations required
- *                     before userspace accesses the buffer; optional. The
- *                     buffer state can be one of the following: DONE and
- *                     ERROR occur while streaming is in progress, and the
- *                     PREPARED state occurs when the queue has been canceled
- *                     and all pending buffers are being returned to their
- *                     default DEQUEUED state. Typically you only have to do
- *                     something if the state is VB2_BUF_STATE_DONE, since in
- *                     all other cases the buffer contents will be ignored
- *                     anyway.
+ *                     userspace; the buffer is synced for the CPU, so drivers
+ *                     can access/modify the buffer contents; drivers may
+ *                     perform any operations required before userspace
+ *                     accesses the buffer; optional. The buffer state can be
+ *                     one of the following: DONE and ERROR occur while
+ *                     streaming is in progress, and the PREPARED state occurs
+ *                     when the queue has been canceled and all pending
+ *                     buffers are being returned to their default DEQUEUED
+ *                     state. Typically you only have to do something if the
+ *                     state is VB2_BUF_STATE_DONE, since in all other cases
+ *                     the buffer contents will be ignored anyway.
  * @buf_cleanup:       called once before the buffer is freed; drivers may
  *                     perform any additional cleanup; optional.
  * @start_streaming:   called once to enter 'streaming' state; the driver may