| ISF 2.1 Intelligent Sensing Framework for Kinetis with Processor Expert

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_spi_master_adapter.h
Go to the documentation of this file.
1 /*!
2 ********************************************************************************
3 * File: isf_spi_master_adapter.h
4 *
5 * Copyright (c) 2014, Freescale Semiconductor, Inc.
6 *
7 *******************************************************************************/
8 /*!
9 * @file isf_spi_master_adapter.h
10 * @brief \b isf_spi_master_adapter.h defines the API definitions and types for the spi master protocol adapter.
11 */
12 #ifndef ISF_SPI_MASTER_ADAPTER_H_
13 #define ISF_SPI_MASTER_ADAPTER_H_
14 #include "isf_spi_master_types.h"
15 #include "fsl_spi_master_driver.h"
16 #include "fsl_spi_hal.h"
17 #include "isf_comm.h"
18 #include "isf_protocol_adapter.h"
19 /*! @brief This structure defines a device endpoint encapsulation for spi handler. */
20 typedef struct spi_master_Endpoint_struct
21 {
22 busHandle_t* pBusHandle; /*!< The pointer to the bus handle. */
23 spi_master_slaveInfo_t* pSlaveInfo;
24 }spi_master_Endpoint_t;
25 /*! Type specifying for the spi modes */
26 enum spi_comm_flag {
27 SPI_SYNC = 0, /*!< Read/write in synchronized mode.*/
28 SPI_ASYNC = 1, /*!< Read/Write in asynchronized mode.*/
29 };
30
31 enum spi_lock_type{
32 SPI_LOCK_COMMON,
33 SPI_LOCK_READ,
34 };
35
36 typedef comm_Flags_t spi_master_writeFlags_t;
37 typedef comm_Flags_t spi_master_readFlags_t;
38 /*! @brief This function initializes a spi bus.
39 *
40 * @details A bus must be initialized prior to use. Initialization creates the bus and initializes the data structures required to manage the bus.
41 *
42 * @param[in] aBusId The ID of the bus to initialize. This is an index into the array of known spi buses that can be used.
43 * @param[out] busHandle_t The handle to the bus to be initialized.
44 *
45 * @return ::spi_master_adapter_init() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
46 * @retval ::ISF_SUCCESS is returned when the bus is initialized successfully and the apBusHandle structure reference has been
47 * populated with initialized spi bus data.
48 * @retval ::COMM_ERROR_NOEXIST is returned when the supplied bus identifier does not exist.
49 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
50 * @retval ::COMM_ERROR_INIT is returned when the bus could not be initialized.
51 *
52 *
53 * @Constraints None
54 *
55 * @Reentrant Yes
56 * @Libs None
57 */
58 isf_status_t spi_master_adapter_init(comm_Id_t aBusId, busHandle_t *apBusHandle);
59 /*! @brief This function reconfigures an already initialized bus.
60 *
61 * @details A bus may be reconfigured after initialization. Calls to spi_master_adapter_configure() after initialization will override any previous
62 * configuration values and must be made while the bus state is ::COMM_STATE_STOPPED. The typical usage involves retrieving the
63 * current configuration using ::spi_master_adapter_get_config(), making modifications to the returned configuration, and then calling
64 * spi_master_adapter_configure() with the updated configuration. The bus is implicitly locked during the configuration.
65 *
66 * @param[in] busHandle_t The handle of the bus to be configured.
67 * @param[in] apBusConfig The configuration value for the bus to be configured.
68 *
69 * @return ::spi_master_adapter_configure() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
70 * @retval ::ISF_SUCCESS is returned when the bus was reconfigured successfully.
71 * @retval ::COMM_ERROR_STOP is returned when the bus was not STOPPED.
72 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
73 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
74 *
75 *
76 * @Constraints The following constraints must be observed when using this function:
77 * @li apBusHandle must be valid. A valid spi bus handler is created
78 * when the ::spi_master_adapter_init() function call is successfully returned.
79 *
80 * @Reentrant Yes
81 * @Libs None
82 */
83 isf_status_t spi_master_adapter_configure(busHandle_t *apBusHandle, spi_master_busConfig_t* apBusConfig);
84 /*! @brief This function returns the current bus state.
85 *
86 * @details A bus may be queried for its current state.
87 *
88 * @param[in] apBusHandle The handle of the bus to be queried.
89 *
90 * @return ::spi_master_adapter_get_state() returns a value of type
91 * ::comm_State_t indicating the current state of the bus.
92 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
93 *
94 * @Constraints The following constraints must be observed when using this function:
95 * @li apBusHandle must be valid. A valid spi bus handle is created when ::spi_master_adapter_init() function call returns successfully.
96 *
97 * @Reentrant Yes
98 * @Libs None.
99 */
100 comm_State_t spi_master_adapter_get_state(busHandle_t *apBusHandle);
101 /*! @brief This function returns the current bus configuration.
102 *
103 * @details A bus may be queried for the current configuration.
104 *
105 * @param[in] apBusHandle The handle of the bus to be queried.
106 * @param[out] apBusConfig The address of a bus configuration to be filled.
107 *
108 * @return ::spi_master_adapter_get_config() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
109 * @retval ::ISF_SUCCESS is returned when the bus configuration is retrieved successfully.
110 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
111 * @retval ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized bus.
112
113 * @Constraints The following constraints must be observed when using this function:
114 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
115 *
116 * @Reentrant Yes
117 * @Libs None
118 */
119 isf_status_t spi_master_adapter_get_config(busHandle_t *apBusHandle, void* apBusConfig);
120 /*! @brief This function locks the bus for exclusive access.
121 *
122 * @details spi_master_adapter_acquire_lock() serializes multi-client access. While holding the bus lock,
123 * no other clients may perform any bus operations. Therefore, it is important to release the lock
124 * with ::spi_master_adapter_release_lock() as soon as practical.
125 *
126 * @param[in] apBusHandle The handle of the bus to be started.
127 * @param[in] aTimeout The time to wait for the lock before returning without the lock. The timeout parameter may be set to zero to wait for calls that fail to return without
128 * acquiring the lock, or wait as long as necessary for the lock to be acquired.
129 * @return ::dm_channel_acquire_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
130 * @retval ::ISF_SUCCESS is returned when the bus lock is acquired.
131 * @retval ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized channel.
132 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
133 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
134 *
135 * @Constraints The following constraints must be observed when using this function:
136 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
137 *
138 * @Reentrant Yes
139 * @Libs None
140 */
141 isf_status_t spi_master_adapter_acquire_lock(busHandle_t *apBusHandle, isf_duration_t aTimeout );
142 /*! @brief This function releases exclusive bus access.
143 *
144 * @details spi_master_adapter_release_lock() is used to relinquish exclusive access on a particular bus. It is the inverse of ::spi_master_adapter_acquire_lock().
145 *
146 * @param[in] apBusHandle The handle of the bus to unlock.
147 * @return ::spi_master_adapter_release_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
148 * @retval ::ISF_SUCCESS is returned when the bus released successfully.
149 * @retval ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized channel.
150 * @retval ::COMM_ERROR_LOCK is returned when no lock was held on the specified bus.
151 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
152 *
153 * @Constraints The following constraints must be observed when using this function:
154 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
155 *
156 * @Reentrant Yes
157 * @Libs None
158 */
159 isf_status_t spi_master_adapter_release_lock(busHandle_t *apBusHandle);
160 /*! @brief This function starts a bus.
161 *
162 * @details spi_master_adapter_start() enables communications with an initialized bus.
163 * @param[in] apBusHandle The handle of the bus to be started.
164 * @return ::spi_master_adapter_start() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
165 * @retval ::ISF_SUCCESS is returned when the bus was started successfully.
166 * @retval ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized channel.
167 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
168 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
169 *
170 * @Constraints The following constraints must be observed when using this function:
171 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
172 *
173 * @Reentrant Yes
174 * @Libs None
175 */
176 isf_status_t spi_master_adapter_start(busHandle_t *apBusHandle);
177 /*! @brief This function stops the given spi bus.
178 *
179 * @details spi_master_adapter_stop() disables an initialized bus and stops communications with the channel.
180 *
181 * @param[in] apBusHandle The handle of the bus to be stopped.
182 * @return ::spi_master_adapter_stop() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
183 *
184 * @retval ::ISF_SUCCESS is returned when the bus is successfully stopped.
185 * @retval ::COMM_ERROR_INIT is returned when the bus handle refers to a non-initialized channel.
186 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
187 *
188 * @Constraints The following constraints must be observed when using this function:
189 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
190 *
191 * @Reentrant Yes
192 * @Libs None
193 */
194 isf_status_t spi_master_adapter_stop(busHandle_t *apBusHandle);
195 /*! @brief This function creates a endpoint for a device at a specified bus address.
196 *
197 * @details The spi_master_adapter_get_endpoint() function may be used to get a handle to a device at a known bus address.
198 *
199 * @param[in] apBusHandle The handle of the bus to be opened.
200 * @param[in] apDevice The known information of the device to be opened.
201 * @param[out] apEndpointHandle The address of a apEndpointHandle to be filled.
202 *
203 * @return ::spi_master_adapter_get_endpoint() returns a value of type ::isf_status_t indicating the success or failure of the function call.
204 *
205 * @retval ::ISF_SUCCESS is returned when the device is located and a valid handle is returned.
206 * @retval ::COMM_ERROR_NOEXIST is returned when a device does not exist at the specified bus.
207 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
208 * @retval ::COMM_ERROR_STOP is returned when the channel has not been started.
209 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
210 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
211 *
212 * @Constraints The following constraints must be observed when using this function:
213 * @li apBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
214 *
215 * @Reentrant Yes
216 * @Libs isf_core.lib
217 */
218 isf_status_t spi_master_adapter_get_endpoint(busHandle_t *apBusHandle, void *apDevice , void** apEndpointHandle);
219 /*! @brief This function closes a particular endpoint.
220 *
221 * @details The spi_master_adapter_release_endpoint() function is used when no further communication with the device is needed. A closed device should not be
222 * passed to ::spi_master_adapter_write() or ::spi_master_adapter_write().
223 *
224 * @param[in] apEndpoint The address of the end point where the endpoint is established.
225 * @return ::spi_master_adapter_release_endpoint() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
226 * @retval ::ISF_SUCCESS is returned when the device changes to closed.
227 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
228 *
229 * @Constraints The following constraints must be observed when using this function:
230 * @li pBusHandle must be valid. A valid spi bus handle is created when the ::spi_master_adapter_init() function call returns successfully.
231 *
232 * @Reentrant Yes
233 * @Libs None
234 */
235 isf_status_t spi_master_adapter_release_endpoint(spi_master_Endpoint_t *apEndpoint);
236 /*! @brief This function writes to a spi device.
237 *
238 * @details spi_master_adapter_write () writes data to the specified device. The device is implicitly locked during the write.
239 *
240 * @param[in] apEndpointHandle The handle to the device endpoint to which to write is performed.
241 * @param[in] offset The read offset/sub address from which the data to be write.
242 * @param[in] apWriteBuffer The buffer address where write data is placed.
243 * @param[in] aBuffsize The size of the buffer passed.
244 * @param[in] aNbyteRead The number of bytes to write to the device.
245 * @param[in] aFlags The write flag that change the mode of read of operation.
246 * @return ::spi_master_adapter_write() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
247 * @retval ::ISF_SUCCESS is returned when the device was written successfully.
248 * @retval ::COMM_ERROR_STOP is returned when the write is invoked on a stopped channel.
249 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
250 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
251 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
252 *
253 * @Constraints The following constraints must be observed when using this function:
254 * @li apEndpointHandle must be valid. A valid device endpoint handle is created when the ::spi_master_adapter_get_endpoint() function returns successfully.
255 *
256 * @Reentrant Yes
257 * @Libs isf_core.lib
258 */
259 isf_status_t spi_master_adapter_write(void* apEndpointHandle, int32 offset, void* apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite, spi_master_writeFlags_t aFlags);
260 /*! @brief This function reads from a spi device.
261 *
262 * @details spi_master_adapter_read() reads data from the specified device. The supplied command is sent to the device triggering the
263 * device to return some data. Any data returned by the device is read and placed in the provided read buffer.
264 * The device is implicitly locked during the read.
265 *
266 * @param[in] apEndpointHandle The handle to the device endpoint for.
267 * @param[in] offset The read offset/sub address from which the data to be read.
268 * @param[in] apReadBuffer The buffer address where any returned data is placed.
269 * @param[in] aBuffsize The size of the buffer passed.
270 * @param[in] aNbyteRead The number of bytes to read from the device.
271 * @param[in] aFlags The read flag that change the mode of read of operation.
272
273 * @return ::spi_master_adapter_read() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
274 *
275 * @retval ::ISF_SUCCESS is returned when data from the device was read successfully.
276 * @retval ::COMM_ERROR_BUF_SIZE is returned when the provided buffer is too small to hold all the data or the number of bytes read is zero.
277 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
278 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
279 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
280 *
281 * @Constraints The following constraints must be observed when using this function:
282 * @li apEndpointHandle must be valid. A valid device endpoint handle is created when the ::spi_master_adapter_get_endpoint() function returns successfully.
283 *
284 * @Reentrant Yes
285 * @Libs None
286 */
287 isf_status_t spi_master_adapter_read(void* apEndpointHandle, int32 offset, void* apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead, spi_master_readFlags_t aFlags);
288
289
290 #endif /* ISF_SPI_MASTER_ADAPTER_H_ */
291
292
spi_master_adapter_configure
isf_status_t spi_master_adapter_configure(busHandle_t *apBusHandle, spi_master_busConfig_t *apBusConfig)
This function reconfigures an already initialized bus.
Definition: isf_spi_master_adapter.c:95
spi_master_adapter_get_config
isf_status_t spi_master_adapter_get_config(busHandle_t *apBusHandle, void *apBusConfig)
This function returns the current bus configuration.
Definition: isf_spi_master_adapter.c:138
spi_master_adapter_read
isf_status_t spi_master_adapter_read(void *apEndpointHandle, int32 offset, void *apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead, spi_master_readFlags_t aFlags)
This function reads from a spi device.
Definition: isf_spi_master_adapter.c:328
spi_master_Endpoint_struct::pBusHandle
busHandle_t * pBusHandle
Definition: isf_spi_master_adapter.h:22
comm_Id_t
uint32 comm_Id_t
This type is for a numeric channel identifier- index into an array of channels in the system...
Definition: isf_comm.h:50
SPI_LOCK_COMMON
Definition: isf_spi_master_adapter.h:32
fsl_spi_master_driver.h
fsl_spi_master_driver.h defines structures and types for the spi master driver.
spi_mater_slaveInfo
This structure defines the slave specific spi information.
Definition: isf_spi_master_types.h:46
spi_master_BusConfig_struct
Definition: isf_spi_master_types.h:17
spi_master_Endpoint_t
struct spi_master_Endpoint_struct spi_master_Endpoint_t
This structure defines a device endpoint encapsulation for spi handler.
uint32
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
spi_master_Endpoint_struct::pSlaveInfo
spi_master_slaveInfo_t * pSlaveInfo
Definition: isf_spi_master_adapter.h:23
spi_master_adapter_release_endpoint
isf_status_t spi_master_adapter_release_endpoint(spi_master_Endpoint_t *apEndpoint)
This function closes a particular endpoint.
Definition: isf_spi_master_adapter.c:267
spi_master_adapter_get_state
comm_State_t spi_master_adapter_get_state(busHandle_t *apBusHandle)
This function returns the current bus state.
Definition: isf_spi_master_adapter.c:124
fsl_spi_hal.h
fsl_spi_hal.h defines structures and types for the spi master HAL layer.
spi_master_adapter_init
isf_status_t spi_master_adapter_init(comm_Id_t aBusId, busHandle_t *apBusHandle)
This function initializes a spi bus.
Definition: isf_spi_master_adapter.c:45
spi_master_Endpoint_struct
This structure defines a device endpoint encapsulation for spi handler.
Definition: isf_spi_master_adapter.h:20
spi_master_readFlags_t
comm_Flags_t spi_master_readFlags_t
Definition: isf_spi_master_adapter.h:37
isf_protocol_adapter.h
isf_protocol_adapter.h defines the general interface definition for the protocol adapter.
spi_master_adapter_release_lock
isf_status_t spi_master_adapter_release_lock(busHandle_t *apBusHandle)
This function releases exclusive bus access.
Definition: isf_spi_master_adapter.c:173
spi_master_adapter_write
isf_status_t spi_master_adapter_write(void *apEndpointHandle, int32 offset, void *apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite, spi_master_writeFlags_t aFlags)
This function writes to a spi device.
Definition: isf_spi_master_adapter.c:282
spi_master_writeFlags_t
comm_Flags_t spi_master_writeFlags_t
Definition: isf_spi_master_adapter.h:36
SPI_LOCK_READ
Definition: isf_spi_master_adapter.h:33
busHandle_struct
This structure is a declaration of a BusHandle type.
Definition: isf_protocol_adapter.h:86
comm_Flags_t
uint8 comm_Flags_t
This is a bit array of flags governing device read/write behavior.
Definition: isf_comm.h:59
spi_master_adapter_stop
isf_status_t spi_master_adapter_stop(busHandle_t *apBusHandle)
This function stops the given spi bus.
Definition: isf_spi_master_adapter.c:211
SPI_SYNC
Definition: isf_spi_master_adapter.h:27
SPI_ASYNC
Definition: isf_spi_master_adapter.h:28
isf_duration_t
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:59
int32
long int32
This defines int32 as long.
Definition: isf_types.h:32
spi_comm_flag
spi_comm_flag
Definition: isf_spi_master_adapter.h:26
spi_lock_type
spi_lock_type
Definition: isf_spi_master_adapter.h:31
isf_status_t
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
spi_master_adapter_acquire_lock
isf_status_t spi_master_adapter_acquire_lock(busHandle_t *apBusHandle, isf_duration_t aTimeout)
This function locks the bus for exclusive access.
Definition: isf_spi_master_adapter.c:156
isf_spi_master_types.h
isf_spi_master_types.h defines the spi protocol adapter structure and types.
spi_master_adapter_get_endpoint
isf_status_t spi_master_adapter_get_endpoint(busHandle_t *apBusHandle, void *apDevice, void **apEndpointHandle)
This function creates a endpoint for a device at a specified bus address.
Definition: isf_spi_master_adapter.c:235
isf_comm.h
isf_comm.h defines the common types for the Communications Service Family of the Intelligent Sensing ...
comm_State_t
enum comm_State_vals comm_State_t
This enum holds an enumerated value describing the state of a channel.
Definition: isf_comm.h:53
spi_master_adapter_start
isf_status_t spi_master_adapter_start(busHandle_t *apBusHandle)
This function starts a bus.
Definition: isf_spi_master_adapter.c:189
- © Freescale Semiconductor, Inc. 2015. All Rights Reserved.