Re: [PATCH v1 1/1] device property: Advertise fwnode and device property count API calls

[Rafael J. Wysocki]

On Mon, May 2, 2022 at 11:51 AM Andy Shevchenko
<andriy.shevchenko@xxxxxxxxxxxxxxx> wrote:
>
> The documentation of fwnode and device property array API calls isn't
> pointing out to the shortcuts to count the number of elements of size
> in an array. Amend the documentation to advertise fwnode and device
> property count API calls.
>
> Reported-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx>
> ---
>  drivers/base/property.c | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
>
> diff --git a/drivers/base/property.c b/drivers/base/property.c
> index f289f582209c..836124f54332 100644
> --- a/drivers/base/property.c
> +++ b/drivers/base/property.c
> @@ -68,6 +68,9 @@ EXPORT_SYMBOL_GPL(fwnode_property_present);
>   * Function reads an array of u8 properties with @propname from the device
>   * firmware description and stores them to @val if found.
>   *
> + * It's recommended to call device_property_count_u8() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -93,6 +96,9 @@ EXPORT_SYMBOL_GPL(device_property_read_u8_array);
>   * Function reads an array of u16 properties with @propname from the device
>   * firmware description and stores them to @val if found.
>   *
> + * It's recommended to call device_property_count_u16() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -118,6 +124,9 @@ EXPORT_SYMBOL_GPL(device_property_read_u16_array);
>   * Function reads an array of u32 properties with @propname from the device
>   * firmware description and stores them to @val if found.
>   *
> + * It's recommended to call device_property_count_u32() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -143,6 +152,9 @@ EXPORT_SYMBOL_GPL(device_property_read_u32_array);
>   * Function reads an array of u64 properties with @propname from the device
>   * firmware description and stores them to @val if found.
>   *
> + * It's recommended to call device_property_count_u64() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -168,6 +180,9 @@ EXPORT_SYMBOL_GPL(device_property_read_u64_array);
>   * Function reads an array of string properties with @propname from the device
>   * firmware description and stores them to @val if found.
>   *
> + * It's recommended to call device_property_string_array_count() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values read on success if @val is non-NULL,
>   *        number of values available on success if @val is NULL,
>   *        %-EINVAL if given arguments are not valid,
> @@ -256,6 +271,9 @@ static int fwnode_property_read_int_array(const struct fwnode_handle *fwnode,
>   * Read an array of u8 properties with @propname from @fwnode and stores them to
>   * @val if found.
>   *
> + * It's recommended to call fwnode_property_count_u8() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -282,6 +300,9 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_u8_array);
>   * Read an array of u16 properties with @propname from @fwnode and store them to
>   * @val if found.
>   *
> + * It's recommended to call fwnode_property_count_u16() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -308,6 +329,9 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_u16_array);
>   * Read an array of u32 properties with @propname from @fwnode store them to
>   * @val if found.
>   *
> + * It's recommended to call fwnode_property_count_u32() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -334,6 +358,9 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_u32_array);
>   * Read an array of u64 properties with @propname from @fwnode and store them to
>   * @val if found.
>   *
> + * It's recommended to call fwnode_property_count_u64() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values if @val was %NULL,
>   *         %0 if the property was found (success),
>   *        %-EINVAL if given arguments are not valid,
> @@ -360,6 +387,9 @@ EXPORT_SYMBOL_GPL(fwnode_property_read_u64_array);
>   * Read an string list property @propname from the given firmware node and store
>   * them to @val if found.
>   *
> + * It's recommended to call fwnode_property_string_array_count() instead of calling
> + * this function with @val equals %NULL and @nval equals 0.
> + *
>   * Return: number of values read on success if @val is non-NULL,
>   *        number of values available on success if @val is NULL,
>   *        %-EINVAL if given arguments are not valid,
> --

Applied as 5.19 material, thanks!