Statistics
| Branch: | Tag: | Revision:

amiro-os / periphery-lld / periphAL.h @ 40d4810c

History | View | Annotate | Download (18.3 KB)

1
/*
2
AMiRo-OS is an operating system designed for the Autonomous Mini Robot (AMiRo) platform.
3
Copyright (C) 2016..2018  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
#ifndef _AMIROOS_PERIPHAL_H_
20
#define _AMIROOS_PERIPHAL_H_
21

    
22
/*============================================================================*/
23
/* VERSION                                                                    */
24
/*============================================================================*/
25

    
26
/**
27
 * @brief   The periphery abstraction layer interface major version.
28
 * @note    Changes of the major version imply incompatibilities.
29
 */
30
#define PERIPHAL_VERSION_MAJOR    1
31

    
32
/**
33
 * @brief   The periphery abstraction layer interface minor version.
34
 * @note    A higher minor version implies new functionalty, but all old interfaces are still available.
35
 */
36
#define PERIPHAL_VERSION_MINOR    0
37

    
38
/*============================================================================*/
39
/* DEPENDENCIES                                                               */
40
/*============================================================================*/
41

    
42
#include <periphALtypes.h>
43
#include <hal.h>
44
#include <hal_qei.h>
45
#include <aos_debug.h>
46

    
47
/*============================================================================*/
48
/* GENERAL                                                                    */
49
/*============================================================================*/
50

    
51
/**
52
 * @brief Delay execution by a specific number of microseconds.
53
 *
54
 * @param[in]   us    Time to sleep until execution continues in microseconds.
55
 */
56
static inline void usleep(apalTime_t us)
57
{
58
  // check if the specified time can be represented by the system
59
  aosDbgCheck(us <= chTimeI2US(TIME_INFINITE));
60

    
61
  const sysinterval_t si = chTimeUS2I(us);
62
  // TIME_IMMEDIATE makes no sense and would even cause system halt
63
  if (si != TIME_IMMEDIATE) {
64
    chThdSleep(si);
65
  }
66
  return;
67
}
68

    
69
/*============================================================================*/
70
/* GPIO                                                                       */
71
/*============================================================================*/
72

    
73
#if HAL_USE_PAL || defined (__DOXYGEN__)
74

    
75
/**
76
 * @brief GPIO driver type.
77
 */
78
struct apalGpio_t {
79
  ioportid_t port;
80
  iopadid_t pad;
81
} PACKED_VAR;
82

    
83
/**
84
 * @brief Read the current value of a GPIO pin.
85
 *
86
 * @param[in]   gpio  GPIO to read.
87
 * @param[out]  val   Current value of the GPIO.
88
 *
89
 * @return The status indicates whether the function call was successful.
90
 */
91
static inline apalExitStatus_t apalGpioRead(apalGpio_t* gpio, apalGpioState_t* const val)
92
{
93
  aosDbgCheck(gpio != NULL);
94
  aosDbgCheck(val != NULL);
95

    
96
  *val = (palReadPad(gpio->port, gpio->pad) == PAL_HIGH) ? APAL_GPIO_HIGH : APAL_GPIO_LOW;
97
  return APAL_STATUS_OK;
98
}
99

    
100
/**
101
 * @brief Set the value of a GPIO pin.
102
 *
103
 * @param[in] gpio  GPIO to write.
104
 * @param[in] val   Value to set for the GPIO.
105
 *
106
 * @return The status indicates whether the function call was successful.
107
 */
108
static inline apalExitStatus_t apalGpioWrite(apalGpio_t* gpio, const apalGpioState_t val)
109
{
110
  aosDbgCheck(gpio != NULL);
111

    
112
  // palWritePad() is not guaranteed to be atomic, thus the scheduler is locked.
113
  syssts_t sysstatus = chSysGetStatusAndLockX();
114
  palWritePad(gpio->port, gpio->pad, (val == APAL_GPIO_HIGH) ? PAL_HIGH : PAL_LOW);
115
  chSysRestoreStatusX(sysstatus);
116
  return APAL_STATUS_OK;
117
}
118

    
119
/**
120
 * @brief Toggle the output of a GPIO.
121
 *
122
 * @param[in] gpio  GPIO to toggle.
123
 *
124
 * @return The status indicates whether the function call was successful.
125
 */
