test/media_device/media_device_print_test.cpp


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

/* SPDX-License-Identifier: GPL-2.0-or-later */
/*
 * Copyright (C) 2018-2019, Google Inc.
 *
 * media_device_print_test.cpp - Print out media devices
 */

#include <iostream>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

#include "media_device.h"

#include "test.h"

using namespace libcamera;
using namespace std;

/*
 * MediaDevicePrintTest takes all media devices found in the system and print
 * them out to verify correctness.
 *
 * If no accessible media device is found, the test is skipped.
 */
class MediaDevicePrintTest : public Test
{
public:
	MediaDevicePrintTest() {}
	~MediaDevicePrintTest() {}

protected:
	int init() { return 0; }
	int run();
	void cleanup() {}

private:
	int testMediaDevice(string deviceNode);

	void printMediaGraph(const MediaDevice &media, ostream &os);
	void printLinkFlags(const MediaLink *link, ostream &os);
	void printNode(const MediaPad *pad, ostream &os);
};

void MediaDevicePrintTest::printNode(const MediaPad *pad, ostream &os)
{
	const MediaEntity *entity = pad->entity();

	os << "\"" << entity->name() << "\"["
	   << pad->index() << "]";
}

void MediaDevicePrintTest::printLinkFlags(const MediaLink *link, ostream &os)
{
	unsigned int flags = link->flags();

	os << " [";
	if (flags) {
		os << (flags & MEDIA_LNK_FL_ENABLED ? "ENABLED," : "")
		   << (flags & MEDIA_LNK_FL_IMMUTABLE ? "IMMUTABLE" : "");
	}
	os  << "]\n";
}

/*
 * For each entity in the media graph, printout links directed to its sinks
 * and source pads.
 */
void MediaDevicePrintTest::printMediaGraph(const MediaDevice &media, ostream &os)
{
	os << "\n" << media.driver() << " - " << media.deviceNode() << "\n\n";

	for (auto const &entity : media.entities()) {
		os << "\"" << entity->name() << "\"\n";

		for (auto const &sink : entity->pads()) {
			if (!(sink->flags() & MEDIA_PAD_FL_SINK))
				continue;

			os << "  [" << sink->index() << "]" << ": Sink\n";
			for (auto const &link : sink->links()) {
				os << "\t";
				printNode(sink, os);
				os << " <- ";
				printNode(link->source(), os);
				printLinkFlags(link, os);
			}
			os << "\n";
		}

		for (auto const &source : entity->pads()) {
			if (!(source->flags() & MEDIA_PAD_FL_SOURCE))
				continue;

			os << "  [" << source->index() << "]" << ": Source\n";
			for (auto const &link : source->links()) {
				os << "\t";
				printNode(source, os);
				os << " -> ";
				printNode(link->sink(), os);
				printLinkFlags(link, os);
			}
			os << "\n";
		}
	}

	os.flush();
}

/* Test a single media device. */
int MediaDevicePrintTest::testMediaDevice(const string deviceNode)
{
	MediaDevice dev(deviceNode);
	int ret;

	ret = dev.populate();
	if (ret)
		return ret;

	/* Print out the media graph. */
	printMediaGraph(dev, cerr);

	return 0;
}

/* Run tests on all media devices. */
#define MAX_MEDIA_DEV 256
int MediaDevicePrintTest::run()
{
	const string deviceNode("/dev/media");
	unsigned int i;
	int ret = 77; /* skip test exit code */

	/*
	 * Run the test sequence on all media device found in the
	 * system, if any.
	 */
	for (i = 0; i < MAX_MEDIA_DEV; i++) {
		string mediadev = deviceNode + to_string(i);
		struct stat pstat = {};

		if (stat(mediadev.c_str(), &pstat))
			continue;

		ret = testMediaDevice(mediadev);
		if (ret)
			return ret;

	}

	return ret;
}

TEST_REGISTER(MediaDevicePrintTest);
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2018, Google Inc.
 *
 * Media device handler
 */

#include "libcamera/internal/media_device.h"

#include <errno.h>
#include <fcntl.h>
#include <stdint.h>
#include <string>
#include <string.h>
#include <sys/ioctl.h>
#include <unistd.h>
#include <vector>

#include <linux/media.h>

#include <libcamera/base/log.h>

/**
 * \file media_device.h
 * \brief Provide a representation of a Linux kernel Media Controller device
 * that exposes the full graph topology.
 */

