1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
/* 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 */
|
