KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
clbstate.h
Go to the documentation of this file.
1 /*
2  * state.h
3  *
4  * Created on: 6 aug. 2013
5  * Author: vincentb
6  */
7 
8 #ifndef STATE_H_
9 #define STATE_H_
10 
11 /**
12  * @file
13  *
14  * @ingroup app
15  *
16  * The CLB stare module tracks is responsible for state management of the various sub-systems on
17  * the CLB. It also tracks the error of each subsystem.
18  * CLB State machine
19  *
20  *
21  * The following state machine is used:
22  * @verbatim
23  * +-----------+ +-----------+
24  * | | | |
25  * | Undefined |----Boot---->| Idle |
26  * | | | |
27  * +-----------+ +-----------+
28  * ^ |
29  * Reset Init
30  * | V
31  * +-----------+ +-----------+
32  * | |<-Configure--| |
33  * | Ready | | StandBy |
34  * | |----Quit---->| |
35  * +-----------+ +-----------+
36  * | ^
37  * Start Stop
38  * V |
39  * +-----------+ +-----------+
40  * | |<--Continue--| |
41  * | Running | | Paused |
42  * | |---Pause---->| |
43  * +-----------+ +-----------+
44  * @endverbatim
45  */
46 
47 #include <stdint.h>
48 #include <stdbool.h>
49 
50 #include "cfg_subsys.h"
51 #include "util/macro.h"
52 #include "kernel/err.h"
53 
54 #include "appcode.h"
55 
56 /**
57  * Various states
58  */
59 typedef enum
60 {
61  clbStateUndefined = 0, //!< Undefined state (prior to module init, should never be seen on shore)
62  clbStateIdle = 1, //!< Idle state
63  clbStateStandBy = 2, //!< StandBy state
64  clbStateReady = 3, //!< Ready state
65  clbStatePaused = 4, //!< Paused state
66  clbStateRunning = 5 //!< Running state
67 } ClbState;
68 
69 /**
70  * Contains a list of all the subsystems.
71  */
72 extern const char * const clbSubsystemNames[CLB_SUB_CNT];
73 
74 
75 /**
76  * Contains list of the state names
77  */
78 extern const char * const clbStateNames[6];
79 
80 /**
81  * Mapping from subsystem ID to index.
82  */
83 extern uint8_t clbSys2Idx[CLB_SUB_MAX];
84 
85 /**
86  * All state change events
87  */
88 typedef enum
89 {
90  clbEventNone = -1, //!< Internal use only
91  clbEventBoot = 0, //!< Undefined => Idle, for internal use only
92  clbEventInit = 1, //!< Idle => StandBy
93  clbEventConfigure = 2, //!< StandBy => Ready
94  clbEventStart = 3, //!< Ready => Running
95  clbEventPause = 4, //!< Running => Paused
96  clbEventContinue = 5, //!< Paused => Running
97  clbEventStop = 6, //!< Paused => StandBy
98  clbEventQuit = 7, //!< Ready => StandBy
99  clbEventReset = 8 //!< StandBy => Idle
100 } ClbEvent;
101 
102 /**
103  * All state change event names.
104  */
105 extern const char * const clbEventNames[9];
106 
107 #define E_CLBSTATE_STATECHANGE ( E_CLBSTATE + 0x01 ) ///< Invalid state change
108 #define E_CLBSTATE_STATECHANGE_DESCR "Invalid State Change"
109 
110 //! Indicates all subsystems. Can be used in clbStateGoto.
111 #define CLB_SUB_ALL 255
112 
113 //! Indicates that the subsystem is in transit to a new state.
114 #define CLB_STATUS_PENDING BIT(0)
115 #define CLB_STATUS_ERROR BIT(1)
116 
117 #define SUBS(IDX, ID, NAME) \
118  void _subs ## NAME ## ExecEvent (ClbEvent event);
119 
120 SUBSYSTEMS
121 
122 #undef SUBS
123 
124 #define SUBS(IDX, ID, NAME) \
125  bool _subs ## NAME ## Update (ClbState state, uint32_t time) __attribute__((weak));
126 
127 SUBSYSTEMS
128 
129 #undef SUBS
130 
131 
132 /**
133  * Initializes the state machine.
134  */
135 void clbStateInit();
136 
137 /**
138  * Request a subsystem to go to a certain state.
139  *
140  * @param idx The index, or CLB_SUB_ALL for all subsystems.
141  * @param event The event to execute
142  */
143 bool clbEvent(int idx, ClbEvent event);
144 
145 /**
146  * Executes an autonomous a sequence of events. Change updates are suppressed during this operation.
147  *
148  * @note The list of events is not copied, thus should always be present in RAM.
149  *
150  * @param events A list of events to execute
151  * @param seqLen The number of events.
152  */
153 void clbAutoEventSeq(ClbEvent * events, int seqLen);
154 
155 /**
156  * Invoked by the subsystem to indicate a state change has happened.
157  *
158  * @param idx The subsystem index which the state change was effected on
159  * @param event The event triggered
160  * @param status The current status
161  */
162 void _clbStateUpdate(int idx, ClbEvent event, uint8_t status);
163 
164 /**
165  * Returns the subsystem ID code for the provided index.
166  *
167  * @param idx Subsystem index.
168  *
169  * @return Subsystem ID code.
170  */
171 int clbSubId(int idx);
172 
173 /**
174  * Invoked by subsystem to indicate an error happened. The state will automatically be
175  * set to clbStateError.
176  *
177  * @param idx The subsystem index.
178  * @param error The error code
179  * @param message The message, if any
180  */
181 void _clbStateError(int idx, int error, const char * message, const char * name);
182 
183 /**
184  * Invoked by subsystem to indicate an error happened. The state will automatically be
185  * set to clbStateError. This copies the error from the error module and clears it.
186  *
187  * @param idx The subsystem index.
188  */
189 static inline void _clbStateModErr(int idx)
190 {
191  if (errHas()) {
193  errClear();
194  } else {
196  }
197 }
198 
199 
200 /**
201  * Retrieves the error of a subsystem (if any).
202  *
203  * @param idx Subsystem index
204  * @param code Pointer in which the code will be written
205  * @param message Pointer to which the message will be set
206  *
207  * @retval true Subsystem has an error
208  * @retval false Subsystem does not have an error
209  */
210 bool clbStateError(int idx, int * code, const char ** message);
211 
212 /**
213  * Returns the current clbSubState for the specified subsystem.
214  *
215  * @param idx The subsystem index to request the state of.
216  * @return The state of the subsystem
217  */
218 ClbState clbState(int idx);
219 
220 
221 /**
222  * Returns the current subsystem status.
223  *
224  * @param idx The subsystem index to request the state of.
225  * @return The status of the subsystem
226  */
227 uint8_t clbStatus(int idx);
228 
229 /**
230  * Clears the error state of the specific subsystem.
231  *
232  * @param idx The index of the subsystem.
233  */
234 void clbClearErrorState(int idx);
235 
236 /**
237  * Invoked the update method on each subsystem.
238  */
239 void clbUpdateSubsys();
240 
241 #endif /* STATE_H_ */
242 
bool errHas()
Returns whether there is an error pending.
Definition: err.c:52
Ready state.
Definition: clbstate.h:64
const char *const clbEventNames[9]
All state change event names.
Definition: clbstate.c:66
Idle state.
Definition: clbstate.h:62
Running =&gt; Paused.
Definition: clbstate.h:95
ClbEvent
All state change events.
Definition: clbstate.h:88
Application specific error codes.
static void _clbStateModErr(int idx)
Invoked by subsystem to indicate an error happened.
Definition: clbstate.h:189
ClbState clbState(int idx)
Returns the current clbSubState for the specified subsystem.
Definition: clbstate.c:92
Ready =&gt; Running.
Definition: clbstate.h:94
bool clbEvent(int idx, ClbEvent event)
Request a subsystem to go to a certain state.
Definition: clbstate.c:221
Paused =&gt; Running.
Definition: clbstate.h:96
const char * errGetDescr()
Returns the last error description, if any, else null.
Definition: err.c:57
Running state.
Definition: clbstate.h:66
void clbClearErrorState(int idx)
Clears the error state of the specific subsystem.
Definition: clbstate.c:241
void clbAutoEventSeq(ClbEvent *events, int seqLen)
Executes an autonomous a sequence of events.
Definition: clbstate.c:317
bool clbStateError(int idx, int *code, const char **message)
Retrieves the error of a subsystem (if any).
Definition: clbstate.c:106
uint8_t clbSys2Idx[6]
Mapping from subsystem ID to index.
Definition: clbstate.c:59
void clbUpdateSubsys()
Invoked the update method on each subsystem.
Definition: clbstate.c:282
Paused state.
Definition: clbstate.h:65
const char *const clbSubsystemNames[5]
Contains a list of all the subsystems.
Definition: clbstate.c:53
int clbSubId(int idx)
Returns the subsystem ID code for the provided index.
Definition: clbstate.c:99
ClbState
Various states.
Definition: clbstate.h:59
Manages the global system error.
Undefined =&gt; Idle, for internal use only.
Definition: clbstate.h:91
StandBy =&gt; Idle.
Definition: clbstate.h:99
void clbStateInit()
Initializes the state machine.
Definition: clbstate.c:327
StandBy state.
Definition: clbstate.h:63
const char *const clbStateNames[6]
Contains list of the state names.
Definition: clbstate.c:61
void errClear()
Clears the current error.
Definition: err.c:46
uint32_t errGet()
Returns the last error code, or null.
Definition: err.c:74
Ready =&gt; StandBy.
Definition: clbstate.h:98
Idle =&gt; StandBy.
Definition: clbstate.h:92
const char * errGetName()
Returns the last error cause name, or null.
Definition: err.c:65
#define ERROR(CODE,...)
Expands an error code to an error code with a description (if ERROR_W_DESCR is declared).
StandBy =&gt; Ready.
Definition: clbstate.h:93
Provides common macros.
Internal use only.
Definition: clbstate.h:90
Paused =&gt; StandBy.
Definition: clbstate.h:97
void _clbStateError(int idx, int error, const char *message, const char *name)
Invoked by subsystem to indicate an error happened.
Definition: clbstate.c:258
#define E_UNKNOWN
Generic error: Unknown error.
Definition: errorcode.h:97
void _clbStateUpdate(int idx, ClbEvent event, uint8_t status)
Invoked by the subsystem to indicate a state change has happened.
Definition: clbstate.c:204
Undefined state (prior to module init, should never be seen on shore)
Definition: clbstate.h:61
uint8_t clbStatus(int idx)
Returns the current subsystem status.
Definition: clbstate.c:118