namespace libcamera {

LOG_DEFINE_CATEGORY(MediaDevice)

/**
 * \class MediaDevice
 * \brief 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.
 */

/**
 * \brief Construct a MediaDevice
 * \param[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.
 */
MediaDevice::MediaDevice(const std::string &deviceNode)
	: deviceNode_(deviceNode), valid_(false), acquired_(false)
{
}

MediaDevice::~MediaDevice()
{
	fd_.reset();
	clear();
}

std::string MediaDevice::logPrefix() const
{
	return deviceNode() + "[" + driver() + "]";
}

/**
 * \brief 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.
 *
 * \return true if the device was successfully claimed, or false if it was
 * already in use
 * \sa release(), busy()
 */
bool MediaDevice::acquire()
{
	if (acquired_)
		return false;

	if (open())
		return false;

	acquired_ = true;
	return true;
}

/**
 * \brief Release a device previously claimed for exclusive use
 * \sa acquire(), busy()
 */
void MediaDevice::release()
{
	close();
	acquired_ = false;
}

/**
 * \brief 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.
 *
 * \return True if the device could be locked, false otherwise
 * \sa unlock()
 */
bool MediaDevice::lock()
{
	if (!fd_.isValid())
		return false;

	if (lockf(fd_.get(), F_TLOCK, 0))
		return false;

	return true;
}

/**
 * \brief 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.
 *
 * \sa lock()
 */
void MediaDevice::unlock()
{
	if (!fd_.isValid())
		return;

	lockf(fd_.get(), F_ULOCK, 0);
}

/**
 * \fn MediaDevice::busy()
 * \brief Check if a device is in use
 * \return true if the device has been claimed for exclusive use, or false if it
 * is available
 * \sa acquire(), release()
 */

/**
 * \brief 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.
 *
 * \return 0 on success or a negative error code otherwise
 */
int MediaDevice::populate()
{
	struct media_v2_topology topology = {};
	struct media_v2_entity *ents = nullptr;
	struct media_v2_interface *interfaces = nullptr;
	struct media_v2_link *links = nullptr;
	struct media_v2_pad *pads = nullptr;
	__u64 version = -1;
	int ret;

	clear();

	ret = open();
	if (ret)
		return ret;

	struct media_device_info info = {};
	ret = ioctl(fd_.get(), MEDIA_IOC_DEVICE_INFO, &info);
	if (ret) {
		ret = -errno;
		LOG(MediaDevice, Error)
			<< "Failed to get media device info " << strerror(-ret);
		goto done;
	}

	driver_ = info.driver;
	model_ = info.model;
	version_ = info.media_version;
	hwRevision_ = info.hw_revision;

	/*
	 * Keep calling G_TOPOLOGY until the version number stays stable.
	 */
	while (true) {
		topology.topology_version = 0;
		topology.ptr_entities = reinterpret_cast<uintptr_t>(ents);
		topology.ptr_interfaces = reinterpret_cast<uintptr_t>(interfaces);
		topology.ptr_links = reinterpret_cast<uintptr_t>(links);
		topology.ptr_pads = reinterpret_cast<uintptr_t>(pads);

		ret = ioctl(fd_.get(), MEDIA_IOC_G_TOPOLOGY, &topology);
		if (ret < 0) {
			ret = -errno;
			LOG(MediaDevice, Error)
				<< "Failed to enumerate topology: "
				<< strerror(-ret);
			goto done;
		}

		if (version == topology.topology_version)
			break;

		delete[] ents;
		delete[] interfaces;
		delete[] pads;
		delete[] links;

		ents = new struct media_v2_entity[topology.num_entities]();
		interfaces = new struct media_v2_interface[topology.num_interfaces]();
		links = new struct media_v2_link[topology.num_links]();
		pads = new struct media_v2_pad[topology.num_pads]();

		version = topology.topology_version;
	}

	/* Populate entities, pads and links. */
	if (populateEntities(topology) &&
	    populatePads(topology) &&
	    populateLinks(topology))
		valid_ = true;

	ret = 0;
done:
	close();

	delete[] ents;
	delete[] interfaces;
	delete[] pads;
	delete[] links;

	if (!valid_) {
		clear();
		return -EINVAL;
	}

	return ret;
}

/**
 * \fn MediaDevice::isValid()
 * \brief Query whether the media graph has been populated and is valid
 * \return true if the media graph is valid, false otherwise
 */

/**
 * \fn MediaDevice::driver()
 * \brief Retrieve the media device driver name
 * \return The name of the kernel driver that handles the MediaDevice
 */

/**
 * \fn MediaDevice::deviceNode()