Statistics
| Branch: | Tag: | Revision:

amiro-lld / periphAL.h @ 3ed0cc4d

History | View | Annotate | Download (24.1 KB)

1
/*
2
AMiRo-LLD is a compilation of low-level hardware drivers 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 Lesser 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 Lesser General Public License for more details.
14

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

    
19
#ifndef AMIROLLD_PERIPHAL_H
20
#define AMIROLLD_PERIPHAL_H
21

    
22
#include <amiro-lld.h>
23

    
24
/*============================================================================*/
25
/* VERSION                                                                    */
26
/*============================================================================*/
27

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

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

    
40
/*============================================================================*/
41
/* DEPENDENCIES                                                               */
42
/*============================================================================*/
43

    
44
#include <stdint.h>
45

    
46
/*============================================================================*/
47
/* GENERAL                                                                    */
48
/*============================================================================*/
49

    
50
/**
51
 * @brief Status values used as return value for all (or most) function calls.
52
 * @note  The status can be used as mask of flags.
53
 */
54
typedef int8_t apalExitStatus_t;
55

    
56
/**
57
 * @brief   Status value for success (no error or warning occurred).
58
 */
59
#define APAL_STATUS_OK                          ((apalExitStatus_t)0)
60
#define APAL_STATUS_SUCCESS                     ((apalExitStatus_t)0)
61

    
62
/**
63
 * @brief   Status value for unspecified failure.
64
 */
65
#define APAL_STATUS_ERROR                       ((apalExitStatus_t)-1)
66
#define APAL_STATUS_FAILURE                     ((apalExitStatus_t)-1)
67

    
68
/**
69
 * @brief   Status value for timeout failure.
70
 */
71
#define APAL_STATUS_TIMEOUT                     ((apalExitStatus_t)-2)
72

    
73
/**
74
 * @brief   Status value for failure because of invalid arguments.
75
 */
76
#define APAL_STATUS_INVALIDARGUMENTS            ((apalExitStatus_t)-4)
77

    
78
/**
79
 * @brief   Status value for failure because the function is not available/implemented.
80
 */
81
#define APAL_STATUS_UNAVAILABLE                 ((apalExitStatus_t)-8)
82

    
83
/**
84
 * @brief   Status value for unspecified warning.
85
 */
86
#define APAL_STATUS_WARNING                     ((apalExitStatus_t)1)
87

    
88
/*============================================================================*/
89
/* DEBUG                                                                      */
90
/*============================================================================*/
91

    
92
#if (AMIROLLD_CFG_DBG == true) || defined(__DOXYGEN__)
93

    
94
#if defined(__cplusplus)
95
extern "C" {
96
#endif /* defined(__cplusplus) */
97

    
98
#if !defined(apalDbgAssertMsg) || defined(__DOXYGEN__)
99
  /**
100
   * @brief Assert function to check a given condition and print a message string.
101
   *
102
   * @param[in] c     The condition to check.
103
   * @param[in] fmt   Formatted message string to print.
104
   */
105
  void apalDbgAssertMsg(const bool c, const char* fmt, ...);
106
#endif
107

    
108
#if !defined(apalDbgPrintf) || defined(__DOXYGEN__)
109
  /**
110
   * @brief Printf function for messages printed only in debug builds.
111
   *
112
   * @param[in] fmt   Formatted string to print.
113
   *
114
   * return   Number of printed characters.
115
   */
116
  int apalDbgPrintf(const char* fmt, ...);
117
#endif
118

    
119
#if defined(__cplusplus)
120
}
121
#endif /* defined(__cplusplus) */
122

    
123
/**
124
 * @brief Assert function to check a given condition.
125
 *
126
 * @param[in] c     The condition to check.
127
 */
128
#define apalDbgAssert(c) apalDbgAssertMsg(c, "%s(%u): apalDbgAssert failed", __FILE__, __LINE__)
129

    
130
#else /* (AMIROLLD_CFG_DBG == true) */
131

    
132
#define apalDbgAssertMsg(c, fmt, ...)
133

    
134
#define apalDbgPrintf(fmt, ...)                 0
135

    
136
#define apalDbgAssert(c)
137

    
138
#endif /* (AMIROLLD_CFG_DBG == true) */
139

    
140
/*============================================================================*/
141
/* TIMING                                                                     */
142
/*============================================================================*/
143

    
144
/**
145
 * @brief Time measurement type (in microseconds).
146
 */
