linux/drivers/base/swnode.c

// SPDX-License-Identifier: GPL-2.0
/*
 * Software nodes for the firmware node framework.
 *
 * Copyright (C) 2018, Intel Corporation
 * Author: Heikki Krogerus <[email protected]>
 */

#include <linux/container_of.h>
#include <linux/device.h>
#include <linux/err.h>
#include <linux/export.h>
#include <linux/idr.h>
#include <linux/init.h>
#include <linux/kobject.h>
#include <linux/kstrtox.h>
#include <linux/list.h>
#include <linux/property.h>
#include <linux/slab.h>
#include <linux/spinlock.h>
#include <linux/string.h>
#include <linux/sysfs.h>
#include <linux/types.h>

#include "base.h"

struct swnode { … };

static DEFINE_IDA(swnode_root_ids);
static struct kset *swnode_kset;

#define kobj_to_swnode(_kobj_) …

static const struct fwnode_operations software_node_ops;

bool is_software_node(const struct fwnode_handle *fwnode)
{ … }
EXPORT_SYMBOL_GPL(…);

#define to_swnode(__fwnode) …

static inline struct swnode *dev_to_swnode(struct device *dev)
{ … }

static struct swnode *
software_node_to_swnode(const struct software_node *node)
{ … }

const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
{ … }
EXPORT_SYMBOL_GPL(…);

struct fwnode_handle *software_node_fwnode(const struct software_node *node)
{ … }
EXPORT_SYMBOL_GPL(…);

/* -------------------------------------------------------------------------- */
/* property_entry processing */

static const struct property_entry *
property_entry_get(const struct property_entry *prop, const char *name)
{ … }

static const void *property_get_pointer(const struct property_entry *prop)
{ … }

static const void *property_entry_find(const struct property_entry *props,
				       const char *propname, size_t length)
{ … }

static int
property_entry_count_elems_of_size(const struct property_entry *props,
				   const char *propname, size_t length)
{ … }

static int property_entry_read_int_array(const struct property_entry *props,
					 const char *name,
					 unsigned int elem_size, void *val,
					 size_t nval)
{ … }

static int property_entry_read_string_array(const struct property_entry *props,
					    const char *propname,
					    const char **strings, size_t nval)
{ … }

static void property_entry_free_data(const struct property_entry *p)
{ … }

static bool property_copy_string_array(const char **dst_ptr,
				       const char * const *src_ptr,
				       size_t nval)
{ … }

static int property_entry_copy_data(struct property_entry *dst,
				    const struct property_entry *src)
{ … }

/**
 * property_entries_dup - duplicate array of properties
 * @properties: array of properties to copy
 *
 * This function creates a deep copy of the given NULL-terminated array
 * of property entries.
 */
struct property_entry *
property_entries_dup(const struct property_entry *properties)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * property_entries_free - free previously allocated array of properties
 * @properties: array of properties to destroy
 *
 * This function frees given NULL-terminated array of property entries,
 * along with their data.
 */
void property_entries_free(const struct property_entry *properties)
{ … }
EXPORT_SYMBOL_GPL(…);

/* -------------------------------------------------------------------------- */
/* fwnode operations */

static struct fwnode_handle *software_node_get(struct fwnode_handle *fwnode)
{ … }

static void software_node_put(struct fwnode_handle *fwnode)
{ … }

static bool software_node_property_present(const struct fwnode_handle *fwnode,
					   const char *propname)
{ … }

static int software_node_read_int_array(const struct fwnode_handle *fwnode,
					const char *propname,
					unsigned int elem_size, void *val,
					size_t nval)
{ … }

static int software_node_read_string_array(const struct fwnode_handle *fwnode,
					   const char *propname,
					   const char **val, size_t nval)
{ … }

static const char *
software_node_get_name(const struct fwnode_handle *fwnode)
{ … }

static const char *
software_node_get_name_prefix(const struct fwnode_handle *fwnode)
{ … }

static struct fwnode_handle *
software_node_get_parent(const struct fwnode_handle *fwnode)
{ … }

static struct fwnode_handle *
software_node_get_next_child(const struct fwnode_handle *fwnode,
			     struct fwnode_handle *child)
{ … }

static struct fwnode_handle *
software_node_get_named_child_node(const struct fwnode_handle *fwnode,
				   const char *childname)
{ … }

static int
software_node_get_reference_args(const struct fwnode_handle *fwnode,
				 const char *propname, const char *nargs_prop,
				 unsigned int nargs, unsigned int index,
				 struct fwnode_reference_args *args)
{ … }

static struct fwnode_handle *
swnode_graph_find_next_port(const struct fwnode_handle *parent,
			    struct fwnode_handle *port)
{ … }

