![]() |
ISF
1.1
Intelligent Sensing Framework
|
00001 /*! 00002 ******************************************************************************** 00003 * File: isf_devmsg.h 00004 * 00005 * Copyright (c) 2012, Freescale Semiconductor, Inc. 00006 * 00007 *******************************************************************************/ 00008 /*! 00009 * @file isf_devmsg.h 00010 * @brief \b isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component. 00011 */ 00012 #ifndef INCLUDE_DEVICE_MESSAGING_H 00013 #define INCLUDE_DEVICE_MESSAGING_H 00014 00015 #include <isf.h> 00016 #include <isf_comm.h> 00017 #include <isf_i2c.h> 00018 00019 /******************* 00020 ** Macro Definitions 00021 */ 00022 00023 /************** 00024 ** Enumerations 00025 */ 00026 00027 /********************* 00028 ** Structures and Typedefs 00029 */ 00030 00031 /** 00032 * @brief This is the function pointer signature for bus initialization. 00033 */ 00034 typedef isf_status_t (*fnInit_t) (comm_Id_t aBusId, void *apBusHandle); 00035 /** 00036 * @brief This is the function pointer signature for getting the state of the bus. 00037 */ 00038 typedef comm_State_t (*fnGetState_t) (void *apBusHandle); 00039 /** 00040 * @brief This is the function pointer signature for getting the configuration of the bus. 00041 */ 00042 typedef isf_status_t (*fnGetConfig_t) (void *apBusHandle, void *apBusConfig); 00043 /** 00044 * @brief This is the function pointer signature for setting the configuration of the bus. 00045 */ 00046 typedef isf_status_t (*fnConfigure_t) (void *apBusHandle, void *apBusConfig); 00047 /** 00048 * @brief This is the function pointer signature for starting the bus. 00049 */ 00050 typedef isf_status_t (*fnStart_t) (void *apBusHandle); 00051 /** 00052 * @brief This is the function pointer signature for stopping the bus. 00053 */ 00054 typedef isf_status_t (*fnStop_t) (void *apBusHandle, isf_duration_t aTimeout); 00055 /** 00056 * @brief This is the function pointer signature for getting the slave handle. 00057 */ 00058 typedef isf_status_t (*fnGetSlaveAt_t) (void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle); 00059 /** 00060 * @brief This is the function pointer signature for acquiring the lock for a particular bus. 00061 */ 00062 typedef isf_status_t (*fnAcquireLock_t)(void *apBusHandle, isf_duration_t aTimeout); 00063 /** 00064 * @brief This is the function pointer signature for releasing the lock for a particular bus. 00065 */ 00066 typedef isf_status_t (*fnReleaseLock_t)(void *apBusHandle); 00067 /** 00068 * @brief This is the function pointer signature for reading the data from a specified device. 00069 */ 00070 typedef isf_status_t (*fnRead_t) (void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags); 00071 /** 00072 * @brief This is the the function pointer signature for writing the data to a specified device. 00073 */ 00074 typedef isf_status_t (*fnWrite_t) (void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags); 00075 /** 00076 * @brief This structure contains protocol-specific function pointers and properties. 00077 */ 00078 typedef struct { 00079 fnInit_t fnInit; /*!< Initialize a channel. */ 00080 fnGetState_t fnGetState; /*!< Get the state of a channel. */ 00081 fnGetConfig_t fnGetConfig; /*!< Get the current channel configuration. */ 00082 fnConfigure_t fnConfigure; /*!< Reconfigure an already initialized channel. */ 00083 fnStart_t fnStart; /*!< Start a channel. */ 00084 fnStop_t fnStop; /*!< Stop a channel. */ 00085 fnGetSlaveAt_t fnGetSlaveAt; /*!< Get the handle to a slave device at a known address.*/ 00086 fnAcquireLock_t fnAcquireLock; /*!< Lock the channel for exclusive access. */ 00087 fnReleaseLock_t fnReleaseLock; /*!< Release exclusive access. */ 00088 fnRead_t fnRead; /*!< Read from a device. */ 00089 fnWrite_t fnWrite; /*!< Write to a device. */ 00090 } protocol_t; 00091 00092 /*! @brief This typedef is a umeric channel identifier index into an array of channels 00093 * in the system. */ 00094 typedef comm_Id_t dm_ChannelId_t; 00095 00096 /*! @brief This structure defines the user-specified parameters for channel 00097 * configuration. 00098 * 00099 * This type allows the device messaging APIs to handle a 00100 * protocol-specific configuration pointer opaquely until it is passed to 00101 * the specific protocol functions that use the data. 00102 */ 00103 typedef void* dm_ChannelConfig_ptr; 00104 00105 /*! @brief This structure is a declaration of a channel descriptor type. 00106 * @details The channel descriptor contains the bus and protocol information required by the 00107 * device messaging functions to safely use a channel for communications. The 00108 * members are ordered to maintain natural alignment without inserting padding 00109 * bytes. 00110 */ 00111 typedef struct dm_ChannelDescriptor_struct { 00112 union { 00113 i2c_BusHandle_t i2c; /*!< The I2C channel handle. */ 00114 } handle; /*!< The protocol-specific channel handle. */ 00115 const protocol_t * pProtocol; /*!< The pointer to protocol-specific functions and properties. */ 00116 00117 } dm_ChannelDescriptor_t; 00118 00119 /*! @brief This structure defines a handle for the device. 00120 * @details The device handle contains the information required by the device 00121 * messaging functions to address and communicate with a slave device. 00122 */ 00123 typedef struct dm_DeviceHandle_struct { 00124 dm_ChannelDescriptor_t * pChannelDescriptor; /*!< The pointer to the channel descriptor. */ 00125 union { 00126 i2c_SlaveHandle_t i2c; /*!< The I2C device handle. */ 00127 } handle; /*!< The protocol-specific device handle. */ 00128 } dm_DeviceHandle_t; 00129 00130 /********************* 00131 ** Function Prototypes 00132 */ 00133 00134 /** 00135 * @name Initialization Routines 00136 * @{ */ 00137 00138 /*! @brief This function initializes a channel. 00139 * 00140 * @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 00141 * during the initialization. 00142 * 00143 * @param[in] aChannelId The ID of the channel to initialize. This is an index into the array of known channels that can be used. 00144 * @param[out] apChannelDescriptor The address of the channel descriptor structure to be initialized. 00145 * 00146 * @return ::dm_channel_init() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00147 * @retval ::ISF_SUCCESS is returned when the channel initialized successfully and the apChannelDescriptor structure reference has been 00148 * populated with initialized channel data. 00149 * @retval ::COMM_ERROR_NOEXIST is returned when the supplied channel identifier does not exist. 00150 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00151 * @retval ::COMM_ERROR_INIT is returned when the channel could not be initialized. 00152 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00153 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00154 * 00155 * @Constraints The following constraints must be observed when using this function: 00156 * @li aChannelId must be in the range of the known channel identifiers as defined in isf_sysconf_comms.h 00157 * 00158 * @Reentrant Yes 00159 * @Libs isf_core.lib 00160 */ 00161 isf_status_t dm_channel_init( 00162 dm_ChannelId_t aChannelId, 00163 dm_ChannelDescriptor_t *apChannelDescriptor 00164 ); 00165 00166 /*! @brief This function reconfigures an already initialized channel. 00167 * 00168 * @details A channel may be reconfigured after initialization. Calls to dm_channel_configure() after initialization will override any previous 00169 * configuration values and must be made while the channel state is ::COMM_STATE_STOPPED. The typical usage involves retrieving the 00170 * current configuration using ::dm_channel_get_config(), making modifications to the returned configuration, and then calling 00171 * dm_channel_configure() with the updated configuration. The channel is implicitly locked during the configuration. 00172 * 00173 * @param[in] apChannelDescriptor The handle of the channel to be configured. 00174 * @param[in] aChannelConfig The channel configuration used during initialization. 00175 * 00176 * @return ::dm_channel_configure() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00177 * @retval ::ISF_SUCCESS is returned when the channel was reconfigured successfully. 00178 * @retval ::COMM_ERROR_STOP is returned when the channel was not STOPPED. 00179 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00180 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00181 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00182 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00183 * 00184 * @Constraints The following constraints must be observed when using this function: 00185 * @li apChannelDescriptor must be valid. A valid channel descriptor is created 00186 * when the ::dm_channel_init() function call is successfully returned. 00187 * 00188 * @Reentrant Yes 00189 * @Libs isf_core.lib 00190 */ 00191 isf_status_t dm_channel_configure( 00192 dm_ChannelDescriptor_t *apChannelDescriptor, 00193 dm_ChannelConfig_ptr aChannelConfig 00194 ); 00195 00196 /** @} */ 00197 00198 /** 00199 * @name Queries and Status 00200 * @{ */ 00201 00202 /*! @brief This function returns the channel state. 00203 * 00204 * @details A channel may be queried for its current state. 00205 * 00206 * @param[in] apChannelDescriptor The handle of the channel to be queried. 00207 * 00208 * @return ::dm_channel_get_state() returns a value of type 00209 * ::comm_State_t indicating the current state of the channel. 00210 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00211 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00212 * 00213 * @Constraints The following constraints must be observed when using this function: 00214 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when ::dm_channel_init() function call returns successfully. 00215 * 00216 * @Reentrant Yes 00217 * @Libs isf_core.lib 00218 */ 00219 comm_State_t dm_channel_get_state(dm_ChannelDescriptor_t *apChannelDescriptor); 00220 00221 /*! @brief This function returns the current channel configuration. 00222 * 00223 * @details A channel may be queried for the current configuration. 00224 * 00225 * @param[in] apChannelDescriptor The handle of the channel to be queried. 00226 * @param[out] aChannelConfig The address of a channel configuration to be filled. 00227 * 00228 * @return ::dm_channel_get_config() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00229 * @retval ::ISF_SUCCESS is returned when the channel configuration is retrieved successfully. 00230 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00231 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00232 00233 * @Constraints The following constraints must be observed when using this function: 00234 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully. 00235 * 00236 * @Reentrant Yes 00237 * @Libs isf_core.lib 00238 */ 00239 isf_status_t dm_channel_get_config( 00240 dm_ChannelDescriptor_t *apChannelDescriptor, 00241 dm_ChannelConfig_ptr aChannelConfig 00242 ); 00243 00244 /** @} */ 00245 00246 /** 00247 * @name Device Control Routines 00248 * @{ */ 00249 00250 /*! @brief This function creates a device handle for a device at a specified channel address. 00251 * 00252 * @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 00253 * during the open. 00254 * 00255 * @param[in] apChannelDescriptor The handle of the channel to be queried. 00256 * @param[in] aDeviceAddr The known address of a device. 00257 * @param[out] apDeviceHandle The address of a DeviceHandle to be filled. ::dm_device_open() fills the provided device handle structure 00258 * with valid data when a device is found at the specified address. 00259 * @return ::dm_channel_configure() returns a value of type ::isf_status_t indicating the success or failure of the function call. 00260 * 00261 * @retval ::ISF_SUCCESS is returned when the device is located and a valid handle is returned. 00262 * @retval ::COMM_ERROR_NOEXIST is returned when a device does not exist at the specified address. 00263 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00264 * @retval ::COMM_ERROR_STOP is returned when the channel has not been started. 00265 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00266 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00267 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00268 * 00269 * @Constraints The following constraints must be observed when using this function: 00270 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully. 00271 * 00272 * @Reentrant Yes 00273 * @Libs isf_core.lib 00274 */ 00275 isf_status_t dm_device_open( 00276 dm_ChannelDescriptor_t *apChannelDescriptor, 00277 comm_Address_t aDeviceAddr, 00278 dm_DeviceHandle_t *apDeviceHandle 00279 ); 00280 00281 /*! @brief This function closes a device. 00282 * 00283 * @details The dm_device_close() function is used when no further communication with the device is needed. A closed device should not be 00284 * passed to ::dm_device_read() or ::dm_device_write(). The channel is implicitly locked during the close operation. 00285 * 00286 * @param[in] apDeviceHandle The address of the DeviceHandle to be closed. 00287 * @return ::dm_device_open() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00288 * @retval ::ISF_SUCCESS is returned when the device changes to closed. 00289 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00290 * 00291 * @Constraints The following constraints must be observed when using this function: 00292 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function call returns successfully. 00293 * 00294 * @Reentrant Yes 00295 * @Libs isf_core.lib 00296 */ 00297 isf_status_t dm_device_close( 00298 dm_DeviceHandle_t *apDeviceHandle 00299 ); 00300 00301 /** @} */ 00302 00303 /** 00304 * @name Channel Control Routines 00305 * @{ */ 00306 00307 /*! @brief This function starts a channel. 00308 * 00309 * @details dm_channel_start() enables communications with an initialized channel. This call enables the hardware peripherals 00310 * associated with the channel. The channel is implicitly locked during the start operation. 00311 * 00312 * @param[in] apChannelDescriptor The handle of the channel to be started. 00313 * @return ::dm_channel_start() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00314 * @retval ::ISF_SUCCESS is returned when the channel was started successfully. 00315 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00316 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00317 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00318 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00319 * 00320 * @Constraints The following constraints must be observed when using this function: 00321 * @li apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function call returns successfully. 00322 * 00323 * @Reentrant Yes 00324 * @Libs isf_core.lib 00325 */ 00326 isf_status_t dm_channel_start(dm_ChannelDescriptor_t *apChannelDescriptor); 00327 00328 /*! @brief This function stops a channel. 00329 * 00330 * @details dm_channel_stop() disables an initialized channel and stops communications with the channel. This call disables the hardware peripherals 00331 * associated with the channel. The channel is implicitly locked during the stop operation. 00332 * 00333 * @param[in] apChannelDescriptor The handle of the channel to be stopped. 00334 * @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. 00335 * @return ::dm_channel_stop() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00336 * 00337 * @retval ::ISF_SUCCESS is returned when the channel is successfully stopped. 00338 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00339 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00340 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00341 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00342 * 00343 * @Constraints The following constraints must be observed when using this function: 00344 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function call returns successfully. 00345 * 00346 * @Reentrant Yes 00347 * @Libs isf_core.lib 00348 */ 00349 isf_status_t dm_channel_stop( 00350 dm_ChannelDescriptor_t *apChannelDescriptor, 00351 isf_duration_t aTimeout 00352 ); 00353 00354 /*! @brief This function locks the channel for exclusive access. 00355 * 00356 * @details dm_channel_acquire_lock() serializes multi-client access. Each channel user must acquire a lock prior to sending 00357 * device messages. While holding the channel lock, no other clients may perform any channel operations. Therefore, it is important to release the lock 00358 * with ::dm_channel_release_lock() as soon as practical. 00359 * 00360 * @param[in] apChannelDescriptor The handle of the channel to be started. 00361 * @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 00362 * acquiring the lock, or wait as long as necessary for the lock to be acquired. 00363 * @return ::dm_channel_acquire_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00364 * @retval ::ISF_SUCCESS is returned when the channel lock is acquired. 00365 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00366 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00367 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00368 * 00369 * @Constraints The following constraints must be observed when using this function: 00370 * @li The actual time spent in the call may be longer than the specified timeout due to the granularity of the timer used. 00371 * @li A valid device handle should be passed into the function. 00372 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully. 00373 * 00374 * @Reentrant Yes 00375 * @Libs isf_core.lib 00376 */ 00377 isf_status_t dm_channel_acquire_lock( 00378 dm_ChannelDescriptor_t *apChannelDescriptor, 00379 isf_duration_t aTimeout 00380 ); 00381 00382 /*! @brief This function releases exclusive channel access. 00383 * 00384 * @details dm_channel_release_lock() is used to relinquish exclusive access on a paricular channel. It is the inverse of ::dm_channel_acquire_lock(). 00385 * 00386 * @param[in] apChannelDescriptor The handle of the channel to unlock. 00387 * @return ::dm_channel_release_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00388 * @retval ::ISF_SUCCESS is returned when the channel released successfully. 00389 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00390 * @retval ::COMM_ERROR_LOCK is returned when no lock was held on the specified channel. 00391 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00392 * 00393 * @Constraints The following constraints must be observed when using this function: 00394 * @li apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully. 00395 * 00396 * @Reentrant Yes 00397 * @Libs isf_core.lib 00398 */ 00399 isf_status_t dm_channel_release_lock(dm_ChannelDescriptor_t *apChannelDescriptor); 00400 00401 /** @} */ 00402 00403 /** 00404 * @name Device Operation Routines 00405 * @{ */ 00406 00407 /*! @brief This function reads from a device. 00408 * 00409 * @details dm_device_read() reads data from the specified device. The supplied command is sent to the device triggering the 00410 * 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 00411 * does not trigger the device to return data, the dm_device_read() simply returns 0 bytes read. The device is implicitly locked 00412 * during the read. 00413 * 00414 * @param[in] apDeviceHandle The handle to the device from which to read. 00415 * @param[in] apReadCmd The read command to send to the device. 00416 * @param[in] apReadBuffer Buffer address where any returned data is placed. 00417 * @return ::dm_device_read() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00418 * 00419 * @retval ::ISF_SUCCESS is returned when data from the device was read successfully. 00420 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00421 * @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. 00422 * @retval ::COMM_ERROR_STOP is returned when the read is invoked on a stopped channel. 00423 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgment was received from the device. 00424 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00425 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00426 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00427 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device. 00428 * 00429 * @Constraints The following constraints must be observed when using this function: 00430 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function returns successfully. 00431 * 00432 * @Reentrant Yes 00433 * @Libs isf_core.lib 00434 */ 00435 isf_status_t dm_device_read( 00436 dm_DeviceHandle_t *apDeviceHandle, 00437 comm_Command_t *apReadCmd, 00438 comm_MessageBuffer_t *apReadBuffer 00439 ); 00440 00441 /*! @brief This function reads from a device with extended behavior. 00442 * 00443 * @details dm_device_readx() reads data from the specified device. The supplied command is sent to the device which may trigger the device 00444 * to return some data. Any data returned by the device is read and placed in the provided read buffer. dm_device_readx() 00445 * modifies the basic behavior of the read command by passing a set of bit flags to the underlying protocol interface. To 00446 * successfully use the extended behavior, it is necessary to understand the underlying protocol being used and to pass the appropriate flag values. 00447 * The device is implicitly locked during the extension read. 00448 * 00449 * @param[in] apDeviceHandle The handle to the device from which to read. 00450 * @param[in] apReadCmd The read command to transmit to the device. 00451 * @param[out] apReadBuffer Address of the buffer in which to place the read data. 00452 * @param[in] aFlags A set of bit flags controlling the behavior of the read. 00453 * @return ::dm_device_readx() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00454 * @retval ::ISF_SUCCESS is returned when the device was read successfully. 00455 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00456 * @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. 00457 * @retval ::COMM_ERROR_STOP is returned when the read is invoked on a stopped channel. 00458 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgment was received from the device. 00459 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00460 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00461 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00462 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device. 00463 * 00464 * @Constraints The following constraints must be observed when using this function: 00465 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully. 00466 * 00467 * @Reentrant Yes 00468 * @Libs isf_core.lib 00469 */ 00470 isf_status_t dm_device_readx( 00471 dm_DeviceHandle_t *apDeviceHandle, 00472 comm_Command_t *apReadCmd, 00473 comm_MessageBuffer_t *apReadBuffer, 00474 comm_Flags_t aFlags 00475 ); 00476 00477 /*! @brief This function writes to a device. 00478 * 00479 * @details dm_device_write() writes data to the specified device. The device is implicitly locked during the write. 00480 * 00481 * @param[in] apDeviceHandle The handle of the device to which to write. 00482 * @param[in] apWriteCmd The command to send to the device. 00483 * @return ::dm_device_write() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00484 * @retval ::ISF_SUCCESS is returned when the device was written successfully. 00485 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00486 * @retval ::COMM_ERROR_STOP is returned when the write is invoked on a stopped channel. 00487 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgment was received from the device. 00488 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00489 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00490 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00491 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device. 00492 * 00493 * @Constraints The following constraints must be observed when using this function: 00494 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully. 00495 * 00496 * @Reentrant Yes 00497 * @Libs isf_core.lib 00498 */ 00499 isf_status_t dm_device_write( 00500 dm_DeviceHandle_t *apDeviceHandle, 00501 comm_Command_t *apWriteCmd 00502 ); 00503 00504 /*! @brief This function writes data to a device with extended write behavior. 00505 * 00506 * @details dm_device_writex() writes data to the specified device. This function modifies the basic behavior of the write command by passing a set of bit flags to the underlying 00507 * protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol used and to pass 00508 * 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 00509 * flag values to explicitly control the RepeatedStart behavior at the conclusion of the ::dm_device_write() call. The device is implicitly locked during 00510 * the extension write. 00511 * 00512 * @param[in] apDeviceHandle The handle of the device to which to write. 00513 * @param[in] apWriteCmd The command to send to the device. 00514 * @param[in] aFlags A set of bit flags controlling the behavior of the write. 00515 * @return ::dm_device_writex() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful. 00516 * @retval ::ISF_SUCCESS is returned when the data was successfully written to the device. 00517 * @retval ::COMM_ERROR_INIT is returned when the channel handle refers to a non-initialized channel. 00518 * @retval ::COMM_ERROR_STOP is returned when the write is invoked on a stopped channel. 00519 * @retval ::COMM_ERROR_NO_ACK is returned when no acknowledgment was received from the device. 00520 * @retval ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function. 00521 * @retval ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period. 00522 * @retval ::COMM_ERROR_LOCK is returned when a lock could not be acquired properly. 00523 * @retval ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device. 00524 * 00525 * @Constraints The following constraints must be observed when using this function: 00526 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function returns successfully. 00527 * 00528 * @Reentrant Yes 00529 * @Libs isf_core.lib 00530 */ 00531 isf_status_t dm_device_writex( 00532 dm_DeviceHandle_t *apDeviceHandle, 00533 comm_Command_t *apWriteCmd, 00534 comm_Flags_t aFlags 00535 ); 00536 00537 /** @} */ 00538 00539 /*! @brief This function retrieves the channel descriptor from a device handle. 00540 * 00541 * @details dm_channel_get_descriptor() returns the channel descriptor associated with the channel on which the device resides. 00542 * 00543 * @param[in] apDeviceHandle Handle of device connected on the channel of interest. 00544 * 00545 * @return ::dm_channel_get_descriptor() returns a value of type ::dm_ChannelDescriptor_t which is pointer to an object. 00546 * @retval NULL is returned when the specified device handle is invalid. 00547 * 00548 * @Constraints None 00549 * 00550 * @Constraints The following constraints must be observed when using this function: 00551 * @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully. 00552 * 00553 * @Reentrant Yes 00554 * @Libs isf_core.lib 00555 */ 00556 dm_ChannelDescriptor_t* dm_channel_get_descriptor(dm_DeviceHandle_t *apDeviceHandle); 00557 00558 #endif /* INCLUDE_DEVICE_MESSAGING_H */ 00559