Statistics
| Branch: | Tag: | Revision:

amiro-blt / Target / Source / AMiRo / interfaces.h @ 69661903

History | View | Annotate | Download (10.5 KB)

1 69661903 Thomas Schöpping
/**
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 BL_INTERFACES_H
11
#define BL_INTERFACES_H
12
13
#include <stdint.h>
14
15
/*===========================================================================*/
16
/**
17
 * @defgroup  AMiRo-BLT-IF 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 at address @ref BL_CALLBACK_TABLE_ADDRESS in the MCUs flash memory (ROM).
28
 *          It contains version information and a bunch of callback function pointers.
29
 */
30
///@{
31
32
/**
33
 * @brief   The memory address where the @ref BlCallbackTable struct is located in flash memory.
34
 * @note    This address must correspond with the @p _callback_table section in file @p memory.x of the bootloader.
35
 */
36
#define BL_CALLBACK_TABLE_ADDRESS                 (uint32_t)(0x08000000u + 0x01C0u)
37
38
/**
39
 * @brief   A magic number to detect whether the callback table exists.
40
 */
41
#define BL_MAGIC_NUMBER                           ((uint32_t)0xFF669900u)
42
43
/**
44
 * @brief   The major version number of the bootloader.
45
 */
46
#define BL_VERSION_MAJOR                          0
47
48
/**
49
 * @brief   The minor version number of the bootloader.
50
 */
51
#define BL_VERSION_MINOR                          3
52
53
/**
54
 * @brief   The major version number of the implemented SSSP (Startup & Synchronization Protocol).
55
 */
56
#define SSSP_VERSION_MAJOR                        1
57
58
/**
59
 * @brief   The minor version number of the implemented SSSP (Startup & Synchronization Protocol).
60
 */
61
#define SSSP_VERSION_MINOR                        1
62
63
/**
64
 * @brief   This struct contains information about the bootloader version and pointers to several callback function.
65
 *          It is located at the constant address @ref BL_CALLBACK_TABLE_ADDRESS in the flash memory.
66
 * @note    Sicne the actual implementations of the callback functions are optional, the pointers must be checked not to be @p NULL before use!
67
 */
68
struct BlCallbackTable {
69
  const uint32_t magicNumber;                     /**< A magic number that can be used for sanity checks. @sa BL_MAGIC_NUMBER */
70
  const uint32_t versionMajor;                    /**< The major version number of the bootloader. @sa BL_VERSION_MAJOR */
71
  const uint32_t versionMinor;                    /**< The minor version number of the bootloader. @sa BL_VERSION_MINOR */
72
  const uint32_t versionHotfix;                   /**< The hotfix indicator of the bootloader. */
73
  /**
74
   * @brief   Callback function pointer to enter hibernate mode.
75
   * @details In hibernate mode, the system enters maximum power-saving mode, but will wake up periodically in order to read some sensors.
76
   */
77
  void (*const cbShutdownHibernate)(void);
78
  /**
79
   * @brief   Callback function pointer to enter deepsleep mode.
80
   * @details In deepsleep mode, the system enters maximum power-saving mode, but basic sensors (e.g. charging plug) can wake the system.
81
   */
82
  void (*const cbShutdownDeepsleep)(void);
83
  /**
84
   * @brief   Callback function pointer to enter transportation mode.
85
   * @details In transportation mode, the system enters maximum power-saving mode and all wakeup signals are deactivated.
86
   *          Thus, the only way to reactivate the system will be a hard reset.
87
   */
88
  void (*const cbShutdownTransportation)(void);   /**< Callback function pointer to enter transportation mode. */
89
  /**
90
   * @brief   Callback function pointer to restart the system.
91
   */
92
  void (*const cbShutdownRestart)(void);
93
  /**
94
   * @brief   Callback function pointer to handle a shutdown request from another module.
95
   * @details Depending on the result of the disambiguation procedure, the module will enter the requested low-power mode.
96
   */
97
  void (*const cbHandleShutdownRequest)(void);
98
  void (*const cb5)(void);                        /**< Reserved but currently unused callback function pointer. */
99
  void (*const cb6)(void);                        /**< Reserved but currently unused callback function pointer. */
100
  void (*const cb7)(void);                        /**< Reserved but currently unused callback function pointer. */
101
  void (*const cb8)(void);                        /**< Reserved but currently unused callback function pointer. */
102
  void (*const cb9)(void);                        /**< Reserved but currently unused callback function pointer. */
103
  void (*const cb10)(void);                       /**< Reserved but currently unused callback function pointer. */
104
  void (*const cb11)(void);                       /**< Reserved but currently unused callback function pointer. */
105
};
106
107
/**
108
 * @brief Synonym for simplified access.
109
 */
110
typedef struct BlCallbackTable BlCallbackTable;
111
112
///@}
113
/*===========================================================================*/
114
115
/*===========================================================================*/
116
/**
117
 * @name    Backup Register
118
 * @details For the STM32F4 MCU (PowerManagement), the backup register contains additional information about the last shutdown and wakeup of the system.
119
 */
120
///@{
121
122
/**
123
 * @brief   Number of the RTC backup register in which some persistent information is stored.
124
 * @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.
125
 */
126
#define BL_RTC_BACKUP_REG                         0
127
128
/**
129
 * @brief   This union is used for interpretation of the content of the backup register.
130
 */
