The MediaDevice represents a Media Controller device with its full graph of connected objects. More...

Inheritance diagram for libcamera::MediaDevice:

Collaboration diagram for libcamera::MediaDevice:

Public Member Functions
	MediaDevice (const std::string &deviceNode)
	Construct a MediaDevice. More...

bool	acquire ()
	Claim a device for exclusive use. More...

void	release ()
	Release a device previously claimed for exclusive use. More...

bool	busy () const
	Check if a device is in use. More...

bool	lock ()
	Lock the device to prevent it from being used by other instances of libcamera. More...

void	unlock ()
	Unlock the device and free it for use for libcamera instances. More...

int	populate ()
	Populate the MediaDevice with device information and media objects. More...

bool	isValid () const
	Query whether the media graph has been populated and is valid. More...

const std::string &	driver () const
	Retrieve the media device driver name. More...

const std::string &	deviceNode () const
	Retrieve the media device node path. More...

const std::string &	model () const
	Retrieve the media device model name. More...

unsigned int	version () const
	Retrieve the media device API version. More...

unsigned int	hwRevision () const
	Retrieve the media device hardware revision. More...

const std::vector< MediaEntity * > &	entities () const
	Retrieve the list of entities in the media graph. More...

MediaEntity *	getEntityByName (const std::string &name) const
	Return the MediaEntity with name name. More...

MediaLink *	link (const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx)
	Retrieve the MediaLink connecting two pads, identified by entity names and pad indexes. More...

MediaLink *	link (const MediaEntity source, unsigned int sourceIdx, const MediaEntity sink, unsigned int sinkIdx)
	Retrieve the MediaLink connecting two pads, identified by the entities they belong to and pad indexes. More...

MediaLink *	link (const MediaPad source, const MediaPad sink)
	Retrieve the MediaLink that connects two pads. More...

int	disableLinks ()
	Disable all links in the media device. More...

Public Attributes
Signal	disconnected
	Signal emitted when the media device is disconnected from the system. More...

Protected Member Functions
std::string	logPrefix () const override
	Retrieve a string to be prefixed to the log message. More...

Protected Member Functions inherited from libcamera::Loggable
LogMessage	_log (const LogCategory category, LogSeverity severity, const char fileName=__builtin_FILE(), unsigned int line=__builtin_LINE()) const
	Create a temporary LogMessage object to log a message. More...

Friends
int	MediaLink::setEnabled (bool enable)

Detailed Description

The MediaDevice represents a Media Controller device with its full graph of connected objects.

A MediaDevice instance is associated with a media controller device node when created, and that association is kept for the lifetime of the MediaDevice instance.

The instance is created with an empty media graph. Before performing any other operation, it must be populate by calling populate(). Instances of MediaEntity, MediaPad and MediaLink are created to model the media graph, and stored in a map indexed by object id.

The graph is valid once successfully populated, as reported by the isValid() function. It can be queried to list all entities(), or entities can be looked up by name with getEntityByName(). The graph can be traversed from entity to entity through pads and links as exposed by the corresponding classes.

Media devices can be claimed for exclusive use with acquire(), released with release() and tested with busy(). This mechanism is aimed at pipeline managers to claim media devices they support during enumeration.

Constructor & Destructor Documentation

◆ MediaDevice()

libcamera::MediaDevice::MediaDevice ( const std::string & deviceNode )

Construct a MediaDevice.

Parameters

[in] deviceNode The media device node path

Once constructed the media device is invalid, and must be populated with populate() before the media graph can be queried.

Member Function Documentation

◆ acquire()

bool libcamera::MediaDevice::acquire ( )

Claim a device for exclusive use.

The device claiming mechanism offers simple media device access arbitration between multiple users. When the media device is created, it is available to all users. Users can query the media graph to determine whether they can support the device and, if they do, claim the device for exclusive use. Other users are then expected to skip over media devices in use as reported by the busy() function.

Once claimed the device shall be released by its user when not needed anymore by calling the release() function. Acquiring the media device opens a file descriptor to the device which is kept open until release() is called.

Exclusive access is only guaranteed if all users of the media device abide by the device claiming mechanism, as it isn't enforced by the media device itself.

Returns: true if the device was successfully claimed, or false if it was already in use

See also: release(), busy()

◆ busy()

libcamera::MediaDevice::busy ( ) const

inline

Check if a device is in use.

Returns: true if the device has been claimed for exclusive use, or false if it is available

See also: acquire(), release()

◆ deviceNode()

libcamera::MediaDevice::deviceNode ( ) const

inline

Retrieve the media device node path.

Returns: The MediaDevice deviceNode path

◆ disableLinks()

int libcamera::MediaDevice::disableLinks ( )

Disable all links in the media device.

Disable all the media device links, clearing the MEDIA_LNK_FL_ENABLED flag on links which are not flagged as IMMUTABLE.

Returns: 0 on success or a negative error code otherwise

◆ driver()

libcamera::MediaDevice::driver ( ) const

inline

Retrieve the media device driver name.

Returns: The name of the kernel driver that handles the MediaDevice

◆ entities()

libcamera::MediaDevice::entities ( ) const

inline

Retrieve the list of entities in the media graph.

Returns: The list of MediaEntities registered in the MediaDevice

◆ getEntityByName()

MediaEntity * libcamera::MediaDevice::getEntityByName ( const std::string & name ) const

Return the MediaEntity with name name.

Parameters

[in] name The entity name

Returns: The entity with name, or nullptr if no such entity is found

