/* SPDX-License-Identifier: LGPL-2.1-or-later */ /* * Copyright (C) 2018, Google Inc. * * Pipeline handler infrastructure */ #include "libcamera/internal/pipeline_handler.h" #include #include #include #include #include #include #include #include #include #include "libcamera/internal/camera.h" #include "libcamera/internal/camera_manager.h" #include "libcamera/internal/device_enumerator.h" #include "libcamera/internal/media_device.h" #include "libcamera/internal/request.h" #include "libcamera/internal/tracepoints.h" /** * \file pipeline_handler.h * \brief Create pipelines and cameras from a set of media devices * * Each pipeline supported by libcamera needs to be backed by a pipeline * handler implementation that operate on a set of media devices. The pipeline * handler is responsible for matching the media devices it requires with the * devices present in the system, and once all those devices can be acquired, * create corresponding Camera instances. * * Every subclass of PipelineHandler shall be registered with libcamera using * the REGISTER_PIPELINE_HANDLER() macro. */ using namespace std::chrono_literals; namespace libcamera { LOG_DEFINE_CATEGORY(Pipeline) /** * \class PipelineHandler * \brief Create and manage cameras based on a set of media devices * * The PipelineHandler matches the media devices provided by a DeviceEnumerator * with the pipelines it supports and creates corresponding Camera devices. * * Pipeline handler instances are reference-counted through std::shared_ptr<>. * They implement std::enable_shared_from_this<> in order to create new * std::shared_ptr<> in code paths originating from member functions of the * PipelineHandler class where only the 'this' pointer is available. */ /** * \brief Construct a PipelineHandler instance * \param[in] manager The camera manager * * In order to honour the std::enable_shared_from_this<> contract, * PipelineHandler instances shall never be constructed manually, but always * through the PipelineHandlerFactoryBase::create() function. */ PipelineHandler::PipelineHandler(CameraManager *manager) : manager_(manager), useCount_(0) { } PipelineHandler::~PipelineHandler() { for (std::shared_ptr media : mediaDevices_) media->release(); } /** * \fn PipelineHandler::match(DeviceEnumerator *enumerator) * \brief Match media devices and create camera instances * \param[in] enumerator The enumerator providing all media devices found in the * system * * This function is the main entry point of the pipeline handler. It is called * by the camera manager with the \a enumerator passed as an argument. It shall * acquire from the \a enumerator all the media devices it needs for a single * pipeline, create one or multiple Camera instances and register them with the * camera manager. * * If all media devices needed by the pipeline handler are found, they must all * be acquired by a call to MediaDevice::acquire(). This function shall then * create the corresponding Camera instances, store them internally, and return * true. Otherwise it shall not acquire any media device (or shall release all * the media devices is has acquired by calling MediaDevice::release()) and * return false. * * If multiple instances of a pipeline are available in the system, the * PipelineHandler class will be instantiated once per instance, and its match() * function called for every instance. Each call shall acquire media devices for * one pipeline instance, until all compatible media devices are exhausted. * * If this function returns true, a new instance of the pipeline handler will * be created and its match() function called. * * \context This function is called from the CameraManager thread. * * \return true if media devices have been acquired and camera instances * created, or false otherwise */ /** * \brief Search and acquire a MediaDevice matching a device pattern * \param[in] enumerator Enumerator containing all media devices in the system * \param[in] dm Device match pattern * * Search the device \a enumerator for an available media device matching the * device match pattern \a dm. Matching media device that have previously been * acquired by MediaDevice::acquire() are not considered. If a match is found, * the media device is acquired and returned. The caller shall not release the * device explicitly, it will be automatically released when the pipeline * handler is destroyed. * * \context This function shall be called from the CameraManager thread. * * \return A pointer to the matching MediaDevice, or nullptr if no match is found */ MediaDevice *PipelineHandler::acquireMediaDevice(DeviceEnumerator *enumerator, const DeviceMatch &dm) { std::shared_ptr media = enumerator->search(dm); if (!media) return nullptr; if (!media->acquire()) return nullptr; mediaDevices_.push_back(media); return media.get(); } /** * \brief Acquire exclusive access to the pipeline handler for the process * * This function locks all the media devices used by the pipeline to ensure * that no other process can access them concurrently. * * Access to a pipeline handler may be acquired recursively from within the * same process. Every successful acquire() call shall be matched with a * release() call. This allows concurrent access to the same pipeline handler * from different cameras within the same process. * * Pipeline handlers shall not call this function directly as the Camera class * handles access internally. * * \context This function is called from the CameraManager thread. * * \return True if the pipeline handler was acquired, false if another process * has already acquired it * \sa release() */ bool PipelineHandler::acquire(Camera *camera) { if (useCount_ == 0) { for (std::shared_ptr &media : mediaDevices_) { if (!media->lock()) { unlockMediaDevices(); return false; } } } if (!acquireDevice(camera)) { if (useCount_ == 0) unlockMediaDevices(); return false; } ++useCount_; return true; } /** * \brief Release exclusive access to the pipeline handler * \param[in] camera The camera for which to release data * * This function releases access to the pipeline handler previously acquired by * a call to acquire(). Every release() call shall match a previous successful * acquire() call. Calling this function on a pipeline handler that hasn't been * acquired results in undefined behaviour. * * Pipeline handlers shall not call this function directly as the Camera class * handles access internally. * * \context This function is called from the CameraManager thread. * * \sa acquire() */ void PipelineHandler::release(Camera *camera) { ASSERT(useCount_); releaseDevice(camera); if (useCount_ == 1) unlockMediaDevices(); --useCount_; } /** * \brief Acquire resources associated with this camera * \param[in] camera The camera for which to acquire resources * * Pipeline handlers may override this in order to get resources such as opening * devices and allocating buffers when a camera is acquired. * * This is used by the uvcvideo pipeline handler to delay opening /dev/video# * until the camera is acquired to avoid excess power consumption. The delayed * opening of /dev/video# is a special case because the kernel uvcvideo driver * powers on the USB device as soon as /dev/video# is opened. This behavior * should *not* be copied by other pipeline handlers. * * \context This function is called from the CameraManager thread. * * \return True on success, false on failure * \sa releaseDevice() */ bool PipelineHandler::acquireDevice([[maybe_unused]] Camera *camera) { return true; } /** * \brief Release resources associated with this camera * \param[in] camera The camera for which to release resources * * Pipeline handlers may override this in order to perform cleanup operations * when a camera is released, such as freeing memory. * * This is called once for every camera that is released. If there are resources * shared by multiple cameras then the pipeline handler must take care to not * release them until releaseDevice() has been called for all previously * acquired cameras. * * \context This function is called from the CameraManager thread. * * \sa acquireDevice() */ void PipelineHandler::releaseDevice([[maybe_unused]] Camera *camera) { } void PipelineHandler::unlockMediaDevices() { for (std::shared_ptr &media : mediaDevices_) media->unlock(); } /** * \fn PipelineHandler::generateConfiguration() * \brief Generate a camera configuration for a specified camera * \param[in] camera The camera to generate a default configuration for * \param[in] roles A list of stream roles * * Generate a default configuration for the \a camera for a specified list of * stream roles. The caller shall populate the \a roles with the use-cases it * wishes to fetch the default configuration for. The returned configuration * can then be examined by the caller to learn about the selected streams and * their default parameters. * * The intended companion to this is \a configure() which can be used to change * the group of streams parameters. * * \context This function may be called from any thread and shall be * \threadsafe. It shall not modify the state of the \a camera in the pipeline * handler. * * \return A valid CameraConfiguration if the requested roles can be satisfied, * or a null pointer otherwise. */ /** * \fn PipelineHandler::configure() * \brief Configure a group of streams for capture * \param[in] camera The camera to configure * \param[in] config The camera configurations to setup * * Configure the specified group of streams for \a camera according to the * configuration specified in \a config. The intended caller of this interface * is the Camera class which will receive configuration to apply from the * application. * * The configuration is guaranteed to have been validated with * CameraConfiguration::validate(). The pipeline handler implementation shall * not perform further validation and may rely on any custom field stored in its * custom CameraConfiguration derived class. * * When configuring the camera the pipeline handler shall associate a Stream * instance to each StreamConfiguration entry in the CameraConfiguration using * the StreamConfiguration::setStream() function. * * \context This function is called from the CameraManager thread. * * \return 0 on success or a negative error code otherwise */ /** * \fn PipelineHandler::exportFrameBuffers() * \brief Allocate and export buffers for \a stream * \param[in] camera The camera * \param[in] stream The stream to allocate buffers for * \param[out] buffers Array of buffers successfully allocated * * This function allocates buffers for the \a stream from the devices associated * with the stream in the corresponding pipeline handler. Those buffers shall be * suitable to be added to a Request for the stream, and shall be mappable to * the CPU through their associated dmabufs with mmap(). * * The function may only be called after the Camera has been configured and * before it gets started, or after it gets stopped. It shall be called only for * streams that are part of the active camera configuration. * * The only intended caller is Camera::exportFrameBuffers(). * * \context This function is called from the CameraManager thread. * * \return The number of allocated buffers on success or a negative error code * otherwise */ /** * \fn PipelineHandler::start() * \brief Start capturing from a group of streams * \param[in] camera The camera to start * \param[in] controls Controls to be applied before starting the Camera * * Start the group of streams that have been configured for capture by * \a configure(). The intended caller of this function is the Camera class * which will in turn be called from the application to indicate that it has * configured the streams and is ready to capture. * * \context This function is called from the CameraManager thread. * * \return 0 on success or a negative error code otherwise */ /** * \brief Stop capturing from all running streams and cancel pending requests * \param[in] camera The camera to stop * * This function stops capturing and processing requests immediately. All * pending requests are cancelled and complete immediately in an error state. * * \context This function is called from the CameraManager thread. */ void PipelineHandler::stop(Camera *camera) { /* Stop the pipeline handler and let the queued requests complete. */ stopDevice(camera); /* Cancel and signal as complete all waiting requests. */ while (!waitingRequests_.empty()) { Request *request = waitingRequests_.front(); waitingRequests_.pop(); request->_d()->cancel(); completeRequest(request); } /* Make sure no requests are pending. */ Camera::Private *data = camera->_d(); ASSERT(data->queuedRequests_.empty()); data->requestSequence_ = 0; } /** * \fn PipelineHandler::stopDevice() * \brief Stop capturing from all running streams * \param[in] camera The camera to stop * * This function stops capturing and processing requests immediately. All * pending requests are cancelled and complete immediately in an error state. */ /** * \brief Determine if the camera has any requests pending * \param[in] camera The camera to check * * This function determines if there are any requests queued to the pipeline * awaiting processing. * * \return True if there are pending requests, or false otherwise */ bool PipelineHandler::hasPendingRequests(const Camera *camera) const { return !camera->_d()->queuedRequests_.empty(); } /** * \fn PipelineHandler::registerRequest() * \brief Register a request for use by the pipeline handler * \param[in] request The request to register * * This function is called when the request is created, and allows the pipeline * handler to perform any one-time initialization it requries for the request. */ void PipelineHandler::registerRequest(Request *request) { /* * Connect the request prepared signal to notify the pipeline handler * when a request is ready to be processed. */ request->_d()->prepared.connect(this, &PipelineHandler::doQueueRequests); } /** * \fn PipelineHandler::queueRequest() * \brief Queue a request * \param[in] request The request to queue * * This function queues a capture request to the pipeline handler for * processing. The request is first added to the internal list of waiting * requests which have to be prepared to make sure they are ready for being * queued to the pipeline handler. * * The queue of waiting requests is iterated and all prepared requests are * passed to the pipeline handler in the same order they have been queued by * calling this function. * * If a Request fails during the preparation phase or if the pipeline handler * fails in queuing the request to the hardware the request is cancelled. * * Keeping track of queued requests ensures automatic completion of all requests * when the pipeline handler is stopped with stop(). Request completion shall be * signalled by the pipeline handler using the completeRequest() function. * * \context This function is called from the CameraManager thread. */ void PipelineHandler::queueRequest(Request *request) { LIBCAMERA_TRACEPOINT(request_queue, request); waitingRequests_.push(request); request->_d()->prepare(300ms); } /** * \brief Queue one requests to the device */ void PipelineHandler::doQueueRequest(Request *request) { LIBCAMERA_TRACEPOINT(request_device_queue, request); Camera *camera = request->_d()->camera(); Camera::Private *data = camera->_d(); data->queuedRequests_.push_back(request); request->_d()->sequence_ = data->requestSequence_++; if (request->_d()->cancelled_) { completeRequest(request); return; } int ret = queueRequestDevice(camera, request); if (ret) { request->_d()->cancel(); completeRequest(request); } } /** * \brief Queue prepared requests to the device * * Iterate the list of waiting requests and queue them to the device one * by one if they have been prepared. */ void PipelineHandler::doQueueRequests() { while (!waitingRequests_.empty()) { Request *request = waitingRequests_.front(); if (!request->_d()->prepared_) break; doQueueRequest(request); waitingRequests_.pop(); } } /** * \fn PipelineHandler::queueRequestDevice() * \brief Queue a request to the device * \param[in] camera The camera to queue the request to * \param[in] request The request to queue * * This function queues a capture request to the device for processing. The * request contains a set of buffers associated with streams and a set of * parameters. The pipeline handler shall program the device to ensure that the * parameters will be applied to the frames captured in the buffers provided in * the request. * * \context This function is called from the CameraManager thread. * * \return 0 on success or a negative error code otherwise */ /** * \brief Complete a buffer for a request * \param[in] request The request the buffer belongs to * \param[in] buffer The buffer that has completed * * This function shall be called by pipeline handlers to signal completion of * the \a buffer part of the \a request. It notifies applications of buffer * completion and updates the request's internal buffer tracking. The request * is not completed automatically when the last buffer completes to give * pipeline handlers a chance to perform any operation that may still be * needed. They shall complete requests explicitly with completeRequest(). * * \context This function shall be called from the CameraManager thread. * * \return True if all buffers contained in the request have completed, false * otherwise */ bool PipelineHandler::completeBuffer(Request *request, FrameBuffer *buffer) { Camera *camera = request->_d()->camera(); camera->bufferCompleted.emit(request, buffer); return request->_d()->completeBuffer(buffer); } /** * \brief Signal request completion * \param[in] request The request that has completed * * The pipeline handler shall call this function to notify the \a camera that * the request has completed. The request is no longer managed by the pipeline * handler and shall not be accessed once this function returns. * * This function ensures that requests will be returned to the application in * submission order, the pipeline handler may call it on any complete request * without any ordering constraint. * * \context This function shall be called from the CameraManager thread. */ void PipelineHandler::completeRequest(Request *request) { Camera *camera = request->_d()->camera(); request->_d()->complete(); Camera::Private *data = camera->_d(); while (!data->queuedRequests_.empty()) { Request *req = data->queuedRequests_.front(); if (req->status() == Request::RequestPending) break; ASSERT(!req->hasPendingBuffers()); data->queuedRequests_.pop_front(); camera->requestComplete(req); } } /** * \brief Retrieve the absolute path to a platform configuration file * \param[in] subdir The pipeline handler specific subdirectory name * \param[in] name The configuration file name * * This function locates a named platform configuration file and returns * its absolute path to the pipeline handler. It searches the following * directories, in order: * * - If libcamera is not installed, the src/libcamera/pipeline/\/data/ * directory within the source tree ; otherwise * - The system data (share/libcamera/pipeline/\) directory. * * The system directories are not searched if libcamera is not installed. * * \return The full path to the pipeline handler configuration file, or an empty * string if no configuration file can be found */ std::string PipelineHandler::configurationFile(const std::string &subdir, const std::string &name) const { std::string confPath; struct stat statbuf; int ret; std::string root = utils::libcameraSourcePath(); if (!root.empty()) { /* * When libcamera is used before it is installed, load * configuration files from the source directory. The * configuration files are then located in the 'data' * subdirectory of the corresponding pipeline handler. */ std::string confDir = root + "src/libcamera/pipeline/"; confPath = confDir + subdir + "/data/" + name; LOG(Pipeline, Info) << "libcamera is not installed. Loading platform configuration file from '" << confPath << "'"; } else { /* Else look in the system locations. */ confPath = std::string(LIBCAMERA_DATA_DIR) + "/pipeline/" + subdir + '/' + name; } ret = stat(confPath.c_str(), &statbuf); if (ret == 0 && (statbuf.st_mode & S_IFMT) == S_IFREG) return confPath; LOG(Pipeline, Error) << "Configuration file '" << confPath << "' not found for pipeline handler '" << PipelineHandler::name() << "'"; return std::string(); } /** * \brief Register a camera to the camera manager and pipeline handler * \param[in] camera The camera to be added * * This function is called by pipeline handlers to register the cameras they * handle with the camera manager. * * \context This function shall be called from the CameraManager thread. */ void PipelineHandler::registerCamera(std::shared_ptr camera) { cameras_.push_back(camera); if (mediaDevices_.empty()) LOG(Pipeline, Fatal) << "Registering camera with no media devices!"; /* * Walk the entity list and map the devnums of all capture video nodes * to the camera. */ std::vector devnums; for (const std::shared_ptr &media : mediaDevices_) { for (const MediaEntity *entity : media->entities()) { if (entity->pads().size() == 1 && (entity->pads()[0]->flags() & MEDIA_PAD_FL_SINK) && entity->function() == MEDIA_ENT_F_IO_V4L) { devnums.push_back(makedev(entity->deviceMajor(), entity->deviceMinor())); } } } /* * Store the associated devices as a property of the camera to allow * systems to identify which devices are managed by libcamera. */ Camera::Private *data = camera->_d(); data->properties_.set(properties::SystemDevices, devnums); manager_->_d()->addCamera(std::move(camera)); } /** * \brief Enable hotplug handling for a media device * \param[in] media The media device * * This function enables hotplug handling, and especially hot-unplug handling, * of the \a media device. It shall be called by pipeline handlers for all the * media devices that can be disconnected. * * When a media device passed to this function is later unplugged, the pipeline * handler gets notified and automatically disconnects all the cameras it has * registered without requiring any manual intervention. */ void PipelineHandler::hotplugMediaDevice(MediaDevice *media) { media->disconnected.connect(this, [this, media] { mediaDeviceDisconnected(media); }); } /** * \brief Slot for the MediaDevice disconnected signal */ void PipelineHandler::mediaDeviceDisconnected(MediaDevice *media) { media->disconnected.disconnect(this); if (cameras_.empty()) return; disconnect(); } /** * \brief Device disconnection handler * * This virtual function is called to notify the pipeline handler that the * device it handles has been disconnected. It notifies all cameras created by * the pipeline handler that they have been disconnected, and unregisters them * from the camera manager. * * The function can be overloaded by pipeline handlers to perform custom * operations at disconnection time. Any overloaded version shall call the * PipelineHandler::disconnect() base function for proper hot-unplug operation. */ void PipelineHandler::disconnect() { /* * Each camera holds a reference to its associated pipeline handler * instance. Hence, when the last camera is dropped, the pipeline * handler will get destroyed by the last manager_->removeCamera(camera) * call in the loop below. * * This is acceptable as long as we make sure that the code path does not * access any member of the (already destroyed) pipeline handler instance * afterwards. Therefore, we move the cameras_ vector to a local temporary * container to avoid accessing freed memory later i.e. to explicitly run * cameras_.clear(). */ std::vector> cameras{ std::move(cameras_) }; for (const std::weak_ptr &ptr : cameras) { std::shared_ptr camera = ptr.lock(); if (!camera) continue; camera->disconnect(); manager_->_d()->removeCamera(camera); } } /** * \var PipelineHandler::manager_ * \brief The Camera manager associated with the pipeline handler * * The camera manager pointer is stored in the pipeline handler for the * convenience of pipeline handler implementations. It remains valid and * constant for the whole lifetime of the pipeline handler. */ /** * \fn PipelineHandler::name() * \brief Retrieve the pipeline handler name * \context This function shall be \threadsafe. * \return The pipeline handler name */ /** * \fn PipelineHandler::cameraManager() const * \brief Retrieve the CameraManager that this pipeline handler belongs to * \context This function is \threadsafe. * \return The CameraManager for this pipeline handler */ /** * \class PipelineHandlerFactoryBase * \brief Base class for pipeline handler factories * * The PipelineHandlerFactoryBase class is the base of all specializations of * the PipelineHandlerFactory class template. It implements the factory * registration, maintains a registry of factories, and provides access to the * registered factories. */ /** * \brief Construct a pipeline handler factory base * \param[in] name Name of the pipeline handler class * * Creating an instance of the factory base registers it with the global list of * factories, accessible through the factories() function. * * The factory \a name is used for debug purpose and shall be unique. */ PipelineHandlerFactoryBase::PipelineHandlerFactoryBase(const char *name) : name_(name) { registerType(this); } /** * \brief Create an instance of the PipelineHandler corresponding to the factory * \param[in] manager The camera manager * * \return A shared pointer to a new instance of the PipelineHandler subclass * corresponding to the factory */ std::shared_ptr PipelineHandlerFactoryBase::create(CameraManager *manager) const { std::unique_ptr handler = createInstance(manager); handler->name_ = name_.c_str(); return std::shared_ptr(std::move(handler)); } /** * \fn PipelineHandlerFactoryBase::name() * \brief Retrieve the factory name * \return The factory name */ /** * \brief Add a pipeline handler class to the registry * \param[in] factory Factory to use to construct the pipeline handler * * The caller is responsible to guarantee the uniqueness of the pipeline handler * name. */ void PipelineHandlerFactoryBase::registerType(PipelineHandlerFactoryBase *factory) { std::vector &factories = PipelineHandlerFactoryBase::factories(); factories.push_back(factory); } /** * \brief Retrieve the list of all pipeline handler factories * \return the list of pipeline handler factories */ std::vector &PipelineHandlerFactoryBase::factories() { /* * The static factories map is defined inside the function to ensure * it gets initialized on first use, without any dependency on * link order. */ static std::vector factories; return factories; } /** * \brief Return the factory for the pipeline handler with name \a name * \param[in] name The pipeline handler name * \return The factory of the pipeline with name \a name, or nullptr if not found */ const PipelineHandlerFactoryBase *PipelineHandlerFactoryBase::getFactoryByName(const std::string &name) { const std::vector &factories = PipelineHandlerFactoryBase::factories(); auto iter = std::find_if(factories.begin(), factories.end(), [&name](const PipelineHandlerFactoryBase *f) { return f->name() == name; }); if (iter != factories.end()) return *iter; return nullptr; } /** * \class PipelineHandlerFactory * \brief Registration of PipelineHandler classes and creation of instances * \tparam _PipelineHandler The pipeline handler class type for this factory * * To facilitate discovery and instantiation of PipelineHandler classes, the * PipelineHandlerFactory class implements auto-registration of pipeline * handlers. Each PipelineHandler subclass shall register itself using the * REGISTER_PIPELINE_HANDLER() macro, which will create a corresponding * instance of a PipelineHandlerFactory and register it with the static list of * factories. */ /** * \fn PipelineHandlerFactory::PipelineHandlerFactory(const char *name) * \brief Construct a pipeline handler factory * \param[in] name Name of the pipeline handler class * * Creating an instance of the factory registers it with the global list of * factories, accessible through the factories() function. * * The factory \a name is used for debug purpose and shall be unique. */ /** * \fn PipelineHandlerFactory::createInstance() const * \brief Create an instance of the PipelineHandler corresponding to the factory * \param[in] manager The camera manager * \return A unique pointer to a newly constructed instance of the * PipelineHandler subclass corresponding to the factory */ /** * \def REGISTER_PIPELINE_HANDLER * \brief Register a pipeline handler with the pipeline handler factory * \param[in] handler Class name of PipelineHandler derived class to register * \param[in] name Name assigned to the pipeline handler, matching the pipeline * subdirectory name in the source tree. * * Register a PipelineHandler subclass with the factory and make it available to * try and match devices. */ } /* namespace libcamera */