131
union BlBackupRegister {
132
  /**
133
   * @brief The raw data of the register.
134
   */
135
  uint32_t raw;
136
137
  /**
138
   * @brief A struct to interpret the content of the register.
139
   */
140
  struct {
141
    /**
142
     * @brief The primary reason for the last system shutdown.
143
     * @note  The content of this member is enum-like.
144
     * @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
145
     */
146
    uint8_t shutdown_pri_reason;
147
148
    /**
149
     * @brief The secondary reason for the last system shutdown.
150
     * @note  The content of this member is enum-like.
151
     * @sa    BL_SHUTDOWN_SEC_RSN_UNKNOWN
152
     */
153
    uint8_t shutdown_sec_reason;
154
155
    /**
156
     * @brief The primary reason for the last system wakeup.
157
     * @note  The content of this member is bitmask-like.
158
     * @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
159
     */
160
    uint8_t wakeup_pri_reason;
161
162
    /**
163
     * @brief The secondary reason for the last system wakeup.
164
     * @note  The content of this member is bitmask-like.
165
     * @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
166
     */
167
    uint8_t wakeup_sec_reason;
168
  };
169
};
170
typedef union BlBackupRegister BlBackupRegister;
171
172
/**
173
 * @brief The reason was not set or the register was reset.
174
 */
175
#define BL_SHUTDOWN_PRI_RSN_UNKNOWN               0x00u
176
177
/**
178
 * @brief The system was shut down to enter hibernate mode.
179
 */
180
#define BL_SHUTDOWN_PRI_RSN_HIBERNATE             0x01u
181
182
/**
183
 * @brief The system was shut down to enter deepsleep mode.
184
 */
185
#define BL_SHUTDOWN_PRI_RSN_DEEPSLEEP             0x02u
186
187
/**
188
 * @brief The system was shut down to enter transportation mode.
189
 */
190
#define BL_SHUTDOWN_PRI_RSN_TRANSPORT             0x03u
191
192
/**
193
 * @brief The system was shut down to restart.
194
 */
195
#define BL_SHUTDOWN_PRI_RSN_RESTART               0x04u
196
197
/**
198
 * @brief   The default shutdown mode.
199
 * @details This mode is used, if the shutdown sequence was triggered by another module than the PowerManagement.
200
 */
201
#define BL_SHUTDOWN_PRI_RSN_DEFAULT               BL_SHUTDOWN_PRI_RSN_DEEPSLEEP
202
203
204
205
/**
206
 * @brief The reason was not set or the regsiter was reset.
207
 */
208
#define BL_SHUTDOWN_SEC_RSN_UNKNOWN               0x00u
209
210
211
212
/**
213
 * @brief The reason could not be determined.
214
 */
215
#define BL_WAKEUP_PRI_RSN_UNKNOWN                 0x00u
216
217
/**
218
 * @brief The system was reset because of the low-power management configuration.
219
 */
220
#define BL_WAKEUP_PRI_RSN_LPWRRST                 0x01u
221
222
/**
223
 * @brief The system was woken by the window watchdog.
224
 */
225
#define BL_WAKEUP_PRI_RSN_WWDGRST                 0x02u
226
227
/**
228
 * @brief The system was woken by the independant watchdog.
229
 */
230
#define BL_WAKEUP_PRI_RSN_IWDGRST                 0x04u
231
232
/**
233
 * @brief The system was reset by software.
234
 */
235
#define BL_WAKEUP_PRI_RSN_SFTRST                  0x08u
236
237
/**
238
 * @brief The system was woken by a power-on/power-down reset.
239
 */
240
#define BL_WAKEUP_PRI_RSN_PORRST                  0x10u
241
242
/**
243
 * @brief The system was reset via the NRST pin.
244
 */
245
#define BL_WAKEUP_PRI_RSN_PINRST                  0x20u
246
247
/**
248
 * @brief The system was woken by a power-on/power-down, or a brownout reset.
249
 */
250
#define BL_WAKEUP_PRI_RSN_BORRST                  0x40u
251
252
/**
253
 * @brief The system was woken via the WKUP pin.
254
 */
255
#define BL_WAKEUP_PRI_RSN_WKUP                    0x80u
256
257
258
259
/**
260
 * @brief The reason could not be determined.
261
 */
262
#define BL_WAKEUP_SEC_RSN_UNKNOWN                 0x00u
263
264
/**
265
 * @brief The WKUP pin was triggered by the UART signal.
266
 */
267
#define BL_WAKEUP_SEC_RSN_UART                    0x01u
268
269
/**
270
 * @brief The WKUP pin was triggered by plugging in a power plug.
271
 */
272
#define BL_WAKEUP_SEC_RSN_PWRPLUG                 0x02u
273
274
/**
275
 * @brief The internal ADC detected a system voltage higher than the configured threshold.
276
 * @note  Usually the threshold is set to 9V.
277
 */
278
#define BL_WAKEUP_SEC_RSN_VSYSHIGH                0x04u
279
280
/**
281
 * @brief The internal ADC detected a system voltage lower than the configured threshold.
282
 */
283
#define BL_WAKEUP_SEC_RSN_VSYSLOW                 0x08u
284
285
/**
286
 * @brief The WKUP pin was triggered by an interrupt from the touch sensors.
287
 */
288
#define BL_WAKEUP_SEC_RSN_TOUCH                   0x10u
289
290
/**
291
 * @brief The WKUP pin was triggered by an interrupt from the accelerometer.
292
 */
293
#define BL_WAKEUP_SEC_RSN_ACCEL                   0x20u
294
295
/**
296
 * @brief Reserved value that must not be used right now, but might become valid in a future version.
297
 */
298
#define BL_WAKEUP_SEC_RSN_RSVD                    0xC0u
299
300
///@}
301
302
/** @} */
303
304
#endif // BL_INTERFACES_H
305
306
/** @} */