ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_spi_master_adapter.h File Reference

isf_spi_master_adapter.h defines the API definitions and types for the spi master protocol adapter. More...

#include "isf_spi_master_types.h"
#include "fsl_spi_master_driver.h"
#include "fsl_spi_hal.h"
#include "isf_comm.h"
#include "isf_protocol_adapter.h"
Include dependency graph for isf_spi_master_adapter.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  spi_master_Endpoint_struct
 This structure defines a device endpoint encapsulation for spi handler. More...
 

Typedefs

typedef struct
spi_master_Endpoint_struct 
spi_master_Endpoint_t
 This structure defines a device endpoint encapsulation for spi handler. More...
 
typedef comm_Flags_t spi_master_writeFlags_t
 
typedef comm_Flags_t spi_master_readFlags_t
 

Enumerations

enum  spi_comm_flag { SPI_SYNC = 0, SPI_ASYNC = 1 }
 
enum  spi_lock_type { SPI_LOCK_COMMON, SPI_LOCK_READ }
 

Functions

isf_status_t spi_master_adapter_init (comm_Id_t aBusId, busHandle_t *apBusHandle)
 This function initializes a spi bus. More...
 
isf_status_t spi_master_adapter_configure (busHandle_t *apBusHandle, spi_master_busConfig_t *apBusConfig)
 This function reconfigures an already initialized bus. More...
 
comm_State_t spi_master_adapter_get_state (busHandle_t *apBusHandle)
 This function returns the current bus state. More...
 
isf_status_t spi_master_adapter_get_config (busHandle_t *apBusHandle, void *apBusConfig)
 This function returns the current bus configuration. More...
 
isf_status_t spi_master_adapter_acquire_lock (busHandle_t *apBusHandle, isf_duration_t aTimeout)
 This function locks the bus for exclusive access. More...
 
isf_status_t spi_master_adapter_release_lock (busHandle_t *apBusHandle)
 This function releases exclusive bus access. More...
 
isf_status_t spi_master_adapter_start (busHandle_t *apBusHandle)
 This function starts a bus. More...
 
isf_status_t spi_master_adapter_stop (busHandle_t *apBusHandle)
 This function stops the given spi bus. More...
 
isf_status_t spi_master_adapter_get_endpoint (busHandle_t *apBusHandle, void *apDevice, void **apEndpointHandle)
 This function creates a endpoint for a device at a specified bus address. More...
 
isf_status_t spi_master_adapter_release_endpoint (spi_master_Endpoint_t *apEndpoint)
 This function closes a particular endpoint. More...
 
isf_status_t spi_master_adapter_write (void *apEndpointHandle, int32 offset, void *apWriteBuffer, uint32 aBuffsize, uint32 aNbyteWrite, spi_master_writeFlags_t aFlags)
 This function writes to a spi device. More...
 
isf_status_t spi_master_adapter_read (void *apEndpointHandle, int32 offset, void *apReadBuffer, uint32 aBuffsize, uint32 aNbyteRead, spi_master_readFlags_t aFlags)
 This function reads from a spi device. More...
 

Detailed Description

isf_spi_master_adapter.h defines the API definitions and types for the spi master protocol adapter.

File: isf_spi_master_adapter.h

Copyright (c) 2014, Freescale Semiconductor, Inc.

Definition in file isf_spi_master_adapter.h.

Typedef Documentation

This structure defines a device endpoint encapsulation for spi handler.

Definition at line 37 of file isf_spi_master_adapter.h.

Definition at line 36 of file isf_spi_master_adapter.h.

Enumeration Type Documentation

Type specifying for the spi modes

Enumerator
SPI_SYNC 

Read/write in synchronized mode.

SPI_ASYNC 

Read/Write in asynchronized mode.

Definition at line 26 of file isf_spi_master_adapter.h.

Enumerator
SPI_LOCK_COMMON 
SPI_LOCK_READ 

Definition at line 31 of file isf_spi_master_adapter.h.

Function Documentation

isf_status_t spi_master_adapter_acquire_lock ( busHandle_t apBusHandle,
isf_duration_t  aTimeout 
)

This function locks the bus for exclusive access.

spi_master_adapter_acquire_lock() serializes multi-client access. While holding the bus lock, no other clients may perform any bus operations. Therefore, it is important to release the lock with spi_master_adapter_release_lock() as soon as practical.

Parameters
[in]apBusHandleThe handle of the bus to be started.
[in]aTimeoutThe 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.
Returns
dm_channel_acquire_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus lock is acquired.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized channel.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 156 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busConfig, COMM_ERROR_NULL_PTR, ISF_SUCCESS, busHandle_struct::pHandle, SPI_LOCK_COMMON, and spi_master_BusConfig_struct::timeout.

isf_status_t spi_master_adapter_configure ( busHandle_t apBusHandle,
spi_master_busConfig_t apBusConfig 
)

This function reconfigures an already initialized bus.