◆ hwRevision()

libcamera::MediaDevice::hwRevision ( ) const

inline

Retrieve the media device hardware revision.

The hardware revision is in a driver-specific format.

Returns: The MediaDevice hardware revision

◆ isValid()

libcamera::MediaDevice::isValid ( ) const

inline

Query whether the media graph has been populated and is valid.

Returns: true if the media graph is valid, false otherwise

◆ link() [1/3]

MediaLink * libcamera::MediaDevice::link	(	const std::string &	sourceName,
		unsigned int	sourceIdx,
		const std::string &	sinkName,
		unsigned int	sinkIdx
	)

Retrieve the MediaLink connecting two pads, identified by entity names and pad indexes.

Parameters

[in]	sourceName	The source entity name
[in]	sourceIdx	The index of the source pad
[in]	sinkName	The sink entity name
[in]	sinkIdx	The index of the sink pad

Find the link that connects the pads at index sourceIdx of the source entity with name sourceName, to the pad at index sinkIdx of the sink entity with name sinkName, if any.

See also: link(const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx); link(const MediaPad *source, const MediaPad *sink)

Returns: The link that connects the two pads, or nullptr if no such a link exists

◆ link() [2/3]

MediaLink * libcamera::MediaDevice::link	(	const MediaEntity *	source,
		unsigned int	sourceIdx,
		const MediaEntity *	sink,
		unsigned int	sinkIdx
	)

Retrieve the MediaLink connecting two pads, identified by the entities they belong to and pad indexes.

Parameters

[in]	source	The source entity
[in]	sourceIdx	The index of the source pad
[in]	sink	The sink entity
[in]	sinkIdx	The index of the sink pad

Find the link that connects the pads at index sourceIdx of the source entity source, to the pad at index sinkIdx of the sink entity sink, if any.

See also: link(const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx); link(const MediaPad *source, const MediaPad *sink)

Returns: The link that connects the two pads, or nullptr if no such a link exists

◆ link() [3/3]

MediaLink * libcamera::MediaDevice::link	(	const MediaPad *	source,
		const MediaPad *	sink
	)

Retrieve the MediaLink that connects two pads.

Parameters

[in]	source	The source pad
[in]	sink	The sink pad

See also: link(const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx); link(const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx)

Returns: The link that connects the two pads, or nullptr if no such a link exists

◆ lock()

bool libcamera::MediaDevice::lock ( )

Lock the device to prevent it from being used by other instances of libcamera.

Multiple instances of libcamera might be running on the same system, at the same time. To allow the different instances to coexist, system resources in the form of media devices must be accessible for enumerating the cameras they provide at all times, while still allowing an instance to lock a resource while it prepares to actively use a camera from the resource.

This function shall not be called from a pipeline handler implementation directly, as the base PipelineHandler implementation handles this on the behalf of the specified implementation.

Returns: True if the device could be locked, false otherwise

See also: unlock()

◆ logPrefix()

std::string libcamera::MediaDevice::logPrefix ( ) const

overrideprotectedvirtual

Retrieve a string to be prefixed to the log message.

This function allows classes inheriting from the Loggable class to extend the logger with an object-specific prefix output right before the log message contents.

Returns: A string to be prefixed to the log message

Implements libcamera::Loggable.

◆ model()

libcamera::MediaDevice::model ( ) const

inline

Retrieve the media device model name.

Returns: The MediaDevice model name

◆ populate()

int libcamera::MediaDevice::populate ( )

Populate the MediaDevice with device information and media objects.

This function retrieves the media device information and enumerates all media objects in the media device graph and creates their MediaObject representations. All entities, pads and links are stored as MediaEntity, MediaPad and MediaLink respectively, with cross-references between objects. Interfaces are not processed.

Entities are stored in a separate list in the MediaDevice to ease lookup, while pads are accessible from the entity they belong to and links from the pads they connect.

Returns: 0 on success or a negative error code otherwise

◆ release()

void libcamera::MediaDevice::release ( )

Release a device previously claimed for exclusive use.

See also: acquire(), busy()

◆ unlock()

void libcamera::MediaDevice::unlock ( )

Unlock the device and free it for use for libcamera instances.

This function shall not be called from a pipeline handler implementation directly, as the base PipelineHandler implementation handles this on the behalf of the specified implementation.

See also: lock()

◆ version()

libcamera::MediaDevice::version ( ) const

inline

Retrieve the media device API version.

The version is formatted with the KERNEL_VERSION() macro.

Returns: The MediaDevice API version

Member Data Documentation

◆ disconnected

libcamera::MediaDevice::disconnected

Signal emitted when the media device is disconnected from the system.

This signal is emitted when the device enumerator detects that the media device has been removed from the system. For hot-pluggable devices this is usually caused by physical device disconnection, but can also result from driver unloading for most devices. The media device is passed as a parameter.

The documentation for this class was generated from the following files:

include/libcamera/internal/media_device.h
src/libcamera/media_device.cpp

Public Member Functions

Public Attributes

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ MediaDevice()

Member Function Documentation

◆ acquire()

◆ busy()

◆ deviceNode()

◆ disableLinks()

◆ driver()

◆ entities()

◆ getEntityByName()

◆ hwRevision()

◆ isValid()

◆ link() [1/3]

◆ link() [2/3]

◆ link() [3/3]

◆ lock()

◆ logPrefix()

◆ model()

◆ populate()

◆ release()

◆ unlock()

◆ version()

Member Data Documentation

◆ disconnected