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