1  /* SPDX-License-Identifier: GPL-2.0-only */
2  /*
3   * fwnode.h - Firmware device node object handle type definition.
4   *
5   * Copyright (C) 2015, Intel Corporation
6   * Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
7   */
8  
9  #ifndef _LINUX_FWNODE_H_
10  #define _LINUX_FWNODE_H_
11  
12  #include <linux/bits.h>
13  #include <linux/err.h>
14  #include <linux/list.h>
15  #include <linux/types.h>
16  
17  enum dev_dma_attr {
18  	DEV_DMA_NOT_SUPPORTED,
19  	DEV_DMA_NON_COHERENT,
20  	DEV_DMA_COHERENT,
21  };
22  
23  struct fwnode_operations;
24  struct device;
25  
26  /*
27   * fwnode flags
28   *
29   * LINKS_ADDED:	The fwnode has already be parsed to add fwnode links.
30   * NOT_DEVICE:	The fwnode will never be populated as a struct device.
31   * INITIALIZED: The hardware corresponding to fwnode has been initialized.
32   * NEEDS_CHILD_BOUND_ON_ADD: For this fwnode/device to probe successfully, its
33   *			     driver needs its child devices to be bound with
34   *			     their respective drivers as soon as they are
35   *			     added.
36   * BEST_EFFORT: The fwnode/device needs to probe early and might be missing some
37   *		suppliers. Only enforce ordering with suppliers that have
38   *		drivers.
39   */
40  #define FWNODE_FLAG_LINKS_ADDED			BIT(0)
41  #define FWNODE_FLAG_NOT_DEVICE			BIT(1)
42  #define FWNODE_FLAG_INITIALIZED			BIT(2)
43  #define FWNODE_FLAG_NEEDS_CHILD_BOUND_ON_ADD	BIT(3)
44  #define FWNODE_FLAG_BEST_EFFORT			BIT(4)
45  #define FWNODE_FLAG_VISITED			BIT(5)
46  
47  struct fwnode_handle {
48  	struct fwnode_handle *secondary;
49  	const struct fwnode_operations *ops;
50  
51  	/* The below is used solely by device links, don't use otherwise */
52  	struct device *dev;
53  	struct list_head suppliers;
54  	struct list_head consumers;
55  	u8 flags;
56  };
57  
58  /*
59   * fwnode link flags
60   *
61   * CYCLE:	The fwnode link is part of a cycle. Don't defer probe.
62   * IGNORE:	Completely ignore this link, even during cycle detection.
63   */
64  #define FWLINK_FLAG_CYCLE			BIT(0)
65  #define FWLINK_FLAG_IGNORE			BIT(1)
66  
67  struct fwnode_link {
68  	struct fwnode_handle *supplier;
69  	struct list_head s_hook;
70  	struct fwnode_handle *consumer;
71  	struct list_head c_hook;
72  	u8 flags;
73  };
74  
75  /**
76   * struct fwnode_endpoint - Fwnode graph endpoint
77   * @port: Port number
78   * @id: Endpoint id
79   * @local_fwnode: reference to the related fwnode
80   */
81  struct fwnode_endpoint {
82  	unsigned int port;
83  	unsigned int id;
84  	const struct fwnode_handle *local_fwnode;
85  };
86  
87  /*
88   * ports and endpoints defined as software_nodes should all follow a common
89   * naming scheme; use these macros to ensure commonality.
90   */
91  #define SWNODE_GRAPH_PORT_NAME_FMT		"port@%u"
92  #define SWNODE_GRAPH_ENDPOINT_NAME_FMT		"endpoint@%u"
93  
94  #define NR_FWNODE_REFERENCE_ARGS	8
95  
96  /**
97   * struct fwnode_reference_args - Fwnode reference with additional arguments
98   * @fwnode:- A reference to the base fwnode
99   * @nargs: Number of elements in @args array
100   * @args: Integer arguments on the fwnode
101   */
102  struct fwnode_reference_args {
103  	struct fwnode_handle *fwnode;
104  	unsigned int nargs;
105  	u64 args[NR_FWNODE_REFERENCE_ARGS];
106  };
107  
108  /**
109   * struct fwnode_operations - Operations for fwnode interface
110   * @get: Get a reference to an fwnode.
111   * @put: Put a reference to an fwnode.
112   * @device_is_available: Return true if the device is available.
113   * @device_get_match_data: Return the device driver match data.
114   * @property_present: Return true if a property is present.
115   * @property_read_int_array: Read an array of integer properties. Return zero on
116   *			     success, a negative error code otherwise.
117   * @property_read_string_array: Read an array of string properties. Return zero
118   *				on success, a negative error code otherwise.
119   * @get_name: Return the name of an fwnode.
120   * @get_name_prefix: Get a prefix for a node (for printing purposes).
121   * @get_parent: Return the parent of an fwnode.
122   * @get_next_child_node: Return the next child node in an iteration.
123   * @get_named_child_node: Return a child node with a given name.
124   * @get_reference_args: Return a reference pointed to by a property, with args
125   * @graph_get_next_endpoint: Return an endpoint node in an iteration.
126   * @graph_get_remote_endpoint: Return the remote endpoint node of a local
127   *			       endpoint node.
128   * @graph_get_port_parent: Return the parent node of a port node.
129   * @graph_parse_endpoint: Parse endpoint for port and endpoint id.
130   * @add_links:	Create fwnode links to all the suppliers of the fwnode. Return
131   *		zero on success, a negative error code otherwise.
132   */
133  struct fwnode_operations {
134  	struct fwnode_handle *(*get)(struct fwnode_handle *fwnode);
135  	void (*put)(struct fwnode_handle *fwnode);
136  	bool (*device_is_available)(const struct fwnode_handle *fwnode);
137  	const void *(*device_get_match_data)(const struct fwnode_handle *fwnode,
138  					     const struct device *dev);
139  	bool (*device_dma_supported)(const struct fwnode_handle *fwnode);
140  	enum dev_dma_attr
141  	(*device_get_dma_attr)(const struct fwnode_handle *fwnode);
142  	bool (*property_present)(const struct fwnode_handle *fwnode,
143  				 const char *propname);
144  	int (*property_read_int_array)(const struct fwnode_handle *fwnode,
145  				       const char *propname,
146  				       unsigned int elem_size, void *val,
147  				       size_t nval);
148  	int
149  	(*property_read_string_array)(const struct fwnode_handle *fwnode_handle,
150  				      const char *propname, const char **val,
151  				      size_t nval);
152  	const char *(*get_name)(const struct fwnode_handle *fwnode);
153  	const char *(*get_name_prefix)(const struct fwnode_handle *fwnode);
154  	struct fwnode_handle *(*get_parent)(const struct fwnode_handle *fwnode);
155  	struct fwnode_handle *
156  	(*get_next_child_node)(const struct fwnode_handle *fwnode,
157  			       struct fwnode_handle *child);
158  	struct fwnode_handle *
159  	(*get_named_child_node)(const struct fwnode_handle *fwnode,
160  				const char *name);
161  	int (*get_reference_args)(const struct fwnode_handle *fwnode,
162  				  const char *prop, const char *nargs_prop,
163  				  unsigned int nargs, unsigned int index,
164  				  struct fwnode_reference_args *args);
165  	struct fwnode_handle *
166  	(*graph_get_next_endpoint)(const struct fwnode_handle *fwnode,
167  				   struct fwnode_handle *prev);
168  	struct fwnode_handle *
169  	(*graph_get_remote_endpoint)(const struct fwnode_handle *fwnode);
170  	struct fwnode_handle *
171  	(*graph_get_port_parent)(struct fwnode_handle *fwnode);
172  	int (*graph_parse_endpoint)(const struct fwnode_handle *fwnode,
173  				    struct fwnode_endpoint *endpoint);
174  	void __iomem *(*iomap)(struct fwnode_handle *fwnode, int index);
175  	int (*irq_get)(const struct fwnode_handle *fwnode, unsigned int index);
176  	int (*add_links)(struct fwnode_handle *fwnode);
177  };
178  
179  #define fwnode_has_op(fwnode, op)					\
180  	(!IS_ERR_OR_NULL(fwnode) && (fwnode)->ops && (fwnode)->ops->op)
181  
182  #define fwnode_call_int_op(fwnode, op, ...)				\
183  	(fwnode_has_op(fwnode, op) ?					\
184  	 (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : (IS_ERR_OR_NULL(fwnode) ? -EINVAL : -ENXIO))
185  
186  #define fwnode_call_bool_op(fwnode, op, ...)		\
187  	(fwnode_has_op(fwnode, op) ?			\
188  	 (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : false)
189  
190  #define fwnode_call_ptr_op(fwnode, op, ...)		\
191  	(fwnode_has_op(fwnode, op) ?			\
192  	 (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : NULL)
193  #define fwnode_call_void_op(fwnode, op, ...)				\
194  	do {								\
195  		if (fwnode_has_op(fwnode, op))				\
196  			(fwnode)->ops->op(fwnode, ## __VA_ARGS__);	\
197  	} while (false)
198  
fwnode_init(struct fwnode_handle * fwnode,const struct fwnode_operations * ops)199  static inline void fwnode_init(struct fwnode_handle *fwnode,
200  			       const struct fwnode_operations *ops)
201  {
202  	fwnode->ops = ops;
203  	INIT_LIST_HEAD(&fwnode->consumers);
204  	INIT_LIST_HEAD(&fwnode->suppliers);
205  }
206  
fwnode_dev_initialized(struct fwnode_handle * fwnode,bool initialized)207  static inline void fwnode_dev_initialized(struct fwnode_handle *fwnode,
208  					  bool initialized)
209  {
210  	if (IS_ERR_OR_NULL(fwnode))
211  		return;
212  
213  	if (initialized)
214  		fwnode->flags |= FWNODE_FLAG_INITIALIZED;
215  	else
216  		fwnode->flags &= ~FWNODE_FLAG_INITIALIZED;
217  }
218  
219  int fwnode_link_add(struct fwnode_handle *con, struct fwnode_handle *sup,
220  		    u8 flags);
221  void fwnode_links_purge(struct fwnode_handle *fwnode);
222  void fw_devlink_purge_absent_suppliers(struct fwnode_handle *fwnode);
223  bool fw_devlink_is_strict(void);
224  
225  #endif
226