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!
