include: zephyr: arch: common: fix sys_test_bit() and friends documentation #97487
Conversation
zephyrbot
added
size: XS
|
Not sure this is a good idea to change the inner working of this, as there are probably lots of divers and apps depending on this behavior. |
|
Indeed this is something I would fear. At least, there are no such examples in-tree, in zephyr repo as well as HALs (and the other few modules referred in west.yml). Alternatively, should we correct the documentation of these functions? |
Yes, align the doc instead with the code behavior. Otherwise this will be considered a public API breaking change & will have to go through the relevant process |
|
The fact these functions return an |
Correct the documentation of sys_test_bit() and its derivative helper functions (listed below) since these return a bit mask value instead of an essentially boolean value as previosuly described. In tree implementation do conform with that: the result of these functions are always implicitly tested against being 0 or a non-zero value. Helper functions which documentation is modified are sys_test_bit(), sys_test_and_set_bit(), sys_test_and_clear_bit(), sys_bitfield_test_bit(), sys_bitfield_test_and_set_bit() and sys_bitfield_test_and_clear_bit(). Signed-off-by: Etienne Carriere <[email protected]>
etienne-lms
force-pushed
the
sys-test-bit
branch
from
ccb05bb to
31a75e7
Compare
etienne-lms
changed the title
|
5 participants
Changesys_test_bit()to have severalsys_*_test_bit()helper functions to return 0 or 1 (respectively when target bit is clear or set) as described in their documentation (include/zephyr/sys/sys_io.h) instead of returning a bit mask result.Correct the documentation of sys_test_bit() and its derivative helper functions (listed below) since these return a bit mask value instead of an essentially boolean value as previously described.
In tree implementation do conform with that: the result of these functions are always implicitly tested against being 0 or a non-zero value.
Affected helper functions fix by this change are
sys_test_bit(),sys_test_and_set_bit(),sys_test_and_clear_bit(),sys_bitfield_test_bit(),sys_bitfield_test_and_set_bit()andsys_bitfield_test_and_clear_bit().