LCOV - code coverage report
Current view: top level - include/zephyr - device.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 2 30 6.7 %
Date: 2022-08-18 11:36:24 Functions: 1 4 25.0 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 0 18 0.0 %

           Branch data     Line data    Source code
       1                 :            : /*
       2                 :            :  * Copyright (c) 2015 Intel Corporation.
       3                 :            :  *
       4                 :            :  * SPDX-License-Identifier: Apache-2.0
       5                 :            :  */
       6                 :            : 
       7                 :            : #ifndef ZEPHYR_INCLUDE_DEVICE_H_
       8                 :            : #define ZEPHYR_INCLUDE_DEVICE_H_
       9                 :            : 
      10                 :            : /**
      11                 :            :  * @brief Device Driver APIs
      12                 :            :  * @defgroup io_interfaces Device Driver APIs
      13                 :            :  * @{
      14                 :            :  * @}
      15                 :            :  */
      16                 :            : /**
      17                 :            :  * @brief Miscellaneous Drivers APIs
      18                 :            :  * @defgroup misc_interfaces Miscellaneous Drivers APIs
      19                 :            :  * @ingroup io_interfaces
      20                 :            :  * @{
      21                 :            :  * @}
      22                 :            :  */
      23                 :            : /**
      24                 :            :  * @brief Device Model APIs
      25                 :            :  * @defgroup device_model Device Model APIs
      26                 :            :  * @{
      27                 :            :  */
      28                 :            : 
      29                 :            : #include <init.h>
      30                 :            : #include <linker/sections.h>
      31                 :            : #include <sys/device_mmio.h>
      32                 :            : #include <sys/util.h>
      33                 :            : 
      34                 :            : #ifdef __cplusplus
      35                 :            : extern "C" {
      36                 :            : #endif
      37                 :            : 
      38                 :            : /**
      39                 :            :  * @brief Type used to represent a "handle" for a device.
      40                 :            :  *
      41                 :            :  * Every struct device has an associated handle. You can get a pointer
      42                 :            :  * to a device structure from its handle and vice versa, but the
      43                 :            :  * handle uses less space than a pointer. The device.h API mainly uses
      44                 :            :  * handles to store lists of multiple devices in a compact way.
      45                 :            :  *
      46                 :            :  * The extreme values and zero have special significance. Negative
      47                 :            :  * values identify functionality that does not correspond to a Zephyr
      48                 :            :  * device, such as the system clock or a SYS_INIT() function.
      49                 :            :  *
      50                 :            :  * @see device_handle_get()
      51                 :            :  * @see device_from_handle()
      52                 :            :  */
      53                 :            : typedef int16_t device_handle_t;
      54                 :            : 
      55                 :            : /** @brief Flag value used in lists of device handles to separate
      56                 :            :  * distinct groups.
      57                 :            :  *
      58                 :            :  * This is the minimum value for the device_handle_t type.
      59                 :            :  */
      60                 :            : #define DEVICE_HANDLE_SEP INT16_MIN
      61                 :            : 
      62                 :            : /** @brief Flag value used in lists of device handles to indicate the
      63                 :            :  * end of the list.
      64                 :            :  *
      65                 :            :  * This is the maximum value for the device_handle_t type.
      66                 :            :  */
      67                 :            : #define DEVICE_HANDLE_ENDS INT16_MAX
      68                 :            : 
      69                 :            : /** @brief Flag value used to identify an unknown device. */
      70                 :            : #define DEVICE_HANDLE_NULL 0
      71                 :            : 
      72                 :            : #define Z_DEVICE_MAX_NAME_LEN   48
      73                 :            : 
      74                 :            : /**
      75                 :            :  * @def DEVICE_NAME_GET
      76                 :            :  *
      77                 :            :  * @brief Expands to the name of a global device object.
      78                 :            :  *
      79                 :            :  * @details Return the full name of a device object symbol created by
      80                 :            :  * DEVICE_DEFINE(), using the dev_name provided to DEVICE_DEFINE().
      81                 :            :  * This is the name of the global variable storing the device
      82                 :            :  * structure, not a pointer to the string in the device's @p name
      83                 :            :  * field.
      84                 :            :  *
      85                 :            :  * It is meant to be used for declaring extern symbols pointing to device
      86                 :            :  * objects before using the DEVICE_GET macro to get the device object.
      87                 :            :  *
      88                 :            :  * This macro is normally only useful within device driver source
      89                 :            :  * code. In other situations, you are probably looking for
      90                 :            :  * device_get_binding().
      91                 :            :  *
      92                 :            :  * @param name The same @p dev_name token given to DEVICE_DEFINE()
      93                 :            :  *
      94                 :            :  * @return The full name of the device object defined by DEVICE_DEFINE()
      95                 :            :  */
      96                 :            : #define DEVICE_NAME_GET(name) _CONCAT(__device_, name)
      97                 :            : 
      98                 :            : /**
      99                 :            :  * @def SYS_DEVICE_DEFINE
     100                 :            :  *
     101                 :            :  * @brief Run an initialization function at boot at specified priority.
     102                 :            :  *
     103                 :            :  * @deprecated Use SYS_INIT() instead.
     104                 :            :  *
     105                 :            :  * @param drv_name A string name for the pseudo-device (unused).
     106                 :            :  * @param init_fn Pointer to the function which should run at boot time.
     107                 :            :  * @param level Initialization level to run the function in.
     108                 :            :  * @param prio Function's priority within its initialization level.
     109                 :            :  */
     110                 :            : #define SYS_DEVICE_DEFINE(drv_name, init_fn, level, prio)               \
     111                 :            :         __DEPRECATED_MACRO SYS_INIT(init_fn, level, prio)
     112                 :            : 
     113                 :            : /* Node paths can exceed the maximum size supported by device_get_binding() in user mode,
     114                 :            :  * so synthesize a unique dev_name from the devicetree node.
     115                 :            :  *
     116                 :            :  * The ordinal used in this name can be mapped to the path by
     117                 :            :  * examining zephyr/include/generated/device_extern.h header. If the
     118                 :            :  * format of this conversion changes, gen_defines should be updated to
     119                 :            :  * match it.
     120                 :            :  */
     121                 :            : #define Z_DEVICE_DT_DEV_NAME(node_id) _CONCAT(dts_ord_, DT_DEP_ORD(node_id))
     122                 :            : 
     123                 :            : /* Synthesize a unique name for the device state associated with
     124                 :            :  * dev_name.
     125                 :            :  */
     126                 :            : #define Z_DEVICE_STATE_NAME(dev_name) _CONCAT(__devstate_, dev_name)
     127                 :            : 
     128                 :            : /**
     129                 :            :  * @brief Utility macro to define and initialize the device state.
     130                 :            :  *
     131                 :            :  * @param node_id Devicetree node id of the device.
     132                 :            :  * @param dev_name Device name.
     133                 :            :  */
     134                 :            : #define Z_DEVICE_STATE_DEFINE(node_id, dev_name)                        \
     135                 :            :         static struct device_state Z_DEVICE_STATE_NAME(dev_name)        \
     136                 :            :         __attribute__((__section__(".z_devstate")));
     137                 :            : 
     138                 :            : /**
     139                 :            :  * @def DEVICE_DEFINE
     140                 :            :  *
     141                 :            :  * @brief Create a device object and set it up for boot time initialization.
     142                 :            :  *
     143                 :            :  * @details This macro defines a <tt>struct device</tt> that is
     144                 :            :  * automatically configured by the kernel during system
     145                 :            :  * initialization. This macro should only be used when the device is
     146                 :            :  * not being allocated from a devicetree node. If you are allocating a
     147                 :            :  * device from a devicetree node, use DEVICE_DT_DEFINE() or
     148                 :            :  * DEVICE_DT_INST_DEFINE() instead.
     149                 :            :  *
     150                 :            :  * @param dev_name A unique token which is used in the name of the
     151                 :            :  * global device structure as a C identifier.
     152                 :            :  *
     153                 :            :  * @param drv_name A string name for the device, which will be stored
     154                 :            :  * in the device structure's @p name field. This name can be used to
     155                 :            :  * look up the device with device_get_binding(). This must be less
     156                 :            :  * than Z_DEVICE_MAX_NAME_LEN characters (including terminating NUL)
     157                 :            :  * in order to be looked up from user mode.
     158                 :            :  *
     159                 :            :  * @param init_fn Pointer to the device's initialization function,
     160                 :            :  * which will be run by the kernel during system initialization.
     161                 :            :  *
     162                 :            :  * @param pm_device Pointer to the device's power management
     163                 :            :  * resources, a <tt>struct pm_device</tt>, which will be stored in the
     164                 :            :  * device structure's @p pm field. Use NULL if the device does not use
     165                 :            :  * PM.
     166                 :            :  *
     167                 :            :  * @param data_ptr Pointer to the device's private mutable data, which
     168                 :            :  * will be stored in the device structure's @p data field.
     169                 :            :  *
     170                 :            :  * @param cfg_ptr Pointer to the device's private constant data, which
     171                 :            :  * will be stored in the device structure's @p config field.
     172                 :            :  *
     173                 :            :  * @param level The device's initialization level. See SYS_INIT() for
     174                 :            :  * details.
     175                 :            :  *
     176                 :            :  * @param prio The device's priority within its initialization level.
     177                 :            :  * See SYS_INIT() for details.
     178                 :            :  *
     179                 :            :  * @param api_ptr Pointer to the device's API structure. Can be NULL.
     180                 :            :  */
     181                 :            : #define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_device,           \
     182                 :            :                       data_ptr, cfg_ptr, level, prio, api_ptr)          \
     183                 :            :         Z_DEVICE_STATE_DEFINE(DT_INVALID_NODE, dev_name) \
     184                 :            :         Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, drv_name, init_fn,   \
     185                 :            :                         pm_device,                                      \
     186                 :            :                         data_ptr, cfg_ptr, level, prio, api_ptr,        \
     187                 :            :                         &Z_DEVICE_STATE_NAME(dev_name))
     188                 :            : 
     189                 :            : /**
     190                 :            :  * @def DEVICE_DT_NAME
     191                 :            :  *
     192                 :            :  * @brief Return a string name for a devicetree node.
     193                 :            :  *
     194                 :            :  * @details This macro returns a string literal usable as a device's
     195                 :            :  * @p name field from a devicetree node identifier.
     196                 :            :  *
     197                 :            :  * @param node_id The devicetree node identifier.
     198                 :            :  *
     199                 :            :  * @return The value of the node's "label" property, if it has one.
     200                 :            :  * Otherwise, the node's full name in "node-name@@unit-address" form.
     201                 :            :  */
     202                 :            : #define DEVICE_DT_NAME(node_id) \
     203                 :            :         DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))
     204                 :            : 
     205                 :            : /**
     206                 :            :  * @def DEVICE_DT_DEFINE
     207                 :            :  *
     208                 :            :  * @brief Create a device object from a devicetree node identifier and
     209                 :            :  * set it up for boot time initialization.
     210                 :            :  *
     211                 :            :  * @details This macro defines a <tt>struct device</tt> that is
     212                 :            :  * automatically configured by the kernel during system
     213                 :            :  * initialization. The global device object's name as a C identifier
     214                 :            :  * is derived from the node's dependency ordinal. The device
     215                 :            :  * structure's @p name field is set to
     216                 :            :  * <tt>DEVICE_DT_NAME(node_id)</tt>.
     217                 :            :  *
     218                 :            :  * The device is declared with extern visibility, so a pointer to a
     219                 :            :  * global device object can be obtained with
     220                 :            :  * <tt>DEVICE_DT_GET(node_id)</tt> from any source file that includes
     221                 :            :  * device.h. Before using the pointer, the referenced object should be
     222                 :            :  * checked using device_is_ready().
     223                 :            :  *
     224                 :            :  * @param node_id The devicetree node identifier.
     225                 :            :  *
     226                 :            :  * @param init_fn Pointer to the device's initialization function,
     227                 :            :  * which will be run by the kernel during system initialization.
     228                 :            :  *
     229                 :            :  * @param pm_device Pointer to the device's power management
     230                 :            :  * resources, a <tt>struct pm_device</tt>, which will be stored in the
     231                 :            :  * device structure's @p pm field. Use NULL if the device does not use
     232                 :            :  * PM.
     233                 :            :  *
     234                 :            :  * @param data_ptr Pointer to the device's private mutable data, which
     235                 :            :  * will be stored in the device structure's @p data field.
     236                 :            :  *
     237                 :            :  * @param cfg_ptr Pointer to the device's private constant data, which
     238                 :            :  * will be stored in the device structure's @p config field.
     239                 :            :  *
     240                 :            :  * @param level The device's initialization level. See SYS_INIT() for
     241                 :            :  * details.
     242                 :            :  *
     243                 :            :  * @param prio The device's priority within its initialization level.
     244                 :            :  * See SYS_INIT() for details.
     245                 :            :  *
     246                 :            :  * @param api_ptr Pointer to the device's API structure. Can be NULL.
     247                 :            :  */
     248                 :            : #define DEVICE_DT_DEFINE(node_id, init_fn, pm_device,                   \
     249                 :            :                          data_ptr, cfg_ptr, level, prio,                \
     250                 :            :                          api_ptr, ...)                                  \
     251                 :            :         Z_DEVICE_STATE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id)) \
     252                 :            :         Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id),         \
     253                 :            :                         DEVICE_DT_NAME(node_id), init_fn,               \
     254                 :            :                         pm_device,                                      \
     255                 :            :                         data_ptr, cfg_ptr, level, prio,                 \
     256                 :            :                         api_ptr,                                        \
     257                 :            :                         &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_NAME(node_id)),        \
     258                 :            :                         __VA_ARGS__)
     259                 :            : 
     260                 :            : /**
     261                 :            :  * @def DEVICE_DT_INST_DEFINE
     262                 :            :  *
     263                 :            :  * @brief Like DEVICE_DT_DEFINE(), but uses an instance of a
     264                 :            :  * DT_DRV_COMPAT compatible instead of a node identifier.
     265                 :            :  *
     266                 :            :  * @param inst instance number. The @p node_id argument to
     267                 :            :  * DEVICE_DT_DEFINE is set to <tt>DT_DRV_INST(inst)</tt>.
     268                 :            :  *
     269                 :            :  * @param ... other parameters as expected by DEVICE_DT_DEFINE.
     270                 :            :  */
     271                 :            : #define DEVICE_DT_INST_DEFINE(inst, ...) \
     272                 :            :         DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
     273                 :            : 
     274                 :            : /**
     275                 :            :  * @def DEVICE_DT_NAME_GET
     276                 :            :  *
     277                 :            :  * @brief The name of the global device object for @p node_id
     278                 :            :  *
     279                 :            :  * @details Returns the name of the global device structure as a C
     280                 :            :  * identifier. The device must be allocated using DEVICE_DT_DEFINE()
     281                 :            :  * or DEVICE_DT_INST_DEFINE() for this to work.
     282                 :            :  *
     283                 :            :  * This macro is normally only useful within device driver source
     284                 :            :  * code. In other situations, you are probably looking for
     285                 :            :  * DEVICE_DT_GET().
     286                 :            :  *
     287                 :            :  * @param node_id Devicetree node identifier
     288                 :            :  *
     289                 :            :  * @return The name of the device object as a C identifier
     290                 :            :  */
     291                 :            : #define DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_NAME(node_id))
     292                 :            : 
     293                 :            : /**
     294                 :            :  * @def DEVICE_DT_GET
     295                 :            :  *
     296                 :            :  * @brief Get a <tt>const struct device*</tt> from a devicetree node
     297                 :            :  * identifier
     298                 :            :  *
     299                 :            :  * @details Returns a pointer to a device object created from a
     300                 :            :  * devicetree node, if any device was allocated by a driver.
     301                 :            :  *
     302                 :            :  * If no such device was allocated, this will fail at linker time. If
     303                 :            :  * you get an error that looks like <tt>undefined reference to
     304                 :            :  * __device_dts_ord_<N></tt>, that is what happened. Check to make
     305                 :            :  * sure your device driver is being compiled, usually by enabling the
     306                 :            :  * Kconfig options it requires.
     307                 :            :  *
     308                 :            :  * @param node_id A devicetree node identifier
     309                 :            :  * @return A pointer to the device object created for that node
     310                 :            :  */
     311                 :            : #define DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
     312                 :            : 
     313                 :            : /** @def DEVICE_DT_INST_GET
     314                 :            :  *
     315                 :            :  * @brief Get a <tt>const struct device*</tt> for an instance of a
     316                 :            :  *        DT_DRV_COMPAT compatible
     317                 :            :  *
     318                 :            :  * @details This is equivalent to <tt>DEVICE_DT_GET(DT_DRV_INST(inst))</tt>.
     319                 :            :  *
     320                 :            :  * @param inst DT_DRV_COMPAT instance number
     321                 :            :  * @return A pointer to the device object created for that instance
     322                 :            :  */
     323                 :            : #define DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
     324                 :            : 
     325                 :            : /**
     326                 :            :  * @def DEVICE_DT_GET_ANY
     327                 :            :  *
     328                 :            :  * @brief Get a <tt>const struct device*</tt> from a devicetree compatible
     329                 :            :  *
     330                 :            :  * If an enabled devicetree node has the given compatible and a device
     331                 :            :  * object was created from it, this returns a pointer to that device.
     332                 :            :  *
     333                 :            :  * If there no such devices, this returns NULL.
     334                 :            :  *
     335                 :            :  * If there are multiple, this returns an arbitrary one.
     336                 :            :  *
     337                 :            :  * If this returns non-NULL, the device must be checked for readiness
     338                 :            :  * before use, e.g. with device_is_ready().
     339                 :            :  *
     340                 :            :  * @param compat lowercase-and-underscores devicetree compatible
     341                 :            :  * @return a pointer to a device, or NULL
     342                 :            :  */
     343                 :            : #define DEVICE_DT_GET_ANY(compat)                                           \
     344                 :            :         COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                      \
     345                 :            :                     (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
     346                 :            :                     (NULL))
     347                 :            : 
     348                 :            : /**
     349                 :            :  * @def DEVICE_DT_GET_ONE
     350                 :            :  *
     351                 :            :  * @brief Get a <tt>const struct device*</tt> from a devicetree compatible
     352                 :            :  *
     353                 :            :  * @details If an enabled devicetree node has the given compatible and
     354                 :            :  * a device object was created from it, this returns a pointer to that
     355                 :            :  * device.
     356                 :            :  *
     357                 :            :  * If there no such devices, this will fail at compile time.
     358                 :            :  *
     359                 :            :  * If there are multiple, this returns an arbitrary one.
     360                 :            :  *
     361                 :            :  * If this returns non-NULL, the device must be checked for readiness
     362                 :            :  * before use, e.g. with device_is_ready().
     363                 :            :  *
     364                 :            :  * @param compat lowercase-and-underscores devicetree compatible
     365                 :            :  * @return a pointer to a device
     366                 :            :  */
     367                 :            : #define DEVICE_DT_GET_ONE(compat)                                           \
     368                 :            :         COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                      \
     369                 :            :                     (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
     370                 :            :                     (ZERO_OR_COMPILE_ERROR(0)))
     371                 :            : 
     372                 :            : /**
     373                 :            :  * @def DEVICE_DT_GET_OR_NULL
     374                 :            :  *
     375                 :            :  * @brief Utility macro to obtain an optional reference to a device.
     376                 :            :  *
     377                 :            :  * @details If the node identifier refers to a node with status
     378                 :            :  * "okay", this returns <tt>DEVICE_DT_GET(node_id)</tt>. Otherwise, it
     379                 :            :  * returns NULL.
     380                 :            :  *
     381                 :            :  * @param node_id devicetree node identifier
     382                 :            :  *
     383                 :            :  * @return a <tt>const struct device*</tt> for the node identifier,
     384                 :            :  * which may be NULL.
     385                 :            :  */
     386                 :            : #define DEVICE_DT_GET_OR_NULL(node_id)                                  \
     387                 :            :         COND_CODE_1(DT_NODE_HAS_STATUS(node_id, okay),                  \
     388                 :            :                     (DEVICE_DT_GET(node_id)), (NULL))
     389                 :            : 
     390                 :            : /**
     391                 :            :  * @def DEVICE_GET
     392                 :            :  *
     393                 :            :  * @brief Obtain a pointer to a device object by name
     394                 :            :  *
     395                 :            :  * @details Return the address of a device object created by
     396                 :            :  * DEVICE_DEFINE(), using the dev_name provided to DEVICE_DEFINE().
     397                 :            :  *
     398                 :            :  * @param name The same as dev_name provided to DEVICE_DEFINE()
     399                 :            :  *
     400                 :            :  * @return A pointer to the device object created by DEVICE_DEFINE()
     401                 :            :  */
     402                 :            : #define DEVICE_GET(name) (&DEVICE_NAME_GET(name))
     403                 :            : 
     404                 :            : /** @def DEVICE_DECLARE
     405                 :            :  *
     406                 :            :  * @brief Declare a static device object
     407                 :            :  *
     408                 :            :  * This macro can be used at the top-level to declare a device, such
     409                 :            :  * that DEVICE_GET() may be used before the full declaration in
     410                 :            :  * DEVICE_DEFINE().
     411                 :            :  *
     412                 :            :  * This is often useful when configuring interrupts statically in a
     413                 :            :  * device's init or per-instance config function, as the init function
     414                 :            :  * itself is required by DEVICE_DEFINE() and use of DEVICE_GET()
     415                 :            :  * inside it creates a circular dependency.
     416                 :            :  *
     417                 :            :  * @param name Device name
     418                 :            :  */
     419                 :            : #define DEVICE_DECLARE(name) static const struct device DEVICE_NAME_GET(name)
     420                 :            : 
     421                 :            : /**
     422                 :            :  * @brief Runtime device dynamic structure (in RAM) per driver instance
     423                 :            :  *
     424                 :            :  * Fields in this are expected to be default-initialized to zero. The
     425                 :            :  * kernel driver infrastructure and driver access functions are
     426                 :            :  * responsible for ensuring that any non-zero initialization is done
     427                 :            :  * before they are accessed.
     428                 :            :  */
     429                 :            : struct device_state {
     430                 :            :         /** Non-negative result of initializing the device.
     431                 :            :          *
     432                 :            :          * The absolute value returned when the device initialization
     433                 :            :          * function was invoked, or `UINT8_MAX` if the value exceeds
     434                 :            :          * an 8-bit integer. If initialized is also set, a zero value
     435                 :            :          * indicates initialization succeeded.
     436                 :            :          */
     437                 :            :         unsigned int init_res : 8;
     438                 :            : 
     439                 :            :         /** Indicates the device initialization function has been
     440                 :            :          * invoked.
     441                 :            :          */
     442                 :            :         bool initialized : 1;
     443                 :            : };
     444                 :            : 
     445                 :            : struct pm_device;
     446                 :            : 
     447                 :            : #ifdef CONFIG_HAS_DYNAMIC_DEVICE_HANDLES
     448                 :            : #define Z_DEVICE_HANDLES_CONST
     449                 :            : #else
     450                 :            : #define Z_DEVICE_HANDLES_CONST const
     451                 :            : #endif
     452                 :            : 
     453                 :            : /**
     454                 :            :  * @brief Runtime device structure (in ROM) per driver instance
     455                 :            :  */
     456                 :            : struct device {
     457                 :            :         /** Name of the device instance */
     458                 :            :         const char *name;
     459                 :            :         /** Address of device instance config information */
     460                 :            :         const void *config;
     461                 :            :         /** Address of the API structure exposed by the device instance */
     462                 :            :         const void *api;
     463                 :            :         /** Address of the common device state */
     464                 :            :         struct device_state * const state;
     465                 :            :         /** Address of the device instance private data */
     466                 :            :         void * const data;
     467                 :            :         /** optional pointer to handles associated with the device.
     468                 :            :          *
     469                 :            :          * This encodes a sequence of sets of device handles that have
     470                 :            :          * some relationship to this node. The individual sets are
     471                 :            :          * extracted with dedicated API, such as
     472                 :            :          * device_required_handles_get().
     473                 :            :          */
     474                 :            :         Z_DEVICE_HANDLES_CONST device_handle_t * const handles;
     475                 :            : 
     476                 :            : #ifdef CONFIG_PM_DEVICE
     477                 :            :         /** Reference to the device PM resources. */
     478                 :            :         struct pm_device * const pm;
     479                 :            : #endif
     480                 :            : };
     481                 :            : 
     482                 :            : /**
     483                 :            :  * @brief Get the handle for a given device
     484                 :            :  *
     485                 :            :  * @param dev the device for which a handle is desired.
     486                 :            :  *
     487                 :            :  * @return the handle for the device, or DEVICE_HANDLE_NULL if the
     488                 :            :  * device does not have an associated handle.
     489                 :            :  */
     490                 :            : static inline device_handle_t
     491                 :            : device_handle_get(const struct device *dev)
     492                 :            : {
     493                 :            :         device_handle_t ret = DEVICE_HANDLE_NULL;
     494                 :            :         extern const struct device __device_start[];
     495                 :            : 
     496                 :            :         /* TODO: If/when devices can be constructed that are not part of the
     497                 :            :          * fixed sequence we'll need another solution.
     498                 :            :          */
     499                 :            :         if (dev != NULL) {
     500                 :            :                 ret = 1 + (device_handle_t)(dev - __device_start);
     501                 :            :         }
     502                 :            : 
     503                 :            :         return ret;
     504                 :            : }
     505                 :            : 
     506                 :            : /**
     507                 :            :  * @brief Get the device corresponding to a handle.
     508                 :            :  *
     509                 :            :  * @param dev_handle the device handle
     510                 :            :  *
     511                 :            :  * @return the device that has that handle, or a null pointer if @p
     512                 :            :  * dev_handle does not identify a device.
     513                 :            :  */
     514                 :            : static inline const struct device *
     515                 :          0 : device_from_handle(device_handle_t dev_handle)
     516                 :            : {
     517                 :            :         extern const struct device __device_start[];
     518                 :            :         extern const struct device __device_end[];
     519                 :          0 :         const struct device *dev = NULL;
     520                 :          0 :         size_t numdev = __device_end - __device_start;
     521                 :            : 
     522   [ #  #  #  # ]:          0 :         if ((dev_handle > 0) && ((size_t)dev_handle <= numdev)) {
     523                 :          0 :                 dev = &__device_start[dev_handle - 1];
     524                 :            :         }
     525                 :            : 
     526                 :          0 :         return dev;
     527                 :            : }
     528                 :            : 
     529                 :            : /**
     530                 :            :  * @brief Prototype for functions used when iterating over a set of devices.
     531                 :            :  *
     532                 :            :  * Such a function may be used in API that identifies a set of devices and
     533                 :            :  * provides a visitor API supporting caller-specific interaction with each
     534                 :            :  * device in the set.
     535                 :            :  *
     536                 :            :  * The visit is said to succeed if the visitor returns a non-negative value.
     537                 :            :  *
     538                 :            :  * @param dev a device in the set being iterated
     539                 :            :  *
     540                 :            :  * @param context state used to support the visitor function
     541                 :            :  *
     542                 :            :  * @return A non-negative number to allow walking to continue, and a negative
     543                 :            :  * error code to case the iteration to stop.
     544                 :            :  *
     545                 :            :  * @see device_required_foreach()
     546                 :            :  * @see device_supported_foreach()
     547                 :            :  */
     548                 :            : typedef int (*device_visitor_callback_t)(const struct device *dev, void *context);
     549                 :            : 
     550                 :            : /**
     551                 :            :  * @brief Get the device handles for devicetree dependencies of this device.
     552                 :            :  *
     553                 :            :  * This function returns a pointer to an array of device handles. The
     554                 :            :  * length of the array is stored in the @p count parameter.
     555                 :            :  *
     556                 :            :  * The array contains a handle for each device that @p dev requires
     557                 :            :  * directly, as determined from the devicetree. This does not include
     558                 :            :  * transitive dependencies; you must recursively determine those.
     559                 :            :  *
     560                 :            :  * @param dev the device for which dependencies are desired.
     561                 :            :  *
     562                 :            :  * @param count pointer to where this function should store the length
     563                 :            :  * of the returned array. No value is stored if the call returns a
     564                 :            :  * null pointer. The value may be set to zero if the device has no
     565                 :            :  * devicetree dependencies.
     566                 :            :  *
     567                 :            :  * @return a pointer to a sequence of @p *count device handles, or a null
     568                 :            :  * pointer if @p dev does not have any dependency data.
     569                 :            :  */
     570                 :            : static inline const device_handle_t *
     571                 :          0 : device_required_handles_get(const struct device *dev,
     572                 :            :                             size_t *count)
     573                 :            : {
     574                 :          0 :         const device_handle_t *rv = dev->handles;
     575                 :            : 
     576         [ #  # ]:          0 :         if (rv != NULL) {
     577                 :          0 :                 size_t i = 0;
     578                 :            : 
     579         [ #  # ]:          0 :                 while ((rv[i] != DEVICE_HANDLE_ENDS)
     580         [ #  # ]:          0 :                        && (rv[i] != DEVICE_HANDLE_SEP)) {
     581                 :          0 :                         ++i;
     582                 :            :                 }
     583                 :          0 :                 *count = i;
     584                 :            :         }
     585                 :            : 
     586                 :          0 :         return rv;
     587                 :            : }
     588                 :            : 
     589                 :            : /**
     590                 :            :  * @brief Get the set of handles that this device supports.
     591                 :            :  *
     592                 :            :  * This function returns a pointer to an array of device handles. The
     593                 :            :  * length of the array is stored in the @p count parameter.
     594                 :            :  *
     595                 :            :  * The array contains a handle for each device that @p dev "supports"
     596                 :            :  * -- that is, devices that require @p dev directly -- as determined
     597                 :            :  * from the devicetree. This does not include transitive dependencies;
     598                 :            :  * you must recursively determine those.
     599                 :            :  *
     600                 :            :  * @param dev the device for which supports are desired.
     601                 :            :  *
     602                 :            :  * @param count pointer to where this function should store the length
     603                 :            :  * of the returned array. No value is stored if the call returns a
     604                 :            :  * null pointer. The value may be set to zero if nothing in the
     605                 :            :  * devicetree depends on @p dev.
     606                 :            :  *
     607                 :            :  * @return a pointer to a sequence of @p *count device handles, or a null
     608                 :            :  * pointer if @p dev does not have any dependency data.
     609                 :            :  */
     610                 :            : static inline const device_handle_t *
     611                 :          0 : device_supported_handles_get(const struct device *dev,
     612                 :            :                              size_t *count)
     613                 :            : {
     614                 :          0 :         const device_handle_t *rv = dev->handles;
     615                 :          0 :         size_t region = 0;
     616                 :          0 :         size_t i = 0;
     617                 :            : 
     618         [ #  # ]:          0 :         if (rv != NULL) {
     619                 :            :                 /* Fast forward to supporting devices */
     620         [ #  # ]:          0 :                 while (region != 2) {
     621         [ #  # ]:          0 :                         if (*rv == DEVICE_HANDLE_SEP) {
     622                 :          0 :                                 region++;
     623                 :            :                         }
     624                 :          0 :                         rv++;
     625                 :            :                 }
     626                 :            :                 /* Count supporting devices */
     627         [ #  # ]:          0 :                 while (rv[i] != DEVICE_HANDLE_ENDS) {
     628                 :          0 :                         ++i;
     629                 :            :                 }
     630                 :          0 :                 *count = i;
     631                 :            :         }
     632                 :            : 
     633                 :          0 :         return rv;
     634                 :            : }
     635                 :            : 
     636                 :            : /**
     637                 :            :  * @brief Visit every device that @p dev directly requires.
     638                 :            :  *
     639                 :            :  * Zephyr maintains information about which devices are directly required by
     640                 :            :  * another device; for example an I2C-based sensor driver will require an I2C
     641                 :            :  * controller for communication. Required devices can derive from
     642                 :            :  * statically-defined devicetree relationships or dependencies registered
     643                 :            :  * at runtime.
     644                 :            :  *
     645                 :            :  * This API supports operating on the set of required devices. Example uses
     646                 :            :  * include making sure required devices are ready before the requiring device
     647                 :            :  * is used, and releasing them when the requiring device is no longer needed.
     648                 :            :  *
     649                 :            :  * There is no guarantee on the order in which required devices are visited.
     650                 :            :  *
     651                 :            :  * If the @p visitor function returns a negative value iteration is halted,
     652                 :            :  * and the returned value from the visitor is returned from this function.
     653                 :            :  *
     654                 :            :  * @note This API is not available to unprivileged threads.
     655                 :            :  *
     656                 :            :  * @param dev a device of interest. The devices that this device depends on
     657                 :            :  * will be used as the set of devices to visit. This parameter must not be
     658                 :            :  * null.
     659                 :            :  *
     660                 :            :  * @param visitor_cb the function that should be invoked on each device in the
     661                 :            :  * dependency set. This parameter must not be null.
     662                 :            :  *
     663                 :            :  * @param context state that is passed through to the visitor function. This
     664                 :            :  * parameter may be null if @p visitor tolerates a null @p context.
     665                 :            :  *
     666                 :            :  * @return The number of devices that were visited if all visits succeed, or
     667                 :            :  * the negative value returned from the first visit that did not succeed.
     668                 :            :  */
     669                 :            : int device_required_foreach(const struct device *dev,
     670                 :            :                           device_visitor_callback_t visitor_cb,
     671                 :            :                           void *context);
     672                 :            : 
     673                 :            : /**
     674                 :            :  * @brief Visit every device that @p dev directly supports.
     675                 :            :  *
     676                 :            :  * Zephyr maintains information about which devices are directly supported by
     677                 :            :  * another device; for example an I2C controller will support an I2C-based
     678                 :            :  * sensor driver. Supported devices can derive from statically-defined
     679                 :            :  * devicetree relationships.
     680                 :            :  *
     681                 :            :  * This API supports operating on the set of supported devices. Example uses
     682                 :            :  * include iterating over the devices connected to a regulator when it is
     683                 :            :  * powered on.
     684                 :            :  *
     685                 :            :  * There is no guarantee on the order in which required devices are visited.
     686                 :            :  *
     687                 :            :  * If the @p visitor function returns a negative value iteration is halted,
     688                 :            :  * and the returned value from the visitor is returned from this function.
     689                 :            :  *
     690                 :            :  * @note This API is not available to unprivileged threads.
     691                 :            :  *
     692                 :            :  * @param dev a device of interest. The devices that this device supports
     693                 :            :  * will be used as the set of devices to visit. This parameter must not be
     694                 :            :  * null.
     695                 :            :  *
     696                 :            :  * @param visitor_cb the function that should be invoked on each device in the
     697                 :            :  * support set. This parameter must not be null.
     698                 :            :  *
     699                 :            :  * @param context state that is passed through to the visitor function. This
     700                 :            :  * parameter may be null if @p visitor tolerates a null @p context.
     701                 :            :  *
     702                 :            :  * @return The number of devices that were visited if all visits succeed, or
     703                 :            :  * the negative value returned from the first visit that did not succeed.
     704                 :            :  */
     705                 :            : int device_supported_foreach(const struct device *dev,
     706                 :            :                              device_visitor_callback_t visitor_cb,
     707                 :            :                              void *context);
     708                 :            : 
     709                 :            : /**
     710                 :            :  * @brief Get a <tt>const struct device*</tt> from its @p name field
     711                 :            :  *
     712                 :            :  * @details This function iterates through the devices on the system.
     713                 :            :  * If a device with the given @p name field is found, and that device
     714                 :            :  * initialized successfully at boot time, this function returns a
     715                 :            :  * pointer to the device.
     716                 :            :  *
     717                 :            :  * If no device has the given name, this function returns NULL.
     718                 :            :  *
     719                 :            :  * This function also returns NULL when a device is found, but it
     720                 :            :  * failed to initialize successfully at boot time. (To troubleshoot
     721                 :            :  * this case, set a breakpoint on your device driver's initialization
     722                 :            :  * function.)
     723                 :            :  *
     724                 :            :  * @param name device name to search for. A null pointer, or a pointer
     725                 :            :  * to an empty string, will cause NULL to be returned.
     726                 :            :  *
     727                 :            :  * @return pointer to device structure with the given name; NULL if
     728                 :            :  * the device is not found or if the device with that name's
     729                 :            :  * initialization function failed.
     730                 :            :  */
     731                 :            : __syscall const struct device *device_get_binding(const char *name);
     732                 :            : 
     733                 :            : /** @brief Get access to the static array of static devices.
     734                 :            :  *
     735                 :            :  * @param devices where to store the pointer to the array of
     736                 :            :  * statically allocated devices. The array must not be mutated
     737                 :            :  * through this pointer.
     738                 :            :  *
     739                 :            :  * @return the number of statically allocated devices.
     740                 :            :  */
     741                 :            : size_t z_device_get_all_static(const struct device * *devices);
     742                 :            : 
     743                 :            : /**
     744                 :            :  * @brief Verify that a device is ready for use.
     745                 :            :  *
     746                 :            :  * This is the implementation underlying device_is_ready(), without the overhead
     747                 :            :  * of a syscall wrapper.
     748                 :            :  *
     749                 :            :  * @param dev pointer to the device in question.
     750                 :            :  *
     751                 :            :  * @retval true If the device is ready for use.
     752                 :            :  * @retval false If the device is not ready for use or if a NULL device pointer
     753                 :            :  * is passed as argument.
     754                 :            :  *
     755                 :            :  * @see device_is_ready()
     756                 :            :  */
     757                 :            : bool z_device_is_ready(const struct device *dev);
     758                 :            : 
     759                 :            : /** @brief Verify that a device is ready for use.
     760                 :            :  *
     761                 :            :  * Indicates whether the provided device pointer is for a device known to be
     762                 :            :  * in a state where it can be used with its standard API.
     763                 :            :  *
     764                 :            :  * This can be used with device pointers captured from DEVICE_DT_GET(), which
     765                 :            :  * does not include the readiness checks of device_get_binding(). At minimum
     766                 :            :  * this means that the device has been successfully initialized.
     767                 :            :  *
     768                 :            :  * @param dev pointer to the device in question.
     769                 :            :  *
     770                 :            :  * @retval true If the device is ready for use.
     771                 :            :  * @retval false If the device is not ready for use or if a NULL device pointer
     772                 :            :  * is passed as argument.
     773                 :            :  */
     774                 :            : __syscall bool device_is_ready(const struct device *dev);
     775                 :            : 
     776                 :          1 : static inline bool z_impl_device_is_ready(const struct device *dev)
     777                 :            : {
     778                 :          1 :         return z_device_is_ready(dev);
     779                 :            : }
     780                 :            : 
     781                 :            : /**
     782                 :            :  * @brief Determine whether a device is ready for use
     783                 :            :  *
     784                 :            :  * This is equivalent to device_usable_check(), without the overhead of a
     785                 :            :  * syscall wrapper.
     786                 :            :  *
     787                 :            :  * @deprecated Use z_device_is_ready() instead.
     788                 :            :  *
     789                 :            :  * @param dev Device instance.
     790                 :            :  *
     791                 :            :  * @retval 0 If device is usable.
     792                 :            :  * @retval -ENODEV If device is not usable.
     793                 :            :  */
     794                 :            : __deprecated static inline int z_device_usable_check(const struct device *dev)
     795                 :            : {
     796                 :            :         return z_device_is_ready(dev) ? 0 : -ENODEV;
     797                 :            : }
     798                 :            : 
     799                 :            : /**
     800                 :            :  * @brief Determine whether a device is ready for use
     801                 :            :  *
     802                 :            :  * @deprecated Use device_is_ready() instead.
     803                 :            :  *
     804                 :            :  * @param dev Device instance.
     805                 :            :  *
     806                 :            :  * @retval 0 If device is usable.
     807                 :            :  * @retval -ENODEV If device is not usable.
     808                 :            :  */
     809                 :            : __deprecated static inline int device_usable_check(const struct device *dev)
     810                 :            : {
     811                 :            :         return device_is_ready(dev) ? 0 : -ENODEV;
     812                 :            : }
     813                 :            : 
     814                 :            : /**
     815                 :            :  * @}
     816                 :            :  */
     817                 :            : 
     818                 :            : /* Synthesize the name of the object that holds device ordinal and
     819                 :            :  * dependency data. If the object doesn't come from a devicetree
     820                 :            :  * node, use dev_name.
     821                 :            :  */
     822                 :            : #define Z_DEVICE_HANDLE_NAME(node_id, dev_name)                         \
     823                 :            :         _CONCAT(__devicehdl_,                                           \
     824                 :            :                 COND_CODE_1(DT_NODE_EXISTS(node_id),                    \
     825                 :            :                             (node_id),                                  \
     826                 :            :                             (dev_name)))
     827                 :            : 
     828                 :            : #define Z_DEVICE_EXTRA_HANDLES(...)                             \
     829                 :            :         FOR_EACH_NONEMPTY_TERM(IDENTITY, (,), __VA_ARGS__)
     830                 :            : 
     831                 :            : /*
     832                 :            :  * Utility macro to define and initialize the device state.
     833                 :            :  *
     834                 :            :  * @param node_id Devicetree node id of the device.
     835                 :            :  * @param dev_name Device name.
     836                 :            :  */
     837                 :            : #define Z_DEVICE_STATE_DEFINE(node_id, dev_name)                        \
     838                 :            :         static struct device_state Z_DEVICE_STATE_NAME(dev_name)        \
     839                 :            :         __attribute__((__section__(".z_devstate")));
     840                 :            : 
     841                 :            : /* Construct objects that are referenced from struct device. These
     842                 :            :  * include power management and dependency handles.
     843                 :            :  */
     844                 :            : #define Z_DEVICE_DEFINE_PRE(node_id, dev_name, ...)                     \
     845                 :            :         Z_DEVICE_DEFINE_HANDLES(node_id, dev_name, __VA_ARGS__)
     846                 :            : 
     847                 :            : /* Initial build provides a record that associates the device object
     848                 :            :  * with its devicetree ordinal, and provides the dependency ordinals.
     849                 :            :  * These are provided as weak definitions (to prevent the reference
     850                 :            :  * from being captured when the original object file is compiled), and
     851                 :            :  * in a distinct pass1 section (which will be replaced by
     852                 :            :  * postprocessing).
     853                 :            :  *
     854                 :            :  * Before processing in gen_handles.py, the array format is:
     855                 :            :  * {
     856                 :            :  *     DEVICE_ORDINAL (or DEVICE_HANDLE_NULL if not a devicetree node),
     857                 :            :  *     List of devicetree dependency ordinals (if any),
     858                 :            :  *     DEVICE_HANDLE_SEP,
     859                 :            :  *     List of injected dependency ordinals (if any),
     860                 :            :  *     DEVICE_HANDLE_SEP,
     861                 :            :  *     List of devicetree supporting ordinals (if any),
     862                 :            :  * }
     863                 :            :  *
     864                 :            :  * After processing in gen_handles.py, the format is updated to:
     865                 :            :  * {
     866                 :            :  *     List of existing devicetree dependency handles (if any),
     867                 :            :  *     DEVICE_HANDLE_SEP,
     868                 :            :  *     List of injected dependency ordinals (if any),
     869                 :            :  *     DEVICE_HANDLE_SEP,
     870                 :            :  *     List of existing devicetree support handles (if any),
     871                 :            :  *     DEVICE_HANDLE_NULL
     872                 :            :  * }
     873                 :            :  *
     874                 :            :  * It is also (experimentally) necessary to provide explicit alignment
     875                 :            :  * on each object. Otherwise x86-64 builds will introduce padding
     876                 :            :  * between objects in the same input section in individual object
     877                 :            :  * files, which will be retained in subsequent links both wasting
     878                 :            :  * space and resulting in aggregate size changes relative to pass2
     879                 :            :  * when all objects will be in the same input section.
     880                 :            :  *
     881                 :            :  * The build assert will fail if device_handle_t changes size, which
     882                 :            :  * means the alignment directives in the linker scripts and in
     883                 :            :  * `gen_handles.py` must be updated.
     884                 :            :  */
     885                 :            : BUILD_ASSERT(sizeof(device_handle_t) == 2, "fix the linker scripts");
     886                 :            : #define Z_DEVICE_DEFINE_HANDLES(node_id, dev_name, ...)                 \
     887                 :            :         extern Z_DEVICE_HANDLES_CONST device_handle_t                   \
     888                 :            :                 Z_DEVICE_HANDLE_NAME(node_id, dev_name)[];              \
     889                 :            :         Z_DEVICE_HANDLES_CONST device_handle_t                          \
     890                 :            :         __aligned(sizeof(device_handle_t))                              \
     891                 :            :         __attribute__((__weak__,                                        \
     892                 :            :                        __section__(".__device_handles_pass1")))               \
     893                 :            :         Z_DEVICE_HANDLE_NAME(node_id, dev_name)[] = {                   \
     894                 :            :         COND_CODE_1(DT_NODE_EXISTS(node_id), (                          \
     895                 :            :                         DT_DEP_ORD(node_id),                            \
     896                 :            :                         DT_REQUIRES_DEP_ORDS(node_id)                   \
     897                 :            :                 ), (                                                    \
     898                 :            :                         DEVICE_HANDLE_NULL,                             \
     899                 :            :                 ))                                                      \
     900                 :            :                         DEVICE_HANDLE_SEP,                              \
     901                 :            :                         Z_DEVICE_EXTRA_HANDLES(__VA_ARGS__)             \
     902                 :            :                         DEVICE_HANDLE_SEP,                              \
     903                 :            :         COND_CODE_1(DT_NODE_EXISTS(node_id),                            \
     904                 :            :                         (DT_SUPPORTS_DEP_ORDS(node_id)), ())            \
     905                 :            :                 };
     906                 :            : 
     907                 :            : #define Z_DEVICE_DEFINE_INIT(node_id, dev_name)                         \
     908                 :            :         .handles = Z_DEVICE_HANDLE_NAME(node_id, dev_name),
     909                 :            : 
     910                 :            : /* Like DEVICE_DEFINE but takes a node_id AND a dev_name, and trailing
     911                 :            :  * dependency handles that come from outside devicetree.
     912                 :            :  */
     913                 :            : #define Z_DEVICE_DEFINE(node_id, dev_name, drv_name, init_fn, pm_device,\
     914                 :            :                         data_ptr, cfg_ptr, level, prio, api_ptr, state_ptr, ...)        \
     915                 :            :         Z_DEVICE_DEFINE_PRE(node_id, dev_name, __VA_ARGS__)             \
     916                 :            :         COND_CODE_1(DT_NODE_EXISTS(node_id), (), (static))              \
     917                 :            :                 const Z_DECL_ALIGN(struct device)                       \
     918                 :            :                 DEVICE_NAME_GET(dev_name) __used                        \
     919                 :            :         __attribute__((__section__(".z_device_" #level STRINGIFY(prio)"_"))) = { \
     920                 :            :                 .name = drv_name,                                       \
     921                 :            :                 .config = (cfg_ptr),                                    \
     922                 :            :                 .api = (api_ptr),                                       \
     923                 :            :                 .state = (state_ptr),                                   \
     924                 :            :                 .data = (data_ptr),                                     \
     925                 :            :                 COND_CODE_1(CONFIG_PM_DEVICE, (.pm = pm_device,), ())   \
     926                 :            :                 Z_DEVICE_DEFINE_INIT(node_id, dev_name)                 \
     927                 :            :         };                                                              \
     928                 :            :         BUILD_ASSERT(sizeof(Z_STRINGIFY(drv_name)) <= Z_DEVICE_MAX_NAME_LEN, \
     929                 :            :                      Z_STRINGIFY(DEVICE_NAME_GET(drv_name)) " too long"); \
     930                 :            :         Z_INIT_ENTRY_DEFINE(DEVICE_NAME_GET(dev_name), init_fn,         \
     931                 :            :                 (&DEVICE_NAME_GET(dev_name)), level, prio)
     932                 :            : 
     933                 :            : #ifdef __cplusplus
     934                 :            : }
     935                 :            : #endif
     936                 :            : 
     937                 :            : /* device_extern is generated based on devicetree nodes */
     938                 :            : #include <device_extern.h>
     939                 :            : 
     940                 :            : #include <syscalls/device.h>
     941                 :            : 
     942                 :            : #endif /* ZEPHYR_INCLUDE_DEVICE_H_ */

Generated by: LCOV version 1.14