s390/ctcm: Convert fsm.h to proper kernel-doc format
Subsystems (4)
PATCH 1/1 s390/ctcm: Convert fsm.h to proper kernel-doc format
drivers/s390/net/fsm.h contains comments starting with '/**' that don't follow kernel-doc syntax, triggering warnings when running:
scripts/kernel-doc -none -Wall drivers/s390/net/fsm*
Example warning:
Warning: drivers/s390/net/fsm.h:14 This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst
* Define this to get debugging messages.
Convert function declarations to proper kernel-doc format per Documentation/doc-guide/kernel-doc.rst. Change debug macros and internal structure comments from '/**' to '/*' since they are not part of the public API. Also add missing parameter name in fsm_settimer() declaration to match the implementation. Remove redundant extern keywords from all function declarations.
No functional change.
--- drivers/s390/net/fsm.h | 152 +++++++++++++++++++++-------------------- 1 file changed, 78 insertions(+), 74 deletions(-)
drivers/s390/net/fsm.h +78 -74
@@ -11,18 +11,18 @@#include <linux/string.h> #include <linux/atomic.h> -/** +/* * Define this to get debugging messages. */ #define FSM_DEBUG 0 -/** +/* * Define this to get debugging massages for * timer handling. */ #define FSM_TIMER_DEBUG 0 -/** +/* * Define these to record a history of * Events/Statechanges and print it if a * action_function is not found.
@@ -32,12 +32,12 @@struct fsm_instance_t ; -/** +/* * Definition of an action function, called by a FSM */ typedef void (*fsm_function_t )(struct fsm_instance_t *,int ,void *); -/** +/* * Internal jump table for a FSM */ typedef struct {
@@ -49,7 +49,7 @@ typedef struct { } fsm; #if FSM_DEBUG_HISTORY -/** +/* * Element of State/Event history used for debugging. */ typedef struct {
@@ -58,7 +58,7 @@ typedef struct { } fsm_history;#endif -/** +/* * Representation of a FSM */ typedef struct fsm_instance_t {
@@ -75,7 +75,7 @@ typedef struct fsm_instance_t {#endif } fsm_instance; -/** +/* * Description of a state-event combination */ typedef struct {
@@ -84,7 +84,7 @@ typedef struct {fsm_function_t function; } fsm_node; -/** +/* * Description of a FSM Timer. */ typedef struct {
@@ -95,50 +95,52 @@ typedef struct { } fsm_timer;/** -* Creates an FSM +* init_fsm - Creates a finite state machine +* @name: Name of this instance for logging purposes +* @state_names: Array of names for all states for logging purposes +* @event_names: Array of names for all events for logging purposes +* @nr_states: Number of states for this instance +* @nr_events: Number of events for this instance +* @tmpl: Pointer to fsm_node array describing this FSM +* @tmpl_len: Number of entries in the tmpl array +* @order: GFP flags for memory allocation (e.g. GFP_KERNEL) * -* @param name Name of this instance for logging purposes. -* @param state_names An array of names for all states for logging purposes. -* @param event_names An array of names for all events for logging purposes. -* @param nr_states Number of states for this instance. -* @param nr_events Number of events for this instance. -* @param tmpl An array of fsm_nodes, describing this FSM. -* @param tmpl_len Length of the describing array. -* @param order Parameter for allocation of the FSM data structs. +* Allocates and initializes a finite state machine instance with the +* specified states, events, and transition table. +* +* Return: Pointer to initialized FSM instance, or NULL on failure */ -extern fsm_instance * -init_fsm (char *name,const char **state_names, -const char **event_names, -int nr_states,int nr_events,const fsm_node *tmpl, -int tmpl_len,gfp_t order); +fsm_instance *init_fsm (char *name,const char **state_names, +const char **event_names,int nr_states, +int nr_events,const fsm_node *tmpl, +int tmpl_len,gfp_t order);/** -* Releases an FSM +* kfree_fsm - Releases a finite state machine +* @fi: Pointer to FSM instance, previously created with init_fsm() * -* @param fi Pointer to an FSM, previously created with init_fsm. +* Frees all memory associated with the FSM instance. */ -extern void kfree_fsm (fsm_instance *fi); +void kfree_fsm (fsm_instance *fi);#if FSM_DEBUG_HISTORY -extern void -fsm_print_history (fsm_instance *fi); +void fsm_print_history (fsm_instance *fi); -extern void -fsm_record_history (fsm_instance *fi,int state,int event); +void fsm_record_history (fsm_instance *fi,int state,int event);#endif /** -* Emits an event to a FSM. -* If an action function is defined for the current state/event combination, -* this function is called. +* fsm_event - Emits an event to a finite state machine +* @fi: Pointer to FSM which should receive the event +* @event: The event to be delivered +* @arg: Generic argument, passed to the action function * -* @param fi Pointer to FSM which should receive the event. -* @param event The event do be delivered. -* @param arg A generic argument, handed to the action function. +* If an action function is defined for the current state/event +* combination, that function is called with the provided arguments. * -* @return 0 on success, -* 1 if current state or event is out of range -* !0 if state and event in range, but no action defined. +* Return: +* * 0 - Success, action function was called +* * 1 - State/event out of range, or no action function defined */ static inline int fsm_event (fsm_instance *fi,int event,void *arg)
@@ -182,11 +184,12 @@ fsm_event(fsm_instance *fi, int event, void *arg) }/** -* Modifies the state of an FSM. -* This does <em>not</em> trigger an event or calls an action function. +* fsm_newstate - Modifies the state of a finite state machine +* @fi: Pointer to FSM +* @newstate: The new state for this FSM * -* @param fi Pointer to FSM -* @param state The new state for this FSM. +* This does not trigger an event or call an action function. +* Wakes up any processes waiting on the FSM's wait queue. */ static inline void fsm_newstate (fsm_instance *fi,int newstate)
@@ -203,11 +206,10 @@ fsm_newstate(fsm_instance *fi, int newstate) }/** -* Retrieves the state of an FSM -* -* @param fi Pointer to FSM +* fsm_getstate - Retrieves the current state of a finite state machine +* @fi: Pointer to FSM * -* @return The current state of the FSM. +* Return: Current state number */ static inline int fsm_getstate (fsm_instance *fi)
@@ -216,51 +218,53 @@ fsm_getstate(fsm_instance *fi) }/** -* Retrieves the name of the state of an FSM -* -* @param fi Pointer to FSM +* fsm_getstate_str - Retrieves the name of the current FSM state +* @fi: Pointer to FSM * -* @return The current state of the FSM in a human readable form. +* Return: State name string, or "Invalid" if state is out of range */ -extern const char *fsm_getstate_str (fsm_instance *fi); +const char *fsm_getstate_str (fsm_instance *fi);/** -* Initializes a timer for an FSM. -* This prepares an fsm_timer for usage with fsm_addtimer. +* fsm_settimer - Initializes a timer for a finite state machine +* @fi: Pointer to FSM +* @this: The timer to be initialized * -* @param fi Pointer to FSM -* @param timer The timer to be initialized. +* Prepares an fsm_timer for usage with fsm_addtimer(). */ -extern void fsm_settimer (fsm_instance *fi,fsm_timer *); +void fsm_settimer (fsm_instance *fi,fsm_timer *this);/** -* Clears a pending timer of an FSM instance. +* fsm_deltimer - Clears a pending timer of an FSM instance +* @timer: The timer to clear * -* @param timer The timer to clear. +* Stops and removes the timer. Safe to call on an inactive timer. */ -extern void fsm_deltimer (fsm_timer *timer); +void fsm_deltimer (fsm_timer *timer);/** -* Adds and starts a timer to an FSM instance. +* fsm_addtimer - Adds and starts a timer for an FSM instance +* @timer: The timer to be added (timer->fi must point to the FSM instance) +* @millisec: Duration in milliseconds after which the timer expires +* @event: Event to trigger when timer expires +* @arg: Generic argument provided to the event handler * -* @param timer The timer to be added. The field fi of that timer -* must have been set to point to the instance. -* @param millisec Duration, after which the timer should expire. -* @param event Event, to trigger if timer expires. -* @param arg Generic argument, provided to expiry function. +* Starts a timer that will trigger the specified event after the given +* duration. The timer must have been initialized with fsm_settimer(). * -* @return 0 on success, -1 if timer is already active. +* Return: Always returns 0 */ -extern int fsm_addtimer (fsm_timer *timer,int millisec,int event,void *arg); +int fsm_addtimer (fsm_timer *timer,int millisec,int event,void *arg);/** -* Modifies a timer of an FSM. +* fsm_modtimer - Modifies a timer of a finite state machine +* @timer: The timer to modify +* @millisec: New duration in milliseconds after which the timer expires +* @event: Event to trigger when timer expires +* @arg: Generic argument provided to the event handler * -* @param timer The timer to modify. -* @param millisec Duration, after which the timer should expire. -* @param event Event, to trigger if timer expires. -* @param arg Generic argument, provided to expiry function. +* Stops the existing timer and restarts it with new parameters. */ -extern void fsm_modtimer (fsm_timer *timer,int millisec,int event,void *arg); +void fsm_modtimer (fsm_timer *timer,int millisec,int event,void *arg);#endif /* _FSM_H_ */
Signature · 1 line
2.53.0
[email protected]
AI reviewThank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
Pre-existing issues:
- [High] fsm_deltimer() uses non-sync timer_delete(), which can lead to a use-after-free when timers are freed during teardown.
- [High] fsm_addtimer() unconditionally calls timer_setup(), which corrupts the timer wheel if the timer is already active. --
--- Patch [1]: [PATCH net-next] s390/ctcm: Convert fsm.h to proper kernel-doc format --- commit 2780dcd525cc21b0863567563af1ccbda9bf1645
Author: Nagamani PV <[email protected]>
s390/ctcm: Convert fsm.h to proper kernel-doc format
This commit converts function declarations and comments in drivers/s390/net/fsm.h to proper kernel-doc format. It changes debug macros and internal comments to use standard block comments and removes redundant extern keywords.
Quoted 4 lines
drivers/s390/net/fsm.h +0
-0
[ ... ]
drivers/s390/net/fsm.h fsm_getstate(fsm_instance *fi) · line 243
Quoted 10 lines
/**
- * Clears a pending timer of an FSM instance.
+ *fsm_deltimer- Clears a pending timer of an FSM instance
+ * @timer: The timer to clear
*
- * @param timer The timer to clear.
+ * Stops and removes the timer. Safe to call on an inactive timer. */drivers/s390/net/fsm.h +1
-1-extern void fsm_deltimer (fsm_timer *timer); +void fsm_deltimer (fsm_timer *timer);
[Severity: High]
This isn't a bug introduced by this patch, but is it possible for this non-synchronous timer deletion to cause a use-after-free during device teardown?
Looking at fsm_deltimer() in drivers/s390/net/fsm.c, it uses timer_delete(). During teardown in ctcm_free_channel(), the driver calls:
ctcm_free_channel() {
fsm_deltimer(&ch->timer);
...
kfree_fsm(ch->fsm);
kfree(ch);
}Since timer_delete() does not wait for a concurrently executing timer callback, could fsm_expire_timer() still be running on another CPU and dereference ch->fsm after it has been freed by kfree_fsm()? Would it be safer to use timer_shutdown_sync() or timer_delete_sync() here?
Quoted 19 lines
/**
- * Adds and starts a timer to an FSM instance.
+ *fsm_addtimer- Adds and starts a timer for an FSM instance
+ * @timer: The timer to be added (timer->fimust point to the FSM instance)
+ * @millisec: Duration in milliseconds after which the timer expires
+ * @event: Event to trigger when timer expires
+ * @arg: Generic argument provided to the event handler
*
- * @param timer The timer to be added. The field fi of that timer
- * must have been set to point to the instance.
- * @param millisec Duration, after which the timer should expire.
- * @param event Event, to trigger if timer expires.
- * @param arg Generic argument, provided to expiry function.
+ * Starts a timer that will trigger the specified event after the given
+ * duration. The timer must have been initialized withfsm_settimer(). *
- * @return 0 on success, -1 if timer is already active.
+ * Return: Always returns 0
*/
drivers/s390/net/fsm.h fsm_getstate(fsm_instance *fi) · line 257
Quoted 2 lines
drivers/s390/net/fsm.h +1
-1-extern int fsm_addtimer (fsm_timer *timer,int millisec,int event,void *arg); +int fsm_addtimer (fsm_timer *timer,int millisec,int event,void *arg);
[Severity: High]
This is a pre-existing issue, but does fsm_addtimer() risk corrupting the timer wheel if called on an already active timer?
In drivers/s390/net/fsm.c, fsm_addtimer() unconditionally calls timer_setup():
fsm_addtimer() {
timer_setup(&this->tl, fsm_expire_timer, 0);
...
add_timer(&this->tl);
}Since timer_setup() zeros out the list entry fields, calling this on a currently pending timer will corrupt the timer wheel list. While many callers delete the timer first, there are paths like mpc_action_side_xid() in drivers/s390/net/ctcm_mpc.c that invoke fsm_addtimer() without a preceding fsm_deltimer(). Should this use mod_timer() instead to safely handle already active timers?
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Quoted 5 lines · On 04/08/26 11:57 PM, [email protected] wrote:
Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
Pre-existing issues:
- [High]fsm_deltimer()uses non-synctimer_delete(), which can lead to a use-after-free when timers are freed during teardown.
- [High]fsm_addtimer()unconditionally callstimer_setup(), which corrupts the timer wheel if the timer is already active.
Both findings confirmed, reviewed and validated. Note: the report references ctcm_free_channel() which does not exist; the actual teardown function is channel_remove() in ctcm_main.c.
Fixes will be submitted to [email protected] shortly as a two-patch series.
Nagamani
This patch was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:
Hello:
This patch was applied to netdev/net-next.git (main) by Jakub Kicinski <[email protected]>:
Quoted 11 lines · On Mon, 3 Aug 2026 20:27:36 +0200 you wrote:
drivers/s390/net/fsm.hcontains comments starting with '/**' that don't follow kernel-doc syntax, triggering warnings when running:
scripts/kernel-doc-none -Walldrivers/s390/net/fsm*Example warning:
Warning:drivers/s390/net/fsm.h:14This comment starts with '/**', but isn't a kernel-doc comment. Refer toDocumentation/doc-guide/kernel-doc.rst
* Define this to get debugging messages.[...]
Here is the summary with links:
- [net-next] s390/ctcm: Convert fsm.h to proper kernel-doc format
https://git.kernel.org/netdev/net-next/c/0023e4c6171d
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html