libcamera: Define and use MediaDeviceMatch

The xistingdevice search and match criteria implemented by libcamera
only supports 'media device' based cameras, which are supported in the
Linux kernel by the usage of the V4L2/MC API.

Define a MediaDeviceMatch class derived from DeviceMatch and use it
wherever DeviceMatch was used in order to later introduce new derived
classes to support searching and matching devices of a different type.

Signed-off-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>

10 files changed, 37 insertions, 19 deletions

diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp
index 49afd783..3dda0838 100644
--- a/src/libcamera/device_enumerator.cpp
+++ b/src/libcamera/device_enumerator.cpp
@@ -229,7 +229,7 @@ void DeviceEnumerator::removeDevice(const std::string &deviceNode)
  *
  * \return pointer to the matching MediaDevice, or nullptr if no match is found
  */
-std::shared_ptr<MediaDevice> DeviceEnumerator::search(const DeviceMatch &dm)
+std::shared_ptr<MediaDevice> DeviceEnumerator::search(const MediaDeviceMatch &dm)
 {
 	for (std::shared_ptr<MediaDevice> &media : devices_) {
 		if (media->busy())
diff --git a/src/libcamera/device_match.cpp b/src/libcamera/device_match.cpp
index a51b9081..17937d43 100644
--- a/src/libcamera/device_match.cpp
+++ b/src/libcamera/device_match.cpp
@@ -18,21 +18,38 @@ namespace libcamera {
 
 /**
  * \class DeviceMatch
+ * \brief Pure virtual base class for device serch pattern
+ *
+ * The DeviceMatch class defines the interface to implement device search
+ * patterns to allow searching and matching different device typologies, such as
+ * media devices for V4L2/MC cameras, USB for cameras controlled through the USB
+ * protocol which do not implement the UVC specification and for virtual
+ * cameras.
+ *
+ * Pipeline handlers are expected to instantiate the correct derived class
+ * depending on the device type they support and populate it with their desired
+ * matching criteria. Derived classes of DeviceMatch override the pure virtual
+ * match() function to implement custom matching criteria based on the device
+ * type they represent.
+ */
+
+/**
+ * \class MediaDeviceMatch
  * \brief Description of a media device search pattern
  *
- * The DeviceMatch class describes a media device using properties from the
+ * The MediaDeviceMatch class describes a media device using properties from the
  * Media Controller struct media_device_info, entity names in the media graph
  * or other properties that can be used to identify a media device.
  *
  * The description is meant to be filled by pipeline managers and passed to a
  * device enumerator to find matching media devices.
  *
- * A DeviceMatch is created with a specific Linux device driver in mind,
+ * A MediaDeviceMatch is created with a specific Linux device driver in mind,
  * therefore the name of the driver is a required property. One or more Entity
  * names can be added as match criteria.
  *
- * Pipeline handlers are recommended to add entities to DeviceMatch as
- * appropriare to ensure that the media device they need can be uniquely
+ * Pipeline handlers are recommended to add entities to MediaDeviceMatch as
+ * appropriate to ensure that the media device they need can be uniquely
  * identified. This is useful when the corresponding kernel driver can produce
  * different graphs, for instance as a result of different driver versions or
  * hardware configurations, and not all those graphs are suitable for a pipeline
@@ -43,7 +60,7 @@ namespace libcamera {
  * \brief Construct a media device search pattern
  * \param[in] driver The Linux device driver name that created the media device
  */
-DeviceMatch::DeviceMatch(const std::string &driver)
+MediaDeviceMatch::MediaDeviceMatch(const std::string &driver)
 	: driver_(driver)
 {
 }
@@ -52,7 +69,7 @@ DeviceMatch::DeviceMatch(const std::string &driver)
  * \brief Add a media entity name to the search pattern
  * \param[in] entity The name of the entity in the media graph
  */
-void DeviceMatch::add(const std::string &entity)
+void MediaDeviceMatch::add(const std::string &entity)
 {
 	entities_.push_back(entity);
 }
@@ -67,7 +84,7 @@ void DeviceMatch::add(const std::string &entity)
  *
  * \return True if the media device matches the search pattern, false otherwise
  */
-bool DeviceMatch::match(const MediaDevice *device) const
+bool MediaDeviceMatch::match(const MediaDevice *device) const
 {
 	if (driver_ != device->driver())
 		return false;
diff --git a/src/libcamera/pipeline/imx8-isi/imx8-isi.cpp b/src/libcamera/pipeline/imx8-isi/imx8-isi.cpp
index 9bdfff0b..b7670a3c 100644
--- a/src/libcamera/pipeline/imx8-isi/imx8-isi.cpp
+++ b/src/libcamera/pipeline/imx8-isi/imx8-isi.cpp
@@ -971,7 +971,7 @@ int PipelineHandlerISI::queueRequestDevice(Camera *camera, Request *request)
 
 bool PipelineHandlerISI::match(DeviceEnumerator *enumerator)
 {
-	DeviceMatch dm("mxc-isi");
+	MediaDeviceMatch dm("mxc-isi");
 	dm.add("crossbar");
 	dm.add("mxc_isi.0");
 	dm.add("mxc_isi.0.capture");
diff --git a/src/libcamera/pipeline/ipu3/ipu3.cpp b/src/libcamera/pipeline/ipu3/ipu3.cpp
index a81c817a..5eca9eb0 100644
--- a/src/libcamera/pipeline/ipu3/ipu3.cpp
+++ b/src/libcamera/pipeline/ipu3/ipu3.cpp
@@ -846,7 +846,7 @@ bool PipelineHandlerIPU3::match(DeviceEnumerator *enumerator)
 {
 	int ret;
 
-	DeviceMatch cio2_dm("ipu3-cio2");
+	MediaDeviceMatch cio2_dm("ipu3-cio2");
 	cio2_dm.add("ipu3-csi2 0");
 	cio2_dm.add("ipu3-cio2 0");
 	cio2_dm.add("ipu3-csi2 1");
@@ -856,7 +856,7 @@ bool PipelineHandlerIPU3::match(DeviceEnumerator *enumerator)
 	cio2_dm.add("ipu3-csi2 3");
 	cio2_dm.add("ipu3-cio2 3");
 
-	DeviceMatch imgu_dm("ipu3-imgu");
+	MediaDeviceMatch imgu_dm("ipu3-imgu");
 	imgu_dm.add("ipu3-imgu 0");
 	imgu_dm.add("ipu3-imgu 0 input");
 	imgu_dm.add("ipu3-imgu 0 parameters");
diff --git a/src/libcamera/pipeline/rkisp1/rkisp1.cpp b/src/libcamera/pipeline/rkisp1/rkisp1.cpp
index 6efa79f2..5855c9d3 100644
--- a/src/libcamera/pipeline/rkisp1/rkisp1.cpp
+++ b/src/libcamera/pipeline/rkisp1/rkisp1.cpp
@@ -1155,7 +1155,7 @@ bool PipelineHandlerRkISP1::match(DeviceEnumerator *enumerator)
 {
 	const MediaPad *pad;
 
-	DeviceMatch dm("rkisp1");
+	MediaDeviceMatch dm("rkisp1");
 	dm.add("rkisp1_isp");
 	dm.add("rkisp1_resizer_mainpath");
 	dm.add("rkisp1_mainpath");
diff --git a/src/libcamera/pipeline/rpi/vc4/vc4.cpp b/src/libcamera/pipeline/rpi/vc4/vc4.cpp
index 018cf488..78fd3922 100644
--- a/src/libcamera/pipeline/rpi/vc4/vc4.cpp
+++ b/src/libcamera/pipeline/rpi/vc4/vc4.cpp
@@ -175,7 +175,7 @@ bool PipelineHandlerVc4::match(DeviceEnumerator *enumerator)
 	 * device nodes due to a sensor subdevice failure.
 	 */
 	for (unsigned int i = 0; i < numUnicamDevices; i++) {
-		DeviceMatch unicam("unicam");
+		MediaDeviceMatch unicam("unicam");
 		MediaDevice *unicamDevice = acquireMediaDevice(enumerator, unicam);
 
 		if (!unicamDevice) {
@@ -183,7 +183,7 @@ bool PipelineHandlerVc4::match(DeviceEnumerator *enumerator)
 			continue;
 		}
 
-		DeviceMatch isp("bcm2835-isp");
+		MediaDeviceMatch isp("bcm2835-isp");
 		MediaDevice *ispDevice = acquireMediaDevice(enumerator, isp);
 
 		if (!ispDevice) {
diff --git a/src/libcamera/pipeline/simple/simple.cpp b/src/libcamera/pipeline/simple/simple.cpp
index 05ba76bc..88159a0c 100644
--- a/src/libcamera/pipeline/simple/simple.cpp
+++ b/src/libcamera/pipeline/simple/simple.cpp
@@ -1398,7 +1398,7 @@ bool SimplePipelineHandler::match(DeviceEnumerator *enumerator)
 	unsigned int numStreams = 1;
 
 	for (const SimplePipelineInfo &inf : supportedDevices) {
-		DeviceMatch dm(inf.driver);
+		MediaDeviceMatch dm(inf.driver);
 		media_ = acquireMediaDevice(enumerator, dm);
 		if (media_) {
 			info = &inf;
@@ -1410,7 +1410,7 @@ bool SimplePipelineHandler::match(DeviceEnumerator *enumerator)
 		return false;
 
 	for (const auto &[name, streams] : info->converters) {
-		DeviceMatch converterMatch(name);
+		MediaDeviceMatch converterMatch(name);
 		converter_ = acquireMediaDevice(enumerator, converterMatch);
 		if (converter_) {
 			numStreams = streams;
diff --git a/src/libcamera/pipeline/uvcvideo/uvcvideo.cpp b/src/libcamera/pipeline/uvcvideo/uvcvideo.cpp
index 38f48a5d..2114d48a 100644
--- a/src/libcamera/pipeline/uvcvideo/uvcvideo.cpp
+++ b/src/libcamera/pipeline/uvcvideo/uvcvideo.cpp
@@ -387,7 +387,7 @@ int PipelineHandlerUVC::queueRequestDevice(Camera *camera, Request *request)
 bool PipelineHandlerUVC::match(DeviceEnumerator *enumerator)
 {
 	MediaDevice *media;
-	DeviceMatch dm("uvcvideo");
+	MediaDeviceMatch dm("uvcvideo");
 
 	media = acquireMediaDevice(enumerator, dm);
 	if (!media)
diff --git a/src/libcamera/pipeline/vimc/vimc.cpp b/src/libcamera/pipeline/vimc/vimc.cpp
index 00e6f4c6..f97209ba 100644
--- a/src/libcamera/pipeline/vimc/vimc.cpp
+++ b/src/libcamera/pipeline/vimc/vimc.cpp
@@ -442,7 +442,7 @@ int PipelineHandlerVimc::queueRequestDevice(Camera *camera, Request *request)
 
 bool PipelineHandlerVimc::match(DeviceEnumerator *enumerator)
 {
-	DeviceMatch dm("vimc");
+	MediaDeviceMatch dm("vimc");
 
 	dm.add("Raw Capture 0");
 	dm.add("Raw Capture 1");
diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
index 9c74c6cf..ca177cad 100644
--- a/src/libcamera/pipeline_handler.cpp
+++ b/src/libcamera/pipeline_handler.cpp
@@ -22,6 +22,7 @@
 #include "libcamera/internal/camera.h"
 #include "libcamera/internal/camera_manager.h"
 #include "libcamera/internal/device_enumerator.h"
+#include "libcamera/internal/device_match.h"
 #include "libcamera/internal/framebuffer.h"
 #include "libcamera/internal/media_device.h"
 #include "libcamera/internal/request.h"
@@ -129,7 +130,7 @@ PipelineHandler::~PipelineHandler()
  * \return A pointer to the matching MediaDevice, or nullptr if no match is found
  */
 MediaDevice *PipelineHandler::acquireMediaDevice(DeviceEnumerator *enumerator,
-						 const DeviceMatch &dm)
+						 const MediaDeviceMatch &dm)
 {
 	std::shared_ptr<MediaDevice> media = enumerator->search(dm);
 	if (!media)