![]() |
ISF
1.1
Intelligent Sensing Framework
|
isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component. More...
Go to the source code of this file.
Data Structures | |
struct | protocol_t |
This structure contains protocol-specific function pointers and properties. More... | |
struct | dm_ChannelDescriptor_struct |
This structure is a declaration of a channel descriptor type. More... | |
struct | dm_DeviceHandle_struct |
This structure defines a handle for the device. More... | |
Typedefs | |
typedef isf_status_t(* | fnInit_t )(comm_Id_t aBusId, void *apBusHandle) |
This is the function pointer signature for bus initialization. | |
typedef comm_State_t(* | fnGetState_t )(void *apBusHandle) |
This is the function pointer signature for getting the state of the bus. | |
typedef isf_status_t(* | fnGetConfig_t )(void *apBusHandle, void *apBusConfig) |
This is the function pointer signature for getting the configuration of the bus. | |
typedef isf_status_t(* | fnConfigure_t )(void *apBusHandle, void *apBusConfig) |
This is the function pointer signature for setting the configuration of the bus. | |
typedef isf_status_t(* | fnStart_t )(void *apBusHandle) |
This is the function pointer signature for starting the bus. | |
typedef isf_status_t(* | fnStop_t )(void *apBusHandle, isf_duration_t aTimeout) |
This is the function pointer signature for stopping the bus. | |
typedef isf_status_t(* | fnGetSlaveAt_t )(void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle) |
This is the function pointer signature for getting the slave handle. | |
typedef 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. | |
typedef isf_status_t(* | fnReleaseLock_t )(void *apBusHandle) |
This is the function pointer signature for releasing the lock for a particular bus. | |
typedef isf_status_t(* | fnRead_t )(void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags) |
This is the function pointer signature for reading the data from a specified device. | |
typedef isf_status_t(* | fnWrite_t )(void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags) |
This is the the function pointer signature for writing the data to a specified device. | |
typedef comm_Id_t | dm_ChannelId_t |
This typedef is a umeric channel identifier index into an array of channels in the system. | |
typedef void * | dm_ChannelConfig_ptr |
This structure defines the user-specified parameters for channel configuration. | |
typedef struct dm_ChannelDescriptor_struct | dm_ChannelDescriptor_t |
This structure is a declaration of a channel descriptor type. | |
typedef struct dm_DeviceHandle_struct | dm_DeviceHandle_t |
This structure defines a handle for the device. | |
Functions | |
dm_ChannelDescriptor_t * | dm_channel_get_descriptor (dm_DeviceHandle_t *apDeviceHandle) |
This function retrieves the channel descriptor from a device handle. | |
Initialization Routines | |
isf_status_t | dm_channel_init (dm_ChannelId_t aChannelId, dm_ChannelDescriptor_t *apChannelDescriptor) |
This function initializes a channel. | |
isf_status_t | dm_channel_configure (dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr aChannelConfig) |
This function reconfigures an already initialized channel. | |
Queries and Status | |
comm_State_t | dm_channel_get_state (dm_ChannelDescriptor_t *apChannelDescriptor) |
This function returns the channel state. | |
isf_status_t | dm_channel_get_config (dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr aChannelConfig) |
This function returns the current channel configuration. | |
Device Control Routines | |
isf_status_t | dm_device_open (dm_ChannelDescriptor_t *apChannelDescriptor, comm_Address_t aDeviceAddr, dm_DeviceHandle_t *apDeviceHandle) |
This function creates a device handle for a device at a specified channel address. | |
isf_status_t | dm_device_close (dm_DeviceHandle_t *apDeviceHandle) |
This function closes a device. | |
Channel Control Routines | |
isf_status_t | dm_channel_start (dm_ChannelDescriptor_t *apChannelDescriptor) |
This function starts a channel. | |
isf_status_t | dm_channel_stop (dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout) |
This function stops a channel. | |
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_release_lock (dm_ChannelDescriptor_t *apChannelDescriptor) |
This function releases exclusive channel access. | |
Device Operation Routines | |
isf_status_t | dm_device_read (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apReadCmd, comm_MessageBuffer_t *apReadBuffer) |
This function reads from a device. | |
isf_status_t | dm_device_readx (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apReadCmd, comm_MessageBuffer_t *apReadBuffer, comm_Flags_t aFlags) |
This function reads from a device with extended behavior. | |
isf_status_t | dm_device_write (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apWriteCmd) |
This function writes to a device. | |
isf_status_t | dm_device_writex (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apWriteCmd, comm_Flags_t aFlags) |
This function writes data to a device with extended write behavior. |
isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component.
File: isf_devmsg.h
Copyright (c) 2012, Freescale Semiconductor, Inc.
Definition in file isf_devmsg.h.
typedef void* dm_ChannelConfig_ptr |
This structure defines the user-specified parameters for channel configuration.
This type allows the device messaging APIs to handle a protocol-specific configuration pointer opaquely until it is passed to the specific protocol functions that use the data.
Definition at line 103 of file isf_devmsg.h.
typedef struct dm_ChannelDescriptor_struct dm_ChannelDescriptor_t |
This structure is a declaration of a channel descriptor type.
The channel descriptor contains the bus and protocol information required by the device messaging functions to safely use a channel for communications. The members are ordered to maintain natural alignment without inserting padding bytes.
typedef comm_Id_t dm_ChannelId_t |
This typedef is a umeric channel identifier index into an array of channels in the system.
Definition at line 94 of file isf_devmsg.h.
typedef struct dm_DeviceHandle_struct dm_DeviceHandle_t |
This structure defines a handle for the device.
The device handle contains the information required by the device messaging functions to address and communicate with a slave device.
typedef 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.
Definition at line 62 of file isf_devmsg.h.
typedef isf_status_t(* fnConfigure_t)(void *apBusHandle, void *apBusConfig) |
This is the function pointer signature for setting the configuration of the bus.
Definition at line 46 of file isf_devmsg.h.
typedef isf_status_t(* fnGetConfig_t)(void *apBusHandle, void *apBusConfig) |
This is the function pointer signature for getting the configuration of the bus.
Definition at line 42 of file isf_devmsg.h.
typedef isf_status_t(* fnGetSlaveAt_t)(void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle) |
This is the function pointer signature for getting the slave handle.
Definition at line 58 of file isf_devmsg.h.
typedef comm_State_t(* fnGetState_t)(void *apBusHandle) |
This is the function pointer signature for getting the state of the bus.
Definition at line 38 of file isf_devmsg.h.
typedef isf_status_t(* fnInit_t)(comm_Id_t aBusId, void *apBusHandle) |
This is the function pointer signature for bus initialization.
Definition at line 34 of file isf_devmsg.h.
typedef isf_status_t(* fnRead_t)(void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags) |
This is the function pointer signature for reading the data from a specified device.
Definition at line 70 of file isf_devmsg.h.
typedef isf_status_t(* fnReleaseLock_t)(void *apBusHandle) |
This is the function pointer signature for releasing the lock for a particular bus.
Definition at line 66 of file isf_devmsg.h.
typedef isf_status_t(* fnStart_t)(void *apBusHandle) |
This is the function pointer signature for starting the bus.
Definition at line 50 of file isf_devmsg.h.
typedef isf_status_t(* fnStop_t)(void *apBusHandle, isf_duration_t aTimeout) |
This is the function pointer signature for stopping the bus.
Definition at line 54 of file isf_devmsg.h.
typedef isf_status_t(* fnWrite_t)(void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags) |
This is the the function pointer signature for writing the data to a specified device.
Definition at line 74 of file isf_devmsg.h.
isf_status_t dm_channel_acquire_lock | ( | dm_ChannelDescriptor_t * | apChannelDescriptor, |
isf_duration_t | aTimeout | ||
) |
This function locks the channel for exclusive access.
dm_channel_acquire_lock() serializes multi-client access. Each channel user must acquire a lock prior to sending device messages. While holding the channel lock, no other clients may perform any channel operations. Therefore, it is important to release the lock with dm_channel_release_lock() as soon as practical.
[in] | apChannelDescriptor | The handle of the channel to be started. |
[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 acquiring the lock, or wait as long as necessary for the lock to be acquired. |
ISF_SUCCESS | is returned when the channel lock is acquired. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
isf_status_t dm_channel_configure | ( | dm_ChannelDescriptor_t * | apChannelDescriptor, |
dm_ChannelConfig_ptr | aChannelConfig | ||
) |
This function reconfigures an already initialized channel.
A channel may be reconfigured after initialization. Calls to dm_channel_configure() after initialization will override any previous configuration values and must be made while the channel state is COMM_STATE_STOPPED. The typical usage involves retrieving the current configuration using dm_channel_get_config(), making modifications to the returned configuration, and then calling dm_channel_configure() with the updated configuration. The channel is implicitly locked during the configuration.
[in] | apChannelDescriptor | The handle of the channel to be configured. |
[in] | aChannelConfig | The channel configuration used during initialization. |
ISF_SUCCESS | is returned when the channel was reconfigured successfully. |
COMM_ERROR_STOP | is returned when the channel was not STOPPED. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
isf_status_t dm_channel_get_config | ( | dm_ChannelDescriptor_t * | apChannelDescriptor, |
dm_ChannelConfig_ptr | aChannelConfig | ||
) |
This function returns the current channel configuration.
A channel may be queried for the current configuration.
[in] | apChannelDescriptor | The handle of the channel to be queried. |
[out] | aChannelConfig | The address of a channel configuration to be filled. |
ISF_SUCCESS | is returned when the channel configuration is retrieved successfully. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
dm_ChannelDescriptor_t* dm_channel_get_descriptor | ( | dm_DeviceHandle_t * | apDeviceHandle | ) |
This function retrieves the channel descriptor from a device handle.
dm_channel_get_descriptor() returns the channel descriptor associated with the channel on which the device resides.
[in] | apDeviceHandle | Handle of device connected on the channel of interest. |
NULL | is returned when the specified device handle is invalid. |
comm_State_t dm_channel_get_state | ( | dm_ChannelDescriptor_t * | apChannelDescriptor | ) |
This function returns the channel state.
A channel may be queried for its current state.
[in] | apChannelDescriptor | The handle of the channel to be queried. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
isf_status_t dm_channel_init | ( | dm_ChannelId_t | aChannelId, |
dm_ChannelDescriptor_t * | apChannelDescriptor | ||
) |
This function initializes a channel.
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 during the initialization.
[in] | aChannelId | The ID of the channel to initialize. This is an index into the array of known channels that can be used. |
[out] | apChannelDescriptor | The address of the channel descriptor structure to be initialized. |
ISF_SUCCESS | is returned when the channel initialized successfully and the apChannelDescriptor structure reference has been populated with initialized channel data. |
COMM_ERROR_NOEXIST | is returned when the supplied channel identifier does not exist. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_INIT | is returned when the channel could not be initialized. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
isf_status_t dm_channel_release_lock | ( | dm_ChannelDescriptor_t * | apChannelDescriptor | ) |
This function releases exclusive channel access.
dm_channel_release_lock() is used to relinquish exclusive access on a paricular channel. It is the inverse of dm_channel_acquire_lock().
[in] | apChannelDescriptor | The handle of the channel to unlock. |
ISF_SUCCESS | is returned when the channel released successfully. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_LOCK | is returned when no lock was held on the specified channel. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
isf_status_t dm_channel_start | ( | dm_ChannelDescriptor_t * | apChannelDescriptor | ) |
This function starts a channel.
dm_channel_start() enables communications with an initialized channel. This call enables the hardware peripherals associated with the channel. The channel is implicitly locked during the start operation.
[in] | apChannelDescriptor | The handle of the channel to be started. |
ISF_SUCCESS | is returned when the channel was started successfully. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
isf_status_t dm_channel_stop | ( | dm_ChannelDescriptor_t * | apChannelDescriptor, |
isf_duration_t | aTimeout | ||
) |
This function stops a channel.
dm_channel_stop() disables an initialized channel and stops communications with the channel. This call disables the hardware peripherals associated with the channel. The channel is implicitly locked during the stop operation.
[in] | apChannelDescriptor | The handle of the channel to be stopped. |
[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. |
ISF_SUCCESS | is returned when the channel is successfully stopped. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
isf_status_t dm_device_close | ( | dm_DeviceHandle_t * | apDeviceHandle | ) |
This function closes a device.
The dm_device_close() function is used when no further communication with the device is needed. A closed device should not be passed to dm_device_read() or dm_device_write(). The channel is implicitly locked during the close operation.
[in] | apDeviceHandle | The address of the DeviceHandle to be closed. |
ISF_SUCCESS | is returned when the device changes to closed. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
isf_status_t dm_device_open | ( | dm_ChannelDescriptor_t * | apChannelDescriptor, |
comm_Address_t | aDeviceAddr, | ||
dm_DeviceHandle_t * | apDeviceHandle | ||
) |
This function creates a device handle for a device at a specified channel address.
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 during the open.
[in] | apChannelDescriptor | The handle of the channel to be queried. |
[in] | aDeviceAddr | The known address of a device. |
[out] | apDeviceHandle | The address of a DeviceHandle to be filled. dm_device_open() fills the provided device handle structure with valid data when a device is found at the specified address. |
ISF_SUCCESS | is returned when the device is located and a valid handle is returned. |
COMM_ERROR_NOEXIST | is returned when a device does not exist at the specified address. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_STOP | is returned when the channel has not been started. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
isf_status_t dm_device_read | ( | dm_DeviceHandle_t * | apDeviceHandle, |
comm_Command_t * | apReadCmd, | ||
comm_MessageBuffer_t * | apReadBuffer | ||
) |
This function reads from a device.
dm_device_read() reads data from the specified device. The supplied command is sent to the device triggering the 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 does not trigger the device to return data, the dm_device_read() simply returns 0 bytes read. The device is implicitly locked during the read.
[in] | apDeviceHandle | The handle to the device from which to read. |
[in] | apReadCmd | The read command to send to the device. |
[in] | apReadBuffer | Buffer address where any returned data is placed. |
ISF_SUCCESS | is returned when data from the device was read successfully. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
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. |
COMM_ERROR_STOP | is returned when the read is invoked on a stopped channel. |
COMM_ERROR_NO_ACK | is returned when no acknowledgment was received from the device. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
COMM_ERROR_DEV_CLOSED | is returned when the read is invoked on a closed device. |
isf_status_t dm_device_readx | ( | dm_DeviceHandle_t * | apDeviceHandle, |
comm_Command_t * | apReadCmd, | ||
comm_MessageBuffer_t * | apReadBuffer, | ||
comm_Flags_t | aFlags | ||
) |
This function reads from a device with extended behavior.
dm_device_readx() reads data from the specified device. The supplied command is sent to the device which may trigger the device to return some data. Any data returned by the device is read and placed in the provided read buffer. dm_device_readx() modifies the basic behavior of the read command by passing a set of bit flags to the underlying protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol being used and to pass the appropriate flag values. The device is implicitly locked during the extension read.
[in] | apDeviceHandle | The handle to the device from which to read. |
[in] | apReadCmd | The read command to transmit to the device. |
[out] | apReadBuffer | Address of the buffer in which to place the read data. |
[in] | aFlags | A set of bit flags controlling the behavior of the read. |
ISF_SUCCESS | is returned when the device was read successfully. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_BUF_SIZE | The provided buffer is too small to hold all the data or the number of bytes to read is zero. |
COMM_ERROR_STOP | is returned when the read is invoked on a stopped channel. |
COMM_ERROR_NO_ACK | is returned when no acknowledgment was received from the device. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
COMM_ERROR_DEV_CLOSED | is returned when the read is invoked on a closed device. |
isf_status_t dm_device_write | ( | dm_DeviceHandle_t * | apDeviceHandle, |
comm_Command_t * | apWriteCmd | ||
) |
This function writes to a device.
dm_device_write() writes data to the specified device. The device is implicitly locked during the write.
[in] | apDeviceHandle | The handle of the device to which to write. |
[in] | apWriteCmd | The command to send to the device. |
ISF_SUCCESS | is returned when the device was written successfully. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_STOP | is returned when the write is invoked on a stopped channel. |
COMM_ERROR_NO_ACK | is returned when no acknowledgment was received from the device. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
COMM_ERROR_DEV_CLOSED | is returned when the write is invoked on a closed device. |
isf_status_t dm_device_writex | ( | dm_DeviceHandle_t * | apDeviceHandle, |
comm_Command_t * | apWriteCmd, | ||
comm_Flags_t | aFlags | ||
) |
This function writes data to a device with extended write behavior.
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 protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol used and to pass 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 flag values to explicitly control the RepeatedStart behavior at the conclusion of the dm_device_write() call. The device is implicitly locked during the extension write.
[in] | apDeviceHandle | The handle of the device to which to write. |
[in] | apWriteCmd | The command to send to the device. |
[in] | aFlags | A set of bit flags controlling the behavior of the write. |
ISF_SUCCESS | is returned when the data was successfully written to the device. |
COMM_ERROR_INIT | is returned when the channel handle refers to a non-initialized channel. |
COMM_ERROR_STOP | is returned when the write is invoked on a stopped channel. |
COMM_ERROR_NO_ACK | is returned when no acknowledgment was received from the device. |
COMM_ERROR_NULL_PTR | is returned when a NULL pointer argument was passed into the function. |
COMM_ERROR_TIME_OUT | is returned when the request could not be fulfilled in the specified timeout period. |
COMM_ERROR_LOCK | is returned when a lock could not be acquired properly. |
COMM_ERROR_DEV_CLOSED | is returned when the write is invoked on a closed device. |