Statistics
| Branch: | Tag: | Revision:

amiro-blt / Target / Source / AMiRo / amiroblt.h @ 470d0567

History | View | Annotate | Download (13.4 KB)

1
/**
2
 * @file    interfaces.h
3
 * @brief   Interfaces to access and interpret information of the bootloader by an operating system.
4
 *
5
 * @addtogroup  AMiRo-BLT
6
 * @details     Data structures and constants to interfere with the bootloader form an operating system.
7
 * @{
8
 */
9

    
10
#ifndef _AMIROBLT_H_
11
#define _AMIROBLT_H_
12

    
13
#include <stdint.h>
14

    
15
/*============================================================================*/
16
/**
17
 * @defgroup  AMiRo-BLT-IF AMiRo Bootloader Interface
18
 * @details   This interface can be used to interface the AMiRo bootloader from an operating system.
19
 *
20
 * @{
21
 */
22
/*============================================================================*/
23

    
24
/*============================================================================*/
25
/**
26
 * @name    Callback Table
27
 * @details The callback table is a static struct, located in the MCUs flash memory (ROM) with offset @ref BL_CALLBACK_TABLE_OFFSET .
28
 *          It contains version information and a bunch of callback function pointers.
29
 */
30
///@{
31

    
32
/**
33
 * @brief   The offset from the flash memory base address to where the @ref blCallbackTable_t struct is stored.
34
 * @note    This offset must correspond with the @p _callback_table section in file @p memory.x of the bootloader.
35
 */
36
#define BL_CALLBACK_TABLE_OFFSET                  0x000001C0u
37

    
38
/**
39
 * @brief   The memory address where the @ref blCallbackTable_t struct is located in flash memory.
40
 * @note    This adress must correspond with the @p _callback_table section in file @p memory.x of the bootloader.
41
 * @deprecated  The @ref BL_CALLBACK_TABLE_OFFSET macro must be used for new software.
42
 */
43
#define BL_CALLBACK_TABLE_ADDRESS                 ((blCallbackTable_t*)(0x08000000u + BL_CALLBACK_TABLE_OFFSET))
44

    
45
/**
46
 * @brief   The major version number of the bootloader.
47
 */
48
#define BL_VERSION_MAJOR                          1
49

    
50
/**
51
 * @brief   The minor version number of the bootloader.
52
 */
53
#define BL_VERSION_MINOR                          0
54

    
55
/**
56
 * @brief   The major version number of the implemented SSSP (Startup & Shutdown Synchronization Protocol).
57
 */
58
#define SSSP_VERSION_MAJOR                        1
59

    
60
/**
61
 * @brief   The minor version number of the implemented SSSP (Startup & Shutdown Synchronization Protocol).
62
 */
63
#define SSSP_VERSION_MINOR                        1
64

    
65
/**
66
 * @brief   A struct to define a version in a generic way.
67
 */
68
struct blVersion_t {
69
  const uint8_t identifier;   /**< The identifier can be used if the version can be ambiguous.  */
70
  const uint8_t major;        /**< Major version number.                                        */
71
  const uint8_t minor;        /**< Minor version number.                                        */
72
  const uint8_t patch;        /**< Patch level number.                                          */
73
} __attribute__((packed));
74

    
75
/**
76
 * @brief   Synonym for simplified access.
77
 */
78
typedef struct blVersion_t blVersion_t;
79

    
80
/**
81
 * @brief   An enum that defines possible values for the 'identifier' member of the @p blVersion_t struct.
82
 * @note    The values must be in (unsigned) 8 bit integer range.
83
 */
