8ac8ecb1e1
Introduce a Fence class which models a synchronization primitive that allows to notify the availability of a resource. The Fence is modeled as a wrapper of a UniqueFD instance where read events are used to signal the Fence. The class can be later extended to support additional signalling mechanisms. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
113 lines
3.7 KiB
C++
113 lines
3.7 KiB
C++
/* SPDX-License-Identifier: LGPL-2.1-or-later */
|
|
/*
|
|
* Copyright (C) 2021, Google Inc.
|
|
*
|
|
* fence.cpp - Synchronization fence
|
|
*/
|
|
|
|
#include "libcamera/fence.h"
|
|
|
|
namespace libcamera {
|
|
|
|
/**
|
|
*
|
|
* \file libcamera/fence.h
|
|
* \brief Definition of the Fence class
|
|
*/
|
|
|
|
/**
|
|
* \class Fence
|
|
* \brief Synchronization primitive to manage resources
|
|
*
|
|
* The Fence class models a synchronization primitive that can be used by
|
|
* applications to explicitly synchronize resource usage, and can be shared by
|
|
* multiple processes.
|
|
*
|
|
* Fences are most commonly used in association with frame buffers. A
|
|
* FrameBuffer can be associated with a Fence so that the library can wait for
|
|
* the Fence to be signalled before allowing the camera device to actually
|
|
* access the memory area described by the FrameBuffer.
|
|
*
|
|
* \sa Request::addBuffer()
|
|
*
|
|
* By using a fence, applications can then synchronize between frame buffer
|
|
* consumers and producers, as for example a display device and a camera, to
|
|
* guarantee that a new data transfers only happen once the existing frames have
|
|
* been displayed.
|
|
*
|
|
* A Fence can be realized by different event notification primitives, the most
|
|
* common of which is represented by waiting for read events to happen on a
|
|
* <a href="https://www.kernel.org/doc/html/latest/driver-api/sync_file.html">kernel sync file.</a>
|
|
* This is currently the only mechanism supported by libcamera, but others can
|
|
* be implemented by extending or subclassing this class and implementing
|
|
* opportune handling in the core library.
|
|
*
|
|
* \internal
|
|
*
|
|
* The Fence class is a thin abstraction around a UniqueFD which simply allows
|
|
* to access it as a const reference or to move its ownership to the caller.
|
|
*
|
|
* The usage of the Fence class allows to abstract the underlying
|
|
* synchronization mechanism in use and implement an interface towards other
|
|
* library components that will not change when new synchronization primitives
|
|
* will be added as fences.
|
|
*
|
|
* A Fence is constructed with a UniqueFD whose ownership is moved in the Fence.
|
|
* A FrameBuffer can be associated with a Fence by passing it to the
|
|
* Request::addBuffer() function, which will move the Fence into the FrameBuffer
|
|
* itself. Once a Request is queued to the Camera, a preparation phase
|
|
* guarantees that before actually applying the Request to the hardware, all the
|
|
* valid fences of the frame buffers in a Request are correctly signalled. Once
|
|
* a Fence has completed, the library will release the FrameBuffer fence so that
|
|
* application won't be allowed to access it.
|
|
*
|
|
* An optional timeout can be started while waiting for a fence to complete. If
|
|
* waiting on a Fence fails for whatever reason, the FrameBuffer's fence is not
|
|
* reset and is made available to application for them to handle it, by
|
|
* releasing the Fence to correctly close the underlying UniqueFD.
|
|
*
|
|
* A failure in waiting for a Fence to complete will result in the Request to
|
|
* complete in failed state.
|
|
*
|
|
* \sa Request::prepare()
|
|
* \sa PipelineHandler::doQueueRequests()
|
|
*/
|
|
|
|
/**
|
|
* \brief Create a Fence
|
|
* \param[in] fd The fence file descriptor
|
|
*
|
|
* The file descriptor ownership is moved to the Fence.
|
|
*/
|
|
Fence::Fence(UniqueFD fd)
|
|
: fd_(std::move(fd))
|
|
{
|
|
}
|
|
|
|
/**
|
|
* \fn Fence::isValid()
|
|
* \brief Check if a Fence is valid
|
|
*
|
|
* A Fence is valid if the file descriptor it wraps is valid.
|
|
*
|
|
* \return True if the Fence is valid, false otherwise
|
|
*/
|
|
|
|
/**
|
|
* \fn Fence::fd()
|
|
* \brief Retrieve a constant reference to the file descriptor
|
|
* \return A const reference to the fence file descriptor
|
|
*/
|
|
|
|
/**
|
|
* \fn Fence::release()
|
|
* \brief Release the ownership of the file descriptor
|
|
*
|
|
* Release the ownership of the wrapped file descriptor by returning it to the
|
|
* caller.
|
|
*
|
|
* \return The wrapper UniqueFD
|
|
*/
|
|
|
|
} /* namespace libcamera */
|