1/*
2 * wpa_supplicant/hostapd - State machine definitions
3 * Copyright (c) 2002-2005, Jouni Malinen <j@w1.fi>
4 *
5 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
7 *
8 * This file includes a set of pre-processor macros that can be used to
9 * implement a state machine. In addition to including this header file, each
10 * file implementing a state machine must define STATE_MACHINE_DATA to be the
11 * data structure including state variables (enum machine_state,
12 * Boolean changed), and STATE_MACHINE_DEBUG_PREFIX to be a string that is used
13 * as a prefix for all debug messages. If SM_ENTRY_MA macro is used to define
14 * a group of state machines with shared data structure, STATE_MACHINE_ADDR
15 * needs to be defined to point to the MAC address used in debug output.
16 * SM_ENTRY_M macro can be used to define similar group of state machines
17 * without this additional debug info.
18 */
19
20#ifndef STATE_MACHINE_H
21#define STATE_MACHINE_H
22
23/**
24 * SM_STATE - Declaration of a state machine function
25 * @machine: State machine name
26 * @state: State machine state
27 *
28 * This macro is used to declare a state machine function. It is used in place
29 * of a C function definition to declare functions to be run when the state is
30 * entered by calling SM_ENTER or SM_ENTER_GLOBAL.
31 */
32#define SM_STATE(machine, state) \
33static void sm_ ## machine ## _ ## state ## _Enter(STATE_MACHINE_DATA *sm, \
34	int global)
35
36/**
37 * SM_ENTRY - State machine function entry point
38 * @machine: State machine name
39 * @state: State machine state
40 *
41 * This macro is used inside each state machine function declared with
42 * SM_STATE. SM_ENTRY should be in the beginning of the function body, but
43 * after declaration of possible local variables. This macro prints debug
44 * information about state transition and update the state machine state.
45 */
46#define SM_ENTRY(machine, state) \
47if (!global || sm->machine ## _state != machine ## _ ## state) { \
48	sm->changed = TRUE; \
49	wpa_printf(MSG_DEBUG, STATE_MACHINE_DEBUG_PREFIX ": " #machine \
50		   " entering state " #state); \
51} \
52sm->machine ## _state = machine ## _ ## state;
53
54/**
55 * SM_ENTRY_M - State machine function entry point for state machine group
56 * @machine: State machine name
57 * @_state: State machine state
58 * @data: State variable prefix (full variable: prefix_state)
59 *
60 * This macro is like SM_ENTRY, but for state machine groups that use a shared
61 * data structure for more than one state machine. Both machine and prefix
62 * parameters are set to "sub-state machine" name. prefix is used to allow more
63 * than one state variable to be stored in the same data structure.
64 */
65#define SM_ENTRY_M(machine, _state, data) \
66if (!global || sm->data ## _ ## state != machine ## _ ## _state) { \
67	sm->changed = TRUE; \
68	wpa_printf(MSG_DEBUG, STATE_MACHINE_DEBUG_PREFIX ": " \
69		   #machine " entering state " #_state); \
70} \
71sm->data ## _ ## state = machine ## _ ## _state;
72
73/**
74 * SM_ENTRY_MA - State machine function entry point for state machine group
75 * @machine: State machine name
76 * @_state: State machine state
77 * @data: State variable prefix (full variable: prefix_state)
78 *
79 * This macro is like SM_ENTRY_M, but a MAC address is included in debug
80 * output. STATE_MACHINE_ADDR has to be defined to point to the MAC address to
81 * be included in debug.
82 */
83#define SM_ENTRY_MA(machine, _state, data) \
84if (!global || sm->data ## _ ## state != machine ## _ ## _state) { \
85	sm->changed = TRUE; \
86	wpa_printf(MSG_DEBUG, STATE_MACHINE_DEBUG_PREFIX ": " MACSTR " " \
87		   #machine " entering state " #_state, \
88		   MAC2STR(STATE_MACHINE_ADDR)); \
89} \
90sm->data ## _ ## state = machine ## _ ## _state;
91
92/**
93 * SM_ENTER - Enter a new state machine state
94 * @machine: State machine name
95 * @state: State machine state
96 *
97 * This macro expands to a function call to a state machine function defined
98 * with SM_STATE macro. SM_ENTER is used in a state machine step function to
99 * move the state machine to a new state.
100 */
101#define SM_ENTER(machine, state) \
102sm_ ## machine ## _ ## state ## _Enter(sm, 0)
103
104/**
105 * SM_ENTER_GLOBAL - Enter a new state machine state based on global rule
106 * @machine: State machine name
107 * @state: State machine state
108 *
109 * This macro is like SM_ENTER, but this is used when entering a new state
110 * based on a global (not specific to any particular state) rule. A separate
111 * macro is used to avoid unwanted debug message floods when the same global
112 * rule is forcing a state machine to remain in on state.
113 */
114#define SM_ENTER_GLOBAL(machine, state) \
115sm_ ## machine ## _ ## state ## _Enter(sm, 1)
116
117/**
118 * SM_STEP - Declaration of a state machine step function
119 * @machine: State machine name
120 *
121 * This macro is used to declare a state machine step function. It is used in
122 * place of a C function definition to declare a function that is used to move
123 * state machine to a new state based on state variables. This function uses
124 * SM_ENTER and SM_ENTER_GLOBAL macros to enter new state.
125 */
126#define SM_STEP(machine) \
127static void sm_ ## machine ## _Step(STATE_MACHINE_DATA *sm)
128
129/**
130 * SM_STEP_RUN - Call the state machine step function
131 * @machine: State machine name
132 *
133 * This macro expands to a function call to a state machine step function
134 * defined with SM_STEP macro.
135 */
136#define SM_STEP_RUN(machine) sm_ ## machine ## _Step(sm)
137
138#endif /* STATE_MACHINE_H */
139