147
#if (AMIROLLD_CFG_TIME_SIZE == 8)
148
  typedef uint8_t   apalTime_t;
149
#elif (AMIROLLD_CFG_TIME_SIZE == 16)
150
  typedef uint16_t  apalTime_t;
151
#elif (AMIROLLD_CFG_TIME_SIZE == 32)
152
  typedef uint32_t  apalTime_t;
153
#elif (AMIROLLD_CFG_TIME_SIZE == 64)
154
  typedef uint64_t  apalTime_t;
155
#else
156
  #error "AMIROLLD_CFG_TIME_SIZE must be 8, 16, 32 or 64"
157
#endif
158

    
159
#ifdef __cplusplus
160
extern "C" {
161
#endif
162

    
163
#if !defined(apalSleep) || defined(__DOXYGEN__)
164
  /**
165
   * @brief Delay execution by a specific number of microseconds.
166
   *
167
   * @param[in]   us    Time to sleep until execution continues in microseconds.
168
   */
169
  void apalSleep(apalTime_t us);
170
#endif
171

    
172
#if !defined(apalGetTime) || defined(__DOXYGEN__)
173
  /**
174
   * @brief Retrieve current system time in microseconds.
175
   * @details Return value may differ from true system time due to overflows.
176
   *
177
   * @return  Current system time.
178
   */
179
  apalTime_t apalGetTime(void);
180
#endif
181

    
182
#ifdef __cplusplus
183
}
184
#endif
185

    
186
/*============================================================================*/
187
/* GPIO                                                                       */
188
/*============================================================================*/
189

    
190
#if (AMIROLLD_CFG_GPIO == true) || defined(__DOXYGEN__)
191

    
192
/*
193
 * The following type must be defined by the implementation:
194
 *
195
 * apalGpio_t
196
 *   Type to represent a GPIO object.
197
 *   Is only used via pointer by the API.
198
 */
199

    
200
/**
201
 * @brief Status values to read/write a GPIO port.
202
 */
203
typedef uint8_t apalGpioState_t;
204

    
205
/**
206
 * @brief   GPIO physical low state.
207
 */
208
#define APAL_GPIO_LOW                           ((apalGpioState_t)0)
209

    
210
/**
211
 * @brief   GPIO physical high state.
212
 */
213
#define APAL_GPIO_HIGH                          ((apalGpioState_t)1)
214

    
215
/**
216
 * @brief   Invert a physical GPIO state.
217
 *
218
 * @param[in] state   GPIO state to invert.
219
 *
220
 * @return  Inverted physical GPIO state.
221
 */
222
#define APAL_GPIO_STATE_INVERT(state) (                                       \
223
  (apalGpioState_t)state ^ APAL_GPIO_HIGH                                     \
224
)
225

    
226
/**
227
 * @brief Logical status values to turn a control GPIO 'on' and 'off'.
228
 */
229
typedef uint8_t apalControlGpioState_t;
230

    
231
/**
232
 * @brief   GPIO logical off state.
233
 */
234
#define APAL_GPIO_OFF                           ((apalControlGpioState_t)0)
235

    
236
/**
237
 * @brief   GPIO logical on state.
238
 */
239
#define APAL_GPIO_ON                            ((apalControlGpioState_t)1)
240

    
241
/**
242
 * @brief   Polarity state of the control GPIO.
243
 */
244
typedef uint8_t apalGpioActive_t;
245

    
246
/**
247
 * @brief   The control GPIO is never defined to be 'on' (does not apply).
248
 */
249
#define APAL_GPIO_ACTIVE_NONE                   ((apalGpioActive_t)0)
250

    
251
/**
252
 * @brief   The control GPIO is defined to be 'on' when it is phsically low.
253
 */
254
#define APAL_GPIO_ACTIVE_LOW                    ((apalGpioActive_t)1)
255

    
256
/**
257
 * @brief   The control GPIO is defined to be 'on' when it is physically high.
258
 */
