Re: [Xen-devel][PATCH v4 1/1] cameraif: add ABI for para-virtual camera

[Hans Verkuil <hverkuil@xs4all.nl>]

On 2/5/19 1:30 PM, Oleksandr Andrushchenko wrote:
>> Sorry for paying so much attention to this, but I think it is important that
>> this is documented precisely.
> Thank you for helping with this - your comments are really
> important and make the description precise. Ok, so finally:
> 
>  * num_bufs - uint8_t, desired number of buffers to be used.
>  *
>  * If num_bufs is not zero then the backend validates the requested number of
>  * buffers and responds with the number of buffers allowed for this frontend.
>  * Frontend is responsible for checking the corresponding response in order to
>  * see if the values reported back by the backend do match the desired ones
>  * and can be accepted.
>  * Frontend is allowed to send multiple XENCAMERA_OP_BUF_REQUEST requests
>  * before sending XENCAMERA_OP_STREAM_START request to update or tune the
>  * final configuration.
>  * Frontend is not allowed to change the number of buffers and/or camera
>  * configuration after the streaming has started.
>  *
>  * If num_bufs is 0 and streaming has not started yet, then the backend may
>  * free all previously allocated buffers (if any) or do nothing.

I would rephrase this:

* If num_bufs is 0 and streaming has not started yet, then the backend will
* free all previously allocated buffers (if any).

The previous text suggested that the backend might choose not to free
the allocated buffers, but that's not the case.

>  * Trying to call this if streaming is in progress will result in an error.
>  *
>  * If camera reconfiguration is required then the streaming must be stopped
>  * and this request must be sent with num_bufs set to zero and finally
>  * buffers destroyed.
>  *
>  * Please note, that the number of buffers in this request must not exceed
>  * the value configured in XenStore.max-buffers.
>  *
>  * See response format for this request.

With that small change the text looks good to me.

Regards,

	Hans