[libcamera-devel] [PATCH 3/8] libcamera: camera: document return values for application facing functions

[Niklas Söderlund]

Hi Laurent,

Thanks for your feedback.

On 2019-02-27 15:01:07 +0200, Laurent Pinchart wrote:
> Hello,
> 
> On Wed, Feb 27, 2019 at 10:48:29AM +0100, Jacopo Mondi wrote:
> > On Tue, Feb 26, 2019 at 07:53:50PM +0100, Niklas Söderlund wrote:
> > > On 2019-02-26 17:56:09 +0100, Jacopo Mondi wrote:
> > >> On Tue, Feb 26, 2019 at 03:18:52AM +0100, Niklas Söderlund wrote:
> > >>> In preparation for adding a state machine to control access to the
> > >>> functions facing the application document the error codes which will be
> > >>> returned once it's in place.
> > >>>
> > >>> Signed-off-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
> > >>> ---
> > >>>  src/libcamera/camera.cpp | 12 +++++++++---
> > >>>  1 file changed, 9 insertions(+), 3 deletions(-)
> > >>>
> > >>> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> > >>> index e2372fea31e2921a..d4258fe3c7551af3 100644
> > >>> --- a/src/libcamera/camera.cpp
> > >>> +++ b/src/libcamera/camera.cpp
> > >>> @@ -158,6 +158,7 @@ void Camera::disconnect()
> > >>>   * \todo Implement exclusive access across processes.
> > >>>   *
> > >>>   * \return 0 on success or a negative error code
> > >>> + * \retval -EBUSY The camera is not free and can't be acquired by the caller.
> > >>>   */
> > >>>  int Camera::acquire()
> > >>>  {
> > >>> @@ -236,9 +237,8 @@ Camera::streamConfiguration(std::vector<Stream *> &streams)
> > >>>   * to calling this function, otherwise an -EACCES error will be returned.
> > >>>   *
> > >>>   * \return 0 on success or a negative error code
> > >>> - * \retval -ENODEV The camera is not connected to any hardware
> > >>> - * \retval -EACCES The user has not acquired exclusive access to the camera
> > >>> - * \retval -EINVAL The configuration is not valid
> > >>> + * \retval -EACCES The camera is not in a state where it can be configured.
> 
> Did we standardize on periods at the end of \retval statements ?

Woops, I think we standardize on not having . at the end of \retval 
statement. At least that what the rest of the code base does, will 
remove it for v2.

> 
> > >>
> > >> I'm not sure I like "the camera is not in a state where", here and in other
> > >> places, but I got nothing better to offer, so feel free to keep it there :)
> 
> Wouldn't it make sense to keep a different return code to report camera
> disconnection, to simplify hot-unplug handling ?

I wrestled with they question myself when writing this but abandoned to 
try and keep the logic simple. But as you now suggest it I will give it 
another try and see if I can add it and still keep it simple.

> 
> > >>> + * \retval -EINVAL The configuration is not valid.
> > >>>   */
> > >>>  int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
> > >>>  {
> > >>> @@ -279,6 +279,8 @@ int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
> > >>>  /**
> > >>>   * \brief Allocate buffers for all configured streams
> > >>>   * \return 0 on success or a negative error code
> > >>> + * \retval -EACCES The camera is not in a state where it can allocate buffers.
> > >>> + * \retval -EINVAL The configuration is not valid.
> > >>>   */
> > >>>  int Camera::allocateBuffers()
> > >>>  {
> > >>> @@ -330,6 +332,7 @@ void Camera::freeBuffers()
> > >>>   * responsible for either queueing the request or deleting it.
> > >>>   *
> > >>>   * \return A pointer to the newly created request, or nullptr on error
> > >>> + * \retval -EACCES The camera is not in a state where requests can be created.
> > >>
> > >> This returns nullptr, am I wrong?
> > >
> > > Correct, my bad will drop this change for v2.
> > >
> > >>>   */
> > >>>  Request *Camera::createRequest()
> > >>>  {
> > >>> @@ -351,6 +354,7 @@ Request *Camera::createRequest()
> > >>>   * automatically after it completes.
> > >>>   *
> > >>>   * \return 0 on success or a negative error code
> > >>> + * \retval -EACCES The camera is not running so requests can't be queued.
> > >>
> > >> I think this returns EBUSY, right?
> > >>
> > >> Well, I assume this patch should come after you have changed the code,
> > >> which I assume happens later in the series, otherwise it is difficult
> > >> to make sure the comments are correct.
> > >
> > > As the commit message says this updates the documentation only for the
> > > new return codes which are introduced in 5/8. I contemplated squashing
> > > the two but opted to keep the separate.
> > >
> > > As the cam tool needs to be updated (patch 4/5) before the state machine
> > > is added I judged it to be easier to review this in these three parts;
> > > documentation, cam tool, state machine. As it the cam tool change would
> > > then make sens. If this is confusing I can squash this in with 5/8. Let
> > > me know what you think.
> > 
> > No need to squash if you don't want to, I was just pointing out that
> > to make sure documentation is updated properly, I had to look at this
> > after 5/8 is applied. I would have just re-sorted them, but that's
> > fine.
> 
> I would have squashed them too. If this was about code you'd create a
> bisection error, and it's more difficult to review this way. No big deal
> though.

I will squash it in v2 as it's now served it's purpose to to spur 
discussion :-)

> 
> > >>>   */
> > >>>  int Camera::queueRequest(Request *request)
> > >>>  {
> > >>> @@ -377,6 +381,7 @@ int Camera::queueRequest(Request *request)
> > >>>   * until the capture session is terminated with \a stop().
> > >>>   *
> > >>>   * \return 0 on success or a negative error code
> > >>> + * \retval -EACCES The camera is not in a state where it can be started.
> > >>>   */
> > >>>  int Camera::start()
> > >>>  {
> > >>> @@ -396,6 +401,7 @@ int Camera::start()
> > >>>   * requests are cancelled and complete synchronously in an error state.
> > >>>   *
> > >>>   * \return 0 on success or a negative error code
> > >>> + * \retval -EACCES The camera is not running so can't be stopped.
> > >>>   */
> > >>>  int Camera::stop()
> > >>>  {
> 
> -- 
> Regards,
> 
> Laurent Pinchart

-- 
Regards,
Niklas Söderlund