libcamera  v0.3.0
Supporting cameras in Linux since 2019
v4l2_videodevice.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2 /*
3  * Copyright (C) 2019, Google Inc.
4  *
5  * V4L2 Video Device
6  */
7 
8 #pragma once
9 
10 #include <array>
11 #include <atomic>
12 #include <memory>
13 #include <optional>
14 #include <ostream>
15 #include <stdint.h>
16 #include <string>
17 #include <unordered_set>
18 #include <vector>
19 
20 #include <linux/videodev2.h>
21 
22 #include <libcamera/base/class.h>
23 #include <libcamera/base/log.h>
24 #include <libcamera/base/signal.h>
25 #include <libcamera/base/timer.h>
27 #include <libcamera/base/utils.h>
28 
29 #include <libcamera/color_space.h>
30 #include <libcamera/framebuffer.h>
31 #include <libcamera/geometry.h>
32 #include <libcamera/pixel_format.h>
33 
37 
38 namespace libcamera {
39 
40 class EventNotifier;
41 class MediaDevice;
42 class MediaEntity;
43 
44 struct V4L2Capability final : v4l2_capability {
45  const char *driver() const
46  {
47  return reinterpret_cast<const char *>(v4l2_capability::driver);
48  }
49  const char *card() const
50  {
51  return reinterpret_cast<const char *>(v4l2_capability::card);
52  }
53  const char *bus_info() const
54  {
55  return reinterpret_cast<const char *>(v4l2_capability::bus_info);
56  }
57  unsigned int device_caps() const
58  {
59  return capabilities & V4L2_CAP_DEVICE_CAPS
60  ? v4l2_capability::device_caps
61  : v4l2_capability::capabilities;
62  }
63  bool isMultiplanar() const
64  {
65  return device_caps() & (V4L2_CAP_VIDEO_CAPTURE_MPLANE |
66  V4L2_CAP_VIDEO_OUTPUT_MPLANE |
67  V4L2_CAP_VIDEO_M2M_MPLANE);
68  }
69  bool isCapture() const
70  {
71  return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
72  V4L2_CAP_VIDEO_CAPTURE_MPLANE |
73  V4L2_CAP_META_CAPTURE);
74  }
75  bool isOutput() const
76  {
77  return device_caps() & (V4L2_CAP_VIDEO_OUTPUT |
78  V4L2_CAP_VIDEO_OUTPUT_MPLANE |
79  V4L2_CAP_META_OUTPUT);
80  }
81  bool isVideo() const
82  {
83  return device_caps() & (V4L2_CAP_VIDEO_CAPTURE |
84  V4L2_CAP_VIDEO_CAPTURE_MPLANE |
85  V4L2_CAP_VIDEO_OUTPUT |
86  V4L2_CAP_VIDEO_OUTPUT_MPLANE);
87  }
88  bool isM2M() const
89  {
90  return device_caps() & (V4L2_CAP_VIDEO_M2M |
91  V4L2_CAP_VIDEO_M2M_MPLANE);
92  }
93  bool isMeta() const
94  {
95  /* Treat devs which combine video and meta as video not meta */
96  if (isVideo())
97  return false;
98 
99  return device_caps() & (V4L2_CAP_META_CAPTURE |
100  V4L2_CAP_META_OUTPUT);
101  }
102  bool isVideoCapture() const
103  {
104  return isVideo() && isCapture();
105  }
106  bool isVideoOutput() const
107  {
108  return isVideo() && isOutput();
109  }
110  bool isMetaCapture() const
111  {
112  return isMeta() && isCapture();
113  }
114  bool isMetaOutput() const
115  {
116  return isMeta() && isOutput();
117  }
118  bool hasStreaming() const
119  {
120  return device_caps() & V4L2_CAP_STREAMING;
121  }
122  bool hasMediaController() const
123  {
124  return device_caps() & V4L2_CAP_IO_MC;
125  }
126 };
127 
129 {
130 public:
131  V4L2BufferCache(unsigned int numEntries);
132  V4L2BufferCache(const std::vector<std::unique_ptr<FrameBuffer>> &buffers);
133  ~V4L2BufferCache();
134 
135  bool isEmpty() const;
136  int get(const FrameBuffer &buffer);
137  void put(unsigned int index);
138 
139 private:
140  class Entry
141  {
142  public:
143  Entry();
144  Entry(bool free, uint64_t lastUsed, const FrameBuffer &buffer);
145 
146  bool operator==(const FrameBuffer &buffer) const;
147 
148  bool free_;
149  uint64_t lastUsed_;
150 
151  private:
152  struct Plane {
153  Plane(const FrameBuffer::Plane &plane)
154  : fd(plane.fd.get()), length(plane.length)
155  {
156  }
157 
158  int fd;
159  unsigned int length;
160  };
161 
162  std::vector<Plane> planes_;
163  };
164 
165  std::atomic<uint64_t> lastUsedCounter_;
166  std::vector<Entry> cache_;
167  /* \todo Expose the miss counter through an instrumentation API. */
168  unsigned int missCounter_;
169 };
170 
172 {
173 public:
174  struct Plane {
175  uint32_t size = 0;
176  uint32_t bpl = 0;
177  };
178 
181  std::optional<ColorSpace> colorSpace;
182 
183  std::array<Plane, 3> planes;
184  unsigned int planesCount = 0;
185 
186  const std::string toString() const;
187 };
188 
189 std::ostream &operator<<(std::ostream &out, const V4L2DeviceFormat &f);
190 
192 {
193 public:
194  using Formats = std::map<V4L2PixelFormat, std::vector<SizeRange>>;
195 
196  explicit V4L2VideoDevice(const std::string &deviceNode);
197  explicit V4L2VideoDevice(const MediaEntity *entity);
198  ~V4L2VideoDevice();
199 
200  int open();
201  int open(SharedFD handle, enum v4l2_buf_type type);
202  void close();
203 
204  const char *driverName() const { return caps_.driver(); }
205  const char *deviceName() const { return caps_.card(); }
206  const char *busName() const { return caps_.bus_info(); }
207 
208  const V4L2Capability &caps() const { return caps_; }
209 
210  int getFormat(V4L2DeviceFormat *format);
211  int tryFormat(V4L2DeviceFormat *format);
212  int setFormat(V4L2DeviceFormat *format);
213  Formats formats(uint32_t code = 0);
214 
215  int setSelection(unsigned int target, Rectangle *rect);
216 
217  int allocateBuffers(unsigned int count,
218  std::vector<std::unique_ptr<FrameBuffer>> *buffers);
219  int exportBuffers(unsigned int count,
220  std::vector<std::unique_ptr<FrameBuffer>> *buffers);
221  int importBuffers(unsigned int count);
222  int releaseBuffers();
223 
224  int queueBuffer(FrameBuffer *buffer);
226 
227  int streamOn();
228  int streamOff();
229 
230  void setDequeueTimeout(utils::Duration timeout);
232 
233  static std::unique_ptr<V4L2VideoDevice>
234  fromEntityName(const MediaDevice *media, const std::string &entity);
235 
236  V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const;
237 
238 protected:
239  std::string logPrefix() const override;
240 
241 private:
243 
244  enum class State {
245  Streaming,
246  Stopping,
247  Stopped,
248  };
249 
250  int initFormats();
251 
252  int getFormatMeta(V4L2DeviceFormat *format);
253  int trySetFormatMeta(V4L2DeviceFormat *format, bool set);
254 
255  int getFormatMultiplane(V4L2DeviceFormat *format);
256  int trySetFormatMultiplane(V4L2DeviceFormat *format, bool set);
257 
258  int getFormatSingleplane(V4L2DeviceFormat *format);
259  int trySetFormatSingleplane(V4L2DeviceFormat *format, bool set);
260 
261  std::vector<V4L2PixelFormat> enumPixelformats(uint32_t code);
262  std::vector<SizeRange> enumSizes(V4L2PixelFormat pixelFormat);
263 
264  int requestBuffers(unsigned int count, enum v4l2_memory memoryType);
265  int createBuffers(unsigned int count,
266  std::vector<std::unique_ptr<FrameBuffer>> *buffers);
267  std::unique_ptr<FrameBuffer> createBuffer(unsigned int index);
268  UniqueFD exportDmabufFd(unsigned int index, unsigned int plane);
269 
270  void bufferAvailable();
271  FrameBuffer *dequeueBuffer();
272 
273  void watchdogExpired();
274 
275  template<typename T>
276  static std::optional<ColorSpace> toColorSpace(const T &v4l2Format);
277 
278  V4L2Capability caps_;
279  V4L2DeviceFormat format_;
280  const PixelFormatInfo *formatInfo_;
281  std::unordered_set<V4L2PixelFormat> pixelFormats_;
282 
283  enum v4l2_buf_type bufferType_;
284  enum v4l2_memory memoryType_;
285 
286  V4L2BufferCache *cache_;
287  std::map<unsigned int, FrameBuffer *> queuedBuffers_;
288 
289  EventNotifier *fdBufferNotifier_;
290 
291  State state_;
292  std::optional<unsigned int> firstFrame_;
293 
294  Timer watchdog_;
295  utils::Duration watchdogDuration_;
296 };
297 
299 {
300 public:
301  V4L2M2MDevice(const std::string &deviceNode);
302  ~V4L2M2MDevice();
303 
304  int open();
305  void close();
306 
307  V4L2VideoDevice *output() { return output_; }
308  V4L2VideoDevice *capture() { return capture_; }
309 
310 private:
311  std::string deviceNode_;
312 
313  V4L2VideoDevice *output_;
314  V4L2VideoDevice *capture_;
315 };
316 
317 } /* namespace libcamera */
Utilities to help constructing class interfaces.
#define LIBCAMERA_DISABLE_COPY(klass)
Disable copy construction and assignment of the klass.
Notify of activity on a file descriptor.
Definition: event_notifier.h:20
Frame buffer data and its associated dynamic metadata.
Definition: framebuffer.h:50
The MediaDevice represents a Media Controller device with its full graph of connected objects.
Definition: media_device.h:26
The MediaEntity represents an entity in the media graph.
Definition: media_object.h:89
Information about pixel formats.
Definition: formats.h:22
libcamera image pixel format
Definition: pixel_format.h:18
Describe a rectangle's position and dimensions.
Definition: geometry.h:243
RAII-style wrapper for file descriptors.
Definition: shared_fd.h:17
int get() const
Retrieve the numerical file descriptor.
Definition: shared_fd.h:30
Generic signal and slot communication mechanism.
Definition: signal.h:40
Describe a two-dimensional size.
Definition: geometry.h:53
Single-shot timer interface.
Definition: timer.h:23
unique_ptr-like wrapper for a file descriptor
Definition: unique_fd.h:18
Hot cache of associations between V4L2 buffer indexes and FrameBuffer.
Definition: v4l2_videodevice.h:129
V4L2BufferCache(unsigned int numEntries)
Create an empty cache with numEntries entries.
Definition: v4l2_videodevice.cpp:175
int get(const FrameBuffer &buffer)
Find the best V4L2 buffer for a FrameBuffer.
Definition: v4l2_videodevice.cpp:230
bool isEmpty() const
Check if all the entries in the cache are unused.
Definition: v4l2_videodevice.cpp:207
void put(unsigned int index)
Mark buffer index as free in the cache.
Definition: v4l2_videodevice.cpp:272
The V4L2 video device image format and sizes.
Definition: v4l2_videodevice.h:172
V4L2PixelFormat fourcc
The fourcc code describing the pixel encoding scheme.
Definition: v4l2_videodevice.h:179
const std::string toString() const
Assemble and return a string describing the format.
Definition: v4l2_videodevice.cpp:433
std::array< Plane, 3 > planes
The per-plane memory size information.
Definition: v4l2_videodevice.h:183
Size size
The image size in pixels.
Definition: v4l2_videodevice.h:180
std::optional< ColorSpace > colorSpace
The color space of the pixels.
Definition: v4l2_videodevice.h:181
unsigned int planesCount
The number of valid data planes.
Definition: v4l2_videodevice.h:184
Base class for V4L2VideoDevice and V4L2Subdevice.
Definition: v4l2_device.h:32
const std::string & deviceNode() const
Retrieve the device node path.
Definition: v4l2_device.h:44
Memory-to-Memory video device.
Definition: v4l2_videodevice.h:299
V4L2VideoDevice * capture()
Retrieve the capture V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:308
void close()
Close the memory-to-memory device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:2155
int open()
Open a V4L2 Memory to Memory device.
Definition: v4l2_videodevice.cpp:2118
V4L2VideoDevice * output()
Retrieve the output V4L2VideoDevice instance.
Definition: v4l2_videodevice.h:307
V4L2M2MDevice(const std::string &deviceNode)
Create a new V4L2M2MDevice from the deviceNode.
Definition: v4l2_videodevice.cpp:2097
V4L2 pixel format FourCC wrapper.
Definition: v4l2_pixelformat.h:24
V4L2VideoDevice object and API.
Definition: v4l2_videodevice.h:192
std::map< V4L2PixelFormat, std::vector< SizeRange > > Formats
A map of supported V4L2 pixel formats to frame sizes.
Definition: v4l2_videodevice.h:194
Signal dequeueTimeout
A Signal emitted when the dequeue watchdog timer expires.
Definition: v4l2_videodevice.h:231
const char * driverName() const
Retrieve the name of the V4L2 device driver.
Definition: v4l2_videodevice.h:204
int importBuffers(unsigned int count)
Prepare the device to import count buffers.
Definition: v4l2_videodevice.cpp:1506
int releaseBuffers()
Release resources allocated by allocateBuffers() or importBuffers()
Definition: v4l2_videodevice.cpp:1534
int tryFormat(V4L2DeviceFormat *format)
Try an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:824
const char * deviceName() const
Retrieve the name of the V4L2 video device.
Definition: v4l2_videodevice.h:205
std::string logPrefix() const override
Retrieve a string to be prefixed to the log message.
Definition: v4l2_videodevice.cpp:793
void setDequeueTimeout(utils::Duration timeout)
Set the dequeue timeout value.
Definition: v4l2_videodevice.cpp:1985
int allocateBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer >> *buffers)
Allocate and export buffers from the video device.
Definition: v4l2_videodevice.cpp:1287
int open()
Open the V4L2 video device node and query its capabilities.
Definition: v4l2_videodevice.cpp:570
int streamOn()
Start the video stream.
Definition: v4l2_videodevice.cpp:1898
int queueBuffer(FrameBuffer *buffer)
Queue a buffer to the video device.
Definition: v4l2_videodevice.cpp:1564
V4L2VideoDevice(const std::string &deviceNode)
Construct a V4L2VideoDevice.
Definition: v4l2_videodevice.cpp:535
int streamOff()
Stop the video stream.
Definition: v4l2_videodevice.cpp:1931
int getFormat(V4L2DeviceFormat *format)
Retrieve the image format set on the V4L2 video device.
Definition: v4l2_videodevice.cpp:804
void close()
Close the video device, releasing any resources acquired by open()
Definition: v4l2_videodevice.cpp:756
const char * busName() const
Retrieve the location of the device in the system.
Definition: v4l2_videodevice.h:206
static std::unique_ptr< V4L2VideoDevice > fromEntityName(const MediaDevice *media, const std::string &entity)
Create a new video device instance from entity in media device media.
Definition: v4l2_videodevice.cpp:2022
int setSelection(unsigned int target, Rectangle *rect)
Set a selection rectangle rect for target.
Definition: v4l2_videodevice.cpp:1201
const V4L2Capability & caps() const
Retrieve the device V4L2 capabilities.
Definition: v4l2_videodevice.h:208
Signal< FrameBuffer * > bufferReady
A Signal emitted when a framebuffer completes.
Definition: v4l2_videodevice.h:225
V4L2PixelFormat toV4L2PixelFormat(const PixelFormat &pixelFormat) const
Convert PixelFormat to a V4L2PixelFormat supported by the device.
Definition: v4l2_videodevice.cpp:2053
int setFormat(V4L2DeviceFormat *format)
Configure an image format on the V4L2 video device.
Definition: v4l2_videodevice.cpp:843
Formats formats(uint32_t code=0)
Enumerate all pixel formats and frame sizes.
Definition: v4l2_videodevice.cpp:1078
int exportBuffers(unsigned int count, std::vector< std::unique_ptr< FrameBuffer >> *buffers)
Export buffers from the video device.
Definition: v4l2_videodevice.cpp:1336
Helper class from std::chrono::duration that represents a time duration in nanoseconds with double pr...
Definition: utils.h:330
Class and enums to represent color spaces.
Frame buffer handling.
Data structures related to geometric objects.
Types and helper functions to handle libcamera image formats.
Logging infrastructure.
Top-level libcamera namespace.
Definition: backtrace.h:17
std::ostream & operator<<(std::ostream &out, const Point &p)
Insert a text representation of a Point into an output stream.
Definition: geometry.cpp:91
bool operator==(const ColorSpace &lhs, const ColorSpace &rhs)
Compare color spaces for equality.
Definition: color_space.cpp:506
libcamera pixel format
Signal & slot implementation.
A memory region to store a single plane of a frame.
Definition: framebuffer.h:54
unsigned int length
The plane length in bytes.
Definition: framebuffer.h:58
SharedFD fd
The dmabuf file descriptor.
Definition: framebuffer.h:56
struct v4l2_capability object wrapper and helpers
Definition: v4l2_videodevice.h:44
bool hasStreaming() const
Determine if the video device can perform Streaming I/O.
Definition: v4l2_videodevice.h:118
unsigned int device_caps() const
Retrieve the capabilities of the video device.
Definition: v4l2_videodevice.h:57
bool isVideoOutput() const
Identify if the video device outputs images.
Definition: v4l2_videodevice.h:106
bool isM2M() const
Identify if the device is a Memory-to-Memory device.
Definition: v4l2_videodevice.h:88
bool isMetaCapture() const
Identify if the video device captures image meta-data.
Definition: v4l2_videodevice.h:110
bool hasMediaController() const
Determine if the video device uses Media Controller to configure I/O.
Definition: v4l2_videodevice.h:122
bool isOutput() const
Identify if the video device outputs data.
Definition: v4l2_videodevice.h:75
bool isVideoCapture() const
Identify if the video device captures images.
Definition: v4l2_videodevice.h:102
bool isMultiplanar() const
Identify if the video device implements the V4L2 multiplanar APIs.
Definition: v4l2_videodevice.h:63
bool isMeta() const
Identify if the video device captures or outputs image meta-data.
Definition: v4l2_videodevice.h:93
bool isCapture() const
Identify if the video device captures data.
Definition: v4l2_videodevice.h:69
bool isMetaOutput() const
Identify if the video device outputs image meta-data.
Definition: v4l2_videodevice.h:114
const char * bus_info() const
Retrieve the location of the video device in the system.
Definition: v4l2_videodevice.h:53
const char * card() const
Retrieve the video device card name.
Definition: v4l2_videodevice.h:49
bool isVideo() const
Identify if the video device captures or outputs images.
Definition: v4l2_videodevice.h:81
const char * driver() const
Retrieve the driver module name.
Definition: v4l2_videodevice.h:45
Per-plane memory size information.
Definition: v4l2_videodevice.h:174
uint32_t size
The plane total memory size (in bytes)
Definition: v4l2_videodevice.h:175
uint32_t bpl
The plane line stride (in bytes)
Definition: v4l2_videodevice.h:176
Generic timer.
File descriptor wrapper that owns a file descriptor.
Miscellaneous utility functions.
Common base for V4L2 devices and subdevices.
V4L2 Pixel Format.