126
static inline apalExitStatus_t apalGpioToggle(apalGpio_t* gpio)
127
{
128
  aosDbgCheck(gpio != NULL);
129

    
130
  // palWritePad() is not guaranteed to be atomic, thus the scheduler is locked.
131
  syssts_t sysstatus = chSysGetStatusAndLockX();
132
  palWritePad(gpio->port, gpio->pad, (palReadPad(gpio->port, gpio->pad) == PAL_HIGH) ? PAL_LOW : PAL_HIGH);
133
  chSysRestoreStatusX(sysstatus);
134
  return APAL_STATUS_OK;
135
}
136

    
137
/**
138
 * @brief Get the current on/off state of a control GPIO.
139
 *
140
 * @param[in]   gpio  Control GPIO to read.
141
 * @param[out]  val   Current activation status of the control GPIO.
142
 *
143
 * @return The status indicates whether the function call was successful.
144
 */
145
static inline apalExitStatus_t apalControlGpioGet(const apalControlGpio_t* const cgpio, apalControlGpioState_t* const val)
146
{
147
  aosDbgCheck(cgpio != NULL);
148
  aosDbgCheck(cgpio->gpio != NULL);
149
  aosDbgCheck(val != NULL);
150

    
151
  *val = ((palReadPad(cgpio->gpio->port, cgpio->gpio->pad) == PAL_HIGH) ^ (cgpio->meta.active == APAL_GPIO_ACTIVE_HIGH)) ? APAL_GPIO_OFF : APAL_GPIO_ON;
152
  return APAL_STATUS_OK;
153
}
154

    
155
/**
156
 * @brief Turn a control GPIO 'on' or 'off' respectively.
157
 *
158
 * @param[in] gpio  Control GPIO to set.
159
 * @param[in] val   Activation value to set for the control GPIO.
160
 *
161
 * @return The status indicates whether the function call was successful.
162
 */
163
static inline apalExitStatus_t apalControlGpioSet(const apalControlGpio_t* const cgpio, const apalControlGpioState_t val)
164
{
165
  aosDbgCheck(cgpio != NULL);
166
  aosDbgCheck(cgpio->gpio != NULL);
167
  aosDbgCheck(cgpio->meta.direction == APAL_GPIO_DIRECTION_OUTPUT || cgpio->meta.direction == APAL_GPIO_DIRECTION_BIDIRECTIONAL);
168

    
169
  // palWritePad() is not guaranteed to be atomic, thus the scheduler is locked.
170
  syssts_t sysstatus = chSysGetStatusAndLockX();
171
  palWritePad(cgpio->gpio->port, cgpio->gpio->pad, ((cgpio->meta.active == APAL_GPIO_ACTIVE_HIGH) ^ (val == APAL_GPIO_ON)) ? PAL_LOW : PAL_HIGH);
172
  chSysRestoreStatusX(sysstatus);
173
  return APAL_STATUS_OK;
174
}
175

    
176
/**
177
 * @brief   Converts an apalGpioEdge_t to an ChibiOS PAL edge.
178
 */
179
#define APAL2CH_EDGE(edge)                                            \
180
  ((edge == APAL_GPIO_EDGE_RISING) ? PAL_EVENT_MODE_RISING_EDGE :     \
181
    (edge == APAL_GPIO_EDGE_FALLING) ? PAL_EVENT_MODE_FALLING_EDGE :  \
182
     (edge == APAL_GPIO_EDGE_BOTH) ? PAL_EVENT_MODE_BOTH_EDGES : 0)
