| // Copyright 2024 The Fuchsia Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| #ifndef LIB_DRIVER_NODE_CPP_ADD_CHILD_H_ | |
| #define LIB_DRIVER_NODE_CPP_ADD_CHILD_H_ | |
| #include <fidl/fuchsia.driver.framework/cpp/markers.h> | |
| #include <lib/driver/logging/cpp/logger.h> | |
| #include <lib/stdcompat/span.h> | |
| // The following functions can be used to add various types of child nodes to a parent node. | |
| // There are two main types of nodes, owned and un-owned. | |
| // | |
| // Owned: An owned node belongs to the driver creating it, so the driver framework will not try to | |
| // match it up to another driver. Therefore when you create an owned node, you must maintain the | |
| // connection to the node by holding on to the client end. | |
| // | |
| // Un-owned: These are nodes that are not owned by the creating driver. The driver framework will | |
| // go through the driver matching process to find a matching driver, and start the matched driver | |
| // and bind it to the node. The node can provide resources to the bound driver through its offers. | |
| // | |
| // Once the type of node being created is chosen, the next step is to choose whether the node | |
| // should export itself into devfs. The driver framework team is currently in the process of | |
| // deprecating devfs in favor of service capabilities, but until that solution is available, devfs | |
| // is how non-driver components can connect to driver provided protocols. If your node needs to | |
| // provide devfs support, that is available through the variants that support the DevfsAddArgs. | |
| namespace fdf { | |
| // Contains the client ends for an owned child node that was created using the helper functions. | |
| // This must be handled since the driver must ensure not to drop the node client. | |
| struct [[nodiscard]] OwnedChildNode { | |
| // This is a client to the node controller. This is safe to drop if not needed. | |
| fidl::ClientEnd<fuchsia_driver_framework::NodeController> node_controller_; | |
| // The client MUST keep this, as dropping it will result in the added node to be removed by the | |
| // driver framework. | |
| fidl::ClientEnd<fuchsia_driver_framework::Node> node_; | |
| }; | |
| // Adds an owned child node under the given |parent|. The driver framework will NOT try to match | |
| // and bind a driver to this child as it is already owned by the current driver. | |
| // | |
| // This is a synchronous call and requires that the dispatcher allow sync calls. | |
| zx::result<OwnedChildNode> AddOwnedChild( | |
| fidl::UnownedClientEnd<fuchsia_driver_framework::Node> parent, fdf::Logger& logger, | |
| std::string_view node_name); | |
| // Creates an owned child node with devfs support under the given |parent|. The driver framework | |
| // will NOT try to match and bind a driver to this child as it is already owned by the current | |
| // driver. | |
| // | |
| // This is a synchronous call and requires that the dispatcher allow sync calls. | |
| zx::result<OwnedChildNode> AddOwnedChild( | |
| fidl::UnownedClientEnd<fuchsia_driver_framework::Node> parent, fdf::Logger& logger, | |
| std::string_view node_name, fuchsia_driver_framework::DevfsAddArgs& devfs_args); | |
| // Adds an un-owned child node under the given |parent|. The driver framework will try to match | |
| // and bind a driver to this child. | |
| // | |
| // This is a synchronous call and requires that the dispatcher allow sync calls. | |
| zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild( | |
| fidl::UnownedClientEnd<fuchsia_driver_framework::Node> parent, fdf::Logger& logger, | |
| std::string_view node_name, | |
| cpp20::span<const fuchsia_driver_framework::NodeProperty2> properties, | |
| cpp20::span<const fuchsia_driver_framework::Offer> offers); | |
| // Adds an un-owned child node under the given |parent|. The driver framework will try to match | |
| // and bind a driver to this child. | |
| // | |
| // This is a synchronous call and requires that the dispatcher allow sync calls. | |
| zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild( | |
| fidl::UnownedClientEnd<fuchsia_driver_framework::Node> parent, fdf::Logger& logger, | |
| std::string_view node_name, fuchsia_driver_framework::DevfsAddArgs& devfs_args, | |
| cpp20::span<const fuchsia_driver_framework::NodeProperty2> properties, | |
| cpp20::span<const fuchsia_driver_framework::Offer> offers); | |
| } // namespace fdf | |
| #endif // LIB_DRIVER_NODE_CPP_ADD_CHILD_H_ |