84
enum blVersionIdentifier_t {
85
  BL_VERSION_ID_UNKNOWN                   = 0x00u,  /**< Unknown identifier                                       */
86
  BL_VERSION_ID_NA                        = 0xFFu,  /**< Identifier not applicable                                */
87
  BL_VERSION_ID_AMiRoBLT_PreAlpha         = 0x01u,  /**< AMiRo-BLT pre-alpha identifier.                          */
88
  BL_VERSION_ID_AMiRoBLT_Alpha            = 0x02u,  /**< AMiRo-BLT alpha version identifier.                      */
89
  BL_VERSION_ID_AMiRoBLT_Beta             = 0x03u,  /**< AMiRo-BLT beta version identifier.                       */
90
  BL_VERSION_ID_AMiRoBLT_ReleaseCandidate = 0x04u,  /**< AMiRo-BLT release candidate (RC) identifier.             */
91
  BL_VERSION_ID_AMiRoBLT_Release          = 0x05u,  /**< AMiRo-BLT release version identifier.                    */
92
  BL_VERSION_ID_SSSP                      = 0x01u,  /**< Startup & Shutdown Synchronization Protocol identifier.  */
93
  BL_VERSION_ID_GCC                       = 0x01u,  /**< Gnu Compiler Collection identifier.                      */
94
};
95

    
96
/**
97
 * @brief   A magic number to detect whether the callback table exists.
98
 * @details The magic number can be interpreted as four character string "A-BL".
99
 *          The according hexadecimal values are 0x41, 0x2D, 0x42, and 0x4C.
100
 *          The according 32 bit integer is 0x412D424C.
101
 */
102
#define BL_MAGIC_NUMBER                           ((uint32_t)(('A'<<24) | ('-'<<16) | ('B'<<8) | ('L'<<0)))
103

    
104
/**
105
 * @brief   This struct contains information about the bootloader version and pointers to several callback function.
106
 *          It is located at the constant address @ref BL_CALLBACK_TABLE_OFFSET in the flash memory.
107
 * @note    Sicne the actual implementations of the callback functions are optional, the pointers must be checked not to be @p NULL before use!
108
 */
109
struct blCallbackTable_t {
110
  const uint32_t magicNumber;                     /**< A magic number that can be used for sanity checks. @sa BL_MAGIC_NUMBER.            */
111
  const blVersion_t vBootloader;                  /**< Version information about the bootloader.                                          */
112
  const blVersion_t vSSSP;                        /**< Version information about the Startup & Shutdown Synchronization Protocol (SSSP).  */
113
  const blVersion_t vCompiler;                    /**< Version information about the used compiler.                                       */
114
  /**
115
   * @brief   Callback function pointer to enter hibernate mode.
116
   * @details In hibernate mode, the system enters maximum power-saving mode, but will wake up periodically in order to read some sensors.
117
   */
118
  void (*const cbShutdownHibernate)(void);
119
  /**
120
   * @brief   Callback function pointer to enter deepsleep mode.
121
   * @details In deepsleep mode, the system enters maximum power-saving mode, but basic sensors (e.g. charging plug) can wake the system.
122
   */
123
  void (*const cbShutdownDeepsleep)(void);
124
  /**
125
   * @brief   Callback function pointer to enter transportation mode.
126
   * @details In transportation mode, the system enters maximum power-saving mode and all wakeup signals are deactivated.
127
   *          Thus, the only way to reactivate the system will be a hard reset.
128
   */
129
  void (*const cbShutdownTransportation)(void);   /**< Callback function pointer to enter transportation mode. */
130
  /**
131
   * @brief   Callback function pointer to restart the system.
132
   */
133
  void (*const cbShutdownRestart)(void);
134
  /**
135
   * @brief   Callback function pointer to handle a shutdown request from another module.
136
   * @details Depending on the result of the disambiguation procedure, the module will enter the requested low-power mode.
137
   */
138
  void (*const cbHandleShutdownRequest)(void);
139
  void (*const cb5)(void);                        /**< Reserved but currently unused callback function pointer. */
140
  void (*const cb6)(void);                        /**< Reserved but currently unused callback function pointer. */
141
  void (*const cb7)(void);                        /**< Reserved but currently unused callback function pointer. */
142
  void (*const cb8)(void);                        /**< Reserved but currently unused callback function pointer. */
143
  void (*const cb9)(void);                        /**< Reserved but currently unused callback function pointer. */
144
  void (*const cb10)(void);                       /**< Reserved but currently unused callback function pointer. */
145
  void (*const cb11)(void);                       /**< Reserved but currently unused callback function pointer. */
146
} __attribute__((__packed__));
147

    
148
/**
149
 * @brief Synonym for simplified access.
150
 */
151
typedef struct blCallbackTable_t blCallbackTable_t;
152

    
153
///@}
154
/*============================================================================*/
155

    
156
/*============================================================================*/
157
/**
158
 * @name    Backup Register
159
 * @details For the STM32F4 MCU (PowerManagement), the backup register contains additional information about the last shutdown and wakeup of the system.
160
 */