259
#define APAL_GPIO_ACTIVE_HIGH                   ((apalGpioActive_t)2)
260

    
261
/**
262
 * @brief   The control GPIO is defined to be always 'on'.
263
 */
264
#define APAL_GPIO_ACTIVE_ANY                    ((apalGpioActive_t)3)
265

    
266
/**
267
 * @brief   Invert a GPIO active state.
268
 * @details The active state is inverted only if it was either low or high.
269
 *          In case it was set to none or any, the value is not modified.
270
 *
271
 * @param[in] active  Active state to be inverted.
272
 *
273
 * @return  Inverted active state.
274
 */
275
#define APAL_GPIO_ACTIVE_INVERT(active) (                                     \
276
  (((apalGpioActive_t)active & APAL_GPIO_ACTIVE_LOW) ^                        \
277
   ((apalGpioActive_t)active & APAL_GPIO_ACTIVE_HIGH)) ?                      \
278
  ((apalGpioActive_t)active ^ APAL_GPIO_ACTIVE_ANY) :                         \
279
  ((apalGpioActive_t)active)                                                  \
280
)
281

    
282
/**
283
 * @brief   Signal direction for the control GPIO.
284
 */
285
typedef uint8_t apalGpioDirection_t;
286

    
287
/**
288
 * @brief   Signal direction for the control GPIO is undefined.
289
 */
290
#define APAL_GPIO_DIRECTION_UNDEFINED           ((apalGpioDirection_t)0)
291

    
292
/**
293
 * @brief   Signal direction for the control GPIO is input only.
294
 */
295
#define APAL_GPIO_DIRECTION_INPUT               ((apalGpioDirection_t)1)
296

    
297
/**
298
 * @brief   Signal direction for the control GPIO is output only.
299
 */
300
#define APAL_GPIO_DIRECTION_OUTPUT              ((apalGpioDirection_t)2)
301

    
302
/**
303
 * @brief   Signal direction for the control GPIO is didirectional.
304
 */
305
#define APAL_GPIO_DIRECTION_BIDIRECTIONAL       ((apalGpioDirection_t)3)
306

    
307
/**
308
 * @brief   Informative or effective signal edge for control GPIOs.
309
 */
310
typedef uint8_t apalGpioEdge_t;
311

    
312
/**
313
 * @brief   No edges indicate an interrupt or trigger an action.
314
 */
315
#define APAL_GPIO_EDGE_NONE                     ((apalGpioEdge_t)0)
316

    
317
/**
318
 * @brief   Rising edges indicate an interrupt or trigger an action.
319
 */
320
#define APAL_GPIO_EDGE_RISING                   ((apalGpioEdge_t)1)
321

    
322
/**
323
 * @brief   Falling edges indicate an interrupt or trigger an action.
324
 */
325
#define APAL_GPIO_EDGE_FALLING                  ((apalGpioEdge_t)2)
326

    
327
/**
328
 * @brief   Both rising and falling edges indicate an interrupt or trigger an action.
329
 */
330
#define APAL_GPIO_EDGE_BOTH                     ((apalGpioEdge_t)3)
331

    
332
/**
333
 * @brief   Inverts the value of the informative or effective signal edge for interrupts.
334
 * @details Rising edge is inverted to falling and vice versa.
335
 *          If none or both edges are enabled, the identical value is returned.
336
 */
337
#define APAL_GPIO_EDGE_INVERT(edge) (                                         \
338
  (((apalGpioEdge_t)edge & APAL_GPIO_EDGE_RISING) ^                           \
339
   ((apalGpioEdge_t)edge & APAL_GPIO_EDGE_FALLING)) ?                         \
340
  ((apalGpioEdge_t)edge ^ APAL_GPIO_EDGE_BOTH) :                              \
341
  ((apalGpioEdge_t)edge)                                                      \
342
)
343

    
344
/**
345
 * @brief Control GPIO meta information
346
 */
347
typedef struct {
348
  apalGpioDirection_t direction : 2;  /**< Direction configuration for according signals */
349
  apalGpioActive_t active       : 2;  /**< Active state of the GPIO */
350
  apalGpioEdge_t edge           : 2;  /**< Edge configuration for according signals */
351
} apalGpioMeta_t;
352

    
353
/**
354
 * @brief Control GPIO type.
355
 */
