contrib/hostapd/src/utils/state_machine.h

   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) \
  39 static 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) \
  53 if (!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 } \
  58 sm->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) \
  72 if (!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 } \
  77 sm->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) \
  90 if (!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 } \
  96 sm->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) \
 108 sm_ ## 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) \
 121 sm_ ## 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) \
 133 static 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 */