161
///@{
162

    
163
/**
164
 * @brief   Number of the RTC backup register in which some persistent information is stored.
165
 * @note    In the RTC section of the STM32F4 reference manual, the RTC backup registers are named @p RTC_BKPxR, where x is the register number.
166
 */
167
#define BL_RTC_BACKUP_REG                         0
168

    
169
/**
170
 * @brief   This union is used for interpretation of the content of the backup register.
171
 */
172
union blBackupRegister_t {
173
  /**
174
   * @brief The raw data of the register.
175
   */
176
  uint32_t raw;
177

    
178
  /**
179
   * @brief A struct to interpret the content of the register.
180
   */
181
  struct {
182
    /**
183
     * @brief The primary reason for the last system shutdown.
184
     * @note  The content of this member is enum-like.
185
     * @sa    BL_SHUTDOWN_PRI_RSN_UNKNOWN, BL_SHUTDOWN_PRI_RSN_HIBERNATE, BL_SHUTDOWN_PRI_RSN_DEEPSLEEP, BL_SHUTDOWN_PRI_RSN_TRANSPORT, BL_SHUTDOWN_PRI_RSN_RESTART
186
     */
187
    uint8_t shutdown_pri_reason;
188

    
189
    /**
190
     * @brief The secondary reason for the last system shutdown.
191
     * @note  The content of this member is enum-like.
192
     * @sa    BL_SHUTDOWN_SEC_RSN_UNKNOWN
193
     */
194
    uint8_t shutdown_sec_reason;
195

    
196
    /**
197
     * @brief The primary reason for the last system wakeup.
198
     * @note  The content of this member is bitmask-like.
199
     * @sa    BL_WAKEUP_PRI_RSN_UNKNOWN, BL_WAKEUP_PRI_RSN_LPWRRST, BL_WAKEUP_PRI_RSN_WWDGRST, BL_WAKEUP_PRI_RSN_IWDGRST, BL_WAKEUP_PRI_RSN_SFTRST, BL_WAKEUP_PRI_RSN_PORRST, BL_WAKEUP_PRI_RSN_PINRST, BL_WAKEUP_PRI_RSN_BORRST, BL_WAKEUP_PRI_RSN_WKUP
200
     */
201
    uint8_t wakeup_pri_reason;
202

    
203
    /**
204
     * @brief The secondary reason for the last system wakeup.
205
     * @note  The content of this member is bitmask-like.
206
     * @sa    BL_WAKEUP_SEC_RSN_UNKNOWN, BL_WAKEUP_SEC_RSN_UART, BL_WAKEUP_SEC_RSN_PWRPLUG, BL_WAKEUP_SEC_RSN_VSYSHIGH, BL_WAKEUP_SEC_RSN_VSYSLOW, BL_WAKEUP_SEC_RSN_TOUCH, BL_WAKEUP_SEC_RSN_ACCEL, BL_WAKEUP_SEC_RSN_RSVD
207
     */
208
    uint8_t wakeup_sec_reason;
209
  } __attribute__((__packed__));
210
};
211

    
212
/**
213
 * @brief   Synonym for simplified access.
214
 */
215
typedef union blBackupRegister_t blBackupRegister_t;
216

    
217
/**
218
 * @brief   An enum defining identifiers for possible reasons for system shutdown.
219
 * @note    The values must be in (unsigned) 8 bit integer range.
220
 */
221
enum blShutdownReason_t {
222
  /**
223
   * @brief The reason was not set or the register was reset.
224
   */
225
  BL_SHUTDOWN_PRI_RSN_UNKNOWN   = 0x00u,
226

    
227
  /**
228
   * @brief The system was shut down to enter hibernate mode.
229
   */
230
  BL_SHUTDOWN_PRI_RSN_HIBERNATE = 0x01u,
231

    
232
  /**
233
   * @brief The system was shut down to enter deepsleep mode.
234
   */
235
  BL_SHUTDOWN_PRI_RSN_DEEPSLEEP = 0x02u,
236

    
237
  /**
238
   * @brief The system was shut down to enter transportation mode.
239
   */
240
  BL_SHUTDOWN_PRI_RSN_TRANSPORT = 0x03u,
241

    
242
  /**
243
   * @brief The system was shut down to restart.
244
   */
245
  BL_SHUTDOWN_PRI_RSN_RESTART   = 0x04u,
246

    
247
  /**
248
   * @brief   The default shutdown mode.
249
   * @details This mode is used, if the shutdown sequence was triggered by another module than the PowerManagement.
250
   */
251
  BL_SHUTDOWN_PRI_RSN_DEFAULT   = BL_SHUTDOWN_PRI_RSN_DEEPSLEEP,
252

    
253
  /**
254
   * @brief The reason was not set or the regsiter was reset.
255
   */
256
  BL_SHUTDOWN_SEC_RSN_UNKNOWN   = 0x00u,
257
};
258

    
259
/**
260
 * @brief   An enum defining identifiers for possible reasons for system wakeup.
261
 * @note    The values must be in (unsigned) 8 bit integer range.
262
 */