356
typedef struct {
357
  apalGpio_t* gpio;     /**< The GPIO to use.                 */
358
  apalGpioMeta_t meta;  /**< Meta information about the GPIO. */
359
} apalControlGpio_t;
360

    
361
#ifdef __cplusplus
362
extern "C" {
363
#endif
364

    
365
#if !defined(apalGpioRead) || defined(__DOXYGEN__)
366
  /**
367
   * @brief Read the current value of a GPIO pin.
368
   *
369
   * @param[in]   gpio  GPIO to read.
370
   * @param[out]  val   Current value of the GPIO.
371
   *
372
   * @return The status indicates whether the function call was successful.
373
   */
374
  apalExitStatus_t apalGpioRead(apalGpio_t* gpio, apalGpioState_t* const val);
375
#endif
376

    
377
#if !defined(apalGpioWrite) || defined(__DOXYGEN__)
378
  /**
379
   * @brief Set the value of a GPIO pin.
380
   *
381
   * @param[in] gpio  GPIO to write.
382
   * @param[in] val   Value to set for the GPIO.
383
   *
384
   * @return The status indicates whether the function call was successful.
385
   */
386
  apalExitStatus_t apalGpioWrite(apalGpio_t* gpio, const apalGpioState_t val);
387
#endif
388

    
389
#if !defined(apalGpioToggle) || defined(__DOXYGEN__)
390
  /**
391
   * @brief Toggle the output of a GPIO.
392
   *
393
   * @param[in] gpio  GPIO to toggle.
394
   *
395
   * @return The status indicates whether the function call was successful.
396
   */
397
  apalExitStatus_t apalGpioToggle(apalGpio_t* gpio);
398
#endif
399

    
400
#if !defined(apalGpioIsInterruptEnabled) || defined(__DOXYGEN__)
401
  /**
402
   * @brief Return the interrupt enable status of the GPIO.
403
   *
404
   * @param[in]   gpio      GPIO to check.
405
   * @param[out]  enabled   Flag, indicating whether interrupt is enabled for the GPIO.
406
   *
407
   * @return The status indicates whether the function call was successful.
408
   */
409
  apalExitStatus_t apalGpioIsInterruptEnabled(apalGpio_t* gpio, bool* const enabled);
410
#endif
411

    
412
#if !defined(apalControlGpioGet) || defined(__DOXYGEN__)
413
  /**
414
   * @brief Get the current on/off state of a control GPIO.
415
   *
416
   * @param[in]   gpio  Control GPIO to read.
417
   * @param[out]  val   Current activation status of the control GPIO.
418
   *
419
   * @return The status indicates whether the function call was successful.
420
   */
421
  apalExitStatus_t apalControlGpioGet(const apalControlGpio_t* const cgpio, apalControlGpioState_t* const val);
422
#endif
423

    
424
#if !defined(apalControlGpioSet) || defined(__DOXYGEN__)
425
  /**
426
   * @brief Turn a control GPIO 'on' or 'off' respectively.
427
   *
428
   * @param[in] gpio  Control GPIO to set.
429
   * @param[in] val   Activation value to set for the control GPIO.
430
   *
431
   * @return The status indicates whether the function call was successful.
432
   */
433
  apalExitStatus_t apalControlGpioSet(const apalControlGpio_t* const cgpio, const apalControlGpioState_t val);
434
#endif
435

    
436
#if !defined(apalControlGpioSetInterrupt) || defined(__DOXYGEN__)
437
  /**
438
   * @brief   Enable or disable the interrupt event functionality.
439
   *
440
   * @param[in] cgpio   Control GPIO to set.
441
   * @param[in] enable  Flag, indicating whether the interrupt shall be activated (true) or deactivated (false).
442
   *
443
   * @return The status indicates whether the function call was successful.
444
   */
445
  apalExitStatus_t apalControlGpioSetInterrupt(const apalControlGpio_t* const cgpio, const bool enable);
446
#endif
447

    
448
#ifdef __cplusplus
449
}
450
#endif
451

    
452
#endif /* (AMIROLLD_CFG_GPIO == true) */
453

    
454
/*============================================================================*/
455
/* PWM                                                                        */
456
/*============================================================================*/
457

    
458
#if (AMIROLLD_CFG_PWM == true) || defined(__DOXYGEN__)
459

    
460
/*
461
 * The following type must be defined by the implementation:
462
 *
463
 * apalPWMDriver_t
464
 *   Type to represent a PWM driver object.
465
 *   Is only used via pointer by the API.
466
 */
