m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_spi.h
Go to the documentation of this file.
1 /* $version: 252203 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
29 #ifndef M2M_M2MB_SPI_API_H
30 #define M2M_M2MB_SPI_API_H
31 
32 /* Global declarations ==========================================================================*/
33 #ifndef NULL
34 #define NULL 0
35 #endif
36 
37 /* Global enums ==============================================================================*/
38 
39 enum M2MB_SPI_IOCTL_REQUEST
40 {
41  M2MB_SPI_IOCTL_SET_CFG = 0, /* set whole spi device configuration */
42  M2MB_SPI_IOCTL_GET_CFG, /* get whole spi device configuration */
43  M2MB_SPI_IOCTL_SET_SHIFT_MODE, /* set spi device shift mode */
44  M2MB_SPI_IOCTL_GET_SHIFT_MODE, /* get spi device shift mode */
45  M2MB_SPI_IOCTL_SET_CS_POLARITY, /* set spi device CS polarity */
46  M2MB_SPI_IOCTL_GET_CS_POLARITY, /* get spi device CS polarity */
47  M2MB_SPI_IOCTL_SET_CS_MODE, /* set spi device CS mode */
48  M2MB_SPI_IOCTL_GET_CS_MODE, /* get spi device CS mode */
49  M2MB_SPI_IOCTL_SET_BYTE_ORDER, /* set spi device endianness */
50  M2MB_SPI_IOCTL_GET_BYTE_ORDER, /* get spi device endianness */
51  M2MB_SPI_IOCTL_SET_CALLBACK_FN, /* set spi device callback function */
52  M2MB_SPI_IOCTL_GET_CALLBACK_FN, /* get spi device callback function */
53  M2MB_SPI_IOCTL_SET_CALLBACK_CTXT, /* set spi device callback context */
54  M2MB_SPI_IOCTL_GET_CALLBACK_CTXT, /* get spi device callback context */
55  M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ, /* set spi device clock frequency in Hz */
56  M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ, /* get spi device clock frequency in Hz */
57  M2MB_SPI_IOCTL_SET_BITS_PER_WORD, /* set spi device bits per word */
58  M2MB_SPI_IOCTL_GET_BITS_PER_WORD, /* get spi device bits per word */
59  M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES, /* set spi device cs_clk_delay_cycles */
60  M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES, /* get spi device cs_clk_delay_cycles */
61  M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES, /* set spi device inter_word_delay_cycles */
62  M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES, /* get spi device inter_word_delay_cycles */
63  M2MB_SPI_IOCTL_SET_LOOPBACK_MODE, /* set spi device loopback mode */
64  M2MB_SPI_IOCTL_GET_LOOPBACK_MODE, /* get spi device loopback mode */
65  M2MB_SPI_IOCTL_NOF_REQ /* number of m2mb ioctl requests */
66 };
67 
68 /* Global typedefs ==============================================================================*/
69 
70 /* SPI phase type.
71  This type defines the clock phase that the client can set in the
72  SPI configuration.
73 */
74 typedef enum
75 {
76  M2MB_SPI_MODE_0, /* CPOL = 0, CPHA = 0 */
77  M2MB_SPI_MODE_1, /* CPOL = 0, CPHA = 1 */
78  M2MB_SPI_MODE_2, /* CPOL = 1, CPHA = 0 */
79  M2MB_SPI_MODE_3, /* CPOL = 1, CPHA = 1 */
80  M2MB_SPI_MODE_INVALID = 0x7FFFFFFF
81 } M2MB_SPI_SHIFT_MODE_T;
82 
83 /* SPI chip select polarity type.
84 */
85 typedef enum
86 {
87  M2MB_SPI_CS_ACTIVE_LOW, /* During Idle state, the CS line is held low */
88  M2MB_SPI_CS_ACTIVE_HIGH, /* During Idle state, the CS line is held high */
89  M2MB_SPI_CS_ACTIVE_INVALID = 0x7FFFFFFF
90 } M2MB_SPI_CS_POLARITY_T;
91 
92 /* SPI chip select assertion type.
93  This type defines how the chip select line is configured between N word cycles.
94 */
95 typedef enum
96 {
97  M2MB_SPI_CS_DEASSERT, /* CS is deasserted after transferring data for N clock cycles */
98  M2MB_SPI_CS_KEEP_ASSERTED, /* CS is asserted as long as the core is in the Run state */
99  M2MB_SPI_CS_MODE_INVALID = 0x7FFFFFFF
100 } M2MB_SPI_CS_MODE_T;
101 
102 /* Order in which bytes from Tx/Rx buffer words are put on the bus.
103 */
104 typedef enum
105 {
106  M2MB_SPI_NATIVE = 0, /* Native */
107  M2MB_SPI_LITTLE_ENDIAN = 0, /* Little Endian */
108  M2MB_SPI_BIG_ENDIAN /* Big Endian (network) */
109 } M2MB_SPI_BYTE_ORDER_T;
110 
111 typedef enum
112 {
113  M2MB_SPI_EV
114 } M2MB_SPI_IND_E;
115 
116 typedef void ( *m2mb_spi_ind_callback )( INT32 fd, M2MB_SPI_IND_E spi_event, UINT16 resp_size, void *resp_struct, void *userdata );
117 
118 /* SPI configuration.
119  The SPI configuration is the collection of settings specified for each SPI
120  transfer call to select the various possible SPI transfer parameters.
121 */
122 typedef struct
123 {
124  M2MB_SPI_SHIFT_MODE_T spi_mode; /* Shift mode */
125  M2MB_SPI_CS_POLARITY_T cs_polarity; /* CS polarity */
126  M2MB_SPI_CS_MODE_T cs_mode; /* CS mode */
127  M2MB_SPI_BYTE_ORDER_T endianness; /* Endianness */
128  m2mb_spi_ind_callback callback_fn; /* Callback function; if NULL, transfer operates in synchronous mode */
129  HANDLE callback_ctxt; /* Pointer to a client object that will be returned as an argument to callback_fn */
130  UINT32 clk_freq_Hz; /* Host sets the SPI clock frequency closest (>=) to the requested frequency. Must be at least 62500 */
131  UINT8 bits_per_word; /* bits per word; any value from 3 to 31 */
132  UINT8 cs_clk_delay_cycles; /* Number of clock cycles to wait after asserting CS before starting transfer */
133  UINT8 inter_word_delay_cycles; /* Number of clock cycles to wait between SPI words */
134  BOOLEAN loopback_mode; /* Normally 0. If set, the SPI controller will enable Loopback mode;
135  used primarily for testing */
136 } M2MB_SPI_CFG_T;
137 
138 /* Global functions =============================================================================*/
139 
140 /*-----------------------------------------------------------------------------------------------*/
141 /* m2mb_spi_open:
142  description:
143  open a SPI device
144  arguments:
145  path: /dev/spidevX.Y where
146  X is the HW SPI master instance index (from 1 to 6). Default is 5.
147  Y is the SPI slave device index. Default is 0.
148  Path "/dev/spidevX" is equivalent to default "/dev/spidevX.0"
149  Path "/dev/spidev" is equivalent to default "/dev/spidev5.0"
150  flags: currently unused
151  return:
152  file descriptor on SUCCESS
153  -1 on FAILURE
154  i.e.: fd = m2mb_spi_open( "/dev/spidev5.0", 0 );
155  Please note that in some modules SPI functionality works only if USIF1 port is not occupied,
156  because they share the same pins. In these cases the customer should select a port variant that
157  does not contemplate an AT instance on USIF1 port.
158 */
159 INT32 m2mb_spi_open( const CHAR *path, INT32 flags, ... );
160 
161 /*-----------------------------------------------------------------------------------------------*/
162 /* m2mb_spi_close:
163  description:
164  close a SPI device
165  arguments:
166  fd: file descriptor returned by m2mb_spi_open
167  return:
168  0 on SUCCESS
169  -1 on FAILURE
170 */
171 INT32 m2mb_spi_close( INT32 fd );
172 
173 /*-----------------------------------------------------------------------------------------------*/
174 /* m2mb_spi_ioctl:
175  description:
176  configure a SPI device
177  arguments:
178  fd: file descriptor returned by m2mb_spi_open
179  request: required operation (see M2MB_SPI_IOCTL_REQUEST)
180  cfg_ptr: pointer to the set/get val, casted to void*
181  return:
182  0 on SUCCESS
183  -1 on FAILURE
184  i.e. m2mb_spi_ioctl(fd, M2MB_SPI_IOCTL_SET_CFG, (void *)&config)
185  where config is a M2MB_SPI_CFG_T struct
186  Please note that in some modules SPI functionality works only if USIF1 port is not occupied,
187  because they share the same pins. In these cases the customer should select a port variant that
188  does not contemplate an AT instance on USIF1 port.
189 */
190 INT32 m2mb_spi_ioctl( INT32 fd, INT32 request, ... );
191 
192 /*-----------------------------------------------------------------------------------------------*/
193 /* m2mb_spi_read:
194  description:
195  read nbyte Bytes from a SPI device into the array pointed by buf
196  arguments:
197  fd: file descriptor returned by m2mb_spi_open
198  buf: destination buffer, previously allocated
199  nbyte: length of destination buffer in Bytes
200  returns:
201  number of read Bytes on SUCCESS
202  -1 on FAILURE
203 */
204 SSIZE_T m2mb_spi_read( INT32 fd, void *buf, SIZE_T nbyte );
205 
206 /*-----------------------------------------------------------------------------------------------*/
207 /* m2mb_spi_write:
208  description:
209  write nbyte Bytes from the array pointed by buf to a SPI device
210  arguments:
211  fd: file descriptor returned by m2mb_spi_open
212  buf: source buffer, previously allocated
213  nbyte: length of source buffer in Bytes
214  returns:
215  number of written Bytes on SUCCESS
216  -1 on FAILURE
217 */
218 SSIZE_T m2mb_spi_write( INT32 fd, const void *buf, SIZE_T nbyte );
219 
220 /*-----------------------------------------------------------------------------------------------*/
221 /* m2mb_spi_write_read:
222  description:
223  perform a bi-directional (full duplex) transfer.
224  Read nbyte Bytes from a SPI device into the buffer bufRd
225  and write nbyte Bytes from the buffer bufWr to a SPI device
226  arguments:
227  fd: file descriptor returned by m2mb_spi_open
228  bufWr: source buffer, previously allocated
229  bufRd: destination buffer, previously allocated
230  nbyte: length of source and destination buffers in Bytes
231  returns:
232  number of written/read Bytes on SUCCESS
233  -1 on FAILURE
234 */
235 SSIZE_T m2mb_spi_write_read( INT32 fd, const void *bufWr, void *bufRd, SIZE_T nbyte );
236 
237 #endif /* M2M_M2MB_SPI_API_H */
238 
239 
M2MB_SPI_CFG_T
Definition: m2mb_spi.h:122