ChibiOS  21.6.0
hal_pal_lld.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_pal_lld.h
19  * @brief PLATFORM PAL subsystem low level driver header.
20  *
21  * @addtogroup PAL
22  * @{
23  */
24 
25 #ifndef HAL_PAL_LLD_H
26 #define HAL_PAL_LLD_H
27 
28 #if (HAL_USE_PAL == TRUE) || defined(__DOXYGEN__)
29 
30 /*===========================================================================*/
31 /* Unsupported modes and specific modes */
32 /*===========================================================================*/
33 
34 /* Specifies palInit() without parameter, required until all platforms will
35  be updated to the new style.*/
36 #define PAL_NEW_INIT
37 
38 /*===========================================================================*/
39 /* I/O Ports Types and constants. */
40 /*===========================================================================*/
41 
42 /**
43  * @name Port related definitions
44  * @{
45  */
46 /**
47  * @brief Width, in bits, of an I/O port.
48  */
49 #define PAL_IOPORTS_WIDTH 16U
50 
51 /**
52  * @brief Whole port mask.
53  * @details This macro specifies all the valid bits into a port.
54  */
55 #define PAL_WHOLE_PORT ((ioportmask_t)0xFFFFU)
56 /** @} */
57 
58 /**
59  * @name Line handling macros
60  * @{
61  */
62 /**
63  * @brief Forms a line identifier.
64  * @details A port/pad pair are encoded into an @p ioline_t type. The encoding
65  * of this type is platform-dependent.
66  */
67 #define PAL_LINE(port, pad) \
68  ((ioline_t)((uint32_t)(port)) | ((uint32_t)(pad)))
69 
70 /**
71  * @brief Decodes a port identifier from a line identifier.
72  */
73 #define PAL_PORT(line) \
74  ((stm32_gpio_t *)(((uint32_t)(line)) & 0xFFFFFFF0U))
75 
76 /**
77  * @brief Decodes a pad identifier from a line identifier.
78  */
79 #define PAL_PAD(line) \
80  ((uint32_t)((uint32_t)(line) & 0x0000000FU))
81 
82 /**
83  * @brief Value identifying an invalid line.
84  */
85 #define PAL_NOLINE 0U
86 /** @} */
87 
88 /**
89  * @brief Generic I/O ports static initializer.
90  * @details An instance of this structure must be passed to @p palInit() at
91  * system startup time in order to initialized the digital I/O
92  * subsystem. This represents only the initial setup, specific pads
93  * or whole ports can be reprogrammed at later time.
94  * @note Implementations may extend this structure to contain more,
95  * architecture dependent, fields.
96  */
97 typedef struct {
98 
99 } PALConfig;
100 
101 /**
102  * @brief Digital I/O port sized unsigned type.
103  */
104 typedef uint32_t ioportmask_t;
105 
106 /**
107  * @brief Digital I/O modes.
108  */
109 typedef uint32_t iomode_t;
110 
111 /**
112  * @brief Type of an I/O line.
113  */
114 typedef uint32_t ioline_t;
115 
116 /**
117  * @brief Port Identifier.
118  * @details This type can be a scalar or some kind of pointer, do not make
119  * any assumption about it, use the provided macros when populating
120  * variables of this type.
121  */
122 typedef uint32_t ioportid_t;
123 
124 /**
125  * @brief Type of an pad identifier.
126  */
127 typedef uint32_t iopadid_t;
128 
129 /*===========================================================================*/
130 /* I/O Ports Identifiers. */
131 /*===========================================================================*/
132 
133 /**
134  * @brief First I/O port identifier.
135  * @details Low level drivers can define multiple ports, it is suggested to
136  * use this naming convention.
137  */
138 #define IOPORT1 0
139 
140 /*===========================================================================*/
141 /* Implementation, some of the following macros could be implemented as */
142 /* functions, if so please put them in pal_lld.c. */
143 /*===========================================================================*/
144 
145 /**
146  * @brief Low level PAL subsystem initialization.
147  *
148  * @notapi
149  */
150 #define pal_lld_init() _pal_lld_init()
151 
152 /**
153  * @brief Reads the physical I/O port states.
154  *
155  * @param[in] port port identifier
156  * @return The port bits.
157  *
158  * @notapi
159  */
160 #define pal_lld_readport(port) 0U
161 
162 /**
163  * @brief Reads the output latch.
164  * @details The purpose of this function is to read back the latched output
165  * value.
166  *
167  * @param[in] port port identifier
168  * @return The latched logical states.
169  *
170  * @notapi
171  */
172 #define pal_lld_readlatch(port) 0U
173 
174 /**
175  * @brief Writes a bits mask on a I/O port.
176  *
177  * @param[in] port port identifier
178  * @param[in] bits bits to be written on the specified port
179  *
180  * @notapi
181  */
182 #define pal_lld_writeport(port, bits) \
183  do { \
184  (void)port; \
185  (void)bits; \
186  } while (false)
187 
188 /**
189  * @brief Sets a bits mask on a I/O port.
190  * @note The @ref PAL provides a default software implementation of this
191  * functionality, implement this function if can optimize it by using
192  * special hardware functionalities or special coding.
193  *
194  * @param[in] port port identifier
195  * @param[in] bits bits to be ORed on the specified port
196  *
197  * @notapi
198  */
199 #define pal_lld_setport(port, bits) \
200  do { \
201  (void)port; \
202  (void)bits; \
203  } while (false)
204 
205 /**
206  * @brief Clears a bits mask on a I/O port.
207  * @note The @ref PAL provides a default software implementation of this
208  * functionality, implement this function if can optimize it by using
209  * special hardware functionalities or special coding.
210  *
211  * @param[in] port port identifier
212  * @param[in] bits bits to be cleared on the specified port
213  *
214  * @notapi
215  */
216 #define pal_lld_clearport(port, bits) \
217  do { \
218  (void)port; \
219  (void)bits; \
220  } while (false)
221 
222 /**
223  * @brief Toggles a bits mask on a I/O port.
224  * @note The @ref PAL provides a default software implementation of this
225  * functionality, implement this function if can optimize it by using
226  * special hardware functionalities or special coding.
227  *
228  * @param[in] port port identifier
229  * @param[in] bits bits to be XORed on the specified port
230  *
231  * @notapi
232  */
233 #define pal_lld_toggleport(port, bits) \
234  do { \
235  (void)port; \
236  (void)bits; \
237  } while (false)
238 
239 /**
240  * @brief Reads a group of bits.
241  * @note The @ref PAL provides a default software implementation of this
242  * functionality, implement this function if can optimize it by using
243  * special hardware functionalities or special coding.
244  *
245  * @param[in] port port identifier
246  * @param[in] mask group mask
247  * @param[in] offset group bit offset within the port
248  * @return The group logical states.
249  *
250  * @notapi
251  */
252 #define pal_lld_readgroup(port, mask, offset) 0U
253 
254 /**
255  * @brief Writes a group of bits.
256  * @note The @ref PAL provides a default software implementation of this
257  * functionality, implement this function if can optimize it by using
258  * special hardware functionalities or special coding.
259  *
260  * @param[in] port port identifier
261  * @param[in] mask group mask
262  * @param[in] offset group bit offset within the port
263  * @param[in] bits bits to be written. Values exceeding the group width
264  * are masked.
265  *
266  * @notapi
267  */
268 #define pal_lld_writegroup(port, mask, offset, bits) \
269  do { \
270  (void)port; \
271  (void)mask; \
272  (void)offset; \
273  (void)bits; \
274  } while (false)
275 
276 /**
277  * @brief Pads group mode setup.
278  * @details This function programs a pads group belonging to the same port
279  * with the specified mode.
280  * @note Programming an unknown or unsupported mode is silently ignored.
281  *
282  * @param[in] port port identifier
283  * @param[in] mask group mask
284  * @param[in] offset group bit offset within the port
285  * @param[in] mode group mode
286  *
287  * @notapi
288  */
289 #define pal_lld_setgroupmode(port, mask, offset, mode) \
290  _pal_lld_setgroupmode(port, mask << offset, mode)
291 
292 /**
293  * @brief Reads a logical state from an I/O pad.
294  * @note The @ref PAL provides a default software implementation of this
295  * functionality, implement this function if can optimize it by using
296  * special hardware functionalities or special coding.
297  *
298  * @param[in] port port identifier
299  * @param[in] pad pad number within the port
300  * @return The logical state.
301  * @retval PAL_LOW low logical state.
302  * @retval PAL_HIGH high logical state.
303  *
304  * @notapi
305  */
306 #define pal_lld_readpad(port, pad) PAL_LOW
307 
308 /**
309  * @brief Writes a logical state on an output pad.
310  * @note This function is not meant to be invoked directly by the
311  * application code.
312  * @note The @ref PAL provides a default software implementation of this
313  * functionality, implement this function if can optimize it by using
314  * special hardware functionalities or special coding.
315  *
316  * @param[in] port port identifier
317  * @param[in] pad pad number within the port
318  * @param[in] bit logical value, the value must be @p PAL_LOW or
319  * @p PAL_HIGH
320  *
321  * @notapi
322  */
323 #define pal_lld_writepad(port, pad, bit) \
324  do { \
325  (void)port; \
326  (void)pad; \
327  (void)bit; \
328  } while (false)
329 
330 /**
331  * @brief Sets a pad logical state to @p PAL_HIGH.
332  * @note The @ref PAL provides a default software implementation of this
333  * functionality, implement this function if can optimize it by using
334  * special hardware functionalities or special coding.
335  *
336  * @param[in] port port identifier
337  * @param[in] pad pad number within the port
338  *
339  * @notapi
340  */
341 #define pal_lld_setpad(port, pad) \
342  do { \
343  (void)port; \
344  (void)pad; \
345  } while (false)
346 
347 /**
348  * @brief Clears a pad logical state to @p PAL_LOW.
349  * @note The @ref PAL provides a default software implementation of this
350  * functionality, implement this function if can optimize it by using
351  * special hardware functionalities or special coding.
352  *
353  * @param[in] port port identifier
354  * @param[in] pad pad number within the port
355  *
356  * @notapi
357  */
358 #define pal_lld_clearpad(port, pad) \
359  do { \
360  (void)port; \
361  (void)pad; \
362  } while (false)
363 
364 /**
365  * @brief Toggles a pad logical state.
366  * @note The @ref PAL provides a default software implementation of this
367  * functionality, implement this function if can optimize it by using
368  * special hardware functionalities or special coding.
369  *
370  * @param[in] port port identifier
371  * @param[in] pad pad number within the port
372  *
373  * @notapi
374  */
375 #define pal_lld_togglepad(port, pad) \
376  do { \
377  (void)port; \
378  (void)pad; \
379  } while (false)
380 
381 /**
382  * @brief Pad mode setup.
383  * @details This function programs a pad with the specified mode.
384  * @note The @ref PAL provides a default software implementation of this
385  * functionality, implement this function if can optimize it by using
386  * special hardware functionalities or special coding.
387  * @note Programming an unknown or unsupported mode is silently ignored.
388  *
389  * @param[in] port port identifier
390  * @param[in] pad pad number within the port
391  * @param[in] mode pad mode
392  *
393  * @notapi
394  */
395 #define pal_lld_setpadmode(port, pad, mode) \
396  do { \
397  (void)port; \
398  (void)pad; \
399  (void)mode; \
400  } while (false)
401 
402 /**
403  * @brief Returns a PAL event structure associated to a pad.
404  *
405  * @param[in] port port identifier
406  * @param[in] pad pad number within the port
407  *
408  * @notapi
409  */
410 #define pal_lld_get_pad_event(port, pad) \
411  &_pal_events[0]; (void)(port); (void)pad
412 
413 /**
414  * @brief Returns a PAL event structure associated to a line.
415  *
416  * @param[in] line line identifier
417  *
418  * @notapi
419  */
420 #define pal_lld_get_line_event(line) \
421  &_pal_events[0]; (void)line
422 
423 #if !defined(__DOXYGEN__)
424 #if (PAL_USE_WAIT == TRUE) || (PAL_USE_CALLBACKS == TRUE)
425 extern palevent_t _pal_events[1];
426 #endif
427 #endif
428 
429 #ifdef __cplusplus
430 extern "C" {
431 #endif
432  void _pal_lld_init(void);
433  void _pal_lld_setgroupmode(ioportid_t port,
434  ioportmask_t mask,
435  iomode_t mode);
436 #ifdef __cplusplus
437 }
438 #endif
439 
440 #endif /* HAL_USE_PAL == TRUE */
441 
442 #endif /* HAL_PAL_LLD_H */
443 
444 /** @} */
ioportid_t
uint32_t ioportid_t
Port Identifier.
Definition: hal_pal_lld.h:122
iopadid_t
uint32_t iopadid_t
Type of an pad identifier.
Definition: hal_pal_lld.h:127
iomode_t
uint32_t iomode_t
Digital I/O modes.
Definition: hal_pal_lld.h:109
ioportmask_t
uint32_t ioportmask_t
Digital I/O port sized unsigned type.
Definition: hal_pal_lld.h:104
ioline_t
uint32_t ioline_t
Type of an I/O line.
Definition: hal_pal_lld.h:114
_pal_lld_init
void _pal_lld_init(void)
STM32 I/O ports configuration.
Definition: hal_pal_lld.c:58
palevent_t
Type of a PAL event record.
Definition: hal_pal.h:154
_pal_lld_setgroupmode
void _pal_lld_setgroupmode(ioportid_t port, ioportmask_t mask, iomode_t mode)
Pads mode setup.
Definition: hal_pal_lld.c:73
PALConfig
Generic I/O ports static initializer.
Definition: hal_pal_lld.h:97