183

    
184
#endif
185

    
186
/*============================================================================*/
187
/* PWM                                                                        */
188
/*============================================================================*/
189

    
190
#if HAL_USE_PWM || defined (__DOXYGEN__)
191

    
192
/**
193
 * @brief PWM driver type.
194
 */
195
typedef PWMDriver apalPWMDriver_t;
196

    
197
/**
198
 * @brief   Set the PWM with given parameters.
199
 *
200
 * @param[in] pwm       PWM driver to set.
201
 * @param[in] channel   Channel of the PWM driver to set.
202
 * @param[in] width     Width to set the channel to.
203
 *
204
 * @return  The status indicates whether the function call was successful.
205
 */
206
static inline apalExitStatus_t apalPWMSet(apalPWMDriver_t* pwm, const apalPWMchannel_t channel, const apalPWMwidth_t width)
207
{
208
  aosDbgCheck(pwm != NULL);
209

    
210
  pwmEnableChannel(pwm, (pwmchannel_t)channel, pwm->period * ((float)width / (float)APAL_PWM_WIDTH_MAX) + 0.5f);
211
  return APAL_STATUS_OK;
212
}
213

    
214
/**
215
 * @brief   Retrieve the current frequency of the PWM.
216
 *
217
 * @param[in]  pwm        PWM driver to read.
218
 * @param[out] frequency  The currently set frequency.
219
 *
220
 * @return  The status indicates whether the function call was successful.
221
 */
222
static inline apalExitStatus_t apalPWMGetFrequency(apalPWMDriver_t* pwm, apalPWMfrequency_t* const frequency)
223
{
224
  aosDbgCheck(pwm != NULL);
225
  aosDbgCheck(frequency != NULL);
226

    
227
  *frequency = pwm->config->frequency;
228
  return APAL_STATUS_OK;
229
}
230

    
231
/**
232
 * @brief   Retrieve the current period of the PWM.
233
 *
234
 * @param[in]   pwm     PWM driver to read.
235
 * @param[out]  period  The currently set period.
236
 *
237
 * @return  The status indicates whether the function call was successful.
238
 */
239
static inline apalExitStatus_t apalPWMGetPeriod(apalPWMDriver_t* pwm, apalPWMperiod_t* const period)
240
{
241
  aosDbgCheck(pwm != NULL);
242
  aosDbgCheck(period != NULL);
243

    
244
  *period = pwm->period;
245
  return APAL_STATUS_OK;
246
}
247

    
248
#endif
249

    
250
/*============================================================================*/
251
/* QEI                                                                        */
252
/*============================================================================*/
253

    
254
#if HAL_USE_QEI || defined (__DOXYGEN__)
255

    
256
/**
257
 * @brief QEI driver type.
258
 */
259
typedef QEIDriver apalQEIDriver_t;
260

    
261
/**
262
 * @brief Gets the direction of the last transition.
263
 *
264
 * @param[in]   qei         The QEI driver to use.
265
 * @param[out]  direction   The direction of the last transition.
266
 *
267
 * @return The status indicates whether the function call was successful.
268
 */
269
static inline apalExitStatus_t apalQEIGetDirection(apalQEIDriver_t* qei, apalQEIDirection_t* const direction)
270
{
271
  aosDbgCheck(qei != NULL);
272
  aosDbgCheck(direction != NULL);
273

    
274
  *direction = (qei_lld_get_direction(qei)) ? APAL_QEI_DIRECTION_DOWN : APAL_QEI_DIRECTION_UP;
275

    
276
  return APAL_STATUS_OK;
277
}
278

    
279
/**
280
 * @brief Gets the current position of the ecnoder.
281
 *
282
 * @param[in]   qei       The QEI driver to use.
283
 * @param[out]  position  The current position of the encoder.
284
 *
285
 * @return The status indicates whether the function call was successful.
286
 */
