{"id":141,"url":"https://patchwork.libcamera.org/api/patches/141/?format=json","web_url":"https://patchwork.libcamera.org/patch/141/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20190103013110.6849-7-laurent.pinchart@ideasonboard.com>","date":"2019-01-03T01:31:08","name":"[libcamera-devel,7/9] libcamera: device_enumerator: Improve documentation","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"a0d87dbb2aa83ce0a62b6048eb72112dac972836","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/?format=json","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/141/mbox/","series":[{"id":51,"url":"https://patchwork.libcamera.org/api/series/51/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=51","date":"2019-01-03T01:31:02","name":"[libcamera-devel,1/9] libcamera: camera_manager: Remove put() method","version":1,"mbox":"https://patchwork.libcamera.org/series/51/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/141/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/141/checks/","tags":{},"headers":{"Return-Path":"","Received":["from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 6026860B40\n\tfor ;\n\tThu, 3 Jan 2019 02:30:15 +0100 (CET)","from avalon.bb.dnainternet.fi\n\t(dfj612ybrt5fhg77mgycy-3.rev.dnainternet.fi\n\t[IPv6:2001:14ba:21f5:5b00:2e86:4862:ef6a:2804])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id DC747A04\n\tfor ;\n\tThu, 3 Jan 2019 02:30:14 +0100 (CET)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1546479015;\n\tbh=Bpz1KlYHEkF+A3MezwnvwYB0mhvamttFcxt2xdw1Ob8=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=Ast0pS7jhTd3T+0M3hSZ2fOmGoIX6TQQulAiL7hrUKauCOUjUAqK2HICMjfTJUM+p\n\tk+dcsIgfF2JzZ7pjYcErTlsXrbJmHBSIsLKOsHb38cGYZjkNmSW8RojNPyD1SnfvnN\n\tYYjPYs/hcHiHkLZVTgw+DotP8MNTNmSSZK0oTi7s=","From":"Laurent Pinchart ","To":"libcamera-devel@lists.libcamera.org","Date":"Thu, 3 Jan 2019 03:31:08 +0200","Message-Id":"<20190103013110.6849-7-laurent.pinchart@ideasonboard.com>","X-Mailer":"git-send-email 2.19.2","In-Reply-To":"<20190103013110.6849-1-laurent.pinchart@ideasonboard.com>","References":"<20190103013110.6849-1-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 7/9] libcamera: device_enumerator: Improve\n\tdocumentation","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Thu, 03 Jan 2019 01:30:16 -0000"},"content":"Miscellaneous documentation improvements for the DeviceEnumerator and\nrelated classes.\n\nSigned-off-by: Laurent Pinchart \n---\n src/libcamera/device_enumerator.cpp | 166 +++++++++++++++-------------\n 1 file changed, 88 insertions(+), 78 deletions(-)","diff":"diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp\nindex a301420f39e1..81f6927b44e1 100644\n--- a/src/libcamera/device_enumerator.cpp\n+++ b/src/libcamera/device_enumerator.cpp\n@@ -17,27 +17,25 @@\n \n /**\n * \\file device_enumerator.h\n- * \\brief Enumerating and matching of media devices\n+ * \\brief Enumeration and matching of media devices\n *\n- * The purpose of device enumeration and matching is to find media\n- * devices in the system and map one or more media devices to a pipeline\n- * handler. During enumeration information about each media device is\n- * gathered, transformed and stored.\n+ * The purpose of device enumeration and matching is to find media devices in\n+ * the system and map them to pipeline handlers.\n *\n- * The core of the enumeration is DeviceEnumerator which is responsible\n- * for all interactions with the operating system and the entry point\n- * for other parts of libcamera.\n+ * At the code of the enumeration is the DeviceEnumerator class, responsible\n+ * for enumerating all media devices in the system. It handles all interactions\n+ * with the operating system in a platform-specific way. For each media device\n+ * found an instance of MediaDevice is created to store information about the\n+ * device gathered from the kernel through the Media Controller API.\n *\n- * The DeviceEnumerator can enumerate all or specific media devices in\n- * the system. When a new media device is added the enumerator creates a\n+ * The DeviceEnumerator can enumerate all or specific media devices in the\n+ * system. When a new media device is added the enumerator creates a\n * corresponding MediaDevice instance.\n *\n- * The last functionality provided is the ability to search among the\n- * enumerate media devices for one matching information known to the\n- * searcher. This is done by populating and passing a DeviceMatch object\n- * to the DeviceEnumerator.\n+ * The enumerator supports searching among enumerated devices based on criteria\n+ * expressed in a DeviceMatch object.\n *\n- * \\todo Add sysfs based device enumerator\n+ * \\todo Add sysfs based device enumerator.\n * \\todo Add support for hot-plug and hot-unplug.\n */\n \n@@ -47,18 +45,17 @@ namespace libcamera {\n * \\class DeviceMatch\n * \\brief Description of a media device search pattern\n *\n- * The DeviceMatch class describes a media device using properties from\n- * the v4l2 struct media_device_info, entity names in the media graph or\n- * other properties which can be used to identify a media device.\n+ * The DeviceMatch class describes a media device using properties from the\n+ * Media Controller struct media_device_info, entity names in the media graph\n+ * or other properties that can be used to identify a media device.\n *\n- * The description of a media device can then be passed to an enumerator\n- * to try and find a matching media device.\n+ * The description is meant to be filled by pipeline managers and passed to a\n+ * device enumerator to find matching media devices.\n */\n \n /**\n * \\brief Construct a media device search pattern\n- *\n- * \\param[in] driver The Linux device driver name who created the media device\n+ * \\param[in] driver The Linux device driver name that created the media device\n */\n DeviceMatch::DeviceMatch(const std::string &driver)\n \t: driver_(driver)\n@@ -67,7 +64,6 @@ DeviceMatch::DeviceMatch(const std::string &driver)\n \n /**\n * \\brief Add a media entity name to the search pattern\n- *\n * \\param[in] entity The name of the entity in the media graph\n */\n void DeviceMatch::add(const std::string &entity)\n@@ -79,8 +75,9 @@ void DeviceMatch::add(const std::string &entity)\n * \\brief Compare a search pattern with a media device\n * \\param[in] device The media device\n *\n- * Matching is performed on the Linux device driver name and entity names\n- * from the media graph.\n+ * Matching is performed on the Linux device driver name and entity names from\n+ * the media graph. A match is found if both the driver name matches and the\n+ * media device contains all the entities listed in the search pattern.\n *\n * \\return true if the media device matches the search pattern, false otherwise\n */\n@@ -108,43 +105,44 @@ bool DeviceMatch::match(const MediaDevice *device) const\n \n /**\n * \\class DeviceEnumerator\n- * \\brief Enumerate, interrogate, store and search media device information\n- *\n- * The DeviceEnumerator class is responsible for all interactions with\n- * the operation system when searching and interrogating media devices.\n+ * \\brief Enumerate, store and search media devices\n *\n- * It is possible to automatically search and add all media devices in\n- * the system or specify which media devices should be interrogated\n- * in order for a specialized application to open as few resources\n- * as possible to get hold of a specific camera.\n- *\n- * Once one or many media devices have been enumerated it is possible\n- * to search among them to try and find a matching device using a\n- * DeviceMatch object.\n+ * The DeviceEnumerator class is responsible for all interactions with the\n+ * operating system related to media devices. It enumerates all media devices\n+ * in the system, and for each device found creates an instance of the\n+ * MediaDevice class and stores it internally. The list of media devices can\n+ * then be searched using DeviceMatch search patterns.\n *\n+ * The enumerator also associates media device entities with device node paths.\n */\n \n /**\n * \\brief Create a new device enumerator matching the systems capabilities\n *\n- * Create a enumerator based on resource available to the system. Not all\n- * different enumerator types are guaranteed to support all features.\n+ * Depending on how the operating system handles device detection, hot-plug\n+ * notification and device node lookup, different device enumerator\n+ * implementations may be needed. This function creates the best enumerator for\n+ * the operating system based on the available resources. Not all different\n+ * enumerator types are guaranteed to support all features.\n */\n DeviceEnumerator *DeviceEnumerator::create()\n {\n \tDeviceEnumerator *enumerator;\n \n-\t/* TODO: add compile time checks to only try udev enumerator if libudev is available */\n+\t/**\n+\t * \\todo Add compile time checks to only try udev enumerator if libudev\n+\t * is available.\n+\t */\n \tenumerator = new DeviceEnumeratorUdev();\n \tif (!enumerator->init())\n \t\treturn enumerator;\n \n \t/*\n-\t * NOTE: Either udev is not available or initialization of it\n-\t * failed, use/fallback on sysfs enumerator\n+\t * Either udev is not available or udev initialization failed. Fall back\n+\t * on the sysfs enumerator.\n \t */\n \n-\t/* TODO: add a sysfs based enumerator */\n+\t/** \\todo Add a sysfs-based enumerator. */\n \n \treturn nullptr;\n }\n@@ -160,13 +158,38 @@ DeviceEnumerator::~DeviceEnumerator()\n }\n \n /**\n- * \\brief Add a media device to the enumerator\n+ * \\fn DeviceEnumerator::init()\n+ * \\brief Initialize the enumerator\n+ * \\return 0 on success, or a negative error code otherwise\n+ * \\retval -EBUSY the enumerator has already been initialized\n+ * \\retval -ENODEV the enumerator can't enumerate devices\n+ */\n+\n+/**\n+ * \\fn DeviceEnumerator::enumerate()\n+ * \\brief Enumerate all media devices in the system\n+ *\n+ * This function finds and add all media devices in the system to the\n+ * enumerator. It shall be implemented by all subclasses of DeviceEnumerator\n+ * using system-specific methods.\n+ *\n+ * Individual media devices that can't be properly enumerated shall be skipped\n+ * with a warning message logged, without returning an error. Only errors that\n+ * prevent enumeration altogether shall be fatal.\n *\n+ * \\return 0 on success, or a negative error code on fatal errors.\n+ */\n+\n+/**\n+ * \\brief Add a media device to the enumerator\n * \\param[in] devnode path to the media device to add\n *\n- * Opens the media device and quires its topology and other information.\n+ * Create a media device for the \\a devnode, open it, populate its media graph,\n+ * and look up device nodes associated with all entities. Store the media device\n+ * in the internal list for later matching with pipeline handlers.\n *\n- * \\return 0 on success none zero otherwise\n+ * \\return 0 on success, or a negative error code if the media device can't be\n+ * created or populated\n */\n int DeviceEnumerator::addDevice(const std::string &devnode)\n {\n@@ -205,15 +228,14 @@ int DeviceEnumerator::addDevice(const std::string &devnode)\n \n /**\n * \\brief Search available media devices for a pattern match\n- *\n * \\param[in] dm Search pattern\n *\n- * Search in the enumerated media devices that are not already in use\n- * for a match described in \\a dm. If a match is found and the caller\n- * intends to use it the caller is responsible to mark the MediaDevice\n- * object as in use and to release it when it's done with it.\n+ * Search in the enumerated media devices that are not already in use for a\n+ * match described in \\a dm. If a match is found and the caller intends to use\n+ * it the caller is responsible for acquiring the MediaDevice object and\n+ * releasing it when done with it.\n *\n- * \\return pointer to the matching MediaDevice, nullptr if no match is found\n+ * \\return pointer to the matching MediaDevice, or nullptr if no match is found\n */\n MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n {\n@@ -229,10 +251,21 @@ MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n }\n \n /**\n- * \\class DeviceEnumeratorUdev\n- * \\brief Udev implementation of device enumeration\n+ * \\fn DeviceEnumerator::lookupDevnode(int major, int minor)\n+ * \\brief Lookup device node path from device number\n+ * \\param major The device major number\n+ * \\param minor The device minor number\n *\n- * Implementation of system enumeration functions using libudev.\n+ * Translate a device number given as \\a major and \\a minor to a device node\n+ * path.\n+ *\n+ * \\return the device node path on success, or an empty string if the lookup\n+ * fails\n+ */\n+\n+/**\n+ * \\class DeviceEnumeratorUdev\n+ * \\brief Device enumerator based on libudev\n */\n \n DeviceEnumeratorUdev::DeviceEnumeratorUdev()\n@@ -246,13 +279,6 @@ DeviceEnumeratorUdev::~DeviceEnumeratorUdev()\n \t\tudev_unref(udev_);\n }\n \n-/**\n- * \\brief Initialize the enumerator\n- *\n- * \\retval 0 Initialized\n- * \\retval -EBUSY Busy (already initialized)\n- * \\retval -ENODEV Failed to talk to udev\n- */\n int DeviceEnumeratorUdev::init()\n {\n \tif (udev_)\n@@ -265,14 +291,6 @@ int DeviceEnumeratorUdev::init()\n \treturn 0;\n }\n \n-/**\n- * \\brief Enumerate all media devices using udev\n- *\n- * Find, enumerate and add all media devices in the system to the\n- * enumerator.\n- *\n- * \\return 0 on success none zero otherwise\n- */\n int DeviceEnumeratorUdev::enumerate()\n {\n \tstruct udev_enumerate *udev_enum = nullptr;\n@@ -323,14 +341,6 @@ done:\n \treturn ret >= 0 ? 0 : ret;\n }\n \n-/**\n- * \\brief Lookup device node from device number using udev\n- *\n- * Translate a device number (major, minor) to a device node path.\n- *\n- * \\return device node path or empty string if lookup fails.\n- *\n- */\n std::string DeviceEnumeratorUdev::lookupDevnode(int major, int minor)\n {\n \tstruct udev_device *device;\n","prefixes":["libcamera-devel","7/9"]}