ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_device_messaging.c
Go to the documentation of this file.
1 
2 /*!
3 ********************************************************************************
4 * File: isf_device_messaging.c
5 *
6 * Copyright (c) 2012-2014, Freescale Semiconductor, Inc.
7 *
8 *******************************************************************************/
9 /*!
10 * @file isf_device_messaging.c
11 * @brief \b isf_device_messaging.c implements device messaging interfaces.
12 */
13 
14 /******************************************************************************
15  * Includes
16  ******************************************************************************/
17 #include "isf_devmsg.h"
18 #include "isf_protocol_adapter.h"
19 #include "isf_sysconf_types.h"
20 /******************************************************************************
21  * External variable definition
22  *****************************************************************************/
23 extern const protocol_t PROTOCOL[];
24 extern const sys_channelDescriptor_t gSys_ConfiguredChannelList[]; // Channel configuration list
25 extern const uint8 gSys_NumChannels; // Number of the channels in the system
26 /******************************************************************************
27  * Private Variable Definitions
28  ******************************************************************************/
29 
30 
31 /******************************************************************************
32  * Public Function Definitions
33  ******************************************************************************/
34 
35 /**
36  * @name Channel
37  * @{ */
38 
39 /***********************************************************************
40  *
41  * Function Name : dm_channel_init
42  * Description : This function initializes a channel.
43  * A channel must be initialized prior to use. Initialization creates the channel and
44  * initializes the data structures required to manage the channel.
45  * The channel is implicitly locked during the initialization.
46  *
47  ***************************************************************************/
49 {
50  isf_status_t ret;
51  if (gSys_NumChannels <= aChannelId ) {
53  }
54  if (apChannelDescriptor == NULL) {
56  }
57  sys_protocolType_t protocolType = gSys_ConfiguredChannelList[aChannelId].protocolType;
58  comm_Id_t instanceId = gSys_ConfiguredChannelList[aChannelId].protocolInstanceId;
59  apChannelDescriptor->pProtocol = &PROTOCOL[protocolType];
60  fnInit_t fnInit = apChannelDescriptor->pProtocol->fnInit;
61  ret = fnInit(instanceId, &apChannelDescriptor->busHandle);
62  // Configure the channel only for the first time.
63  if(COMM_STATE_INIT == apChannelDescriptor->pProtocol->fnGetState(&apChannelDescriptor->busHandle)){
64  const void * pConfig = gSys_ConfiguredChannelList[aChannelId].pConfig;
65  fnConfigure_t fnConfigure = apChannelDescriptor->pProtocol->fnConfigure;
66  ret = fnConfigure(&apChannelDescriptor->busHandle, (void*)pConfig);
67  }
68  return ret;
69 }
70 /***********************************************************************
71  *
72  * Function Name : dm_channel_configure
73  * Description : This function reconfigures an already initialized channel.
74  * A channel may be reconfigured after initialization.The typical usage involves retrieving the
75  The channel is implicitly locked during the configuration.A channel must be initialized prior to use.
76  Initialization creates the channel and initializes the data structures required to manage the channel.
77  * The channel is implicitly locked during the initialization.
78  *
79  ***************************************************************************/
81 {
82  if (apChannelDescriptor == NULL) {
84  }
85  if (apChannelDescriptor->pProtocol == NULL) {
86  return((isf_status_t) COMM_ERROR_INIT);
87  }
88  fnConfigure_t fnConfigure = apChannelDescriptor->pProtocol->fnConfigure;
89  return(fnConfigure(&apChannelDescriptor->busHandle, apChannelConfig));
90 }
91 
92 /***********************************************************************
93  *
94  * Function Name : dm_channel_get_state
95  * Description : A channel may be queried for its current state.
96  * This function provides the current state of the given channel.
97  *
98  *
99  ***************************************************************************/
101 {
102  if (apChannelDescriptor == NULL) {
104  }
105  if (apChannelDescriptor->pProtocol == NULL) {
106  return((comm_State_t) COMM_ERROR_INIT);
107  }
108  fnGetState_t fnGetState = apChannelDescriptor->pProtocol->fnGetState;
109  return(fnGetState(&apChannelDescriptor->busHandle));
110 }
111 /***********************************************************************
112  *
113  * Function Name : dm_channel_get_config
114  * Description : This function returns the current channel configuration.
115  * This function provides the current configuration of the given channel.
116  *
117  ***************************************************************************/
119 {
120  if (apChannelDescriptor == NULL) {
122  }
123  if (apChannelDescriptor->pProtocol == NULL) {
124  return((isf_status_t) COMM_ERROR_INIT);
125  }
126  fnGetConfig_t fnGetConfig = apChannelDescriptor->pProtocol->fnGetConfig;
127  return(fnGetConfig(&apChannelDescriptor->busHandle, apChannelConfig));
128 }
129 /***********************************************************************
130  *
131  * Function Name : dm_channel_start
132  * Description : This function starts a channel. This call enables the hardware peripherals
133  * associated with the channel. The channel is implicitly locked during the start operation.
134  *
135  ***************************************************************************/
136 
138 {
139  if (apChannelDescriptor == NULL) {
141  }
142  if (apChannelDescriptor->pProtocol == NULL) {
143  return((isf_status_t) COMM_ERROR_INIT);
144  }
145  fnStart_t fnStart = apChannelDescriptor->pProtocol->fnStart;
146  return(fnStart(&apChannelDescriptor->busHandle));
147 }
148 /***********************************************************************
149  *
150  * Function Name : dm_channel_stop
151  * Description : This function stops a channel. This call disables the hardware peripherals
152  * associated with the channel. The channel is implicitly locked during the stop operation..
153  *
154  ***************************************************************************/
156 {
157  if (apChannelDescriptor == NULL) {
159  }
160  if (apChannelDescriptor->pProtocol == NULL) {
161  return((isf_status_t) COMM_ERROR_INIT);
162  }
163  fnStop_t fnStop = apChannelDescriptor->pProtocol->fnStop;
164  return(fnStop(&apChannelDescriptor->busHandle,aTimeout));
165 }
166 
167 /***********************************************************************
168  *
169  * Function Name : dm_channel_acquire_lock
170  * Description : This function locks the channel for exclusive access.
171  * While holding the channel lock, no other clients may perform any channel operations.
172  * Therefore, it is important to release the lock with ::dm_channel_release_lock() as soon as practical.
173  ***************************************************************************/
175 {
176  if (apChannelDescriptor == NULL) {
178  }
179  if (apChannelDescriptor->pProtocol == NULL) {
180  return((isf_status_t) COMM_ERROR_INIT);
181  }
182  fnAcquireLock_t fnAcquireLock = apChannelDescriptor->pProtocol->fnAcquireLock;
183  return(fnAcquireLock(&apChannelDescriptor->busHandle,aTimeout));
184 }
185 /***********************************************************************
186  *
187  * Function Name : dm_channel_release_lock
188  * Description : This function is used to relinquish exclusive access on a paricular channel.
189  * It is the inverse of ::dm_channel_acquire_lock().
190  ***************************************************************************/
192 {
193  if (apChannelDescriptor == NULL) {
195  }
196  if (apChannelDescriptor->pProtocol == NULL) {
197  return((isf_status_t) COMM_ERROR_INIT);
198  }
199  fnReleaseLock_t fnReleaseLock = apChannelDescriptor->pProtocol->fnReleaseLock;
200  return(fnReleaseLock(&apChannelDescriptor->busHandle));
201 }
202 
203 /** @} */
204 
205 /**
206  * @name Device
207  * @{ */
208 
209 /***********************************************************************
210  *
211  * Function Name : dm_channel_get_descriptor
212  * Description : This function retrieves the channel descriptor from a device handle.
213  ***************************************************************************/
215 {
216  if (apDeviceDescriptor == NULL) {
217  return(NULL);
218  }
219  return(apDeviceDescriptor->pChannelDescriptor);
220 }
221 
222 /***********************************************************************
223  *
224  * Function Name : dm_device_open
225  * Description : This function creates a device handle for a device at a specified channel address.
226  ***************************************************************************/
227 isf_status_t dm_device_open(dm_ChannelDescriptor_t *apChannelDescriptor, void *apDevice , dm_DeviceDescriptor_t *apDeviceDescriptor)
228 {
229  if ((apChannelDescriptor == NULL) || (apDeviceDescriptor == NULL)) {
231  }
232  if (apChannelDescriptor->pProtocol == NULL) {
233  return((isf_status_t) COMM_ERROR_INIT);
234  }
235  fnConnectToEndpoint_t fnGetEndPointAt = apChannelDescriptor->pProtocol->fnGetEndPointAt;
236  isf_status_t status = fnGetEndPointAt(&apChannelDescriptor->busHandle, apDevice, &apDeviceDescriptor->pEndpointHandle);
237  if (status != ISF_SUCCESS) {
238  apDeviceDescriptor->pChannelDescriptor = NULL;
239  return(status);
240  }
241  apDeviceDescriptor->pChannelDescriptor = apChannelDescriptor;
242 
243  return(ISF_SUCCESS);
244 }
245 /***********************************************************************
246  *
247  * Function Name : dm_device_close
248  * Description : This function closes a device. A closed device should not be
249  * passed to ::dm_device_read() or ::dm_device_write().
250  * The channel is implicitly locked during the close operation.
251  ***************************************************************************/
253 {
254  if (apDeviceDescriptor == NULL) {
256  }
257  fnDisconnectEndpoint_t fnDisEndPoint = apDeviceDescriptor->pChannelDescriptor->pProtocol->fnDisEndPoint;
258  isf_status_t status = fnDisEndPoint(apDeviceDescriptor->pEndpointHandle);
259 
260  apDeviceDescriptor->pChannelDescriptor = NULL;
261 
262  return status;
263 }
264 /***********************************************************************
265  *
266  * Function Name : dm_device_read
267  * Description : This function reads from a device.Any data returned by the device is read
268  * and placed in the provided read buffer. The channel is implicitly locked during the close operation.
269  ***************************************************************************/
270 
272  uint8* apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead)
273 {
274  comm_Flags_t flags = 0;
275  return(dm_device_readx(apDeviceDescriptor, aOffset, apReadBuffer, aBuffsize, aNbyteRead, flags));
276 }
277 /***********************************************************************
278  *
279  * Function Name : dm_device_readx
280  * Description : This function reads from a device. Any data returned by the device is read
281  * and placed in the provided read buffer. dm_device_readx() modifies the basic behaviour
282  * of the read command by passing a set of bit flags to the underlying protocol interface.
283  ***************************************************************************/
285  uint8* apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead, comm_Flags_t aFlags)
286 {
287  if (apDeviceDescriptor == NULL) {
289  }
290  dm_ChannelDescriptor_t * pChannelDescriptor = apDeviceDescriptor->pChannelDescriptor;
291 
292  if (pChannelDescriptor == NULL) {
294  }
295  if (pChannelDescriptor->pProtocol == NULL) {
296  return((isf_status_t) COMM_ERROR_INIT);
297  }
298  fnRead_t fnRead = pChannelDescriptor->pProtocol->fnRead;
299  return(fnRead(apDeviceDescriptor->pEndpointHandle, aOffset, apReadBuffer, aBuffsize, aNbyteRead, aFlags));
300 }
301 /***********************************************************************
302  *
303  * Function Name : dm_device_write
304  * Description : This function writes to a device.
305  * dm_device_write() writes data to the specified device. The device is implicitly locked during the write.
306  *
307  ***************************************************************************/
308 
310  uint8* apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite )
311 {
312  comm_Flags_t flags = 0;
313  return(dm_device_writex(apDeviceDescriptor, aOffset, apWriteBuffer, aBuffsize, aNbyteWrite, flags));
314 }
315 
316 /***********************************************************************
317  *
318  * Function Name : dm_device_writex
319  * Description : This function writes data to a device with extended write behaviour.
320  * dm_device_writex() writes data to the specified device. This function modifies the basic behaviour
321  * of the write command by passing a set of bit flags to the underlying protocol interface.
322  *
323  ***************************************************************************/
324 isf_status_t dm_device_writex(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8* apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite, comm_Flags_t aFlags)
325 {
326  if (apDeviceDescriptor == NULL) {
328  }
329  dm_ChannelDescriptor_t * pChannelDescriptor = apDeviceDescriptor->pChannelDescriptor;
330 
331  if (pChannelDescriptor == NULL) {
333  }
334  if (pChannelDescriptor->pProtocol == NULL) {
335  return((isf_status_t) COMM_ERROR_INIT);
336  }
337  fnWrite_t fnWrite = pChannelDescriptor->pProtocol->fnWrite;
338  return(fnWrite(apDeviceDescriptor->pEndpointHandle, aOffset, apWriteBuffer, aBuffsize, aNbyteWrite, aFlags));
339 }
340 /** @} */
341 
342 
343 
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
void * dm_ChannelConfig_ptr
This structure defines the user-specified parameters for channel configuration.
Definition: isf_devmsg.h:42
fnGetState_t fnGetState
isf_status_t dm_channel_configure(dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr apChannelConfig)
This function reconfigures an already initialized channel.
sys_protocolType_t
This enumerator indexes protocol-specific functions and properties.
isf_status_t dm_channel_start(dm_ChannelDescriptor_t *apChannelDescriptor)
This function starts a channel.
isf_status_t(* fnWrite_t)(void *apEndpointHandle, int32 offset, uint8 *pWriteBuffer, uint32 buffsize, uint32 nBytesWrite, comm_Flags_t aFlags)
This is the the function pointer signature for writing the data to a specified device.
This structure contains protocol-specific function pointers and properties.
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.
const sys_channelDescriptor_t gSys_ConfiguredChannelList[]
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
isf_status_t dm_device_close(dm_DeviceDescriptor_t *apDeviceDescriptor)
This function closes a device.
isf_status_t(* fnDisconnectEndpoint_t)(void *apEndpointHandle)
This is the function pointer signature for closing the Endpoint.
isf_status_t(* fnStart_t)(void *apBusHandle)
This is the function pointer signature for starting the bus.
isf_status_t(* fnConnectToEndpoint_t)(void *apBusHandle, void *apDevice, void **apEndpointHandle)
This is the function pointer signature for getting the Endpoint handle.
dm_ChannelDescriptor_t * pChannelDescriptor
Definition: isf_devmsg.h:62
comm_State_t(* fnGetState_t)(void *apBusHandle)
This is the function pointer signature for getting the state of the bus.
isf_status_t dm_channel_get_config(dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr apChannelConfig)
This function returns the current channel configuration.
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
const uint8 gSys_NumChannels
const protocol_t PROTOCOL[]
Lookup table to find protocol-specific functions and properties. Indexed by sys_protocolType_t.
const protocol_t * pProtocol
Definition: isf_devmsg.h:52
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.
isf_status_t(* fnInit_t)(comm_Id_t aBusId, void *apBusHandle)
This is the function pointer signature for bus initialization.
isf_status_t(* fnStop_t)(void *apBusHandle, isf_duration_t aTimeout)
This is the function pointer signature for stopping the bus.
isf_status_t(* fnReleaseLock_t)(void *apBusHandle)
This is the function pointer signature for releasing the lock for a particular bus.
isf_protocol_adapter.h defines the general interface definition for the protocol adapter.
sys_protocolType_t protocolType
isf_status_t dm_channel_release_lock(dm_ChannelDescriptor_t *apChannelDescriptor)
This function releases exclusive channel access.
isf_status_t dm_channel_acquire_lock(dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
This function locks the channel for exclusive access.
isf_status_t dm_channel_stop(dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
This function stops a channel.
fnGetConfig_t fnGetConfig
isf_status_t dm_device_read(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead)
This function reads from a device.
uint8 comm_Flags_t
This is a bit array of flags governing device read/write behavior.
Definition: isf_comm.h:59
fnReleaseLock_t fnReleaseLock
This structure defines the channel descriptor.
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:59
long int32
This defines int32 as long.
Definition: isf_types.h:32
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.
fnConfigure_t fnConfigure
isf_status_t(* fnConfigure_t)(void *apBusHandle, void *apBusConfig)
This is the function pointer signature for setting the configuration of the bus.
dm_ChannelDescriptor_t * dm_channel_get_descriptor(dm_DeviceDescriptor_t *apDeviceDescriptor)
This function retrieves the channel descriptor from a device handle.
fnConnectToEndpoint_t fnGetEndPointAt
isf_status_t dm_channel_init(dm_ChannelId_t aChannelId, dm_ChannelDescriptor_t *apChannelDescriptor)
This function initializes a channel.
isf_status_t(* fnRead_t)(void *apEndpointHandle, int32 offset, void *apReadBuffer, uint32 buffsize, uint32 nBytesRead, comm_Flags_t aFlags)
This is the function pointer signature for reading the data from a specified device.
isf_status_t dm_device_write(dm_DeviceDescriptor_t *apDeviceDescriptor, int32 aOffset, uint8 *apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite)
This function writes to a device.
fnDisconnectEndpoint_t fnDisEndPoint
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
enum comm_State_vals comm_State_t
This enum holds an enumerated value describing the state of a channel.
Definition: isf_comm.h:53
comm_State_t dm_channel_get_state(dm_ChannelDescriptor_t *apChannelDescriptor)
This function returns the channel state.
This structure defines a handle for the device.
Definition: isf_devmsg.h:61
isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging...
This file defines the configuration types and structures for the system communication channel...
fnAcquireLock_t fnAcquireLock
This structure is a declaration of a channel descriptor type.
Definition: isf_devmsg.h:50
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
isf_status_t(* fnAcquireLock_t)(void *apBusHandle, isf_duration_t aTimeout)
This is the function pointer signature for acquiring the lock for a particular bus.
isf_status_t(* fnGetConfig_t)(void *apBusHandle, void *apBusConfig)
This is the function pointer signature for getting the configuration of the bus.