Statistics
| Branch: | Tag: | Revision:

amiro-os / core / inc / aos_sssp.h @ a93a1019

History | View | Annotate | Download (17 KB)

1
/*
2
AMiRo-OS is an operating system designed for the Autonomous Mini Robot (AMiRo) platform.
3
Copyright (C) 2016..2020  Thomas Schöpping et al.
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 as published by
7
the Free Software Foundation, either version 3 of the License, or
8
(at your option) any later version.
9

10
This program is distributed in the hope that it will be useful,
11
but WITHOUT ANY WARRANTY; without even the implied warranty of
12
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13
GNU General Public License for more details.
14

15
You should have received a copy of the GNU General Public License
16
along with this program.  If not, see <http://www.gnu.org/licenses/>.
17
*/
18

    
19
/**
20
 * @file    aos_sssp.h
21
 * @brief   SSSP related macros, structures and functions.
22
 *
23
 * @addtogroup aos_sssp
24
 * @{
25
 */
26

    
27
#ifndef AMIROOS_SSSP_H
28
#define AMIROOS_SSSP_H
29

    
30
#include <amiroos.h>
31

    
32
#if (AMIROOS_CFG_SSSP_ENABLE == true) || defined(__DOXYGEN__)
33

    
34
/******************************************************************************/
35
/* CONSTANTS                                                                  */
36
/******************************************************************************/
37

    
38
/**
39
 * @brief   Major version of the implemented SSSP.
40
 */
41
#define AOS_SSSP_VERSION_MAJOR                  1
42

    
43
/**
44
 * @brief   Minor version of the implemented SSSP.
45
 */
46
#define AOS_SSSP_VERSION_MINOR                  4
47

    
48
/**
49
 * @brief   Time of delays in microseconds.
50
 */
51
#define AOS_SSSP_DELAY                          AMIROOS_CFG_SSSP_SIGNALDELAY
52

    
53
/**
54
 * @brief   Timeout delay in microseconds according to SSSP.
55
 * @details SSSP 1.x defines timeouts to be ten times longer than the signal delay time.
56
 */
57
#define AOS_SSSP_TIMEOUT                        (10 * AOS_SSSP_DELAY)
58

    
59
/**
60
 * @brief   Value to indicate an invalid module ID.
61
 */
62
#define AOS_SSSP_MODULEID_INVALID               ((aos_ssspmoduleid_t)0)
63

    
64
/**
65
 * @brief   Value for broadcasting, adressing all modules.
66
 * @note    This value is identical to @p AOS_SSSP_MODULEID_INVALID since in the case that no module IDs were applied, addressing of specific modules is not possible, thus every communication would be a broadcast.
67
 */
68
#define AOS_SSSP_MODULEID_BROADCAST             ((aos_ssspmoduleid_t)0)
69

    
70
/******************************************************************************/
71
/* SETTINGS                                                                   */
72
/******************************************************************************/
73

    
74
/******************************************************************************/
75
/* CHECKS                                                                     */
76
/******************************************************************************/
77

    
78
#if (!(AMIROOS_CFG_SSSP_MODULEIDWIDTH == 8) &&                                \
79
   !(AMIROOS_CFG_SSSP_MODULEIDWIDTH == 16)  &&                                \
80
   !(AMIROOS_CFG_SSSP_MODULEIDWIDTH == 32)  &&                                \
81
   !(AMIROOS_CFG_SSSP_MODULEIDWIDTH == 64))
82
  #error "AMIROOS_CFG_SSSP_MODULEIDWIDTH set to an invalid value."
83
#endif
84

    
85
/******************************************************************************/
86
/* DATA STRUCTURES AND TYPES                                                  */
87
/******************************************************************************/
88

    
89
/**
90
 * @brief   Enumeration of the several stages of SSSP.
91
 */
