1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 
16 /*****************************************************************************
17  *
18  *  Filename:      btc/btc_sm.h
19  *
20  *  Description:   Generic BTC state machine API
21  *
22  *****************************************************************************/
23 
24 #ifndef __BTC_SM_H__
25 #define __BTC_SM_H__
26 
27 /*****************************************************************************
28 **  Constants & Macros
29 ******************************************************************************/
30 
31 /* Generic Enter/Exit state machine events */
32 #define BTC_SM_ENTER_EVT 0xFFFF
33 #define BTC_SM_EXIT_EVT  0xFFFE
34 
35 
36 /*****************************************************************************
37 **  Type definitions and return values
38 ******************************************************************************/
39 typedef UINT32 btc_sm_state_t;
40 typedef UINT32 btc_sm_event_t;
41 typedef void *btc_sm_handle_t;
42 typedef BOOLEAN (* btc_sm_handler_t)(btc_sm_event_t event, void *data);
43 
44 
45 /*****************************************************************************
46 **  Functions
47 **
48 **  NOTE: THESE APIs SHOULD BE INVOKED ONLY IN THE BTC CONTEXT
49 **
50 ******************************************************************************/
51 
52 /*****************************************************************************
53 **
54 ** Function     btc_sm_init
55 **
56 ** Description  Initializes the state machine with the state handlers
57 **              The caller should ensure that the table and the corresponding
58 **              states match. The location that 'p_handlers' points to shall
59 **              be available until the btc_sm_shutdown API is invoked.
60 **
61 ** Returns      Returns a pointer to the initialized state machine handle.
62 **
63 ******************************************************************************/
64 btc_sm_handle_t btc_sm_init(const btc_sm_handler_t *p_handlers,
65                             btc_sm_state_t initial_state);
66 
67 /*****************************************************************************
68 **
69 ** Function     btc_sm_shutdown
70 **
71 ** Description  Tears down the state machine
72 **
73 ** Returns      None
74 **
75 ******************************************************************************/
76 void btc_sm_shutdown(btc_sm_handle_t handle);
77 
78 /*****************************************************************************
79 **
80 ** Function     btc_sm_get_state
81 **
82 ** Description  Fetches the current state of the state machine
83 **
84 ** Returns      Current state
85 **
86 ******************************************************************************/
87 btc_sm_state_t btc_sm_get_state(btc_sm_handle_t handle);
88 
89 /*****************************************************************************
90 **
91 ** Function     btc_sm_dispatch
92 **
93 ** Description  Dispatches the 'event' along with 'data' to the current state handler
94 **
95 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
96 **
97 ******************************************************************************/
98 bt_status_t btc_sm_dispatch(btc_sm_handle_t handle, btc_sm_event_t event,
99                             void *data);
100 
101 /*****************************************************************************
102 **
103 ** Function     btc_sm_change_state
104 **
105 ** Description  Make a transition to the new 'state'. The 'BTC_SM_EXIT_EVT'
106 **              shall be invoked before exiting the current state. The
107 **              'BTC_SM_ENTER_EVT' shall be invoked before entering the new state
108 **
109 **
110 ** Returns      Returns BT_STATUS_OK on success, BT_STATUS_FAIL otherwise
111 **
112 ******************************************************************************/
113 bt_status_t btc_sm_change_state(btc_sm_handle_t handle, btc_sm_state_t state);
114 
115 #endif /* __BTC_SM_H__ */
116