287
static inline apalExitStatus_t apalQEIGetPosition(apalQEIDriver_t* qei, apalQEICount_t* const position)
288
{
289
  aosDbgCheck(qei != NULL);
290
  aosDbgCheck(position != NULL);
291

    
292
  *position = qei_lld_get_position(qei);
293

    
294
  return APAL_STATUS_OK;
295
}
296

    
297
/**
298
 * @brief Gets the value range of the encoder.
299
 *
300
 * @param[in]   qei     The QEI driver to use.
301
 * @param[out]  range   The value range of the encoder.
302
 *
303
 * @return The status indicates whether the function call was successful.
304
 */
305
static inline apalExitStatus_t apalQEIGetRange(apalQEIDriver_t* qei, apalQEICount_t* const range)
306
{
307
  aosDbgCheck(qei != NULL);
308
  aosDbgCheck(range != NULL);
309

    
310
  *range = qei_lld_get_range(qei);
311

    
312
  return APAL_STATUS_OK;
313
}
314

    
315
#endif
316

    
317
/*============================================================================*/
318
/* I2C                                                                        */
319
/*============================================================================*/
320

    
321
#if HAL_USE_I2C || defined(__DOXYGEN__)
322

    
323
/**
324
 * @brief I2C driver type.
325
 */
326
typedef I2CDriver apalI2CDriver_t;
327

    
328
/**
329
 * @brief Transmit data and receive a response.
330
 *
331
 * @param[in]   i2cd      The I2C driver to use.
332
 * @param[in]   addr      Address to write to.
333
 * @param[in]   txbuf     Buffer containing data to send.
334
 * @param[in]   txbytes   Number of bytes to send.
335
 * @param[out]  rxbuf     Buffer to store a response to.
336
 * @param[in]   rxbytes   Number of bytes to receive.
337
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
338
 *
339
 * @return The status indicates whether the function call was succesful or a timeout occurred.
340
 */
