Skip to contentSkip to conversation

libfdt: Fix fdt_appendprop_addrrange documentation

PATCH In review Pierre-Clément Tosi 2 participants 2 messages Aug 31, 2023 – Sep 4, 2023 1 message not in the archive

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 libfdt: Fix fdt_appendprop_addrrange documentation

According to the documentation, the function should default to the very common property name <reg> when none is "specified". However, neither passing NULL (ends up calling strlen(NULL) and segfaults) nor "" (appends a property with an empty name) implements this behavior.

Furthermore, the test case supposed to cover this default value actually passes the value to the function, somewhat defeating its own purpose:

    /* 2. default property name */

    // ...

    err = fdt_appendprop_addrrange(fdt, 0, offset, "reg", addr, size);
    if (err)
            FAIL("Failed to set \"reg\": %s", fdt_strerror(err));
    check_getprop_addrrange(fdt, 0, offset, "reg", 1);

Finally, nothing in the implementation of the function seems to attempt to cover that use-case.

As the feature can't ever have been used by clients and as the resulting reduced readability of the caller seems (IMO) to outweigh any potential benefit this API would bring, remove the erroneous documentation instead of trying to fix the function.

---
 libfdt/libfdt.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
libfdt/libfdt.h +1 -1
index 2a4f32c..0677fea 100644
@@ -2029,7 +2029,7 @@ static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
  * address and size) to the value of the named property in the given
  * node, or creates a new property with that value if it does not
  * already exist.
- * If "name" is not specified, a default "reg" is used.
+ *
  * Cell sizes are determined by parent's #address-cells and #size-cells.
  *
  * This function may insert data into the blob, and will therefore
Signature · 5 lines
2.42.0.rc2.253.gd59a3bf2b4-goog


-- 
Pierre

A message that is not in the archive (sent off-list or not yet received): 20230831123918.rf54emwkzgtcb7aw-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org

#2 lore raw
Quoted 20 lines · Pierre-Clément Tosi

According to the documentation, the function should default to the very common property name <reg> when none is "specified". However, neither passing NULL (ends up calling strlen(NULL) and segfaults) nor "" (appends a property with an empty name) implements this behavior.

Furthermore, the test case supposed to cover this default value actually passes the value to the function, somewhat defeating its own purpose:

    /* 2. default property name */

    // ...

    err = fdt_appendprop_addrrange(fdt, 0, offset, "reg", addr, size);
    if (err)
            FAIL("Failed to set \"reg\": %s", fdt_strerror(err));
    check_getprop_addrrange(fdt, 0, offset, "reg", 1);

Finally, nothing in the implementation of the function seems to attempt to cover that use-case.

Quoted 7 lines

As the feature can't ever have been used by clients and as the resulting reduced readability of the caller seems (IMO) to outweigh any potential benefit this API would bring, remove the erroneous documentation instead of trying to fix the function.

Nice catch, and an excellent commit message.

I don't recall this specifically, but my guess would be that an original draft included that behaviour, but I nixed it during review, but then both the submitted and I forgot to update the documentation comments as well.

Merged.

Quoted 17 lines
---
 libfdt/libfdt.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
libfdt/libfdt.h +1 -1
index 2a4f32c..0677fea 100644
@@ -2029,7 +2029,7 @@ static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
  * address and size) to the value of the named property in the given
  * node, or creates a new property with that value if it does not
  * already exist.
- * If "name" is not specified, a default "reg" is used.
+ *
  * Cell sizes are determined by parent's #address-cells and #size-cells.
  *
  * This function may insert data into the blob, and will therefore
Signature · 4 lines
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson