This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 9b7c7717f8a826cca18cec7c0bd674a7916bbcae Author: Justin Hammond <[email protected]> AuthorDate: Tue Aug 18 01:40:32 2026 +0800 drivers/devfreq: Document the frequency table contract. A driver author had to read the core to learn what a frequency table may contain: the rules live in devfreq_table_validate() and in the four other places that skip DEVFREQ_ENTRY_INVALID. State them where the special values are defined instead. A table ascends, DEVFREQ_ENTRY_END terminates it, DEVFREQ_ENTRY_INVALID stands in for a frequency the device cannot use and is skipped by every consumer, and devfreq_register() rejects a table whose usable entries do not ascend. Say on get_table that it is called once, by devfreq_register(), which keeps the returned table for the life of the device. That is a real constraint on the caller, since the table cannot be on its stack, and consumers outside the core retain the same pointer. Comments only, no functional change. Assisted-by: Claude:claude-opus-5 Signed-off-by: Justin Hammond <[email protected]> --- include/nuttx/devfreq.h | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/include/nuttx/devfreq.h b/include/nuttx/devfreq.h index dc1ca051ce0..e5b2d7f7a9b 100644 --- a/include/nuttx/devfreq.h +++ b/include/nuttx/devfreq.h @@ -37,7 +37,11 @@ #define DEVFREQ_PRECHANGE 0 #define DEVFREQ_POSTCHANGE 1 -/* Special Values of .frequency field */ +/* Special values in a frequency table. A table ascends, ends with + * DEVFREQ_ENTRY_END, and may carry DEVFREQ_ENTRY_INVALID in place of a + * frequency the device cannot use, which every consumer of the table skips. + * devfreq_register() rejects a table whose usable entries do not ascend. + */ #define DEVFREQ_ENTRY_INVALID ~0u #define DEVFREQ_ENTRY_END ~1u @@ -96,6 +100,12 @@ struct devfreq_governor_s struct devfreq_driver_s { int conflict_policy; /* DEVFREQ_CONFLICT_PREFER_HIGH or LOW */ + + /* The frequency table in kHz, ascending and DEVFREQ_ENTRY_END terminated. + * Called once, by devfreq_register(), which keeps the returned table for + * the life of the device, so it must not be on the caller's stack. + */ + CODE FAR const uint32_t * (*get_table)(FAR struct devfreq_s *devfreq); CODE int (*target_index)(FAR struct devfreq_s *devfreq,
