Patch Detail
Show a patch.
GET /api/patches/120/?format=api
{ "id": 120, "url": "https://patchwork.libcamera.org/api/patches/120/?format=api", "web_url": "https://patchwork.libcamera.org/patch/120/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20190101212328.18361-4-laurent.pinchart@ideasonboard.com>", "date": "2019-01-01T21:23:28", "name": "[libcamera-devel,4/4] libcamera: mediadevice: Improve documentation", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "52b4dd9c659074b72c58e3e28f2ea4665105e943", "submitter": { "id": 2, "url": "https://patchwork.libcamera.org/api/people/2/?format=api", "name": "Laurent Pinchart", "email": "laurent.pinchart@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/120/mbox/", "series": [ { "id": 45, "url": "https://patchwork.libcamera.org/api/series/45/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=45", "date": "2019-01-01T21:23:26", "name": "[libcamera-devel,1/4] libcamera: mediadevice: Fix graph parsing error handling", "version": 1, "mbox": "https://patchwork.libcamera.org/series/45/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/120/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/120/checks/", "tags": {}, "headers": { "Return-Path": "<laurent.pinchart@ideasonboard.com>", "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 9A40760B35\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 1 Jan 2019 22:22:34 +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 2C7C9505\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 1 Jan 2019 22:22:34 +0100 (CET)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1546377754;\n\tbh=BXCzdJJQ+hMAiaID4Un6OtGijZ8RxPniOI5D89cJDEw=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=Hy/zWKJGKDpwSvF3qUx8ZYpyBNBIXM2O96ic+e/xg5D0nB3mDEAlXCLh5fJzugciF\n\tZoi+iSvsMbEEu5kr/4Ye8G77clhl0KyvrDcmAhZjYXuiG+MWXHkQGKVBd3tR9DzoA7\n\trp5h8XwsSj7adWJXj+2Md4dYtcnDJT/nUNqy8cDs=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Tue, 1 Jan 2019 23:23:28 +0200", "Message-Id": "<20190101212328.18361-4-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.19.2", "In-Reply-To": "<20190101212328.18361-1-laurent.pinchart@ideasonboard.com>", "References": "<20190101212328.18361-1-laurent.pinchart@ideasonboard.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [PATCH 4/4] libcamera: mediadevice: Improve\n\tdocumentation", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.23", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "X-List-Received-Date": "Tue, 01 Jan 2019 21:22:34 -0000" }, "content": "Improve the documentation of the media device operation, including how\nit handles the lifetime of media objects.\n\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n---\n src/libcamera/include/media_device.h | 2 +-\n src/libcamera/media_device.cpp | 113 ++++++++++++++++-----------\n 2 files changed, 70 insertions(+), 45 deletions(-)", "diff": "diff --git a/src/libcamera/include/media_device.h b/src/libcamera/include/media_device.h\nindex fd1e12d1bbcb..d787be391882 100644\n--- a/src/libcamera/include/media_device.h\n+++ b/src/libcamera/include/media_device.h\n@@ -44,7 +44,7 @@ private:\n \n \tstd::map<unsigned int, MediaObject *> objects_;\n \tMediaObject *object(unsigned int id);\n-\tbool addObject(MediaObject *obj);\n+\tbool addObject(MediaObject *object);\n \tvoid clear();\n \n \tstd::vector<MediaEntity *> entities_;\ndiff --git a/src/libcamera/media_device.cpp b/src/libcamera/media_device.cpp\nindex 4c77d3787391..2470c0be806e 100644\n--- a/src/libcamera/media_device.cpp\n+++ b/src/libcamera/media_device.cpp\n@@ -32,37 +32,41 @@ namespace libcamera {\n * \\brief The MediaDevice represents a Media Controller device with its full\n * graph of connected objects.\n *\n- * Media devices are created with an empty graph, which must be populated from\n+ * A MediaDevice instance is associated with a media controller device node when\n+ * created, and that association is kept for the lifetime of the MediaDevice\n+ * instance.\n *\n+ * The instance is created with an empty media graph. Before performing any\n+ * other operation, it must be opened with the open() function and the media\n+ * graph populated by calling populate(). Instances of MediaEntity, MediaPad and\n+ * MediaLink are created to model the media graph, and stored in a map indexed\n+ * by object id.\n *\n- * The caller is responsible for opening the MediaDevice explicitly before\n- * operating on it, and shall close it when not needed anymore, as access\n- * to the MediaDevice is exclusive.\n+ * Once successfully populated the graph is valid, as reported by the valid()\n+ * function. It can be queried to list all entities(), or entities can be\n+ * looked up by name with getEntityByName(). The graph can be traversed from\n+ * entity to entity through pads and links as exposed by the corresponding\n+ * classes.\n *\n- * A MediaDevice is created empty and gets populated by inspecting the media\n- * graph topology using the MEDIA_IOC_G_TOPOLOGY ioctls. Representation\n- * of each entity, pad and link described are created using MediaObject\n- * derived classes.\n- *\n- * All MediaObject are stored in a global pool, where they could be retrieved\n- * from by their globally unique id.\n- *\n- * References to MediaEntity registered in the graph are stored in a vector\n- * to allow easier by-name lookup, and the list of MediaEntities is accessible.\n+ * An open media device will keep an open file handle for the underlying media\n+ * controller device node. It can be closed at any time with a call to close().\n+ * This will not invalidate the media graph and all cached media object remain\n+ * valid and can be accessed normally. The device can then be later reopened if\n+ * needed to perform other operations that interect with the device node.\n */\n \n /**\n * \\brief Construct a MediaDevice\n * \\param devnode The media device node path\n+ *\n+ * Once constructed the media device is invalid, and must be opened and\n+ * populated with open() and populate() before the media graph can be queried.\n */\n MediaDevice::MediaDevice(const std::string &devnode)\n \t: devnode_(devnode), fd_(-1), valid_(false)\n {\n }\n \n-/**\n- * \\brief Close the media device file descriptor and delete all object\n- */\n MediaDevice::~MediaDevice()\n {\n \tif (fd_ != -1)\n@@ -71,11 +75,18 @@ MediaDevice::~MediaDevice()\n }\n \n /**\n- * \\brief Open a media device and retrieve informations from it\n+ * \\brief Open a media device and retrieve device information\n *\n- * The function fails if the media device is already open or if either\n- * open or the media device information retrieval operations fail.\n- * \\return 0 for success or a negative error number otherwise\n+ * Before populating the media graph or performing any operation that interact\n+ * with the device node associated with the media device, the device node must\n+ * be opened.\n+ *\n+ * This function also retrieves media device information from the device node,\n+ * which can be queried through driver().\n+ *\n+ * If the device is already open the function returns -EBUSY.\n+ *\n+ * \\return 0 on success or a negative error code otherwise\n */\n int MediaDevice::open()\n {\n@@ -108,10 +119,17 @@ int MediaDevice::open()\n }\n \n /**\n- * \\brief Close the file descriptor associated with the media device.\n+ * \\brief Close the media device\n+ *\n+ * This function closes the media device node. It does not invalidate the media\n+ * graph and all cached media object remain valid and can be accessed normally.\n+ * Once closed no operation interacting with the media device node can be\n+ * performed until the device is opened again.\n *\n- * After this function has been called, for the MediaDevice to be operated on,\n- * the caller shall open it again.\n+ * Closing an already closed device is allowed and will not performed any\n+ * operation.\n+ *\n+ * \\sa open()\n */\n void MediaDevice::close()\n {\n@@ -130,9 +148,9 @@ void MediaDevice::close()\n * stored as MediaEntity, MediaPad and MediaLink respectively, with cross-\n * references between objects. Interfaces are not processed.\n *\n- * MediaEntities are stored in a global list in the MediaDevice itself to ease\n- * lookup, while MediaPads are accessible from the MediaEntity they belong\n- * to only and MediaLinks from the MediaPad they connect.\n+ * Entities are stored in a separate list in the MediaDevice to ease lookup,\n+ * while pads are accessible from the entity they belong to and links from the\n+ * pad they connect.\n *\n * \\return 0 on success, a negative error code otherwise\n */\n@@ -241,8 +259,9 @@ MediaEntity *MediaDevice::getEntityByName(const std::string &name)\n * object id.\n */\n \n-/*\n- * MediaObject pool lookup by id.\n+/**\n+ * \\brief Retrieve the media graph object specified by \\a id\n+ * \\return The graph object, or nullptr if no object with \\a id is found\n */\n MediaObject *MediaDevice::object(unsigned int id)\n {\n@@ -250,33 +269,40 @@ MediaObject *MediaDevice::object(unsigned int id)\n \treturn (it == objects_.end()) ? nullptr : it->second;\n }\n \n-/*\n- * Add a new object to the global objects pool and fail if the object\n- * has already been registered.\n+/**\n+ * \\brief Add a media object to the media graph\n+ *\n+ * If the \\a object has a unique id it is added to the media graph, and its\n+ * lifetime will be managed by the media device. Otherwise the object isn't\n+ * added to the graph and the caller must delete it.\n+ *\n+ * \\return true if the object was successfully added to the graph and false\n+ * otherwise\n */\n-bool MediaDevice::addObject(MediaObject *obj)\n+bool MediaDevice::addObject(MediaObject *object)\n {\n \n-\tif (objects_.find(obj->id()) != objects_.end()) {\n-\t\tLOG(Error) << \"Element with id \" << obj->id()\n+\tif (objects_.find(object->id()) != objects_.end()) {\n+\t\tLOG(Error) << \"Element with id \" << object->id()\n \t\t\t << \" already enumerated.\";\n \t\treturn false;\n \t}\n \n-\tobjects_[obj->id()] = obj;\n+\tobjects_[object->id()] = object;\n \n \treturn true;\n }\n \n /**\n- * \\brief Delete all media objects in the MediaDevice.\n+ * \\brief Delete all graph objects in the media device\n+ *\n+ * Clear the media graph and delete all the objects it contains. After this\n+ * function returns any previously obtained pointer to a media graph object\n+ * becomes invalid.\n *\n- * Delete all MediaEntities; entities will then delete their pads,\n- * and each source pad will delete links.\n+ * The media device graph state is reset to invalid when the graph is cleared.\n *\n- * After this function has been called, the media graph will be unpopulated\n- * and its media objects deleted. The media device has to be populated\n- * before it could be used again.\n+ * \\sa valid()\n */\n void MediaDevice::clear()\n {\n@@ -295,8 +321,7 @@ void MediaDevice::clear()\n \n /*\n * For each entity in the media graph create a MediaEntity and store a\n- * reference in the MediaObject global pool and in the global vector of\n- * entities.\n+ * reference in the media device objects map and entities list.\n */\n bool MediaDevice::populateEntities(const struct media_v2_topology &topology)\n {\n", "prefixes": [ "libcamera-devel", "4/4" ] }