A bus may be reconfigured after initialization. Calls to spi_master_adapter_configure() after initialization will override any previous configuration values and must be made while the bus state is COMM_STATE_STOPPED. The typical usage involves retrieving the current configuration using spi_master_adapter_get_config(), making modifications to the returned configuration, and then calling spi_master_adapter_configure() with the updated configuration. The bus is implicitly locked during the configuration.

Parameters
[in]busHandle_tThe handle of the bus to be configured.
[in]apBusConfigThe configuration value for the bus to be configured.
Returns
spi_master_adapter_configure() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus was reconfigured successfully.
COMM_ERROR_STOPis returned when the bus was not STOPPED.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handler is created when the spi_master_adapter_init() function call is successfully returned.
Reentrant: Yes
Link Libraries:
None

Definition at line 95 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busConfig, spi_mater_BusHandle_struct::busState, COMM_ERROR_NULL_PTR, COMM_ERROR_STOP, COMM_STATE_INIT, COMM_STATE_STOPPED, SPIHandle::instance, ISF_SUCCESS, busHandle_struct::pHandle, SPI_LOCK_COMMON, SPI_LOCK_READ, spi_master_configure_bus(), spi_mater_BusHandle_struct::spiHandle, and spi_master_BusConfig_struct::timeout.

Here is the call graph for this function:

isf_status_t spi_master_adapter_get_config ( busHandle_t apBusHandle,
void *  apBusConfig 
)

This function returns the current bus configuration.

A bus may be queried for the current configuration.

Parameters
[in]apBusHandleThe handle of the bus to be queried.
[out]apBusConfigThe address of a bus configuration to be filled.
Returns
spi_master_adapter_get_config() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus configuration is retrieved successfully.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized bus.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 138 of file isf_spi_master_adapter.c.

References COMM_ERROR_NULL_PTR, ISF_SUCCESS, and busHandle_struct::pHandle.

isf_status_t spi_master_adapter_get_endpoint ( busHandle_t apBusHandle,
void *  apDevice,
void **  apEndpointHandle 
)

This function creates a endpoint for a device at a specified bus address.

The spi_master_adapter_get_endpoint() function may be used to get a handle to a device at a known bus address.

Parameters
[in]apBusHandleThe handle of the bus to be opened.
[in]apDeviceThe known information of the device to be opened.
[out]apEndpointHandleThe address of a apEndpointHandle to be filled.
Returns
spi_master_adapter_get_endpoint() returns a value of type isf_status_t indicating the success or failure of the function call.
Return values
ISF_SUCCESSis returned when the device is located and a valid handle is returned.
COMM_ERROR_NOEXISTis returned when a device does not exist at the specified bus.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_STOPis returned when the channel has not been started.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib

Definition at line 235 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busConfig, spi_mater_BusHandle_struct::busState, COMM_ERROR_NULL_PTR, COMM_ERROR_STOP, COMM_STATE_OK, ISF_SUCCESS, spi_master_Endpoint_struct::pBusHandle, busHandle_struct::pHandle, spi_master_Endpoint_struct::pSlaveInfo, spi_mater_slaveInfo::slaveinit, SPI_LOCK_COMMON, and spi_master_BusConfig_struct::timeout.

comm_State_t spi_master_adapter_get_state ( busHandle_t apBusHandle)

This function returns the current bus state.

A bus may be queried for its current state.

Parameters
[in]apBusHandleThe handle of the bus to be queried.
Returns
spi_master_adapter_get_state() returns a value of type comm_State_t indicating the current state of the bus.
Return values
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None.

Definition at line 124 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busState, COMM_ERROR_NULL_PTR, and busHandle_struct::pHandle.

isf_status_t spi_master_adapter_init ( comm_Id_t  aBusId,
busHandle_t apBusHandle 
)

This function initializes a spi bus.

A bus must be initialized prior to use. Initialization creates the bus and initializes the data structures required to manage the bus.

Parameters
[in]aBusIdThe ID of the bus to initialize. This is an index into the array of known spi buses that can be used.
[out]busHandle_tThe handle to the bus to be initialized.
Returns
spi_master_adapter_init() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus is initialized successfully and the apBusHandle structure reference has been populated with initialized spi bus data.
COMM_ERROR_NOEXISTis returned when the supplied bus identifier does not exist.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_INITis returned when the bus could not be initialized.
Constraints:
None
Reentrant: Yes
Link Libraries:
None

Definition at line 45 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busState, COMM_ERROR_INIT, COMM_ERROR_NOEXIST, COMM_STATE_INIT, COMM_STATE_NO_INIT, gSys_NumSpiBuses, ISF_SPI_LOCK_DEFAULT, ISF_SUCCESS, busHandle_struct::nLock, busHandle_struct::nRdLock, busHandle_struct::pHandle, busHandle_struct::pLock, busHandle_struct::pRdLock, spi_master_init(), spi_master_lock, and spi_master_rdlock.

Here is the call graph for this function:

isf_status_t spi_master_adapter_read ( void *  apEndpointHandle,
int32  offset,
void *  apReadBuffer,
uint32  aBuffsize,
uint32  aNbyteRead,
spi_master_readFlags_t  aFlags 
)

