| ISF 2.2 rev 5 Intelligent Sensing Framework for Kinetis with Processor Expert

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

isf_devmsg.h
Go to the documentation of this file.
1 /*!
2 ********************************************************************************
3 * File: isf_devmsg.h
4 *
5 * Copyright (c) 2015, Freescale Semiconductor, Inc.
6 *
7 *******************************************************************************/
8 /*!
9 * @file isf_devmsg.h
10 * @brief \b isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component.
11 */
12 #ifndef INCLUDE_DEVICE_MESSAGING_H
13 #define INCLUDE_DEVICE_MESSAGING_H
14
15 #include <isf.h>
16 #include <isf_comm.h>
17 #include "isf_protocol_adapter.h"
18
19 /*******************
20 ** Macro Definitions
21 */
22
23 /**************
24 ** Enumerations
25 */
26
27 /*********************
28 ** Structures and Typedefs
29 */
30
31 /*! @brief This typedef is a numeric channel identifier index into an array of channels
32 * in the system. */
33 typedef comm_Id_t dm_ChannelId_t;
34
35 /*! @brief This structure defines the user-specified parameters for channel
36 * configuration.
37 *
38 * This type allows the device messaging APIs to handle a
39 * protocol-specific configuration pointer opaquely until it is passed to
40 * the specific protocol functions that use the data.
41 */
42 typedef void* dm_ChannelConfig_ptr;
43
44 /*! @brief This structure is a declaration of a channel descriptor type.
45 * @details The channel descriptor contains the bus and protocol information required by the
46 * device messaging functions to safely use a channel for communications. The
47 * members are ordered to maintain natural alignment without inserting padding
48 * bytes.
49 */
50 typedef struct dm_ChannelDescriptor_struct {
51 busHandle_t busHandle;
52 const protocol_t * pProtocol; /*!< The pointer to protocol-specific functions and properties. */
53
54 } dm_ChannelDescriptor_t;
55
56
57 /*! @brief This structure defines a handle for the device.
58 * @details The device handle contains the information required by the device
59 * messaging functions to address and communicate with a slave device.
60 */
61 typedef struct dm_DeviceDescriptor_struct {
62 dm_ChannelDescriptor_t * pChannelDescriptor; /*!< The pointer to the channel descriptor. */
63 void *pEndpointHandle; /*!< The protocol-specific endpoint handle. */
64 } dm_DeviceDescriptor_t;
65 /*! @brief This macro defines the invalid offset for the read and write functions.
66 */
67 #define INVALID_OFFSET (-1)
68 /*********************
69 ** Function Prototypes
70 */
71
72 /**
73 * @name Initialization Routines
74 * @{ */
75
76 /*! @brief This function initializes a channel.
77 *
78 * @details A channel must be initialized prior to use. Initialization creates the channel and initializes the data structures required to manage the channel. The channel is implicitly locked
79 * during the initialization.
80 *
81 * @param[in] aChannelId The ID of the channel to initialize. This is an index into the array of known channels that can be used.
82 * @param[out] apChannelDescriptor The address of the channel descriptor structure to be initialized.
83 *
84 * @return ::dm_channel_init() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
85 * @retval ::ISF_SUCCESS is returned when the channel initialized successfully and the apChannelDescriptor structure reference has been
86 * populated with initialized channel data.
87 * @retval ::COMM_ERROR_NOEXIST is returned when the supplied channel identifier does not exist.
88 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
89 * @retval ::COMM_ERROR_INIT is returned when the channel could not be initialized.
90 *
91 * @Reentrant Yes
92 * @Libs None
93 */
94 isf_status_t dm_channel_init(
95 dm_ChannelId_t aChannelId,
96 dm_ChannelDescriptor_t *apChannelDescriptor
97 );
98
99 /*! @brief This function reconfigures an already initialized channel.
100 *
101 * @details A channel may be reconfigured after initialization. Calls to dm_channel_configure() after initialization will override any previous
102 * configuration values and must be made while the channel state is ::COMM_STATE_STOPPED. The typical usage involves retrieving the
103 * current configuration using ::dm_channel_get_config(), making modifications to the returned configuration, and then calling
104 * dm_channel_configure() with the updated configuration. The channel is implicitly locked during the configuration.
105 *
106 * @param[in] apChannelDescriptor The handle of the channel to be configured.
107 * @param[in] apChannelConfig The channel configuration used during initialization.
108 *
109 * @return ::dm_channel_configure() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
110 * @retval ::ISF_SUCCESS is returned when the channel was reconfigured successfully.
111 * @retval ::COMM_ERROR_STOP is returned when the channel was not STOPPED.
112 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
113 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
114 *
115 *
116 * @Constraints The following constraints must be observed when using this function:
117 * @li apChannelDescriptor must be valid. A valid channel descriptor is created
118 * when the ::dm_channel_init() function call is successfully returned.
119 *
120 * @Reentrant Yes
121 * @Libs None
122 */
123 isf_status_t dm_channel_configure(
124 dm_ChannelDescriptor_t *apChannelDescriptor,
125 dm_ChannelConfig_ptr apChannelConfig
126 );
127
128 /** @} */
129
130 /**
131 * @name Queries and Status
132 * @{ */
133
134 /*! @brief This function returns the channel state.
135 *
136 * @details A channel may be queried for its current state.
137 *
138 * @param[in] apChannelDescriptor The handle of the channel to be queried.
139 *
140 * @return ::dm_channel_get_state() returns a value of type
141 * ::comm_State_t indicating the current state of the channel.
142 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
143 *
144 * @Constraints The following constraints must be observed when using this function:
145 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when ::dm_channel_init() function call returns successfully.
146 *
147 * @Reentrant Yes
148 * @Libs None
149 */
150 comm_State_t dm_channel_get_state(dm_ChannelDescriptor_t *apChannelDescriptor);
151
152 /*! @brief This function returns the current channel configuration.
153 *
154 * @details A channel may be queried for the current configuration.
155 *
156 * @param[in] apChannelDescriptor The handle of the channel to be configured.
157 * @param[out] apChannelConfig The address of a channel configuration to be filled.
158 *
159 * @return ::dm_channel_get_config() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
160 * @retval ::ISF_SUCCESS is returned when the channel configuration is retrieved successfully.
161 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
162 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
163
164 * @Constraints The following constraints must be observed when using this function:
165 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully.
166 *
167 * @Reentrant Yes
168 * @Libs None
169 */
170 isf_status_t dm_channel_get_config(
171 dm_ChannelDescriptor_t *apChannelDescriptor,
172 dm_ChannelConfig_ptr apChannelConfig
173 );
174
175 /** @} */
176
177 /**
178 * @name Device Control Routines
179 * @{ */
180
181 /*! @brief This function creates a device handle for a device at a specified channel address.
182 *
183 * @details The dm_device_open() function may be used to get a handle to a device at a known channel address. The channel is implicity locked
184 * during the open.
185 *
186 * @param[in] apChannelDescriptor The handle of the channel to be opened.
187 * @param[in] apDevice The known information of a device.
188 * @param[out] apDeviceDescriptor The address of a DeviceHandle to be filled. ::dm_device_open() fills the provided device handle structure
189 * with valid data when a device is found at the specified address.
190 * @return ::dm_channel_configure() returns a value of type ::isf_status_t indicating the success or failure of the function call.
191 *
192 * @retval ::ISF_SUCCESS is returned when the device is located and a valid handle is returned.
193 * @retval ::COMM_ERROR_NOEXIST is returned when a device does not exist at the specified address.
194 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
195 * @retval ::COMM_ERROR_STOP is returned when the channel has not been started.
196 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
197 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
198 *
199 * @Constraints The following constraints must be observed when using this function:
200 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully.
201 *
202 * @Reentrant Yes
203 * @Libs None
204 */
205 isf_status_t dm_device_open(
206 dm_ChannelDescriptor_t *apChannelDescriptor,
207 void *apDevice,
208 dm_DeviceDescriptor_t *apDeviceDescriptor
209 );
210
211 /*! @brief This function closes a device.
212 *
213 * @details The dm_device_close() function is used when no further communication with the device is needed. A closed device should not be
214 * passed to ::dm_device_read() or ::dm_device_write(). The channel is implicitly locked during the close operation.
215 *
216 * @param[in] apDeviceDescriptor The address of the DeviceHandle to be closed.
217 * @return ::dm_device_open() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
218 * @retval ::ISF_SUCCESS is returned when the device changes to closed.
219 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
220 *
221 * @Constraints The following constraints must be observed when using this function:
222 * @li apDeviceDescriptor must be valid. A valid device handle is created when the ::dm_device_open() function call returns successfully.
223 *
224 * @Reentrant Yes
225 * @Libs None
226 */
227 isf_status_t dm_device_close(
228 dm_DeviceDescriptor_t *apDeviceDescriptor
229 );
230
231 /** @} */
232
233 /**
234 * @name Channel Control Routines
235 * @{ */
236
237 /*! @brief This function starts a channel.
238 *
239 * @details dm_channel_start() enables communications with an initialized channel. This call enables the hardware peripherals
240 * associated with the channel. The channel is implicitly locked during the start operation.
241 *
242 * @param[in] apChannelDescriptor The handle of the channel to be started.
243 * @return ::dm_channel_start() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
244 * @retval ::ISF_SUCCESS is returned when the channel was started successfully.
245 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
246 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
247 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
248 *
249 * @Constraints The following constraints must be observed when using this function:
250 * @li apDeviceDescriptor must be valid. A valid device handle is created when the dm_device_open() function call returns successfully.
251 *
252 * @Reentrant Yes
253 * @Libs None
254 */
255 isf_status_t dm_channel_start(dm_ChannelDescriptor_t *apChannelDescriptor);
256
257 /*! @brief This function stops a channel.
258 *
259 * @details dm_channel_stop() disables an initialized channel and stops communications with the channel. This call disables the hardware peripherals
260 * associated with the channel. The channel is implicitly locked during the stop operation.
261 *
262 * @param[in] apChannelDescriptor The handle of the channel to be stopped.
263 * @param[in] aTimeout The time to wait for the channel to stop before returning a failure. The timeout parameter may be set to zero to never return without stopping the channel, i.e. wait as long as required for the channel to stop.
264 * @return ::dm_channel_stop() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
265 *
266 * @retval ::ISF_SUCCESS is returned when the channel is successfully stopped.
267 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
268 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
269 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
270 * @Reentrant Yes
271 * @Libs None
272 */
273 isf_status_t dm_channel_stop(
274 dm_ChannelDescriptor_t *apChannelDescriptor,
275 isf_duration_t aTimeout
276 );
277
278 /*! @brief This function locks the channel for exclusive access.
279 *
280 * @details dm_channel_acquire_lock() serializes multi-client access. Each channel user must acquire a lock prior to sending
281 * device messages. While holding the channel lock, no other clients may perform any channel operations. Therefore, it is important to release the lock
282 * with ::dm_channel_release_lock() as soon as practical.
283 *
284 * @param[in] apChannelDescriptor The handle of the channel to be started.
285 * @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
286 * acquiring the lock, or wait as long as necessary for the lock to be acquired.
287 * @return ::dm_channel_acquire_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
288 * @retval ::ISF_SUCCESS is returned when the channel lock is acquired.
289 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
290 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
291 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
292 *
293 * @Constraints The following constraints must be observed when using this function:
294 * @li The actual time spent in the call may be longer than the specified timeout due to the granularity of the timer used.
295 * @li A valid device handle should be passed into the function.
296 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully.
297 *
298 * @Reentrant Yes
299 * @Libs None
300 */
301 isf_status_t dm_channel_acquire_lock(
302 dm_ChannelDescriptor_t *apChannelDescriptor,
303 isf_duration_t aTimeout
304 );
305
306 /*! @brief This function releases exclusive channel access.
307 *
308 * @details dm_channel_release_lock() is used to relinquish exclusive access on a paricular channel. It is the inverse of ::dm_channel_acquire_lock().
309 *
310 * @param[in] apChannelDescriptor The handle of the channel to unlock.
311 * @return ::dm_channel_release_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
312 * @retval ::ISF_SUCCESS is returned when the channel released successfully.
313 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
314 * @retval ::COMM_ERROR_LOCK is returned when no lock was held on the specified channel.
315 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
316 *
317 * @Reentrant Yes
318 * @Libs None
319 */
320 isf_status_t dm_channel_release_lock(dm_ChannelDescriptor_t *apChannelDescriptor);
321
322 /** @} */
323
324 /**
325 * @name Device Operation Routines
326 * @{ */
327
328 /*! @brief This function reads from a device.
329 *
330 * @details dm_device_read() reads data from the specified device. The supplied command is sent to the device triggering the
331 * device to return some data. Any data returned by the device is read and placed in the provided read buffer. Note that if the command sent
332 * does not trigger the device to return data, the dm_device_read() simply returns 0 bytes read. The device is implicitly locked
333 * during the read.
334 *
335 * @param[in] apDeviceDescriptor The handle to the device from which to read.
336 * @param[in] aOffset The offset/sub address from which the read is performed.
337 * @param[in] apReadBuffer The Buffer address where any returned data is placed.
338 * @param[in] aBuffsize The size of the buffer.
339 * @param[in] aNbyteRead The number of bytes to read.
340 * @return ::dm_device_read() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
341 *
342 * @retval ::ISF_SUCCESS is returned when data from the device was read successfully.
343 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
344 * @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.
345 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgement was received from the device.
346 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
347 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
348 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
349 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device.
350 *
351 * @Reentrant Yes
352 * @Libs None
353 */
354 isf_status_t dm_device_read(
355 dm_DeviceDescriptor_t *apDeviceDescriptor,
356 int32 aOffset,
357 uint8* apReadBuffer,
358 uint32 aBuffsize,
359 uint32 aNbyteRead
360 );
361
362 /*! @brief This function reads from a device with extended behavior.
363 *
364 * @details dm_device_readx() reads data from the specified device. The supplied command is sent to the device which may trigger the device
365 * to return some data. Any data returned by the device is read and placed in the provided read buffer. dm_device_readx()
366 * modifies the basic behavior of the read command by passing a set of bit flags to the underlying protocol interface. To
367 * successfully use the extended behavior, it is necessary to understand the underlying protocol being used and to pass the appropriate flag values.
368 * The device is implicitly locked during the extension read.
369 *
370 * @param[in] apDeviceDescriptor The handle to the device from which to read.
371 * @param[in] aOffset The offset/sub address from which the read is performed.
372 * @param[in] apReadBuffer The Buffer address where any returned data is placed.
373 * @param[in] aBuffsize The size of the buffer.
374 * @param[in] aNbyteRead The number of bytes to read.
375 * @param[in] aFlags A set of bit flags controlling the behavior of the write.
376 * @return ::dm_device_readx() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
377 * @retval ::ISF_SUCCESS is returned when the device was read successfully.
378 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
379 * @retval ::COMM_ERROR_BUF_SIZE The provided buffer is too small to hold all the data or the number of bytes to read is zero.
380 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgement was received from the device.
381 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
382 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
383 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
384 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device.
385 *
386 * @Constraints The following constraints must be observed when using this function:
387 * @li apDeviceDescriptor must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
388 *
389 * @Reentrant Yes
390 * @Libs None
391 */
392 isf_status_t dm_device_readx(
393 dm_DeviceDescriptor_t *apDeviceDescriptor,
394 int32 aOffset,
395 uint8* apReadBuffer,
396 uint32 aBuffsize,
397 uint32 aNbyteRead,
398 comm_Flags_t aFlags
399 );
400
401 /*! @brief This function writes to a device.
402 *
403 * @details dm_device_write() writes data to the specified device. The device is implicitly locked during the write.
404 *
405 * @param[in] apDeviceDescriptor The handle of the device to which to write.
406 * @param[in] aOffset The offset/sub address to which the write is performed.
407 * @param[in] apWriteBuffer The Buffer address where any write data is placed.
408 * @param[in] aBuffsize The size of the buffer.
409 * @param[in] aNbyteWrite The number of bytes to write.
410 * @return ::dm_device_write() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
411 * @retval ::ISF_SUCCESS is returned when the device was written successfully.
412 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
413 * @retval ::COMM_ERROR_STOP is returned when the write is invoked on a stopped channel.
414 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgement was received from the device.
415 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
416 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
417 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
418 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device.
419 *
420 * @Constraints The following constraints must be observed when using this function:
421 * @li apDeviceDescriptor must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
422 *
423 * @Reentrant Yes
424 * @Libs None
425 */
426 isf_status_t dm_device_write(
427 dm_DeviceDescriptor_t *apDeviceDescriptor,
428 int32 aOffset,
429 uint8* apWriteBuffer,
430 uint32 aBuffsize,
431 uint32 aNbyteWrite
432 );
433
434 /*! @brief This function writes data to a device with extended write behavior.
435 *
436 * @details dm_device_writex() writes data to the specified device. This function modifies the basic behaviour of the write command by passing a set of bit flags to the underlying
437 * protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol used and to pass
438 * the appropriate flag values. As an example, if it is known that the underlying device is an I2C bus, it is possible to set the appropriate
439 * flag values to explicitly control the RepeatedStart behavior at the conclusion of the ::dm_device_write() call. The device is implicitly locked during
440 * the extension write.
441 *
442 * @param[in] apDeviceDescriptor The handle of the device to which to write.
443 * @param[in] aOffset The offset/sub address to which the write is performed.
444 * @param[in] apWriteBuffer The Buffer address where any write data is placed.
445 * @param[in] aBuffsize The size of the buffer.
446 * @param[in] aNbyteWrite The number of bytes to write..
447 * @param[in] aFlags A set of bit flags controlling the behavior of the write.
448 * @return ::dm_device_writex() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
449 * @retval ::ISF_SUCCESS is returned when the data was successfully written to the device.
450 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel.
451 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgement was received from the device.
452 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
453 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
454 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly.
455 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device.
456 *
457 * @Constraints The following constraints must be observed when using this function:
458 * @li apDeviceDescriptor must be valid. A valid device handle is created when the ::dm_device_open() function returns successfully.
459 *
460 * @Reentrant Yes
461 * @Libs isf_core.lib
462 */
463 isf_status_t dm_device_writex(
464 dm_DeviceDescriptor_t *apDeviceDescriptor,
465 int32 aOffset,
466 uint8* apWriteBuffer,
467 uint32 aBuffsize,
468 uint32 aNbyteWrite,
469 comm_Flags_t aFlags
470 );
471
472 /** @} */
473
474 /*! @brief This function retrieves the channel descriptor from a device handle.
475 *
476 * @details dm_channel_get_descriptor() returns the channel descriptor associated with the channel on which the device resides.
477 *
478 * @param[in] apDeviceDescriptor Handle of device connected on the channel of interest.
479 *
480 * @return ::dm_channel_get_descriptor() returns a value of type ::dm_ChannelDescriptor_t which is pointer to an object.
481 * @retval NULL is returned when the specified device handle is invalid.
482 *
483 * @Constraints None
484 *
485 * @Constraints The following constraints must be observed when using this function:
486 * @li apDeviceDescriptor must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
487 *
488 * @Reentrant Yes
489 * @Libs isf_core.lib
490 */
491 dm_ChannelDescriptor_t* dm_channel_get_descriptor(dm_DeviceDescriptor_t *apDeviceDescriptor);
492
493 #endif /* INCLUDE_DEVICE_MESSAGING_H */
494
495
dm_channel_start
isf_status_t dm_channel_start(dm_ChannelDescriptor_t *apChannelDescriptor)
This function starts a channel.
Definition: isf_device_messaging.c:137
dm_ChannelDescriptor_struct::busHandle
busHandle_t busHandle
Definition: isf_devmsg.h:51
uint8
unsigned char uint8
Definition: isf_types.h:76
dm_ChannelConfig_ptr
void * dm_ChannelConfig_ptr
This structure defines the user-specified parameters for channel configuration.
Definition: isf_devmsg.h:42
dm_device_open
isf_status_t dm_device_open(dm_ChannelDescriptor_t *apChannelDescriptor, void *apDevice, dm_DeviceDescriptor_t *apDeviceDescriptor)
This function creates a device handle for a device at a specified channel address.
Definition: isf_device_messaging.c:227
protocol_t
This structure contains protocol-specific function pointers and properties.
Definition: isf_protocol_adapter.h:68
dm_channel_get_state
comm_State_t dm_channel_get_state(dm_ChannelDescriptor_t *apChannelDescriptor)
This function returns the channel state.
Definition: isf_device_messaging.c:100
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
dm_DeviceDescriptor_struct::pChannelDescriptor
dm_ChannelDescriptor_t * pChannelDescriptor
Definition: isf_devmsg.h:62
dm_device_writex
isf_status_t dm_device_writex(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite, comm_Flags_t aFlags)
This function writes data to a device with extended write behavior.
Definition: isf_device_messaging.c:328
dm_DeviceDescriptor_struct::pEndpointHandle
void * pEndpointHandle
Definition: isf_devmsg.h:63
dm_channel_stop
isf_status_t dm_channel_stop(dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
This function stops a channel.
Definition: isf_device_messaging.c:155
dm_device_write
isf_status_t dm_device_write(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite)
This function writes to a device.
Definition: isf_device_messaging.c:309
dm_ChannelDescriptor_struct::pProtocol
const protocol_t * pProtocol
Definition: isf_devmsg.h:52
dm_DeviceDescriptor_t
struct dm_DeviceDescriptor_struct dm_DeviceDescriptor_t
This structure defines a handle for the device.
isf_protocol_adapter.h
isf_protocol_adapter.h defines the general interface definition for the protocol adapter.
dm_channel_acquire_lock
isf_status_t dm_channel_acquire_lock(dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
This function locks the channel for exclusive access.
Definition: isf_device_messaging.c:174
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
dm_channel_init
isf_status_t dm_channel_init(dm_ChannelId_t aChannelId, dm_ChannelDescriptor_t *apChannelDescriptor)
This function initializes a channel.
Definition: isf_device_messaging.c:48
dm_device_close
isf_status_t dm_device_close(dm_DeviceDescriptor_t *apDeviceDescriptor)
This function closes a device.
Definition: isf_device_messaging.c:252
dm_channel_get_config
isf_status_t dm_channel_get_config(dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr apChannelConfig)
This function returns the current channel configuration.
Definition: isf_device_messaging.c:118
isf_duration_t
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:84
isf.h
Main ISF header file. Contains code common to all ISF components.
int32
signed long int int32
Definition: isf_types.h:74
dm_device_readx
isf_status_t dm_device_readx(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead, comm_Flags_t aFlags)
This function reads from a device with extended behavior.
Definition: isf_device_messaging.c:284
dm_device_read
isf_status_t dm_device_read(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead)
This function reads from a device.
Definition: isf_device_messaging.c:271
isf_status_t
int32 isf_status_t
ISF return status type.
Definition: isf.h:76
isf_comm.h
isf_comm.h defines the common types for the Communications Service Family of the Intelligent Sensing ...
dm_channel_configure
isf_status_t dm_channel_configure(dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr apChannelConfig)
This function reconfigures an already initialized channel.
Definition: isf_device_messaging.c:80
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
dm_channel_release_lock
isf_status_t dm_channel_release_lock(dm_ChannelDescriptor_t *apChannelDescriptor)
This function releases exclusive channel access.
Definition: isf_device_messaging.c:191
uint32
unsigned long int uint32
Definition: isf_types.h:78
dm_channel_get_descriptor
dm_ChannelDescriptor_t * dm_channel_get_descriptor(dm_DeviceDescriptor_t *apDeviceDescriptor)
This function retrieves the channel descriptor from a device handle.
Definition: isf_device_messaging.c:214
dm_DeviceDescriptor_struct
This structure defines a handle for the device.
Definition: isf_devmsg.h:61
dm_ChannelDescriptor_struct
This structure is a declaration of a channel descriptor type.
Definition: isf_devmsg.h:50
dm_ChannelDescriptor_t
struct dm_ChannelDescriptor_struct dm_ChannelDescriptor_t
This structure is a declaration of a channel descriptor type.
dm_ChannelId_t
comm_Id_t dm_ChannelId_t
This typedef is a numeric channel identifier index into an array of channels in the system...
Definition: isf_devmsg.h:33
- © Freescale Semiconductor, Inc. 2016. All Rights Reserved.