mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-08-28 05:14:41 -04:00
Code Issues Packages Projects Releases Wiki Activity

s390/ctcm: Convert fsm.h to proper kernel-doc format

Browse Source 
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.

Reviewed-by: Aswin Karuvally <aswin@linux.ibm.com>
Reviewed-by: Alexandra Winter <wintera@linux.ibm.com>
Signed-off-by: Nagamani PV <nagamani@linux.ibm.com>
Link: https://patch.msgid.link/20260803182736.2356374-1-nagamani@linux.ibm.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Nagamani PV
2026-08-03 20:27:36 +02:00
committed by Jakub Kicinski
parent f59ee23b98
commit 0023e4c617
1 changed files with 78 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
drivers/s390/net/fsm.h
View File

@@ -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
* fsm_getstate - Retrieves the current state of a finite state machine
* @fi: Pointer to FSM
*
* @param 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
* fsm_getstate_str - Retrieves the name of the current FSM state
* @fi: Pointer to FSM
*
* @param 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_ */