467

    
468
/**
469
 * @brief PWM channel type.
470
 */
471
typedef uint8_t   apalPWMchannel_t;
472

    
473
/**
474
 * @brief PWM width type.
475
 */
476
typedef uint16_t  apalPWMwidth_t;
477

    
478
/**
479
 * @brief PWM frequency type.
480
 */
481
typedef uint32_t  apalPWMfrequency_t;
482

    
483
/**
484
 * @brief PWM period time.
485
 */
486
typedef uint32_t  apalPWMperiod_t;
487

    
488
/**
489
 * @brief   PWM width to turn off the PWM.
490
 */
491
#define APAL_PWM_WIDTH_OFF                      ((apalPWMwidth_t)0x0000u)
492

    
493
/**
494
 * @brief   Minimum allowed PWM width.
495
 */
496
#define APAL_PWM_WIDTH_MIN                      ((apalPWMwidth_t)0x0000u)
497

    
498
/**
499
 * @brief   Maximum allowed PWM width.
500
 */
501
#define APAL_PWM_WIDTH_MAX                      ((apalPWMwidth_t)0xFFFFu)
502

    
503
#ifdef __cplusplus
504
extern "C" {
505
#endif
506

    
507
#if !defined(apalPWMSet) || defined(__DOXYGEN__)
508
  /**
509
   * @brief   Set the PWM with given parameters.
510
   *
511
   * @param[in] pwm       PWM driver to set.
512
   * @param[in] channel   Channel of the PWM driver to set.
513
   * @param[in] width     Width to set the channel to.
514
   *
515
   * @return  The status indicates whether the function call was successful.
516
   */
517
  apalExitStatus_t apalPWMSet(apalPWMDriver_t* pwm, const apalPWMchannel_t channel, const apalPWMwidth_t width);
518
#endif
519

    
520
#if !defined(apalPWMGetFrequency) || defined(__DOXYGEN__)
521
  /**
522
   * @brief   Retrieve the current frequency of the PWM.
523
   *
524
   * @param[in]  pwm        PWM driver to read.
525
   * @param[out] frequency  The currently set frequency.
526
   *
527
   * @return  The status indicates whether the function call was successful.
528
   */
529
  apalExitStatus_t apalPWMGetFrequency(apalPWMDriver_t* pwm, apalPWMfrequency_t* const frequency);
530
#endif
531

    
532
#if !defined(apalPWMGetPeriod) || defined(__DOXYGEN__)
533
  /**
534
   * @brief   Retrieve the current period of the PWM.
535
   *
536
   * @param[in]   pwm     PWM driver to read.
537
   * @param[out]  period  The currently set period.
538
   *
539
   * @return  The status indicates whether the function call was successful.
540
   */
541
  apalExitStatus_t apalPWMGetPeriod(apalPWMDriver_t* pwm, apalPWMperiod_t* const period);
542
#endif
543

    
544
#ifdef __cplusplus
545
}
546
#endif
547

    
548
#endif /* (AMIROLLD_CFG_PWM == true) */
549

    
550
/*============================================================================*/
551
/* QEI                                                                        */
552
/*============================================================================*/
553

    
554
#if (AMIROLLD_CFG_QEI == true) || defined(__DOXYGEN__)
555

    
556
/*
557
 * The following type must be defined by the implementation:
558
 *
559
 * apalQEIDriver_t
560
 *   Type to represent a QEI driver object.
561
 *   Is only used via pointer by the API.
562
 */
563

    
564
/**
565
 * @brief QEI counter type.
566
 */
567
typedef uint32_t  apalQEICount_t;
568

    
569
/**
570
 * @brief Direction of the QEI.
571
 */
572
typedef uint8_t apalQEIDirection_t;
573

    
574
/*
575
 * @brief   QEI counts upwards.
576
 */
