libcamera: camera: Rename name() to id()

Rename Camera::name() to camera::id() to better describe what it
represents, a unique and stable ID for the camera. While at it improve
the documentation for the camera ID to describe it needs to be stable
for a camera between resets of the system.

Signed-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

7 files changed, 57 insertions, 37 deletions

diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
index 99cb5048..820fa1e3 100644
--- a/src/libcamera/camera.cpp
+++ b/src/libcamera/camera.cpp
@@ -265,7 +265,7 @@ public:
 		CameraRunning,
 	};
 
-	Private(PipelineHandler *pipe, const std::string &name,
+	Private(PipelineHandler *pipe, const std::string &id,
 		const std::set<Stream *> &streams);
 	~Private();
 
@@ -277,7 +277,7 @@ public:
 	void setState(State state);
 
 	std::shared_ptr<PipelineHandler> pipe_;
-	std::string name_;
+	std::string id_;
 	std::set<Stream *> streams_;
 	std::set<Stream *> activeStreams_;
 
@@ -286,9 +286,9 @@ private:
 	std::atomic<State> state_;
 };
 
-Camera::Private::Private(PipelineHandler *pipe, const std::string &name,
+Camera::Private::Private(PipelineHandler *pipe, const std::string &id,
 			 const std::set<Stream *> &streams)
-	: pipe_(pipe->shared_from_this()), name_(name), streams_(streams),
+	: pipe_(pipe->shared_from_this()), id_(id), streams_(streams),
 	  disconnected_(false), state_(CameraAvailable)
 {
 }
@@ -450,15 +450,21 @@ void Camera::Private::setState(State state)
 /**
  * \brief Create a camera instance
  * \param[in] pipe The pipeline handler responsible for the camera device
- * \param[in] name The name of the camera device
+ * \param[in] id The ID of the camera device
  * \param[in] streams Array of streams the camera provides
  *
- * The caller is responsible for guaranteeing unicity of the camera name.
+ * The caller is responsible for guaranteeing a stable and unique camera ID
+ * matching the constraints described by Camera::id(). Parameters that are
+ * allocated dynamically at system startup, such as bus numbers that may be
+ * enumerated differently, are therefore not suitable to use in the ID.
+ *
+ * Pipeline handlers that use a CameraSensor may use the CameraSensor::id() to
+ * generate an ID that satisfies the criteria of a stable and unique camera ID.
  *
  * \return A shared pointer to the newly created camera object
  */
 std::shared_ptr<Camera> Camera::create(PipelineHandler *pipe,
-				       const std::string &name,
+				       const std::string &id,
 				       const std::set<Stream *> &streams)
 {
 	struct Deleter : std::default_delete<Camera> {
@@ -468,19 +474,34 @@ std::shared_ptr<Camera> Camera::create(PipelineHandler *pipe,
 		}
 	};
 
-	Camera *camera = new Camera(pipe, name, streams);
+	Camera *camera = new Camera(pipe, id, streams);
 
 	return std::shared_ptr<Camera>(camera, Deleter());
 }
 
 /**
- * \brief Retrieve the name of the camera
+ * \brief Retrieve the ID of the camera
+ *
+ * The camera ID is a free-form string that identifies a camera in the system.
+ * IDs are guaranteed to be unique and stable: the same camera, when connected
+ * to the system in the same way (e.g. in the same USB port), will have the same
+ * ID across both unplug/replug and system reboots.
+ *
+ * Applications may store the camera ID and use it later to acquire the same
+ * camera. They shall treat the ID as an opaque identifier, without interpreting
+ * its value.
+ *
+ * Camera IDs may change when the system hardware or firmware is modified, for
+ * instance when replacing a PCI USB controller or moving it to another PCI
+ * slot, or updating the ACPI tables or Device Tree.
+ *
  * \context This function is \threadsafe.
- * \return Name of the camera device
+ *
+ * \return ID of the camera device
  */
-const std::string &Camera::name() const
+const std::string &Camera::id() const
 {
-	return p_->name_;
+	return p_->id_;
 }
 
 /**
@@ -506,9 +527,9 @@ const std::string &Camera::name() const
  * application API calls by returning errors immediately.
  */
 
-Camera::Camera(PipelineHandler *pipe, const std::string &name,
+Camera::Camera(PipelineHandler *pipe, const std::string &id,
 	       const std::set<Stream *> &streams)
-	: p_(new Private(pipe, name, streams))
+	: p_(new Private(pipe, id, streams))
 {
 }
 
@@ -530,7 +551,7 @@ Camera::~Camera()
  */
 void Camera::disconnect()
 {
-	LOG(Camera, Debug) << "Disconnecting camera " << name();
+	LOG(Camera, Debug) << "Disconnecting camera " << id();
 
 	p_->disconnect();
 	disconnected.emit(this);
diff --git a/src/libcamera/camera_controls.cpp b/src/libcamera/camera_controls.cpp
index 371f6d07..cabdcf75 100644
--- a/src/libcamera/camera_controls.cpp
+++ b/src/libcamera/camera_controls.cpp
@@ -36,7 +36,7 @@ CameraControlValidator::CameraControlValidator(Camera *camera)
 
 const std::string &CameraControlValidator::name() const
 {
-	return camera_->name();
+	return camera_->id();
 }
 
 /**
diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp
index c45bf33f..76543b6a 100644
--- a/src/libcamera/camera_manager.cpp
+++ b/src/libcamera/camera_manager.cpp
@@ -181,10 +181,10 @@ void CameraManager::Private::addCamera(std::shared_ptr<Camera> camera,
 	MutexLocker locker(mutex_);
 
 	for (std::shared_ptr<Camera> c : cameras_) {
-		if (c->name() == camera->name()) {
+		if (c->id() == camera->id()) {
 			LOG(Camera, Warning)
-				<< "Registering camera with duplicate name '"
-				<< camera->name() << "'";
+				<< "Registering camera with duplicate ID '"
+				<< camera->id() << "'";
 			break;
 		}
 	}
@@ -208,7 +208,7 @@ void CameraManager::Private::removeCamera(Camera *camera)
 		return;
 
 	LOG(Camera, Debug)
-		<< "Unregistering camera '" << camera->name() << "'";
+		<< "Unregistering camera '" << camera->id() << "'";
 
 	auto iter_d = std::find_if(camerasByDevnum_.begin(), camerasByDevnum_.end(),
 				   [camera](const std::pair<dev_t, std::weak_ptr<Camera>> &p) {
@@ -329,8 +329,8 @@ std::vector<std::shared_ptr<Camera>> CameraManager::cameras() const
 }
 
 /**
- * \brief Get a camera based on name
- * \param[in] name Name of camera to get
+ * \brief Get a camera based on ID
+ * \param[in] id ID of camera to get
  *
  * Before calling this function the caller is responsible for ensuring that
  * the camera manager is running.
@@ -339,12 +339,12 @@ std::vector<std::shared_ptr<Camera>> CameraManager::cameras() const
  *
  * \return Shared pointer to Camera object or nullptr if camera not found
  */
-std::shared_ptr<Camera> CameraManager::get(const std::string &name)
+std::shared_ptr<Camera> CameraManager::get(const std::string &id)
 {
 	MutexLocker locker(p_->mutex_);
 
 	for (std::shared_ptr<Camera> camera : p_->cameras_) {
-		if (camera->name() == name)
+		if (camera->id() == id)
 			return camera;
 	}
 
diff --git a/src/libcamera/framebuffer_allocator.cpp b/src/libcamera/framebuffer_allocator.cpp
index 252191ba..2fbba37a 100644
--- a/src/libcamera/framebuffer_allocator.cpp
+++ b/src/libcamera/framebuffer_allocator.cpp
@@ -95,7 +95,7 @@ int FrameBufferAllocator::allocate(Stream *stream)
 	int ret = camera_->exportFrameBuffers(stream, &buffers_[stream]);
 	if (ret == -EINVAL)
 		LOG(Allocator, Error)
-			<< "Stream is not part of " << camera_->name()
+			<< "Stream is not part of " << camera_->id()
 			<< " active configuration";
 	return ret;
 }
diff --git a/src/libcamera/pipeline/ipu3/ipu3.cpp b/src/libcamera/pipeline/ipu3/ipu3.cpp
index cfee178a..d931ed33 100644
--- a/src/libcamera/pipeline/ipu3/ipu3.cpp
+++ b/src/libcamera/pipeline/ipu3/ipu3.cpp
@@ -629,7 +629,7 @@ int PipelineHandlerIPU3::start(Camera *camera)
 
 error:
 	freeBuffers(camera);
-	LOG(IPU3, Error) << "Failed to start camera " << camera->name();
+	LOG(IPU3, Error) << "Failed to start camera " << camera->id();
 
 	return ret;
 }
@@ -642,8 +642,7 @@ void PipelineHandlerIPU3::stop(Camera *camera)
 	ret |= data->imgu_->stop();
 	ret |= data->cio2_.stop();
 	if (ret)
-		LOG(IPU3, Warning) << "Failed to stop camera "
-				   << camera->name();
+		LOG(IPU3, Warning) << "Failed to stop camera " << camera->id();
 
 	freeBuffers(camera);
 }
diff --git a/src/libcamera/pipeline/raspberrypi/raspberrypi.cpp b/src/libcamera/pipeline/raspberrypi/raspberrypi.cpp
index c55d7325..eeaf335c 100644
--- a/src/libcamera/pipeline/raspberrypi/raspberrypi.cpp
+++ b/src/libcamera/pipeline/raspberrypi/raspberrypi.cpp
@@ -643,7 +643,7 @@ int PipelineHandlerRPi::configure(Camera *camera, CameraConfiguration *config)
 	if (ret)
 		return ret;
 
-	LOG(RPI, Info) << "Sensor: " << camera->name()
+	LOG(RPI, Info) << "Sensor: " << camera->id()
 		       << " - Selected mode: " << sensorFormat.toString();
 
 	/*
@@ -793,7 +793,7 @@ int PipelineHandlerRPi::start(Camera *camera)
 	ret = data->ipa_->start();
 	if (ret) {
 		LOG(RPI, Error)
-			<< "Failed to start IPA for " << camera->name();
+			<< "Failed to start IPA for " << camera->id();
 		stop(camera);
 		return ret;
 	}
diff --git a/src/libcamera/pipeline/rkisp1/rkisp1.cpp b/src/libcamera/pipeline/rkisp1/rkisp1.cpp
index 94561062..b7609cbc 100644
--- a/src/libcamera/pipeline/rkisp1/rkisp1.cpp
+++ b/src/libcamera/pipeline/rkisp1/rkisp1.cpp
@@ -798,7 +798,7 @@ int PipelineHandlerRkISP1::start(Camera *camera)
 	if (ret) {
 		freeBuffers(camera);
 		LOG(RkISP1, Error)
-			<< "Failed to start IPA " << camera->name();
+			<< "Failed to start IPA " << camera->id();
 		return ret;
 	}
 
@@ -809,7 +809,7 @@ int PipelineHandlerRkISP1::start(Camera *camera)
 		data->ipa_->stop();
 		freeBuffers(camera);
 		LOG(RkISP1, Error)
-			<< "Failed to start parameters " << camera->name();
+			<< "Failed to start parameters " << camera->id();
 		return ret;
 	}
 
@@ -819,7 +819,7 @@ int PipelineHandlerRkISP1::start(Camera *camera)
 		data->ipa_->stop();
 		freeBuffers(camera);
 		LOG(RkISP1, Error)
-			<< "Failed to start statistics " << camera->name();
+			<< "Failed to start statistics " << camera->id();
 		return ret;
 	}
 
@@ -831,7 +831,7 @@ int PipelineHandlerRkISP1::start(Camera *camera)
 		freeBuffers(camera);
 
 		LOG(RkISP1, Error)
-			<< "Failed to start camera " << camera->name();
+			<< "Failed to start camera " << camera->id();
 	}
 
 	activeCamera_ = camera;
@@ -870,17 +870,17 @@ void PipelineHandlerRkISP1::stop(Camera *camera)
 	ret = video_->streamOff();
 	if (ret)
 		LOG(RkISP1, Warning)
-			<< "Failed to stop camera " << camera->name();
+			<< "Failed to stop camera " << camera->id();
 
 	ret = stat_->streamOff();
 	if (ret)
 		LOG(RkISP1, Warning)
-			<< "Failed to stop statistics " << camera->name();
+			<< "Failed to stop statistics " << camera->id();
 
 	ret = param_->streamOff();
 	if (ret)
 		LOG(RkISP1, Warning)
-			<< "Failed to stop parameters " << camera->name();
+			<< "Failed to stop parameters " << camera->id();
 
 	data->ipa_->stop();