267 lines · c
1/* SPDX-License-Identifier: GPL-2.0 */2#ifndef _FSM_H_3#define _FSM_H_4 5#include <linux/kernel.h>6#include <linux/types.h>7#include <linux/timer.h>8#include <linux/time.h>9#include <linux/slab.h>10#include <linux/sched.h>11#include <linux/string.h>12#include <linux/atomic.h>13 14/**15 * Define this to get debugging messages.16 */17#define FSM_DEBUG 018 19/**20 * Define this to get debugging massages for21 * timer handling.22 */23#define FSM_TIMER_DEBUG 024 25/**26 * Define these to record a history of27 * Events/Statechanges and print it if a28 * action_function is not found.29 */30#define FSM_DEBUG_HISTORY 031#define FSM_HISTORY_SIZE 4032 33struct fsm_instance_t;34 35/**36 * Definition of an action function, called by a FSM37 */38typedef void (*fsm_function_t)(struct fsm_instance_t *, int, void *);39 40/**41 * Internal jump table for a FSM42 */43typedef struct {44 fsm_function_t *jumpmatrix;45 int nr_events;46 int nr_states;47 const char **event_names;48 const char **state_names;49} fsm;50 51#if FSM_DEBUG_HISTORY52/**53 * Element of State/Event history used for debugging.54 */55typedef struct {56 int state;57 int event;58} fsm_history;59#endif60 61/**62 * Representation of a FSM63 */64typedef struct fsm_instance_t {65 fsm *f;66 atomic_t state;67 char name[16];68 void *userdata;69 int userint;70 wait_queue_head_t wait_q;71#if FSM_DEBUG_HISTORY72 int history_index;73 int history_size;74 fsm_history history[FSM_HISTORY_SIZE];75#endif76} fsm_instance;77 78/**79 * Description of a state-event combination80 */81typedef struct {82 int cond_state;83 int cond_event;84 fsm_function_t function;85} fsm_node;86 87/**88 * Description of a FSM Timer.89 */90typedef struct {91 fsm_instance *fi;92 struct timer_list tl;93 int expire_event;94 void *event_arg;95} fsm_timer;96 97/**98 * Creates an FSM99 *100 * @param name Name of this instance for logging purposes.101 * @param state_names An array of names for all states for logging purposes.102 * @param event_names An array of names for all events for logging purposes.103 * @param nr_states Number of states for this instance.104 * @param nr_events Number of events for this instance.105 * @param tmpl An array of fsm_nodes, describing this FSM.106 * @param tmpl_len Length of the describing array.107 * @param order Parameter for allocation of the FSM data structs.108 */109extern fsm_instance *110init_fsm(char *name, const char **state_names,111 const char **event_names,112 int nr_states, int nr_events, const fsm_node *tmpl,113 int tmpl_len, gfp_t order);114 115/**116 * Releases an FSM117 *118 * @param fi Pointer to an FSM, previously created with init_fsm.119 */120extern void kfree_fsm(fsm_instance *fi);121 122#if FSM_DEBUG_HISTORY123extern void124fsm_print_history(fsm_instance *fi);125 126extern void127fsm_record_history(fsm_instance *fi, int state, int event);128#endif129 130/**131 * Emits an event to a FSM.132 * If an action function is defined for the current state/event combination,133 * this function is called.134 *135 * @param fi Pointer to FSM which should receive the event.136 * @param event The event do be delivered.137 * @param arg A generic argument, handed to the action function.138 *139 * @return 0 on success,140 * 1 if current state or event is out of range141 * !0 if state and event in range, but no action defined.142 */143static inline int144fsm_event(fsm_instance *fi, int event, void *arg)145{146 fsm_function_t r;147 int state = atomic_read(&fi->state);148 149 if ((state >= fi->f->nr_states) ||150 (event >= fi->f->nr_events) ) {151 printk(KERN_ERR "fsm(%s): Invalid state st(%ld/%ld) ev(%d/%ld)\n",152 fi->name, (long)state,(long)fi->f->nr_states, event,153 (long)fi->f->nr_events);154#if FSM_DEBUG_HISTORY155 fsm_print_history(fi);156#endif157 return 1;158 }159 r = fi->f->jumpmatrix[fi->f->nr_states * event + state];160 if (r) {161#if FSM_DEBUG162 printk(KERN_DEBUG "fsm(%s): state %s event %s\n",163 fi->name, fi->f->state_names[state],164 fi->f->event_names[event]);165#endif166#if FSM_DEBUG_HISTORY167 fsm_record_history(fi, state, event);168#endif169 r(fi, event, arg);170 return 0;171 } else {172#if FSM_DEBUG || FSM_DEBUG_HISTORY173 printk(KERN_DEBUG "fsm(%s): no function for event %s in state %s\n",174 fi->name, fi->f->event_names[event],175 fi->f->state_names[state]);176#endif177#if FSM_DEBUG_HISTORY178 fsm_print_history(fi);179#endif180 return !0;181 }182}183 184/**185 * Modifies the state of an FSM.186 * This does <em>not</em> trigger an event or calls an action function.187 *188 * @param fi Pointer to FSM189 * @param state The new state for this FSM.190 */191static inline void192fsm_newstate(fsm_instance *fi, int newstate)193{194 atomic_set(&fi->state,newstate);195#if FSM_DEBUG_HISTORY196 fsm_record_history(fi, newstate, -1);197#endif198#if FSM_DEBUG199 printk(KERN_DEBUG "fsm(%s): New state %s\n", fi->name,200 fi->f->state_names[newstate]);201#endif202 wake_up(&fi->wait_q);203}204 205/**206 * Retrieves the state of an FSM207 *208 * @param fi Pointer to FSM209 *210 * @return The current state of the FSM.211 */212static inline int213fsm_getstate(fsm_instance *fi)214{215 return atomic_read(&fi->state);216}217 218/**219 * Retrieves the name of the state of an FSM220 *221 * @param fi Pointer to FSM222 *223 * @return The current state of the FSM in a human readable form.224 */225extern const char *fsm_getstate_str(fsm_instance *fi);226 227/**228 * Initializes a timer for an FSM.229 * This prepares an fsm_timer for usage with fsm_addtimer.230 *231 * @param fi Pointer to FSM232 * @param timer The timer to be initialized.233 */234extern void fsm_settimer(fsm_instance *fi, fsm_timer *);235 236/**237 * Clears a pending timer of an FSM instance.238 *239 * @param timer The timer to clear.240 */241extern void fsm_deltimer(fsm_timer *timer);242 243/**244 * Adds and starts a timer to an FSM instance.245 *246 * @param timer The timer to be added. The field fi of that timer247 * must have been set to point to the instance.248 * @param millisec Duration, after which the timer should expire.249 * @param event Event, to trigger if timer expires.250 * @param arg Generic argument, provided to expiry function.251 *252 * @return 0 on success, -1 if timer is already active.253 */254extern int fsm_addtimer(fsm_timer *timer, int millisec, int event, void *arg);255 256/**257 * Modifies a timer of an FSM.258 *259 * @param timer The timer to modify.260 * @param millisec Duration, after which the timer should expire.261 * @param event Event, to trigger if timer expires.262 * @param arg Generic argument, provided to expiry function.263 */264extern void fsm_modtimer(fsm_timer *timer, int millisec, int event, void *arg);265 266#endif /* _FSM_H_ */267