[RFC,v1,00/20] libcamera: New enumeration API

28312 mbox series

Hi,

As promised way back in the May F2F (better late than never!), this series adds
a new two-phase camera enumeration API to the CameraManager.

Today, CameraManager::start() creates and initialises every camera in the
system, including IPA initialisation, which can be quite a heavyweight
operation.  Additionally, this stops application from possibly providing camera
specific IPA configurations during initialisation.

The new API splits this operation in two.  CameraManager::enumerate() returns a
CameraDescriptor for every camera in the system, carrying the camera id and the
properties known without touching the hardware.  The application then picks the
ones it wants and calls CameraManager::initialize() on each descriptor to get a
fully initialised Camera.  This API is optional, and applications can still use
start() and cameras() exactly as before.

On the pipeline handler side, match() is split into survey() and createCamera().
survey() reports descriptors using only the DeviceEnumerator and must not
acquire or open anything, while createCamera() does the per-camera work that
match() used to do.  Pipeline handlers may still keep working through match(),
where their cameras are created by start() but are not reported by enumerate().

The patches roughly grouped as follows:

Patches 1-4: Helpers needed to identify a camera without opening it.  Camera IDs
are generated from the media entity (sysfs/firmware node) rather than an opened
subdevice, the model name derivation is factored out, and the device enumerator
gains a non-acquiring searchAll().

Patches 5-7: The CameraDescriptor class and the survey()/createCamera() pipeline
handler API, plus the ability to acquire a specific media device.

Patches 8-15: CameraManager changes.

Patches 16-19: survey()/createCamera() implementations for the RPi (vc4/pisp)
and uvcvideo pipeline handlers, with their match() implementations removed once
they are dead code.

Patch 20: Documentation updates.

I've tested these changes on a branch of rpicam-apps [1] that implements the
enumeration API.  Also done some basic testing with the uvcvideo pipeline
handler in cam.  I'm  unable to test any other pipeline handler, so their code
remains unchanged, using the existing match() API.

There's a few fundamental changes to the CameraManager implemenation here so I'm
sure there is plenty to discuss :)

Regards,
Naush

[1]: https://github.com/raspberrypi/rpicam-apps/tree/enumeration-api

Naushir Patuck (20):
  libcamera: sysfs: Add devicePath() helpers
  libcamera: v4l2_subdevice: Refactor the model name derivation
  libcamera: camera_sensor: Generate sensor IDs from a media entity
  libcamera: device_enumerator: Add non-acquiring searchAll()
  libcamera: Add the CameraDescriptor class
  libcamera: pipeline_handler: Add survey() and createCamera()
  libcamera: pipeline_handler: Allow acquiring a specific media device
  libcamera: camera_manager: Defer IPAManager construction to first use
  libcamera: camera_manager: Track active pipeline handler instances
  libcamera: camera_manager: Extract the pipeline handler factory list
  libcamera: camera_manager: Marshal work onto the camera manager thread
  libcamera: camera_manager: Add CameraManager::enumerate()
  libcamera: camera_manager: Add CameraManager::initialize()
  libcamera: camera_manager: Create cameras through enumeration
  libcamera: pipeline_handler: Make match() optional
  pipeline: rpi: Add platform helpers for camera enumeration
  pipeline: rpi: Implement survey() and createCamera()
  pipeline: uvcvideo: Factor out camera ID generation
  pipeline: uvcvideo: Implement survey() and createCamera()
  Documentation: Describe the two-phase camera enumeration API

 .../guides/application-developer.rst          |  41 ++
 Documentation/guides/pipeline-handler.rst     | 101 +++++
 include/libcamera/camera_descriptor.h         |  34 ++
 include/libcamera/camera_manager.h            |   4 +
 .../libcamera/internal/camera_descriptor.h    |  37 ++
 include/libcamera/internal/camera_manager.h   |  30 +-
 include/libcamera/internal/camera_sensor.h    |   1 +
 .../libcamera/internal/device_enumerator.h    |   1 +
 include/libcamera/internal/meson.build        |   1 +
 include/libcamera/internal/pipeline_handler.h |   8 +-
 include/libcamera/internal/sysfs.h            |   3 +
 include/libcamera/internal/v4l2_subdevice.h   |   1 +
 include/libcamera/meson.build                 |   1 +
 src/libcamera/camera_descriptor.cpp           | 141 +++++++
 src/libcamera/camera_manager.cpp              | 372 ++++++++++++++++--
 src/libcamera/device_enumerator.cpp           |  31 ++
 src/libcamera/meson.build                     |   1 +
 .../pipeline/rpi/common/pipeline_base.cpp     |  99 +++++
 .../pipeline/rpi/common/pipeline_base.h       |  16 +
 src/libcamera/pipeline/rpi/pisp/pisp.cpp      | 121 +++---
 src/libcamera/pipeline/rpi/vc4/vc4.cpp        |  79 ++--
 src/libcamera/pipeline/uvcvideo/uvcvideo.cpp  | 244 +++++++-----
 src/libcamera/pipeline_handler.cpp            | 107 +++++
 src/libcamera/sensor/camera_sensor.cpp        |  27 ++
 src/libcamera/sensor/camera_sensor_legacy.cpp |   6 +-
 src/libcamera/sensor/camera_sensor_raw.cpp    |   3 +-
 src/libcamera/sysfs.cpp                       |  61 +++
 src/libcamera/v4l2_device.cpp                 |  13 +-
 src/libcamera/v4l2_subdevice.cpp              |  60 +--
 29 files changed, 1352 insertions(+), 292 deletions(-)
 create mode 100644 include/libcamera/camera_descriptor.h
 create mode 100644 include/libcamera/internal/camera_descriptor.h
 create mode 100644 src/libcamera/camera_descriptor.cpp