92
typedef enum {
93
  AOS_SSSP_STAGE_UNDEFINED                    = 0x00000000, /**< Identifier of yet undefined stage variable.                                          */
94
  AOS_SSSP_STAGE_STARTUP                      = 0x10000000, /**< Identifier of SSSP startup phase.                                                    */
95
  AOS_SSSP_STAGE_STARTUP_1                    = 0x11000000, /**< Identifier of SSSP startup phase stage 1.                                            */
96
  AOS_SSSP_STAGE_STARTUP_1_1                  = 0x11100000, /**< Identifier of SSSP startup phase stage 1-1.                                          */
97
  AOS_SSSP_STAGE_STARTUP_1_2                  = 0x11200000, /**< Identifier of SSSP startup phase stage 1-2.                                          */
98
  AOS_SSSP_STAGE_STARTUP_1_3                  = 0x11300000, /**< Identifier of SSSP startup phase stage 1-3.                                          */
99
  AOS_SSSP_STAGE_STARTUP_2                    = 0x12000000, /**< Identifier of SSSP startup phase stage 2.                                            */
100
  AOS_SSSP_STAGE_STARTUP_2_1                  = 0x12100000, /**< Identifier of SSSP startup phase stage 2-1.                                          */
101
  AOS_SSSP_STAGE_STARTUP_2_2                  = 0x12200000, /**< Identifier of SSSP startup phase stage 2-2.                                          */
102
  AOS_SSSP_STAGE_STARTUP_3                    = 0x13000000, /**< Identifier of SSSP startup phase stage 3.                                            */
103
  AOS_SSSP_STAGE_STARTUP_3_1                  = 0x13100000, /**< Identifier of SSSP startup phase stage 3-1.                                          */
104
  AOS_SSSP_STAGE_STARTUP_3_1_BROADCASTINIT    = 0x13110001, /**< Identifier of SSSP startup phase stage 3-1 broadcast initialization (master only).   */
105
  AOS_SSSP_STAGE_STARTUP_3_1_WAITFORINIT      = 0x13110002, /**< Identifier of SSSP startup phase stage 3-1 waiting for broadcast (non-master only).  */
106
  AOS_SSSP_STAGE_STARTUP_3_2                  = 0x13200000, /**< Identifier of SSSP startup phase stage 3-2.                                          */
107
  AOS_SSSP_STAGE_STARTUP_3_3                  = 0x13300000, /**< Identifier of SSSP startup phase stage 3-3.                                          */
108
  AOS_SSSP_STAGE_STARTUP_3_3_WAIT4EVENT       = 0x13310000, /**< Identifier of SSSP startup phase stage 3-3 waiting for an event to occurr.           */
109
  AOS_SSSP_STAGE_STARTUP_3_3_BROADCASTID      = 0x13320000, /**< Identifier of SSSP startup phase stage 3-3 broadcasting identifier.                  */
110
  AOS_SSSP_STAGE_STARTUP_3_4                  = 0x13400000, /**< Identifier of SSSP startup phase stage 3-4.                                          */
111
  AOS_SSSP_STAGE_STARTUP_3_4_COMPLETION       = 0x13410000, /**< Identifier of SSSP startup phase stage 3-4 completion.                               */
112
  AOS_SSSP_STAGE_STARTUP_3_4_ABORTION         = 0x13420000, /**< Identifier of SSSP startup phase stage 3-4 abortion.                                 */
113
  AOS_SSSP_STAGE_STARTUP_3_4_ABORTION_INIT    = 0x13421000, /**< Identifier of SSSP startup phase stage 3-4 abortion initialization.                  */
114
  AOS_SSSP_STAGE_STARTUP_3_4_ABORTION_SYNC    = 0x13422000, /**< Identifier of SSSP startup phase stage 3-4 abortion synchronization.                 */
115
  AOS_SSSP_STAGE_OPERATION                    = 0x20000000, /**< Identifier of SSSP operation phase.                                                  */
116
  AOS_SSSP_STAGE_SHUTDOWN                     = 0x30000000, /**< Identifier of SSSP shutdown phase.                                                   */
117
  AOS_SSSP_STAGE_SHUTDOWN_1                   = 0x31000000, /**< Identifier of SSSP shutdown phase stage 1.                                           */
118
  AOS_SSSP_STAGE_SHUTDOWN_1_1                 = 0x31100000, /**< Identifier of SSSP shutdown phase stage 1-1.                                         */
119
  AOS_SSSP_STAGE_SHUTDOWN_1_2                 = 0x31200000, /**< Identifier of SSSP shutdown phase stage 1-2.                                         */
120
  AOS_SSSP_STAGE_SHUTDOWN_1_3                 = 0x31300000, /**< Identifier of SSSP shutdown phase stage 1-3.                                         */
121
  AOS_SSSP_STAGE_SHUTDOWN_2                   = 0x32000000, /**< Identifier of SSSP shutdown phase stage 2.                                           */
122
  AOS_SSSP_STAGE_SHUTDOWN_2_1                 = 0x32100000, /**< Identifier of SSSP shutdown phase stage 2-1.                                         */
123
  AOS_SSSP_STAGE_SHUTDOWN_2_2                 = 0x32200000, /**< Identifier of SSSP shutdown phase stage 2-2.                                         */
124
  AOS_SSSP_STAGE_SHUTDOWN_2_3                 = 0x32300000, /**< Identifier of SSSP shutdown phase stage 2-3.                                         */
125
} aos_ssspstage_t;
126

    
127
/**
128
 * @brief   Type to represent module IDs.
129
 */
