blob: 2ff190859b089ba127af549b211dc86998326b80 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
#pragma once
#include "pb-types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* \ingroup pbdrv-mod
* \defgroup pb_mod Module
* \brief Metadata and auxiliary utility functions
* \{
*/
/**
* \brief Puzzle module name
*
* Optional to define, default value is "???"
*/
extern const char * PB_MOD_NAME;
/**
* \brief Puzzle module bus address
*
* **Required** to define
*/
extern const i2c_addr_t PB_MOD_ADDR;
/**
* \brief Platform-specific blocking delay function
*
* FIXME: this should be removed (see handover: RP2040 I2C limitations)
*/
void pb_mod_blocking_delay_ms(unsigned long ms);
/// \}
/**
* \ingroup pbdrv-mod
* \defgroup pb_i2c I2C
* \brief I2C send/receive handlers
*
* If there is no existing \ref pb_drv "driver" for the microcontroller on
* which you want to use the puzzle bus driver, you may implement the following
* in order to use pbdrv:
*
* - The \c pb_i2c_recv() function must be **called** for every received I2C
* message
* - The \c pb_i2c_send() function must be **implemented** using the
* platform/device-specific I2C write function
*
* \{
*/
/**
* \brief handle a received message from the I2C bus (puzzle bus)
*
* This function attempts to parse an I2C message as a puzzle bus message, and
* calls the appropriate handler for the message if it is considered valid.
* Invalid messages are silently ignored.
*
* \param buf pointer to message content
* \param sz size of \p buf
*
* \note This function should not be directly called from an ISR. Please use
* FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based
* deferred function call mechanism instead.
*/
void pb_i2c_recv(const uint8_t * buf, size_t sz);
/**
* \brief send a message in master-mode on the I2C bus (puzzle bus)
*
* This function sends an I2C message to the address specified by \p i2c_addr.
*
* \param i2c_addr address of slave controller
* \param buf pointer to message content
* \param sz size of \p buf
*/
void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz);
/// \}
/// \ingroup hook
/// \{
/**
* \defgroup pb_hook_mod_state State
* \brief Provide your own global state variable
*
* If your puzzle module defines its own global \c pb_global_state_t, you can
* tell the driver to use it by implementing these functions. These functions
* are also used internally by the driver when creating \c STATE \c REQ and \c
* STATE \c RES commands.
*
* \{
*/
/**
* \brief global state read hook
* \return current value of global state enum
*/
pb_global_state_t pb_hook_mod_state_read();
/**
* \brief global state write hook
* \param state new value of global state enum
*/
void pb_hook_mod_state_write(pb_global_state_t state);
/// \}
/// \}
#ifdef __cplusplus
}
#endif
|