577
#define APAL_QEI_DIRECTION_UP                   ((apalQEIDirection_t)0)
578

    
579
/*
580
 * @brief   QEI counts downwards.
581
 */
582
#define APAL_QEI_DIRECTION_DOWN                 ((apalQEIDirection_t)1)
583

    
584
#ifdef __cplusplus
585
extern "C" {
586
#endif
587

    
588
#if !defined(apalQEIGetDirection) || defined(__DOXYGEN__)
589
  /**
590
   * @brief Gets the direction of the last transition.
591
   *
592
   * @param[in]   qei         The QEI driver to use.
593
   * @param[out]  direction   The direction of the last transition.
594
   *
595
   * @return The status indicates whether the function call was successful.
596
   */
597
  apalExitStatus_t apalQEIGetDirection(apalQEIDriver_t* qei, apalQEIDirection_t* const direction);
598
#endif
599

    
600
#if !defined(apalQEIGetPosition) || defined(__DOXYGEN__)
601
  /**
602
   * @brief Gets the current position of the ecnoder.
603
   *
604
   * @param[in]   qei       The QEI driver to use.
605
   * @param[out]  position  The current position of the encoder.
606
   *
607
   * @return The status indicates whether the function call was successful.
608
   */
609
  apalExitStatus_t apalQEIGetPosition(apalQEIDriver_t* qei, apalQEICount_t* const position);
610
#endif
611

    
612
#if !defined(apalQEIGetRange) || defined(__DOXYGEN__)
613
  /**
614
   * @brief Gets the value range of the encoder.
615
   *
616
   * @param[in]   qei     The QEI driver to use.
617
   * @param[out]  range   The value range of the encoder.
618
   *
619
   * @return The status indicates whether the function call was successful.
620
   */
621
  apalExitStatus_t apalQEIGetRange(apalQEIDriver_t* qei, apalQEICount_t* const range);
622
#endif
623

    
624
#ifdef __cplusplus
625
}
626
#endif
627

    
628
#endif /* (AMIROLLD_CFG_QEI == true) */
629

    
630
/*============================================================================*/
631
/* I2C                                                                        */
632
/*============================================================================*/
633

    
634
#if (AMIROLLD_CFG_I2C == true) || defined(__DOXYGEN__)
635

    
636
/*
637
 * The following type must be defined by the implementation:
638
 *
639
 * apalI2CDriver_t
640
 *   Type to represent a I2C driver object.
641
 *   Is only used via pointer by the API.
642
 */
643

    
644
/**
645
 * @brief I2C address type.
646
 */
647
typedef uint16_t apalI2Caddr_t;
648

    
649
#ifdef __cplusplus
650
extern "C" {
651
#endif
652

    
653
#if !defined(apalI2CMasterTransmit) || defined(__DOXYGEN__)
654
  /**
655
   * @brief Transmit data and receive a response.
656
   *
657
   * @param[in]   i2cd      The I2C driver to use.
658
   * @param[in]   addr      Address to write to.
659
   * @param[in]   txbuf     Buffer containing data to send.
660
   * @param[in]   txbytes   Number of bytes to send.
661
   * @param[out]  rxbuf     Buffer to store a response to.
662
   * @param[in]   rxbytes   Number of bytes to receive.
663
   * @param[in]   timeout   Timeout for the function to return (in microseconds).
664
   *
665
   * @return The status indicates whether the function call was succesful or a timeout occurred.
666
   */
667
  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);
668
#endif
669

    
670
#if !defined(apalI2CMasterReceive) || defined(__DOXYGEN__)
671
  /**
672
   * @brief Read data from a specific address.
673
   *
674
   * @param[in]   i2cd      The I2C driver to use.
675
   * @param[in]   addr      Address to read.
676
   * @param[out]  rxbuf     Buffer to store the response to.
677
   * @param[in]   rxbytes   Number of bytes to receive.
678
   * @param[in]   timeout   Timeout for the function to return (in microseconds).
679
   *
680
   * @return The status indicates whether the function call was succesful or a timeout occurred.
681
   */
682
  apalExitStatus_t apalI2CMasterReceive(apalI2CDriver_t* i2cd, const apalI2Caddr_t addr, uint8_t* const rxbuf, const size_t rxbytes, const apalTime_t timeout);