130
#if (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 8)
131
typedef uint8_t aos_ssspmoduleid_t;
132
#elif (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 16) || defined(__DOXYGEN__)
133
typedef uint16_t aos_ssspmoduleid_t;
134
#elif (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 32)
135
typedef uint32_t aos_ssspmoduleid_t;
136
#elif (AMIROOS_CFG_SSSP_MODULEIDWIDTH == 64)
137
typedef uint64_t aos_ssspmoduleid_t;
138
#endif
139

    
140
/**
141
 * @brief   Data structure holding module-wide SSSP information.
142
 */
143
typedef struct {
144
  /**
145
   * @brief   Current execution stage of SSSP.
146
   */
147
  aos_ssspstage_t stage;
148

    
149
  /**
150
   * @brief   Module identifier.
151
   * @details A value of @p AOS_SSSP_MODULEID_INVALID indicates an uninitialized ID.
152
   */
153
  aos_ssspmoduleid_t moduleId;
154

    
155
} aos_ssspdata_t;
156

    
157
#if (AMIROOS_CFG_SSSP_MSI == true) || defined(__DOXYGEN__)
158

    
159
/**
160
 * @brief   Type to qualify attempts to transmitt/receive mesages via BCB.
161
 */
162
typedef enum {
163
  AOS_SSSP_BCB_SUCCESS,     /**< BCB access was sucessfull. */
164
  AOS_SSSP_BCB_ERROR,       /**< BCB access failed or no message was available. */
165
  AOS_SSSP_BCB_INVALIDMSG,  /**< Invalid BCB message detected. */
166
} aos_ssspbcbstatus_t;
167

    
168
/**
169
 * @brief   Data structure to be transmitted via BCB during module stack initialization (MSI).
170
 */
171
typedef struct {
172

    
173
  /**
174
   * @brief   Type of the message.
175
   */
176
  uint8_t type;
177

    
178
  /**
179
   * @brief   Message payload.
180
   * @details Payload depends on message type.
181
   */
182
  union {
183
    /**
184
     * @brief   Transmitted ID.
185
     * @details This field is only used for @p SSSP_MSI_ID type messages.
186
     */
187
    aos_ssspmoduleid_t id;
188
  } payload PACKED_VAR;
189

    
190
} PACKED_VAR aos_ssspbcbmessage_t;
191

    
192
/*
193
 * Available BCB messages:
194
 */
195
#define AOS_SSSP_BCBMESSAGE_INVALID             0   /**< Invalid BCB message.         */
196
#define AOS_SSSP_BCBMESSAGE_MSIINIT             1   /**< MSI initialization message.  */
197
#define AOS_SSSP_BCBMESSAGE_MSIID               2   /**< MSI identifier message.      */
198
#define AOS_SSSP_BCBMESSAGE_MSIABORT            3   /**< MSI abort message.           */
199

    
200
/**
201
 * @brief   Data structure required for the module stack initialization (MSI) phase.
202
 */
