michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update devicetree/pwms.h

Browse source 
Align with other files.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2020-05-25 18:25:03 -07:00 • committed by Carles Cufí
commit 369dcadc0b
1 changed files with 151 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

267
include/devicetree/pwms.h
View file

@ -23,10 +23,10 @@ extern "C" {
*/
/**
* @brief Get pwm controller "name" (label property) at an index
* @brief Get a label property from a pwms property at an index
*
* It's an error if the pwm controller referenced by the phandle
* in property "pwms" at index "idx" has no label property.
* It's an error if the PWM controller node referenced by the phandle
* in node_id's pwms property at index "idx" has no label property.
*
* Example devicetree fragment:
*
@ -45,21 +45,23 @@ extern "C" {
*
* Example usage:
*
* DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 0) // "PWM_1"
* DT_PWMS_LABEL_BY_IDX(DT_NODELABEL(n), 1) // "PWM_2"
*
* @param node_id node identifier
* @param idx logical index into the property
* @return the label property for the referenced node at index idx
* @param node_id node identifier for a node with a pwms property
* @param idx logical index into pwms property
* @return the label property of the node referenced at index "idx"
* @see DT_PROP_BY_PHANDLE_IDX()
*/
#define DT_PWMS_LABEL_BY_IDX(node_id, idx) \
DT_PROP_BY_PHANDLE_IDX(node_id, pwms, idx, label)
/**
* @brief Get pwm controller "name" (label property) by name
* @brief Get a label property from a pwms property by name
*
* It's an error if the pwm controller referenced by the phandle
* in property "pwms" by name "name" has no label property.
* It's an error if the PWM controller node referenced by the
* phandle in node_id's pwms property at the element named "name"
* has no label property.
*
* Example devicetree fragment:
*
@ -79,11 +81,13 @@ extern "C" {
*
* Example usage:
*
* DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), beta) // "PWM_2"
* DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), alpha) // "PWM_1"
* DT_PWMS_LABEL_BY_NAME(DT_NODELABEL(n), beta) // "PWM_2"
*
* @param node_id node identifier
* @param name lowercase-and-underscores "pwm" name
* @return the label property for the referenced node by name
* @param node_id node identifier for a node with a pwms property
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the label property of the node referenced at the named element
* @see DT_PHANDLE_BY_NAME()
*/
#define DT_PWMS_LABEL_BY_NAME(node_id, name) \
@ -91,28 +95,35 @@ extern "C" {
/**
* @brief Equivalent to DT_PWMS_LABEL_BY_IDX(node_id, 0)
* @param node_id node identifier
* @return the label property for the named specifier at index 0
* @param node_id node identifier for a node with a pwms property
* @return the label property of the node referenced at index 0
* @see DT_PWMS_LABEL_BY_IDX()
*/
#define DT_PWMS_LABEL(node_id) DT_PWMS_LABEL_BY_IDX(node_id, 0)
/**
* @brief Get PWM controller "cell" value at an index
* @brief Get PWM specifier's cell value at an index
*
* Example devicetree fragment:
*
* pwm1: pwm-controller@... {
* compatible = "vnd,pwm";
* label = "PWM_1";
* #pwm-cells = <2>;
* };
*
* pwm2: pwm-controller@... {
* compatible = "vnd,pwm";
* label = "PWM_2";
* #pwm-cells = <2>;
* };
*
* n: node {
* pwms = <&pwm1 1 PWM_POLARITY_NORMAL>,
* <&pwm2 3 PWM_POLARITY_INVERTED>;
* };
*
* Bindings fragment for the gpio0 node:
* Bindings fragment for the "vnd,pwm" compatible:
*
* pwm-cells:
* - channel
@ -121,34 +132,43 @@ extern "C" {
* Example usage:
*
* DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), channel, 0) // 1
* DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), channel, 1) // 3
* DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), flags, 0) // PWM_POLARITY_NORMAL
* DT_PWMS_CELL_BY_IDX(DT_NODELABEL(n), flags, 1) // PWM_POLARITY_INVERTED
*
* @param node_id node identifier
* @param cell binding's cell name within the specifier at index "idx"
* @param idx logical index into the property
* @return the value of the cell inside the specifier at index "idx"
* @see DT_PHA_PHANDLE_IDX()
* @param node_id node identifier for a node with a pwms property
* @param cell lowercase-and-underscores cell name
* @param idx logical index into pwms property
* @return the cell value at index "idx"
* @see DT_PHA_BY_IDX()
*/
#define DT_PWMS_CELL_BY_IDX(node_id, cell, idx) \
DT_PHA_BY_IDX(node_id, pwms, idx, cell)
/**
* @brief Get pwm controller "cell" value by name
* @brief Get a PWM specifier's cell value by name
*
* Example devicetree fragment:
*
* pwm1: pwm-controller@... {
* compatible = "vnd,pwm";
* label = "PWM_1";
* #pwm-cells = <2>;
* };
*
* pwm2: pwm-controller@... {
* compatible = "vnd,pwm";
* label = "PWM_2";
* #pwm-cells = <2>;
* };
*
* n: node {
* pwms = <&pwm1 1 PWM_POLARITY_NORMAL>,
* <&pwm2 3 PWM_POLARITY_INVERTED>;
* pwm-names = "alpha", "beta";
* };
*
* Bindings fragment for the pwm1 node:
* Bindings fragment for the "vnd,pwm" compatible:
*
* pwm-cells:
* - channel
@ -157,12 +177,15 @@ extern "C" {
* Example usage:
*
* DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, channel) // 1
* DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, flags) // PWM_POLARITY_INVERTED
* DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, channel) // 3
* DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), alpha, flags) // PWM_POLARITY_NORMAL
* DT_PWMS_CELL_BY_NAME(DT_NODELABEL(n), beta, flags) // PWM_POLARITY_INVERTED
*
* @param node_id node identifier
* @param name lowercase-and-underscores specifier name
* @param cell binding's cell name within the specifier referenced as "name"
* @return the value of the cell inside the named specifier
* @param node_id node identifier for a node with a pwms property
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @param cell lowercase-and-underscores cell name
* @return the cell value in the specifier at the named element
* @see DT_PHA_BY_NAME()
*/
#define DT_PWMS_CELL_BY_NAME(node_id, name, cell) \
@ -170,38 +193,41 @@ extern "C" {
/**
* @brief Equivalent to DT_PWMS_CELL_BY_IDX(node_id, cell, 0)
* @param node_id node identifier
* @param cell binding's cell name within the specifier at index 0
* @return the value of the cell inside the specifier at index 0
* @param node_id node identifier for a node with a pwms property
* @param cell lowercase-and-underscores cell name
* @return the cell value at index 0
* @see DT_PWMS_CELL_BY_IDX()
*/
#define DT_PWMS_CELL(node_id, cell) DT_PWMS_CELL_BY_IDX(node_id, cell, 0)
/**
* @brief Get pwm controller 'channel' at an index
* @brief Get a PWM specifier's channel cell value at an index
*
* This macro only works for PWM controllers that specify a 'channel'
* field in the phandle-array specifier. Refer to the specific PWM
* controller binding if needed.
* This macro only works for PWM specifiers with cells named "channel".
* Refer to the node's binding to check if necessary.
*
* @param node_id node identifier
* @param idx logical index into the property
* @return the channel value for the named specifier at index idx
* This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, channel, idx).
*
* @param node_id node identifier for a node with a pwms property
* @param idx logical index into pwms property
* @return the channel cell value at index "idx"
* @see DT_PWMS_CELL_BY_IDX()
*/
#define DT_PWMS_CHANNEL_BY_IDX(node_id, idx) \
DT_PWMS_CELL_BY_IDX(node_id, channel, idx)
/**
* @brief Get PWM controller 'channel' by name
* @brief Get a PWM specifier's channel cell value by name
*
* This macro only works for PWM controllers that specify a 'channel'
* field in the phandle-array specifier. Refer to the specific PWM
* controller binding if needed.
* This macro only works for PWM specifiers with cells named "channel".
* Refer to the node's binding to check if necessary.
*
* @param node_id node identifier
* @param name lowercase-and-underscores "pwm" name
* @return the channel value for the named specifier by name
* This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, channel).
*
* @param node_id node identifier for a node with a pwms property
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the channel cell value in the specifier at the named element
* @see DT_PWMS_CELL_BY_NAME()
*/
#define DT_PWMS_CHANNEL_BY_NAME(node_id, name) \
@ -209,37 +235,40 @@ extern "C" {
/**
* @brief Equivalent to DT_PWMS_CHANNEL_BY_IDX(node_id, 0)
* @param node_id node identifier
* @return the channel value for the named specifier at index 0
* @param node_id node identifier for a node with a pwms property
* @return the channel cell value at index 0
* @see DT_PWMS_CHANNEL_BY_IDX()
*/
#define DT_PWMS_CHANNEL(node_id) DT_PWMS_CHANNEL_BY_IDX(node_id, 0)
/**
* @brief Get pwm controller 'flags' at an index
* @brief Get a PWM specifier's flags cell value at an index
*
* This macro only works for PWM controllers that specify a 'flags'
* field in the phandle-array specifier. Refer to the specific PWM
* controller binding if needed.
* This macro only works for PWM specifiers with cells named "flags".
* Refer to the node's binding to check if necessary.
*
* @param node_id node identifier
* @param idx logical index into the property
* @return the flags value for the named specifier at index idx
* This is equivalent to DT_PWMS_CELL_BY_IDX(node_id, flags, idx).
*
* @param node_id node identifier for a node with a pwms property
* @param idx logical index into pwms property
* @return the flags cell value at index "idx"
* @see DT_PWMS_CELL_BY_IDX()
*/
#define DT_PWMS_FLAGS_BY_IDX(node_id, idx) \
DT_PWMS_CELL_BY_IDX(node_id, flags, idx)
/**
* @brief Get PWM controller 'flags' by name
* @brief Get a PWM specifier's flags cell value by name
*
* This macro only works for PWM controllers that specify a 'flags'
* field in the phandle-array specifier. Refer to the specific PWM
* controller binding if needed.
* This macro only works for PWM specifiers with cells named "flags".
* Refer to the node's binding to check if necessary.
*
* @param node_id node identifier
* @param name lowercase-and-underscores "pwm" name
* @return the flags value for the named specifier by name
* This is equivalent to DT_PWMS_CELL_BY_NAME(node_id, name, flags).
*
* @param node_id node identifier for a node with a pwms property
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the flags cell value in the specifier at the named element
* @see DT_PWMS_CELL_BY_NAME()
*/
#define DT_PWMS_FLAGS_BY_NAME(node_id, name) \
@ -247,122 +276,129 @@ extern "C" {
/**
* @brief Equivalent to DT_PWMS_FLAGS_BY_IDX(node_id, 0)
* @param node_id node identifier
* @return the flags value for the named specifier at index 0
* @param node_id node identifier for a node with a pwms property
* @return the flags cell value at index 0
* @see DT_PWMS_FLAGS_BY_IDX()
*/
#define DT_PWMS_FLAGS(node_id) DT_PWMS_FLAGS_BY_IDX(node_id, 0)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "name" at an index
* (see @ref DT_PWMS_LABEL_BY_IDX)
* @param inst instance number
* @param idx logical index into the property
* @return the label property for the named specifier at index idx
* @brief Get a label property from a DT_DRV_COMPAT instance's pwms
* property by name
* @param inst DT_DRV_COMPAT instance number
* @param idx logical index into pwms property
* @return the label property of the node referenced at index "idx"
* @see DT_PWMS_LABEL_BY_IDX()
*/
#define DT_INST_PWMS_LABEL_BY_IDX(inst, idx) \
DT_PWMS_LABEL_BY_IDX(DT_DRV_INST(inst), idx)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "name" (label property) by name
* (see @ref DT_PWMS_LABEL_BY_NAME)
* @param inst instance number
* @param name lowercase-and-underscores specifier name
* @return the label property for the named specifier by name
* @brief Get a label property from a DT_DRV_COMPAT instance's pwms
* property by name
* @param inst DT_DRV_COMPAT instance number
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the label property of the node referenced at the named element
* @see DT_PWMS_LABEL_BY_NAME()
*/
#define DT_INST_PWMS_LABEL_BY_NAME(inst, name) \
DT_PWMS_LABEL_BY_NAME(DT_DRV_INST(inst), name)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "name"
* (see @ref DT_PWMS_LABEL_BY_IDX)
* @param inst instance number
* @return the label property for the named specifier at index 0
* @brief Equivalent to DT_INST_PWMS_LABEL_BY_IDX(inst, 0)
* @param inst DT_DRV_COMPAT instance number
* @return the label property of the node referenced at index 0
* @see DT_PWMS_LABEL_BY_IDX()
*/
#define DT_INST_PWMS_LABEL(inst) DT_INST_PWMS_LABEL_BY_IDX(inst, 0)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "cell" value at an index
* @param inst instance number
* @param cell binding's cell name within the specifier at index "idx"
* @param idx logical index into the property
* @return the value of the cell inside the specifier at index "idx"
* @brief Get a DT_DRV_COMPAT instance's PWM specifier's cell value
* at an index
* @param inst DT_DRV_COMPAT instance number
* @param cell lowercase-and-underscores cell name
* @param idx logical index into pwms property
* @return the cell value at index "idx"
*/
#define DT_INST_PWMS_CELL_BY_IDX(inst, cell, idx) \
DT_PWMS_CELL_BY_IDX(DT_DRV_INST(inst), cell, idx)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "cell" value by name
* (see @ref DT_PWMS_CELL_BY_NAME)
* @param inst instance number
* @param name lowercase-and-underscores specifier name
* @param cell binding's cell name within the specifier referenced as "name"
* @return the value of the cell inside the named specifier
* @brief Get a DT_DRV_COMPAT instance's PWM specifier's cell value by name
* @param inst DT_DRV_COMPAT instance number
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @param cell lowercase-and-underscores cell name
* @return the cell value in the specifier at the named element
* @see DT_PWMS_CELL_BY_NAME()
*/
#define DT_INST_PWMS_CELL_BY_NAME(inst, name, cell) \
DT_PWMS_CELL_BY_NAME(DT_DRV_INST(inst), name, cell)
/**
* @brief Get a DT_DRV_COMPAT pwm controller "cell" value at an index 0
* @param inst instance number
* @param cell binding's cell name within the specifier at index 0
* @return the value of the cell inside the specifier at index 0
* @brief Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, cell, 0)
* @param inst DT_DRV_COMPAT instance number
* @param cell lowercase-and-underscores cell name
* @return the cell value at index 0
*/
#define DT_INST_PWMS_CELL(inst, cell) \
DT_INST_PWMS_CELL_BY_IDX(inst, cell, 0)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'channel' at an index
* @param inst instance number
* @param idx logical index into the property
* @return the channel value for the named specifier at index idx
* @brief Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, channel, idx)
* @param inst DT_DRV_COMPAT instance number
* @param idx logical index into pwms property
* @return the channel cell value at index "idx"
* @see DT_INST_PWMS_CELL_BY_IDX()
*/
#define DT_INST_PWMS_CHANNEL_BY_IDX(inst, idx) \
DT_INST_PWMS_CELL_BY_IDX(inst, channel, idx)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'channel' by name
* @param inst instance number
* @param name lowercase-and-underscores "pwm" name
* @return the channel value for the named specifier by name
* @brief Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, channel)
* @param inst DT_DRV_COMPAT instance number
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the channel cell value in the specifier at the named element
* @see DT_INST_PWMS_CELL_BY_NAME()
*/
#define DT_INST_PWMS_CHANNEL_BY_NAME(inst, name) \
DT_INST_PWMS_CELL_BY_NAME(inst, name, channel)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'channel' value at an index 0
* @param inst instance number
* @return the channel value for the named specifier at index 0
* @brief Equivalent to DT_INST_PWMS_CHANNEL_BY_IDX(inst, 0)
* @param inst DT_DRV_COMPAT instance number
* @return the channel cell value at index 0
* @see DT_INST_PWMS_CHANNEL_BY_IDX()
*/
#define DT_INST_PWMS_CHANNEL(inst) DT_INST_PWMS_CHANNEL_BY_IDX(inst, 0)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'flags' at an index
* @param inst instance number
* @param idx logical index into the property
* @return the flags value for the named specifier at index idx
* @brief Equivalent to DT_INST_PWMS_CELL_BY_IDX(inst, flags, idx)
* @param inst DT_DRV_COMPAT instance number
* @param idx logical index into pwms property
* @return the flags cell value at index "idx"
* @see DT_INST_PWMS_CELL_BY_IDX()
*/
#define DT_INST_PWMS_FLAGS_BY_IDX(inst, idx) \
DT_INST_PWMS_CELL_BY_IDX(inst, flags, idx)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'flags' by name
* @param inst instance number
* @param name lowercase-and-underscores "pwm" name
* @return the flags value for the named specifier by name
* @brief Equivalent to DT_INST_PWMS_CELL_BY_NAME(inst, name, flags)
* @param inst DT_DRV_COMPAT instance number
* @param name lowercase-and-underscores name of a pwms element
* as defined by the node's pwm-names property
* @return the flags cell value in the specifier at the named element
* @see DT_INST_PWMS_CELL_BY_NAME()
*/
#define DT_INST_PWMS_FLAGS_BY_NAME(inst, name) \
DT_INST_PWMS_CELL_BY_NAME(inst, name, flags)
/**
* @brief Get a DT_DRV_COMPAT pwm controller 'flags' value at an index 0
* @param inst instance number
* @return the flags value for the named specifier at index 0
* @brief Equivalent to DT_INST_PWMS_FLAGS_BY_IDX(inst, 0)
* @param inst DT_DRV_COMPAT instance number
* @return the flags cell value at index 0
* @see DT_INST_PWMS_FLAGS_BY_IDX()
*/
#define DT_INST_PWMS_FLAGS(inst) DT_INST_PWMS_FLAGS_BY_IDX(inst, 0)
@ -375,5 +411,4 @@ extern "C" {
}
#endif
#endif /* ZEPHYR_INCLUDE_DEVICETREE_PWMS_H_ */