341
static inline apalExitStatus_t apalI2CMasterTransmit(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, const uint8_t* const txbuf, const size_t txbytes, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout)
342
{
343
  aosDbgCheck(i2cd != NULL);
344

    
345
#if (I2C_USE_MUTUAL_EXCLUSION == TRUE)
346
  i2cAcquireBus(i2cd);
347
#endif
348

    
349
#pragma GCC diagnostic push
350
#pragma GCC diagnostic ignored "-Wtype-limits"
351
#if defined(STM32F1XX_I2C)
352
  // Due to a hardware limitation, for STM32F1 platform the minimum number of bytes that can be received is two.
353
  msg_t status = MSG_OK;
354
  if (rxbytes == 1) {
355
    uint8_t buffer[2];
356
    status = i2cMasterTransmitTimeout(i2cd, addr, txbuf, txbytes, buffer, 2, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
357
    rxbuf[0] = buffer[0];
358
  } else {
359
    status = i2cMasterTransmitTimeout(i2cd, addr, txbuf, txbytes, rxbuf, rxbytes, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
360
  }
361
#else
362
  const msg_t status = i2cMasterTransmitTimeout(i2cd, addr, txbuf, txbytes, rxbuf, rxbytes, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
363
#endif
364
#pragma GCC diagnostic pop
365

    
366
#if (I2C_USE_MUTUAL_EXCLUSION == TRUE)
367
  i2cReleaseBus(i2cd);
368
#endif
369

    
370
  switch (status)
371
  {
372
    case MSG_OK:
373
#if defined(STM32F1XX_I2C)
374
      return (rxbytes != 1) ? APAL_STATUS_OK : APAL_STATUS_WARNING;
375
#else
376
      return APAL_STATUS_OK;
377
#endif
378
    case MSG_TIMEOUT:
379
      return APAL_STATUS_TIMEOUT;
380
    case MSG_RESET:
381
    default:
382
      return APAL_STATUS_ERROR;
383
  }
384
}
385

    
386
/**
387
 * @brief Read data from a specific address.
388
 *
389
 * @param[in]   i2cd      The I2C driver to use.
390
 * @param[in]   addr      Address to read.
391
 * @param[out]  rxbuf     Buffer to store the response to.
392
 * @param[in]   rxbytes   Number of bytes to receive.
393
 * @param[in]   timeout   Timeout for the function to return (in microseconds).
394
 *
395
 * @return The status indicates whether the function call was succesful or a timeout occurred.
396
 */
397
static inline apalExitStatus_t apalI2CMasterReceive(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout)
398
{
399
  aosDbgCheck(i2cd != NULL);
400

    
401
#if (I2C_USE_MUTUAL_EXCLUSION == TRUE)
402
  i2cAcquireBus(i2cd);
403
#endif
404

    
405
#pragma GCC diagnostic push
406
#pragma GCC diagnostic ignored "-Wtype-limits"
407
#if defined(STM32F1XX_I2C)
408
  // Due to a hardware limitation, for STM32F1 platform the minimum number of bytes that can be received is two.
409
  msg_t status = MSG_OK;
410
  if (rxbytes == 1) {
411
    uint8_t buffer[2];
412
    status = i2cMasterReceiveTimeout(i2cd, addr, buffer, 2, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
413
    rxbuf[0] = buffer[0];
414
  } else {
415
    status = i2cMasterReceiveTimeout(i2cd, addr, rxbuf, rxbytes, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
416
  }
417
#else
418
  const msg_t status = i2cMasterReceiveTimeout(i2cd, addr, rxbuf, rxbytes, ((timeout >= TIME_INFINITE) ? TIME_INFINITE : TIME_US2I(timeout)) );
419
#endif
420
#pragma GCC diagnostic pop
421

    
422
#if (I2C_USE_MUTUAL_EXCLUSION == TRUE)
423
  i2cReleaseBus(i2cd);
424
#endif
425

    
426
  switch (status)
427
  {
428
    case MSG_OK:
429
#if defined(STM32F1XX_I2C)
430
      return (rxbytes != 1) ? APAL_STATUS_OK : APAL_STATUS_WARNING;
431
#else
432
      return APAL_STATUS_OK;
433
#endif
434
    case MSG_TIMEOUT:
435
      return APAL_STATUS_TIMEOUT;
436
    case MSG_RESET:
437
    default:
438
      return APAL_STATUS_ERROR;
439
  }
440
}
441

    
442
#endif
443

    
444
/*============================================================================*/
445
/* SPI                                                                        */
446
/*============================================================================*/
447

    
448
#if HAL_USE_SPI || defined(__DOXYGEN__)
449

    
450
/**
451
 * @brief SPI driver type.
452
 */
453
typedef SPIDriver apalSPIDriver_t;
454

    
455
/**
456
 * @brief Transmit and receive data from SPI
457
 *
458
 * @param[in]   spid      The SPI driver to use.
459
 * @param[in]   txData    Buffer containing data to send.
460
 * @param[out]  rxData    Buffer to store.
461
 * @param[in]   length    Number of bytes to send.
462
 *
463
 * @return The status indicates whether the function call was succesful.
464
 */
465
static inline apalExitStatus_t apalSPIExchange(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t length)
466
{
467
  aosDbgCheck(spid != NULL);
468

    
469
#if (SPI_USE_MUTUAL_EXCLUSION)
470
  spiAcquireBus(spid);
471
#endif
472
  spiSelect(spid);
473
  spiExchange(spid, length, txData, rxData);
474
  spiUnselect(spid);
475
#if (SPI_USE_MUTUAL_EXCLUSION)
476
  spiReleaseBus(spid);
477
#endif
478

    
479
  return APAL_STATUS_OK;
480
}
481

    
482
/**
483
 * @brief Receive data from SPI
484
 *
485
 * @param[in]   spid      The SPI driver to use.
486
 * @param[out]  data      Buffer to store.
487
 * @param[in]   length    Number of bytes to send.
488
 *
489
 * @return The status indicates whether the function call was succesful.
490
 */
491
static inline apalExitStatus_t apalSPIReceive(apalSPIDriver_t* spid, uint8_t* const data, const size_t length)
492
{
493
  aosDbgCheck(spid != NULL);
494

    
495
#if (SPI_USE_MUTUAL_EXCLUSION)
496
  spiAcquireBus(spid);
497
#endif
498
  spiSelect(spid);
499
  spiReceive(spid, length, data);
500
  spiUnselect(spid);
501
#if (SPI_USE_MUTUAL_EXCLUSION)
502
  spiReleaseBus(spid);
503
#endif
504

    
505
  return APAL_STATUS_OK;
506
}
507

    
508
/**
509
 * @brief Transmit data to SPI
510
 *
511
 * @param[in]   spid      The SPI driver to use.
512
 * @param[in]   data      Buffer containing data to send.
513
 * @param[in]   length    Number of bytes to send.
514
 *
515
 * @return The status indicates whether the function call was succesful.
516
 */
517
static inline apalExitStatus_t apalSPITransmit(apalSPIDriver_t* spid, const uint8_t* const data, const size_t length)
518
{
519
  aosDbgCheck(spid != NULL);
520

    
521
#if (SPI_USE_MUTUAL_EXCLUSION)
522
  spiAcquireBus(spid);
523
#endif
524
  spiSelect(spid);
525
  spiSend(spid, length, data);
526
  spiUnselect(spid);
527
#if (SPI_USE_MUTUAL_EXCLUSION)
528
  spiReleaseBus(spid);
529
#endif
530

    
531
  return APAL_STATUS_OK;
532
}
533

    
534
/**
535
 * @brief Transmit data to SPI and receive data afterwards without releasing the bus in between
536
 *
537
 * @param   spid        The SPI driver to use.
538
 * @param   txData      Transmit data buffer.
539
 * @param   rxData      Receive data buffer.
540
 * @param   txLength    Number of bytes to send.
541
 * @param   rxLength    Number of bytes to receive.
542
 *
543
 * @return The status indicates whether the function call was succesful.
544
 */
545
static inline apalExitStatus_t apalSPITransmitAndReceive(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t txLength, const size_t rxLength)
546
{
547
  aosDbgCheck(spid != NULL);
548

    
549
#if (SPI_USE_MUTUAL_EXCLUSION)
550
  spiAcquireBus(spid);
551
#endif
552
  spiSelect(spid);
553
  spiSend(spid, txLength, txData);
554
  spiReceive(spid, rxLength, rxData);
555
  spiUnselect(spid);
556
#if (SPI_USE_MUTUAL_EXCLUSION)
557
  spiReleaseBus(spid);
558
#endif
559

    
560
  return APAL_STATUS_OK;
561
}
562

    
563
#endif
564

    
565
/*============================================================================*/
566
/* DEBUG                                                                      */
567
/*============================================================================*/
568

    
569
/**
570
 * @brief Assert function to check a given condition.
571
 *
572
 * @param[in] c   The condition to check.
573
 */
574
#define apalDbgAssert(c)              aosDbgAssert(c)
575

    
576

    
577
/**
578
 * @brief Printf function for messages printed only in debug builds.
579
 *
580
 * @param[in] fmt   Formatted string to print.
581
 */
582
#if (AMIROOS_CFG_DBG == true) || defined(__DOXYGEN__)
583
#define apalDbgPrintf(fmt, ...)       chprintf((BaseSequentialStream*)&aos.iostream, fmt, ##__VA_ARGS__)
584
#else
585
#define apalDbgPrintf(fmt, ...) {                         \
586
  (void)(fmt);                                            \
587
}
588
#endif
589

    
590
#endif /* _AMIROOS_PERIPHAL_H_ */