Line data    Source code

       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/types.h>
      13             : #include <linux/list.h>
      14             : #include <linux/err.h>
      15             : 
      16             : struct fwnode_operations;
      17             : struct device;
      18             : 
      19             : /*
      20             :  * fwnode link flags
      21             :  *
      22             :  * LINKS_ADDED: The fwnode has already be parsed to add fwnode links.
      23             :  * NOT_DEVICE:  The fwnode will never be populated as a struct device.
      24             :  * INITIALIZED: The hardware corresponding to fwnode has been initialized.
      25             :  */
      26             : #define FWNODE_FLAG_LINKS_ADDED         BIT(0)
      27             : #define FWNODE_FLAG_NOT_DEVICE          BIT(1)
      28             : #define FWNODE_FLAG_INITIALIZED         BIT(2)
      29             : 
      30             : struct fwnode_handle {
      31             :         struct fwnode_handle *secondary;
      32             :         const struct fwnode_operations *ops;
      33             :         struct device *dev;
      34             :         struct list_head suppliers;
      35             :         struct list_head consumers;
      36             :         u8 flags;
      37             : };
      38             : 
      39             : struct fwnode_link {
      40             :         struct fwnode_handle *supplier;
      41             :         struct list_head s_hook;
      42             :         struct fwnode_handle *consumer;
      43             :         struct list_head c_hook;
      44             : };
      45             : 
      46             : /**
      47             :  * struct fwnode_endpoint - Fwnode graph endpoint
      48             :  * @port: Port number
      49             :  * @id: Endpoint id
      50             :  * @local_fwnode: reference to the related fwnode
      51             :  */
      52             : struct fwnode_endpoint {
      53             :         unsigned int port;
      54             :         unsigned int id;
      55             :         const struct fwnode_handle *local_fwnode;
      56             : };
      57             : 
      58             : /*
      59             :  * ports and endpoints defined as software_nodes should all follow a common
      60             :  * naming scheme; use these macros to ensure commonality.
      61             :  */
      62             : #define SWNODE_GRAPH_PORT_NAME_FMT              "port@%u"
      63             : #define SWNODE_GRAPH_ENDPOINT_NAME_FMT          "endpoint@%u"
      64             : 
      65             : #define NR_FWNODE_REFERENCE_ARGS        8
      66             : 
      67             : /**
      68             :  * struct fwnode_reference_args - Fwnode reference with additional arguments
      69             :  * @fwnode:- A reference to the base fwnode
      70             :  * @nargs: Number of elements in @args array
      71             :  * @args: Integer arguments on the fwnode
      72             :  */
      73             : struct fwnode_reference_args {
      74             :         struct fwnode_handle *fwnode;
      75             :         unsigned int nargs;
      76             :         u64 args[NR_FWNODE_REFERENCE_ARGS];
      77             : };
      78             : 
      79             : /**
      80             :  * struct fwnode_operations - Operations for fwnode interface
      81             :  * @get: Get a reference to an fwnode.
      82             :  * @put: Put a reference to an fwnode.
      83             :  * @device_is_available: Return true if the device is available.
      84             :  * @device_get_match_data: Return the device driver match data.
      85             :  * @property_present: Return true if a property is present.
      86             :  * @property_read_int_array: Read an array of integer properties. Return zero on
      87             :  *                           success, a negative error code otherwise.
      88             :  * @property_read_string_array: Read an array of string properties. Return zero
      89             :  *                              on success, a negative error code otherwise.
      90             :  * @get_name: Return the name of an fwnode.
      91             :  * @get_name_prefix: Get a prefix for a node (for printing purposes).
      92             :  * @get_parent: Return the parent of an fwnode.
      93             :  * @get_next_child_node: Return the next child node in an iteration.
      94             :  * @get_named_child_node: Return a child node with a given name.
      95             :  * @get_reference_args: Return a reference pointed to by a property, with args
      96             :  * @graph_get_next_endpoint: Return an endpoint node in an iteration.
      97             :  * @graph_get_remote_endpoint: Return the remote endpoint node of a local
      98             :  *                             endpoint node.
      99             :  * @graph_get_port_parent: Return the parent node of a port node.
     100             :  * @graph_parse_endpoint: Parse endpoint for port and endpoint id.
     101             :  * @add_links:  Create fwnode links to all the suppliers of the fwnode. Return
     102             :  *              zero on success, a negative error code otherwise.
     103             :  */
     104             : struct fwnode_operations {
     105             :         struct fwnode_handle *(*get)(struct fwnode_handle *fwnode);
     106             :         void (*put)(struct fwnode_handle *fwnode);
     107             :         bool (*device_is_available)(const struct fwnode_handle *fwnode);
     108             :         const void *(*device_get_match_data)(const struct fwnode_handle *fwnode,
     109             :                                              const struct device *dev);
     110             :         bool (*property_present)(const struct fwnode_handle *fwnode,
     111             :                                  const char *propname);
     112             :         int (*property_read_int_array)(const struct fwnode_handle *fwnode,
     113             :                                        const char *propname,
     114             :                                        unsigned int elem_size, void *val,
     115             :                                        size_t nval);
     116             :         int
     117             :         (*property_read_string_array)(const struct fwnode_handle *fwnode_handle,
     118             :                                       const char *propname, const char **val,
     119             :                                       size_t nval);
     120             :         const char *(*get_name)(const struct fwnode_handle *fwnode);
     121             :         const char *(*get_name_prefix)(const struct fwnode_handle *fwnode);
     122             :         struct fwnode_handle *(*get_parent)(const struct fwnode_handle *fwnode);
     123             :         struct fwnode_handle *
     124             :         (*get_next_child_node)(const struct fwnode_handle *fwnode,
     125             :                                struct fwnode_handle *child);
     126             :         struct fwnode_handle *
     127             :         (*get_named_child_node)(const struct fwnode_handle *fwnode,
     128             :                                 const char *name);
     129             :         int (*get_reference_args)(const struct fwnode_handle *fwnode,
     130             :                                   const char *prop, const char *nargs_prop,
     131             :                                   unsigned int nargs, unsigned int index,
     132             :                                   struct fwnode_reference_args *args);
     133             :         struct fwnode_handle *
     134             :         (*graph_get_next_endpoint)(const struct fwnode_handle *fwnode,
     135             :                                    struct fwnode_handle *prev);
     136             :         struct fwnode_handle *
     137             :         (*graph_get_remote_endpoint)(const struct fwnode_handle *fwnode);
     138             :         struct fwnode_handle *
     139             :         (*graph_get_port_parent)(struct fwnode_handle *fwnode);
     140             :         int (*graph_parse_endpoint)(const struct fwnode_handle *fwnode,
     141             :                                     struct fwnode_endpoint *endpoint);
     142             :         int (*add_links)(struct fwnode_handle *fwnode);
     143             : };
     144             : 
     145             : #define fwnode_has_op(fwnode, op)                               \
     146             :         ((fwnode) && (fwnode)->ops && (fwnode)->ops->op)
     147             : #define fwnode_call_int_op(fwnode, op, ...)                             \
     148             :         (fwnode ? (fwnode_has_op(fwnode, op) ?                          \
     149             :                    (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : -ENXIO) : \
     150             :          -EINVAL)
     151             : 
     152             : #define fwnode_call_bool_op(fwnode, op, ...)            \
     153             :         (fwnode_has_op(fwnode, op) ?                    \
     154             :          (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : false)
     155             : 
     156             : #define fwnode_call_ptr_op(fwnode, op, ...)             \
     157             :         (fwnode_has_op(fwnode, op) ?                    \
     158             :          (fwnode)->ops->op(fwnode, ## __VA_ARGS__) : NULL)
     159             : #define fwnode_call_void_op(fwnode, op, ...)                            \
     160             :         do {                                                            \
     161             :                 if (fwnode_has_op(fwnode, op))                          \
     162             :                         (fwnode)->ops->op(fwnode, ## __VA_ARGS__);        \
     163             :         } while (false)
     164             : #define get_dev_from_fwnode(fwnode)     get_device((fwnode)->dev)
     165             : 
     166           2 : static inline void fwnode_init(struct fwnode_handle *fwnode,
     167             :                                const struct fwnode_operations *ops)
     168             : {
     169           2 :         fwnode->ops = ops;
     170           2 :         INIT_LIST_HEAD(&fwnode->consumers);
     171           2 :         INIT_LIST_HEAD(&fwnode->suppliers);
     172             : }
     173             : 
     174           2 : static inline void fwnode_dev_initialized(struct fwnode_handle *fwnode,
     175             :                                           bool initialized)
     176             : {
     177           4 :         if (IS_ERR_OR_NULL(fwnode))
     178             :                 return;
     179             : 
     180           2 :         if (initialized)
     181           2 :                 fwnode->flags |= FWNODE_FLAG_INITIALIZED;
     182             :         else
     183           0 :                 fwnode->flags &= ~FWNODE_FLAG_INITIALIZED;
     184             : }
     185             : 
     186             : extern u32 fw_devlink_get_flags(void);
     187             : extern bool fw_devlink_is_strict(void);
     188             : int fwnode_link_add(struct fwnode_handle *con, struct fwnode_handle *sup);
     189             : void fwnode_links_purge(struct fwnode_handle *fwnode);
     190             : 
     191             : #endif