683
#endif
684

    
685
#ifdef __cplusplus
686
}
687
#endif
688

    
689
#endif /* (AMIROLLD_CFG_I2C == true) */
690

    
691
/*============================================================================*/
692
/* SPI                                                                        */
693
/*============================================================================*/
694

    
695
#if (AMIROLLD_CFG_SPI == true) || defined(__DOXYGEN__)
696

    
697
/*
698
 * The following types must be defined by the implementation:
699
 *
700
 * apalSPIDriver_t
701
 *   Type to represent a SPI driver object.
702
 *   Is only used via pointer by the API.
703
 *
704
 * apalSPIConfig_t
705
 *   Type to represent SPI a configuration object.
706
 *   Is only used via pointer by the API.
707
 */
708

    
709
#ifdef __cplusplus
710
extern "C" {
711
#endif
712

    
713
#if !defined(apalSPITransmit) || defined(__DOXYGEN__)
714
  /**
715
   * @brief Transmit data to SPI.
716
   *
717
   * @param[in]   spid      The SPI driver to use.
718
   * @param[in]   data      Buffer containing data to send.
719
   * @param[in]   length    Number of bytes to send.
720
   *
721
   * @return The status indicates whether the function call was succesful.
722
   */
723
  apalExitStatus_t apalSPITransmit(apalSPIDriver_t* spid, const uint8_t* const data, const size_t length);
724
#endif
725

    
726
#if !defined(apalSPIReceive) || defined(__DOXYGEN__)
727
  /**
728
   * @brief Receive data from SPI.
729
   *
730
   * @param[in]   spid      The SPI driver to use.
731
   * @param[out]  data      Buffer to store receied data.
732
   * @param[in]   length    Number of bytes to receive.
733
   *
734
   * @return The status indicates whether the function call was succesful.
735
   */
736
  apalExitStatus_t apalSPIReceive(apalSPIDriver_t* spid, uint8_t* const data, const size_t length);
737
#endif
738

    
739
#if !defined(apalSPITransmitAndReceive) || defined(__DOXYGEN__)
740
  /**
741
   * @brief Transmit data to SPI and receive data afterwards without releasing the bus in between.
742
   *
743
   * @param[in]   spid        The SPI driver to use.
744
   * @param[in]   txData      Transmit data buffer.
745
   * @param[in]   rxData      Receive data buffer.
746
   * @param[in]   txLength    Number of bytes to send.
747
   * @param[in]   rxLength    Number of bytes to receive.
748
   *
749
   * @return The status indicates whether the function call was succesful.
750
   */
751
  apalExitStatus_t apalSPITransmitAndReceive(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t txLength, const size_t rxLength);
752
#endif
753

    
754
#if !defined(apalSPIExchange) || defined(__DOXYGEN__)
755
  /**
756
   * @brief Transmit and receive data from SPI simultaneously.
757
   *
758
   * @param[in]   spid      The SPI driver to use.
759
   * @param[in]   txData    Buffer containing data to send.
760
   * @param[out]  rxData    Buffer to store received data.
761
   * @param[in]   length    Number of bytes to send and receive.
762
   *
763
   * @return The status indicates whether the function call was succesful.
764
   */
765
  apalExitStatus_t apalSPIExchange(apalSPIDriver_t* spid, const uint8_t* const txData , uint8_t* const rxData, const size_t length);
766
#endif
767

    
768
#if !defined(apalSPIReconfigure) || defined(__DOXYGEN__)
769
  /**
770
   * @brief Reconfigure an SPI driver.
771
   *
772
   * @param[in] spid    The SPI driver to be reconfigured.
773
   * @param[in] config  Configuration to apply.
774
   *
775
   * @return The status indicates whether the function call was succesful.
776
   */
777
  apalExitStatus_t apalSPIReconfigure(apalSPIDriver_t* spid, const apalSPIConfig_t* config);
778
#endif
779

    
780
#ifdef __cplusplus
781
}
782
#endif
783

    
784
#endif /* (AMIROLLD_CFG_SPI == true) */
785

    
786
#endif /* AMIROOS_PERIPHAL_H */