static struct fwnode_handle *
software_node_graph_get_next_endpoint(const struct fwnode_handle *fwnode,
				      struct fwnode_handle *endpoint)
{ … }

static struct fwnode_handle *
software_node_graph_get_remote_endpoint(const struct fwnode_handle *fwnode)
{ … }

static struct fwnode_handle *
software_node_graph_get_port_parent(struct fwnode_handle *fwnode)
{ … }

static int
software_node_graph_parse_endpoint(const struct fwnode_handle *fwnode,
				   struct fwnode_endpoint *endpoint)
{ … }

static const struct fwnode_operations software_node_ops = …;

/* -------------------------------------------------------------------------- */

/**
 * software_node_find_by_name - Find software node by name
 * @parent: Parent of the software node
 * @name: Name of the software node
 *
 * The function will find a node that is child of @parent and that is named
 * @name. If no node is found, the function returns NULL.
 *
 * NOTE: you will need to drop the reference with fwnode_handle_put() after use.
 */
const struct software_node *
software_node_find_by_name(const struct software_node *parent, const char *name)
{ … }
EXPORT_SYMBOL_GPL(…);

static struct software_node *software_node_alloc(const struct property_entry *properties)
{ … }

static void software_node_free(const struct software_node *node)
{ … }

static void software_node_release(struct kobject *kobj)
{ … }

static const struct kobj_type software_node_type = …;

static struct fwnode_handle *
swnode_register(const struct software_node *node, struct swnode *parent,
		unsigned int allocated)
{ … }

/**
 * software_node_register_node_group - Register a group of software nodes
 * @node_group: NULL terminated array of software node pointers to be registered
 *
 * Register multiple software nodes at once. If any node in the array
 * has its .parent pointer set (which can only be to another software_node),
 * then its parent **must** have been registered before it is; either outside
 * of this function or by ordering the array such that parent comes before
 * child.
 */
int software_node_register_node_group(const struct software_node **node_group)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * software_node_unregister_node_group - Unregister a group of software nodes
 * @node_group: NULL terminated array of software node pointers to be unregistered
 *
 * Unregister multiple software nodes at once. If parent pointers are set up
 * in any of the software nodes then the array **must** be ordered such that
 * parents come before their children.
 *
 * NOTE: If you are uncertain whether the array is ordered such that
 * parents will be unregistered before their children, it is wiser to
 * remove the nodes individually, in the correct order (child before
 * parent).
 */
void software_node_unregister_node_group(
		const struct software_node **node_group)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * software_node_register - Register static software node
 * @node: The software node to be registered
 */
int software_node_register(const struct software_node *node)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * software_node_unregister - Unregister static software node
 * @node: The software node to be unregistered
 */
void software_node_unregister(const struct software_node *node)
{ … }
EXPORT_SYMBOL_GPL(…);

struct fwnode_handle *
fwnode_create_software_node(const struct property_entry *properties,
			    const struct fwnode_handle *parent)
{ … }
EXPORT_SYMBOL_GPL(…);

void fwnode_remove_software_node(struct fwnode_handle *fwnode)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * device_add_software_node - Assign software node to a device
 * @dev: The device the software node is meant for.
 * @node: The software node.
 *
 * This function will make @node the secondary firmware node pointer of @dev. If
 * @dev has no primary node, then @node will become the primary node. The
 * function will register @node automatically if it wasn't already registered.
 */
int device_add_software_node(struct device *dev, const struct software_node *node)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * device_remove_software_node - Remove device's software node
 * @dev: The device with the software node.
 *
 * This function will unregister the software node of @dev.
 */
void device_remove_software_node(struct device *dev)
{ … }
EXPORT_SYMBOL_GPL(…);

/**
 * device_create_managed_software_node - Create a software node for a device
 * @dev: The device the software node is assigned to.
 * @properties: Device properties for the software node.
 * @parent: Parent of the software node.
 *
 * Creates a software node as a managed resource for @dev, which means the
 * lifetime of the newly created software node is tied to the lifetime of @dev.
 * Software nodes created with this function should not be reused or shared
 * because of that. The function takes a deep copy of @properties for the
 * software node.
 *
 * Since the new software node is assigned directly to @dev, and since it should
 * not be shared, it is not returned to the caller. The function returns 0 on
 * success, and errno in case of an error.
 */
int device_create_managed_software_node(struct device *dev,
					const struct property_entry *properties,
					const struct software_node *parent)
{ … }
EXPORT_SYMBOL_GPL(…);

void software_node_notify(struct device *dev)
{ … }

void software_node_notify_remove(struct device *dev)
{ … }

static int __init software_node_init(void)
{ … }
postcore_initcall(software_node_init);

static void __exit software_node_exit(void)
{ … }
__exitcall(…);