203
typedef struct {
204

    
205
  /**
206
   * @brief   Timout related data.
207
   */
208
  struct {
209
    /**
210
     * @brief   Timer to trigger potential timeouts.
211
     * @details This timer must not be an AMiRo-OS timer, since delays occurr before system is initialized.
212
     */
213
    virtual_timer_t timer;
214

    
215
    /**
216
     * @brief   Event source to be triggered on timeout.
217
     */
218
    event_source_t eventsource;
219

    
220
    /**
221
     * @brief   Event listener to inform the MSI thread about timeout events.
222
     */
223
    event_listener_t eventlistener;
224
  } timeout;
225

    
226
  /**
227
   * @brief   Signal related data.
228
   */
229
  struct {
230
    /**
231
     * @brief   Pointer to an existing event listener, which informs about GPIO signal events.
232
     */
233
    event_listener_t* eventlistener;
234
  } signals;
235

    
236
  /**
237
   * @brief   BCB related data.
238
   */
239
  struct {
240
    /**
241
     * @brief   Message object.
242
     */
243
    aos_ssspbcbmessage_t message;
244

    
245
    /**
246
     * @brief   Buffer for (de)serialization BCB messages.
247
     */
248
    uint8_t buffer[sizeof(aos_ssspbcbmessage_t)];
249

    
250
    /**
251
     * @brief   Return status of last BCB access.
252
     */
253
    aos_ssspbcbstatus_t status;
254

    
255
    /**
256
     * @brief   The most recently received identifier.
257
     */
258
    aos_ssspmoduleid_t lastid;
259
  } bcb;
260

    
261
} aos_ssspmsidata_t;
262

    
263
#endif /* (AMIROOS_CFG_SSSP_MSI == true) */
264

    
265
/******************************************************************************/
266
/* MACROS                                                                     */
267
/******************************************************************************/
268

    
269
/******************************************************************************/
270
/* EXTERN DECLARATIONS                                                        */
271
/******************************************************************************/
272

    
273
#if defined(__cplusplus)
274
extern "C" {
275
#endif /* defined(__cplusplus) */
276

    
277
  /*
278
   * module specific interface functions
279
   */
280
#if !defined(moduleSsspSignalPD) || defined(__DOXYGEN__)
281
  /**
282
   * @brief   Retrieve the control GPIO object for the PD signal.
283
   * @return  Pounter to the control GPIO object.
284
   */
285
  apalControlGpio_t* moduleSsspSignalPD(void);
286
#endif /* !defined(moduleSsspSignalPD) */
287
#if !defined(moduleSsspEventflagPD) || defined(__DOXYGEN__)
288
  /**
289
   * @brief   Retrieve the GPIO event flag set by a PD signal edge.
290
   * @return  Eventflag set on PD events.
291
   */
292
  eventflags_t moduleSsspEventflagPD(void);
293
#endif /* !defined(moduleSsspEventflagPD) */
294

    
295
#if !defined(moduleSsspSignalS) || defined(__DOXYGEN__)
296
  /**
297
   * @brief   Retrieve the control GPIO object for the S signal.
298
   * @return  Pounter to the control GPIO object.
299
   */
300
  apalControlGpio_t* moduleSsspSignalS(void);
301
#endif /* !defined(moduleSsspSignalS) */
302
#if !defined(moduleSsspEventflagS) || defined(__DOXYGEN__)
303
  /**
304
   * @brief   Retrieve the GPIO event flag set by a S signal edge.
305
   * @return  Eventflag set on S events.
306
   */
307
  eventflags_t moduleSsspEventflagS(void);
308
#endif /* !defined(moduleSsspEventflagS) */
309

    
310
#if (AMIROOS_CFG_SSSP_MSI == true) || defined(__DOXYGEN__)
311

    
312
#if (AMIROOS_CFG_SSSP_STACK_START != true) || defined(__DOXYGEN__)
313
#if !defined(moduleSsspSignalDN) || defined(__DOXYGEN__)
314
  /**
315
   * @brief   Retrieve the control GPIO object for the DN signal.
316
   * @return  Pounter to the control GPIO object.
317
   */
318
  apalControlGpio_t* moduleSsspSignalDN(void);
319
#endif /* !defined(moduleSsspSignalDN) */
320
#if !defined(moduleSsspEventflagDN) || defined(__DOXYGEN__)
321
  /**
322
   * @brief   Retrieve the GPIO event flag set by a DN signal edge.
323
   * @return  Eventflag set on DN events.
324
   */
325
  eventflags_t moduleSsspEventflagDN(void);
326
#endif /* !defined(moduleSsspEventflagDN) */
327
#endif /* (AMIROOS_CFG_SSSP_STACK_START != true) */
328

    
329
#if (AMIROOS_CFG_SSSP_STACK_END != true) || defined(__DOXYGEN__)
330
#if !defined(moduleSsspSignalUP) || defined(__DOXYGEN__)
331
  /**
332
   * @brief   Retrieve the control GPIO object for the UP signal.
333
   * @return  Pounter to the control GPIO object.
334
   */
335
  apalControlGpio_t* moduleSsspSignalUP(void);
336
#endif /* !defined(moduleSsspSignalUP) */
337
#if !defined(moduleSsspEventflagUP) || defined(__DOXYGEN__)
338
  /**
339
   * @brief   Retrieve the GPIO event flag set by a UP signal edge.
340
   * @return  Eventflag set on UP events.
341
   */
342
  eventflags_t moduleSsspEventflagUP(void);
343
#endif /* !defined(moduleSsspEventflagUP) */
344
#endif /* (AMIROOS_CFG_SSSP_STACK_END != true) */
345

    
346
#if !defined(moduleSsspBcbTransmit) || defined(__DOXYGEN__)
347
  /**
348
   * @brief   Transmit data via BCB.
349
   *
350
   * @param[in] buffer    Pointer to a buffer, that holds the data to be sent.
351
   * @param[in] length    Length of the buffer in bytes.
352
   *
353
   * @return  Status value, indicating whether the operation was successful.
354
   */
355
  aos_ssspbcbstatus_t moduleSsspBcbTransmit(const uint8_t* buffer, size_t length);
356

    
357
  /**
358
   * @brief   Receive a message from BCB.
359
   * @note    If a message is received, which is not defined by SSSP, the data may be irreversibly discarded by this function.
360
   *
361
   * @param[out]    buffer  Pointer to a buffer to store the received data to.
362
   * @param[in]     length  Number of expected bytes to receive.
363
   *                        Obviously, the buffer must be large enough.
364
   *
365
   * @return  Status value, indicating whether the operation was successful.
366
   */
367
  aos_ssspbcbstatus_t moduleSsspBcbReceive(uint8_t* buffer, size_t length);
368
#endif /* !defined(moduleSsspBcbTransmit) */
369

    
370
#endif /* (AMIROOS_CFG_SSSP_MSI == true) */
371

    
372
  /*
373
   * API functions
374
   */
375
  void aosSsspInit(aos_timestamp_t* system_uptime);
376
  aos_status_t aosSsspProceed(event_listener_t* listener, eventmask_t mask, eventmask_t* received);
377
#if (AMIROOS_CFG_SSSP_MSI == true) || defined(__DOXYGEN__)
378
  void aosSsspMsiInit(aos_ssspmsidata_t* msidata, eventmask_t delayMask, eventmask_t timeoutMask, event_listener_t* gpioListener);
379
  void aosSsspMsi(aos_ssspmsidata_t* msidata, eventmask_t* received);
380
#endif /* (AMIROOS_CFG_SSSP_MSI == true) */
381
#if ((AMIROOS_CFG_SSSP_MASTER != true) && (AMIROOS_CFG_PROFILE == true)) || defined(__DOXYGEN__)
382
  float aosSsspGetSyncSkew(void);
383
#endif /* (AMIROOS_CFG_SSSP_MASTER != true) && (AMIROOS_CFG_PROFILE == true) */
384
  void aosSsspShutdownInit(bool active);
385
#if (AMIROOS_CFG_SSSP_SHUTDOWN == true) || defined(__DOXYGEN__)
386
  void aosSsspShutdownBroadcastIdentifier(unsigned int identifier);
387
  eventmask_t aosSsspShutdownWaitForIdentifierPulse(event_listener_t* gpiolistener, eventflags_t sflags, eventmask_t timermask, unsigned int* identifier);
388
#endif /* (AMIROOS_CFG_SSSP_SHUTDOWN == true) */
389

    
390
#if defined(__cplusplus)
391
}
392
#endif /* defined(__cplusplus) */
393

    
394
/******************************************************************************/
395
/* INLINE FUNCTIONS                                                           */
396
/******************************************************************************/
397

    
398
#endif /* (AMIROOS_CFG_SSSP_ENABLE == true) */
399

    
400
#endif /* AMIROOS_SSSP_H */
401

    
402
/** @} */