ChibiOS/HAL  6.1.0
hal_spi_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_spi_lld.h
19  * @brief PLATFORM SPI subsystem low level driver header.
20  *
21  * @addtogroup SPI
22  * @{
23  */
24 
25 #ifndef HAL_SPI_LLD_H
26 #define HAL_SPI_LLD_H
27 
28 #if (HAL_USE_SPI == TRUE) || defined(__DOXYGEN__)
29 
30 /*===========================================================================*/
31 /* Driver constants. */
32 /*===========================================================================*/
33 
34 /**
35  * @brief Circular mode support flag.
36  */
37 #define SPI_SUPPORTS_CIRCULAR TRUE
38 
39 /*===========================================================================*/
40 /* Driver pre-compile time settings. */
41 /*===========================================================================*/
42 
43 /**
44  * @name PLATFORM configuration options
45  * @{
46  */
47 /**
48  * @brief SPI1 driver enable switch.
49  * @details If set to @p TRUE the support for SPI1 is included.
50  * @note The default is @p FALSE.
51  */
52 #if !defined(PLATFORM_SPI_USE_SPI1) || defined(__DOXYGEN__)
53 #define PLATFORM_SPI_USE_SPI1 FALSE
54 #endif
55 /** @} */
56 
57 /*===========================================================================*/
58 /* Derived constants and error checks. */
59 /*===========================================================================*/
60 
61 /*===========================================================================*/
62 /* Driver data structures and types. */
63 /*===========================================================================*/
64 
65 /**
66  * @brief Type of a structure representing an SPI driver.
67  */
68 typedef struct SPIDriver SPIDriver;
69 
70 /**
71  * @brief SPI notification callback type.
72  *
73  * @param[in] spip pointer to the @p SPIDriver object triggering the
74  * callback
75  */
76 typedef void (*spicallback_t)(SPIDriver *spip);
77 
78 /**
79  * @brief Driver configuration structure.
80  * @note Implementations may extend this structure to contain more,
81  * architecture dependent, fields.
82  */
83 typedef struct {
84 #if (SPI_SUPPORTS_CIRCULAR == TRUE) || defined(__DOXYGEN__)
85  /**
86  * @brief Enables the circular buffer mode.
87  */
88  bool circular;
89 #endif
90  /**
91  * @brief Operation complete callback or @p NULL.
92  */
94 #if (SPI_SELECT_MODE == SPI_SELECT_MODE_LINE) || defined(__DOXYGEN__)
95  /**
96  * @brief The chip select line.
97  */
99 #endif
100 #if (SPI_SELECT_MODE == SPI_SELECT_MODE_PORT) || defined(__DOXYGEN__)
101  /**
102  * @brief The chip select port.
103  */
105  /**
106  * @brief The chip select port mask.
107  */
109 #endif
110 #if (SPI_SELECT_MODE == SPI_SELECT_MODE_PAD) || defined(__DOXYGEN__)
111  /**
112  * @brief The chip select port.
113  */
114  ioportid_t ssport;
115  /**
116  * @brief The chip select pad number.
117  */
118  uint_fast8_t sspad;
119 #endif
120  /* End of the mandatory fields.*/
121 } SPIConfig;
122 
123 /**
124  * @brief Structure representing an SPI driver.
125  * @note Implementations may extend this structure to contain more,
126  * architecture dependent, fields.
127  */
128 struct SPIDriver {
129  /**
130  * @brief Driver state.
131  */
133  /**
134  * @brief Current configuration data.
135  */
137 #if (SPI_USE_WAIT == TRUE) || defined(__DOXYGEN__)
138  /**
139  * @brief Waiting thread.
140  */
142 #endif
143 #if (SPI_USE_MUTUAL_EXCLUSION == TRUE) || defined(__DOXYGEN__)
144  /**
145  * @brief Mutex protecting the peripheral.
146  */
148 #endif
149 #if defined(SPI_DRIVER_EXT_FIELDS)
150  SPI_DRIVER_EXT_FIELDS
151 #endif
152  /* End of the mandatory fields.*/
153 };
154 
155 /*===========================================================================*/
156 /* Driver macros. */
157 /*===========================================================================*/
158 
159 /*===========================================================================*/
160 /* External declarations. */
161 /*===========================================================================*/
162 
163 #if (PLATFORM_SPI_USE_SPI1 == TRUE) && !defined(__DOXYGEN__)
164 extern SPIDriver SPID1;
165 #endif
166 
167 #ifdef __cplusplus
168 extern "C" {
169 #endif
170  void spi_lld_init(void);
171  void spi_lld_start(SPIDriver *spip);
172  void spi_lld_stop(SPIDriver *spip);
173 #if (SPI_SELECT_MODE == SPI_SELECT_MODE_LLD) || defined(__DOXYGEN__)
174  void spi_lld_select(SPIDriver *spip);
175  void spi_lld_unselect(SPIDriver *spip);
176 #endif
177  void spi_lld_select(SPIDriver *spip);
178  void spi_lld_unselect(SPIDriver *spip);
179  void spi_lld_ignore(SPIDriver *spip, size_t n);
180  void spi_lld_exchange(SPIDriver *spip, size_t n,
181  const void *txbuf, void *rxbuf);
182  void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf);
183  void spi_lld_receive(SPIDriver *spip, size_t n, void *rxbuf);
184 #if (SPI_SUPPORTS_CIRCULAR == TRUE) || defined(__DOXYGEN__)
185  void spi_lld_abort(SPIDriver *spip);
186 #endif
187  uint16_t spi_lld_polled_exchange(SPIDriver *spip, uint16_t frame);
188 #ifdef __cplusplus
189 }
190 #endif
191 
192 #endif /* HAL_USE_SPI == TRUE */
193 
194 #endif /* HAL_SPI_LLD_H */
195 
196 /** @} */
void spi_lld_ignore(SPIDriver *spip, size_t n)
Ignores data on the SPI bus.
Definition: hal_spi_lld.c:151
uint32_t ioportmask_t
Digital I/O port sized unsigned type.
Definition: hal_pal_lld.h:100
spistate_t
Driver state machine possible states.
Definition: hal_spi.h:107
void spi_lld_receive(SPIDriver *spip, size_t n, void *rxbuf)
Receives data from the SPI bus.
Definition: hal_spi_lld.c:217
uint32_t ioline_t
Type of an I/O line.
Definition: hal_pal_lld.h:110
void spi_lld_send(SPIDriver *spip, size_t n, const void *txbuf)
Sends data over the SPI bus.
Definition: hal_spi_lld.c:196
ioline_t ssline
The chip select line.
Definition: hal_spi_lld.h:98
const SPIConfig * config
Current configuration data.
Definition: hal_spi_lld.h:136
uint32_t ioportid_t
Port Identifier.
Definition: hal_pal_lld.h:118
uint_fast8_t sspad
The chip select pad number.
Definition: hal_spi_lld.h:118
void(* spicallback_t)(SPIDriver *spip)
SPI notification callback type.
Definition: hal_spi_lld.h:76
Driver configuration structure.
Definition: hal_spi_lld.h:83
void spi_lld_exchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf)
Exchanges data on the SPI bus.
Definition: hal_spi_lld.c:173
ioportmask_t ssmask
The chip select port mask.
Definition: hal_spi_lld.h:108
void spi_lld_stop(SPIDriver *spip)
Deactivates the SPI peripheral.
Definition: hal_spi_lld.c:101
void spi_lld_abort(SPIDriver *spip)
Aborts the ongoing SPI operation, if any.
Definition: hal_spi_lld.c:233
void spi_lld_start(SPIDriver *spip)
Configures and activates the SPI peripheral.
Definition: hal_spi_lld.c:80
void * thread_reference_t
Type of a thread reference.
Definition: osal.h:180
void spi_lld_init(void)
Low level SPI driver initialization.
Definition: hal_spi_lld.c:65
mutex_t mutex
Mutex protecting the peripheral.
Definition: hal_spi_lld.h:147
void spi_lld_unselect(SPIDriver *spip)
Deasserts the slave select signal.
Definition: hal_spi_lld.c:134
thread_reference_t thread
Waiting thread.
Definition: hal_spi_lld.h:141
bool circular
Enables the circular buffer mode.
Definition: hal_spi_lld.h:88
uint16_t spi_lld_polled_exchange(SPIDriver *spip, uint16_t frame)
Exchanges one frame using a polled wait.
Definition: hal_spi_lld.c:253
uint32_t mutex_t
Type of a mutex.
Definition: osal.h:223
void spi_lld_select(SPIDriver *spip)
Asserts the slave select signal and prepares for transfers.
Definition: hal_spi_lld.c:120
spicallback_t end_cb
Operation complete callback or NULL.
Definition: hal_spi_lld.h:93
ioportid_t ssport
The chip select port.
Definition: hal_spi_lld.h:104
SPIDriver SPID1
SPI1 driver identifier.
Definition: hal_spi_lld.c:41
Structure representing an SPI driver.
Definition: hal_spi_lld.h:128
spistate_t state
Driver state.
Definition: hal_spi_lld.h:132