devicetree: support disabled devices

[pabigot]

The devicetree status property is generally set to one of these properties (ignoring failure states; descriptions from v0.3-rc2):

• okay Indicates the device is operational.
• disabled Indicates that the device is not presently operational, but it might become operational in the future (for example, something is not plugged in, or switched off).
• reserved Indicates that the device is operational, but should not be used. Typically this is used for devices that are controlled by another software component, such as platform firmware.

Currently the logic in edtlib sets the Node.enabled flag whenever the devicetree node status property is not disabled. In the current device management paradigm enabled has the effect of (a) providing devicetree binding data in the headers and .conf file, and (b) causing the corresponding device to be initialized on startup.

Applications that are power-sensitive are likely to have devices that are to be left off at startup, but become enabled at certain points based on application logic. A natural way to express this is to leave status = disabled in the device tree, then locating the driver and initializing it on demand. A status of reserved could be used for this situation as well.

Applications with a pluggable bus such as USB may have devices that are optional and detected at runtime when they are connected. This also corresponds to a disabled devicetree node status, but reserved is not appropriate.

Neither of these will work edtlib's current handling of enabled: there is no ability to distinguish okay from reserved, and binding data is not generated for devices that are disabled.

We need to figure out how to handle the case of delayed init and pluggable devices in terms of devicetree status field values.

One off-the-cuff approach is to always generate binding data for nodes with status okay, reserved, and disabled, but to also generate the corresponding status value. Then store that in struct device and provide a mechanism for device discovery and enable/disable, possibly based on device power management.

[ulfalizer]

The status value could just be returned directly as a string or something on the edtlib side. The code already checks that it has one of the values from the spec.

Maybe having no status could return "okay" for now, just for backwards compatibility.

[pabigot]

In dev-review because this impacts power management solution design and struct device state; we need to make progress.

[mbolivar-nordic]

Revisiting this again, I believe the basic functionality is there:

/**
 * @brief Does a node identifier refer to a node?
 *
 * Tests whether a node identifier refers to a node which exists, i.e.
 * is defined in the devicetree.
 *
 * It doesn't matter whether or not the node has a matching binding,
 * or what the node's status value is. This is purely a check of
 * whether the node exists at all.
 *
 * @param node_id a node identifier
 * @return 1 if the node identifier refers to a node,
 *         0 otherwise.
 */
#define DT_NODE_EXISTS(node_id) IS_ENABLED(DT_CAT(node_id, _EXISTS))

/**
 * @brief Does a node identifier refer to a node with a status?
 *
 * Example uses:
 *
 *     DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), okay)
 *     DT_NODE_HAS_STATUS(DT_PATH(soc, i2c_12340000), disabled)
 *
 * Tests whether a node identifier refers to a node which:
 *
 * - exists in the devicetree, and
 * - has a status property matching the second argument
 *   (except that either a missing status or an "ok" status
 *   in the devicetree is treated as if it were "okay" instead)
 *
 * @param node_id a node identifier
 * @param status a status as one of the tokens okay or disabled, not a string
 * @return 1 if the node has the given status, 0 otherwise.
 */
#define DT_NODE_HAS_STATUS(node_id, status) \
	DT_NODE_HAS_STATUS_INTERNAL(node_id, status)

Please advise if any additional helpers would be useful. If what is available is enough, please close. Thanks!

[pabigot]

I think what we have is enough until I figure out how this can be used. Thanks.