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 0 18 19 /** 20 * Define this to get debugging massages for 21 * timer handling. 22 */ 23 #define FSM_TIMER_DEBUG 0 24 25 /** 26 * Define these to record a history of 27 * Events/Statechanges and print it if a 28 * action_function is not found. 29 */ 30 #define FSM_DEBUG_HISTORY 0 31 #define FSM_HISTORY_SIZE 40 32 33 struct fsm_instance_t; 34 35 /** 36 * Definition of an action function, called by a FSM 37 */ 38 typedef void (*fsm_function_t)(struct fsm_instance_t *, int, void *); 39 40 /** 41 * Internal jump table for a FSM 42 */ 43 typedef 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_HISTORY 52 /** 53 * Element of State/Event history used for debugging. 54 */ 55 typedef struct { 56 int state; 57 int event; 58 } fsm_history; 59 #endif 60 61 /** 62 * Representation of a FSM 63 */ 64 typedef 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_HISTORY 72 int history_index; 73 int history_size; 74 fsm_history history[FSM_HISTORY_SIZE]; 75 #endif 76 } fsm_instance; 77 78 /** 79 * Description of a state-event combination 80 */ 81 typedef 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 */ 90 typedef 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 FSM 99 * 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 */ 109 extern fsm_instance * 110 init_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 FSM 117 * 118 * @param fi Pointer to an FSM, previously created with init_fsm. 119 */ 120 extern void kfree_fsm(fsm_instance *fi); 121 122 #if FSM_DEBUG_HISTORY 123 extern void 124 fsm_print_history(fsm_instance *fi); 125 126 extern void 127 fsm_record_history(fsm_instance *fi, int state, int event); 128 #endif 129 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 range 141 * !0 if state and event in range, but no action defined. 142 */ 143 static inline int 144 fsm_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_HISTORY 155 fsm_print_history(fi); 156 #endif 157 return 1; 158 } 159 r = fi->f->jumpmatrix[fi->f->nr_states * event + state]; 160 if (r) { 161 #if FSM_DEBUG 162 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 #endif 166 #if FSM_DEBUG_HISTORY 167 fsm_record_history(fi, state, event); 168 #endif 169 r(fi, event, arg); 170 return 0; 171 } else { 172 #if FSM_DEBUG || FSM_DEBUG_HISTORY 173 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 #endif 177 #if FSM_DEBUG_HISTORY 178 fsm_print_history(fi); 179 #endif 180 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 FSM 189 * @param state The new state for this FSM. 190 */ 191 static inline void 192 fsm_newstate(fsm_instance *fi, int newstate) 193 { 194 atomic_set(&fi->state,newstate); 195 #if FSM_DEBUG_HISTORY 196 fsm_record_history(fi, newstate, -1); 197 #endif 198 #if FSM_DEBUG 199 printk(KERN_DEBUG "fsm(%s): New state %s\n", fi->name, 200 fi->f->state_names[newstate]); 201 #endif 202 wake_up(&fi->wait_q); 203 } 204 205 /** 206 * Retrieves the state of an FSM 207 * 208 * @param fi Pointer to FSM 209 * 210 * @return The current state of the FSM. 211 */ 212 static inline int 213 fsm_getstate(fsm_instance *fi) 214 { 215 return atomic_read(&fi->state); 216 } 217 218 /** 219 * Retrieves the name of the state of an FSM 220 * 221 * @param fi Pointer to FSM 222 * 223 * @return The current state of the FSM in a human readable form. 224 */ 225 extern 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 FSM 232 * @param timer The timer to be initialized. 233 */ 234 extern 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 */ 241 extern 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 timer 247 * 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 */ 254 extern 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 */ 264 extern void fsm_modtimer(fsm_timer *timer, int millisec, int event, void *arg); 265 266 #endif /* _FSM_H_ */ 267