This function reads from a spi device.

spi_master_adapter_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. The device is implicitly locked during the read.

Parameters
[in]apEndpointHandleThe handle to the device endpoint for.
[in]offsetThe read offset/sub address from which the data to be read.
[in]apReadBufferThe buffer address where any returned data is placed.
[in]aBuffsizeThe size of the buffer passed.
[in]aNbyteReadThe number of bytes to read from the device.
[in]aFlagsThe read flag that change the mode of read of operation.
Returns
spi_master_adapter_read() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when data from the device was read successfully.
COMM_ERROR_BUF_SIZEis returned when the provided buffer is too small to hold all the data or the number of bytes read is zero.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
Reentrant: Yes
Link Libraries:
None

Definition at line 328 of file isf_spi_master_adapter.c.

References ISF_SUCCESS, spi_master_Endpoint_struct::pBusHandle, and busHandle_struct::pHandle.

isf_status_t spi_master_adapter_release_endpoint ( spi_master_Endpoint_t apEndpoint)

This function closes a particular endpoint.

The spi_master_adapter_release_endpoint() function is used when no further communication with the device is needed. A closed device should not be passed to spi_master_adapter_write() or spi_master_adapter_write().

Parameters
[in]apEndpointThe address of the end point where the endpoint is established.
Returns
spi_master_adapter_release_endpoint() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the device changes to closed.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • pBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 267 of file isf_spi_master_adapter.c.

References COMM_ERROR_NULL_PTR, and ISF_SUCCESS.

isf_status_t spi_master_adapter_release_lock ( busHandle_t apBusHandle)

This function releases exclusive bus access.

spi_master_adapter_release_lock() is used to relinquish exclusive access on a particular bus. It is the inverse of spi_master_adapter_acquire_lock().

Parameters
[in]apBusHandleThe handle of the bus to unlock.
Returns
spi_master_adapter_release_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus released successfully.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized channel.
COMM_ERROR_LOCKis returned when no lock was held on the specified bus.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 173 of file isf_spi_master_adapter.c.

References COMM_ERROR_NULL_PTR, ISF_SUCCESS, and SPI_LOCK_COMMON.

isf_status_t spi_master_adapter_start ( busHandle_t apBusHandle)

This function starts a bus.

spi_master_adapter_start() enables communications with an initialized bus.

Parameters
[in]apBusHandleThe handle of the bus to be started.
Returns
spi_master_adapter_start() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus was started successfully.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 189 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busConfig, spi_mater_BusHandle_struct::busState, COMM_ERROR_NULL_PTR, COMM_STATE_OK, SPIHandle::instance, busHandle_struct::pHandle, spi_hal_enable(), SPI_LOCK_COMMON, spi_mater_BusHandle_struct::spiHandle, and spi_master_BusConfig_struct::timeout.

Here is the call graph for this function:

isf_status_t spi_master_adapter_stop ( busHandle_t apBusHandle)

This function stops the given spi bus.

spi_master_adapter_stop() disables an initialized bus and stops communications with the channel.

Parameters
[in]apBusHandleThe handle of the bus to be stopped.
Returns
spi_master_adapter_stop() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the bus is successfully stopped.
COMM_ERROR_INITis returned when the bus handle refers to a non-initialized channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apBusHandle must be valid. A valid spi bus handle is created when the spi_master_adapter_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
None

Definition at line 211 of file isf_spi_master_adapter.c.

References spi_mater_BusHandle_struct::busConfig, spi_mater_BusHandle_struct::busState, COMM_ERROR_NULL_PTR, COMM_STATE_STOPPED, SPIHandle::instance, busHandle_struct::pHandle, spi_hal_disable(), SPI_LOCK_COMMON, spi_mater_BusHandle_struct::spiHandle, and spi_master_BusConfig_struct::timeout.

Here is the call graph for this function:

isf_status_t spi_master_adapter_write ( void *  apEndpointHandle,
int32  offset,
void *  apWriteBuffer,
uint32  aBuffsize,
uint32  aNbyteWrite,
spi_master_writeFlags_t  aFlags 
)

This function writes to a spi device.

spi_master_adapter_write () writes data to the specified device. The device is implicitly locked during the write.

Parameters
[in]apEndpointHandleThe handle to the device endpoint to which to write is performed.
[in]offsetThe read offset/sub address from which the data to be write.
[in]apWriteBufferThe buffer address where write data is placed.
[in]aBuffsizeThe size of the buffer passed.
[in]aNbyteReadThe number of bytes to write to the device.
[in]aFlagsThe write flag that change the mode of read of operation.
Returns
spi_master_adapter_write() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values
ISF_SUCCESSis returned when the device was written successfully.
COMM_ERROR_STOPis returned when the write is invoked on a stopped channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
Reentrant: Yes
Link Libraries:
isf_core.lib

Definition at line 282 of file isf_spi_master_adapter.c.

References spi_master_Endpoint_struct::pBusHandle, and busHandle_struct::pHandle.