263
enum blWakeupReason_t {
264
  /**
265
   * @brief The reason could not be determined.
266
   */
267
  BL_WAKEUP_PRI_RSN_UNKNOWN    = 0x00u,
268

    
269
  /**
270
   * @brief The system was reset because of the low-power management configuration.
271
   */
272
  BL_WAKEUP_PRI_RSN_LPWRRST    = 0x01u,
273

    
274
  /**
275
   * @brief The system was woken by the window watchdog.
276
   */
277
  BL_WAKEUP_PRI_RSN_WWDGRST    = 0x02u,
278

    
279
  /**
280
   * @brief The system was woken by the independant watchdog.
281
   */
282
  BL_WAKEUP_PRI_RSN_IWDGRST    = 0x04u,
283

    
284
  /**
285
   * @brief The system was reset by software.
286
   */
287
  BL_WAKEUP_PRI_RSN_SFTRST     = 0x08u,
288

    
289
  /**
290
   * @brief The system was woken by a power-on/power-down reset.
291
   */
292
  BL_WAKEUP_PRI_RSN_PORRST     = 0x10u,
293

    
294
  /**
295
   * @brief The system was reset via the NRST pin.
296
   */
297
  BL_WAKEUP_PRI_RSN_PINRST     = 0x20u,
298

    
299
  /**
300
   * @brief The system was woken by a power-on/power-down, or a brownout reset.
301
   */
302
  BL_WAKEUP_PRI_RSN_BORRST     = 0x40u,
303

    
304
  /**
305
   * @brief The system was woken via the WKUP pin.
306
   */
307
  BL_WAKEUP_PRI_RSN_WKUP       = 0x80u,
308

    
309
  /**
310
   * @brief The reason could not be determined.
311
   */
312
  BL_WAKEUP_SEC_RSN_UNKNOWN    = 0x00u,
313

    
314
  /**
315
   * @brief The WKUP pin was triggered by the UART signal.
316
   */
317
  BL_WAKEUP_SEC_RSN_UART       = 0x01u,
318

    
319
  /**
320
   * @brief The WKUP pin was triggered by plugging in a power plug.
321
   */
322
  BL_WAKEUP_SEC_RSN_PWRPLUG    = 0x02u,
323

    
324
  /**
325
   * @brief The internal ADC detected a system voltage higher than the configured threshold.
326
   * @note  Usually the threshold is set to 9V.
327
   */
328
  BL_WAKEUP_SEC_RSN_VSYSHIGH   = 0x04u,
329

    
330
  /**
331
   * @brief The internal ADC detected a system voltage lower than the configured threshold.
332
   */
333
  BL_WAKEUP_SEC_RSN_VSYSLOW    = 0x08u,
334

    
335
  /**
336
   * @brief The WKUP pin was triggered by an interrupt from the touch sensors.
337
   */
338
  BL_WAKEUP_SEC_RSN_TOUCH      = 0x10u,
339

    
340
  /**
341
   * @brief The WKUP pin was triggered by an interrupt from the accelerometer.
342
   */
343
  BL_WAKEUP_SEC_RSN_ACCEL      = 0x20u,
344

    
345
  /**
346
   * @brief Reserved value that must not be used right now, but might become valid in a future version.
347
   */
348
  BL_WAKEUP_SEC_RSN_RSVD       = 0xC0u,
349
};
350

    
351
///@}
352

    
353
/** @} */
354

    
355
#endif // _AMIROBLT_H_
356

    
357
/** @} */