MMAC
Software Group
API – Clocked Serial Interface (CSI)
EMMA2 Software User’s Manual
Contents
1 Introduction .....................................................................................................................................2
1.1 Overview...............................................................................................................................2
2 Architecture .....................................................................................................................................3
2.1 Return codes ........................................................................................................................3
2.2 Includes ................................................................................................................................4
2.3 Initialisation ...........................................................................................................................4
2.4 Configuration ........................................................................................................................4
2.5 Type Definitions ....................................................................................................................5
2.6 Sample Code ........................................................................................................................6
3 Function Prototypes ........................................................................................................................7
MMAC_CSI_Initialise............................................................................................................7
MMAC_CSI_Open................................................................................................................8
MMAC_CSI_Close ...............................................................................................................9
MMAC_CSI_Read ..............................................................................................................10
MMAC_CSI_Write ..............................................................................................................12
MMAC_CSI_Cntrl ...............................................................................................................14
4 Revision History ............................................................................................................................16
Book No: n/a (shared document) Doc No: MMAC0150, Issue: 1.0
© NEC Electronics Corporation 2003, 2004 Date: 2004-02-16
The information is this document is subject to change without notice – it is the reader’s responsibility to check that this is the current version.
This document includes company confidential information. It should only be released to third parties under a Non-Disclosure Agreement.
1 Introduction
1.1 Overview
This document describes the API for the MMAC Clocked Serial Interface (CSI) driver. The API is
defined in terms of a read/write/open/close/cntrl interface. Parameter passing is facilitated through I/O
parameter blocks. Functions are passed a pointer to a function-dependent structure that contains input
and output parameters.
Only one CSI channel is provided.
2 / 16
2 Architecture
2.1 Return codes
The meaning of the various result codes returned by the driver is described in the following table:
Result Code Description
MMAC_CSI_OK A CSI operation has successfully completed.
MMAC_CSI_FAIL A CSI operation has not completed.
A call to MMAC_CSI_Cntrl( ) can be made to determine the
specific error.
MMAC_CSI_ALREADY_ The CSI driver has already been initialised.
INITIALISED
MMAC_CSI_NOT_INITIALISED The CSI driver has not been initialised.
MMAC_CSI_ALREADY_OPEN The CSI channel has already been opened.
MMAC_CSI_NOT_OPEN The CSI channel has not been opened.
MMAC_CSI_INVALID_PARAM A parameter passed is invalid, it is out of range or a NULL pointer
has been passed.
MMAC_CSI_OUT_OF_ Failue to create a semaphore, install or set a interrupt handler.
RESOURCES
MMAC_CSI_READ_TIMEOUT_ A CSI read timed out.
ERROR
MMAC_CSI_WRITE_TIMEOUT_ A CSI write timed out.
ERROR
3 / 16
2.2 Includes
In order to use this API, the following header file must be included:
#include “mmac/csi.h”
2.3 Initialisation
Prior to using any functions in this module, the following function must be called:
MMAC_RTOS_Initialise( )
2.4 Configuration
The default configuration for CSI channel is:
writeTimeout (ticks) MMAC_MAX_RTOS_TIMOUT
readTimeout (ticks) MMAC_MAX_RTOS_TIMOUT
By default the driver will block forever during a read and a write.
This configuration is read/modified using the MMAC_CSI_Cntrl( ) function with the MMAC_CSI_
SET_PARAMS and the MMAC_CSI_GET_PARAMS operations.
E.g. to change the read timeout, do:
{
MMAC_CSI_OPEN_IOPB openIOPB;
MMAC_CSI_CNTRL_IOPB cntrlIOPB;
MMAC_CSI_READ_IOPB readIOPB;
MMAC_CSI_WRITE_IOPB writeIOPB;
UI8 receiveBuffer[1024];
UI8 sendBuffer[]=”Hello”;
MMAC_CSI_Initialise( );
/* Open the CSI port */
MMAC_CSI_Open( &openIOPB );
[Link] = MMAC_CSI_GET_PARAMS;
MMAC_CSI_Cntrl( &cntrlIOPB );
[Link] = MMAC_CSI_SET_PARAMS;
[Link] = 100;
MMAC_CSI_Cntrl( &cntrlIOPB );
[Link] = sendBuffer;
[Link] = sizeof( sendBuffer );
MMAC_CSI_Write( &writeIopb );
[Link] = receiveBuffer;
[Link] = sizeof( receiveBuffer );
MMAC_CSI_Read( &readIOPB );
}
4 / 16
Options
A number of configurable options, in the form of ‘#define’s are specified in the
mmac/mmac_config.h file marked by this comment:
/*******************************************************************/
/* MMAC CSI SETUP */
/*******************************************************************/
These options are:
Define Default Meaning
MMAC_CSI_PARAMETER_ MMAC_YES Enables API level parameter checking.
CHECKING
MMAC_CSI_ACCESS_ MMAC_RTOS_MAX_ The number of ticks a calling task is
CONTROL_WAIT_TIME TIMEOUT blocked waiting for access to the
device.
MMAC_CSI_READ_ MMAC_RTOS_MAX_ The number of ticks a calling task is
TIMEOUT TIMEOUT blocked waiting for a read to complete.
MMAC_CSI_WRITE_ MMAC_RTOS_MAX_ The number of ticks a calling task is
TIMEOUT TIMEOUT blocked waiting for a write to complete.
2.5 Type Definitions
Return Codes
The following result codes are defined for the CSI device. The result code value 0 is reserved for
indication of a successful operation.
typedef enum
{
MMAC_CSI_OK,
MMAC_CSI_FAIL,
MMAC_CSI_INVALID_PARAM,
MMAC_CSI_NOT_OPEN,
MMAC_CSI_ALREADY_OPEN,
MMAC_CSI_TIMEOUT,
MMAC_CSI_NOT_INITIALISED,
MMAC_CSI_ALREADY_INITIALISED,
MMAC_CSI_OUT_OF_RESOURCES,
MMAC_CSI_READ_TIMEOUT_ERROR,
MMAC_CSI_WRITE_TIMEOUT_ERROR
}MMAC_CSI_RESULT_CODE;
MMAC_CSI_Read
The MMAC CSI driver read operation requires the following IOPB.
typedef struct
{
UI8 *data;
UI16 length;
}MMAC_CSI_READ_IOPB;
5 / 16
MMAC_CSI_Write
The MMAC CSI driver write operation requires the following IOPB.
typedef struct
{
UI8 *data;
UI16 length;
}MMAC_CSI_WRITE_IOPB;
MMAC_CSI_Cntrl
The MMAC CSI driver control operation requires the following IOPB.
typedef enum
{
MMAC_CSI_RESET,
MMAC_CSI_GET_PARAMS,
MMAC_CSI_SET_PARAMS,
MMAC_CSI_GET_ERROR
}MMAC_CSI_OPERATION;
typedef enum
{
MMAC_CSI_HW_NO_ERROR = 0x00,
MMAC_CSI_HW_ERROR = 0x01
}MMAC_CSI_ERROR;
typedef struct
{
UI32 writeTimeout;
UI32 readTimeout;
}MMAC_CSI_PARAMS;
typedef struct
{
MMAC_CSI_OPERATION operation;
MMAC_CSI_PARAMS params;
MMAC_CSI_ERROR error;
}MMAC_CSI_CNTRL_IOPB;
2.6 Sample Code
See the individual function descriptions.
6 / 16
3 Function Prototypes
MMAC_CSI_Initialise
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Initialise (void);
Inputs
None
Outputs
None
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_ALREADY_INITIALISED
Description
This function initialises any common hardware and data structures for every device.
See Also
MMAC_CSI_Open( )
Sample Code
if( MMAC_CSI_Initialise() )
{
/* Report Error */
}
7 / 16
MMAC_CSI_Open
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Open (void);
Inputs
None
Outputs
None
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_ALREADY_OPEN
MMAC_CSI_NOT_INITIALISED
Description
This function initialises the CSI hardware, readies it for reading and writing and allocates system
resources.
See Also
MMAC_CSI_Close( )
MMAC_CSI_Read( )
MMAC_CSI_Write( )
MMAC_CSI_Cntrl( )
Sample Code
/* Open the CSI port */
if( MMAC_CSI_Open( &openIOPB ) )
{
/* Report Error */
}
8 / 16
MMAC_CSI_Close
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Close (void);
Inputs
None
Outputs
None
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_NOT_OPEN
MMAC_CSI_NOT_INITIALISED
Description
This function disables the CSI hardware and returns allocated system resources.
See Also
MMAC_CSI_Open( )
MMAC_CSI_Read( )
MMAC_CSI_Write( )
MMAC_CSI_Cntrl( )
Sample Code
N/A
9 / 16
MMAC_CSI_Read
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Read (MMAC_CSI_READ_IOPB *iopb);
Inputs
iopb
This points to an MMAC_CSI_READ_IOPB structure. This structure is used to pass the
following parameters:
length
Length of the data to read.
data
A pointer to a buffer for storing data.
Outputs
iopb
This points to an MMAC_CSI_READ_IOPB structure. This structure is used to pass out the
following parameters:
length
Length of the data in buffer.
data
Data is passed back in the buffer pointed to by this pointer.
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_INVALID_PARAM
MMAC_CSI_NOT_OPEN
MMAC_CSI_FAIL
MMAC_CSI_READ_TIMEOUT_ERROR
MMAC_CSI_NOT_INITIALISED
Description
This function reads up to [Link] bytes from the CSI hardware, storing them in the buffer pointed
to by [Link].
If an error code is returned by this function more information about the error can be retrieved from
the driver using the MMAC_CSI_Cntrl( ) function with the MMAC_CSI_GET_ERROR operation.
See Also
MMAC_CSI_Open( )
MMAC_CSI_Close( )
MMAC_CSI_Write( )
MMAC_CSI_Cntrl( )
10 / 16
Sample Code
[Link] = receiveBuffer;
[Link] = sizeof( receiveBuffer );
if( MMAC_CSI_Read( &readIOPB ) )
{
/* Report Error */
}
11 / 16
MMAC_CSI_Write
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Write (MMAC_CSI_WRITE_IOPB *iopb);
Inputs
iopb
This points to an MMAC_CSI_WRITE_IOPB structure. This structure is used to pass the
following parameters:
length
Length of the data to write.
data
A pointer to a buffer of data.
Outputs
iopb
This points to an MMAC_CSI_WRITE_IOPB structure. This structure is used to pass out the
following parameters:
length
Length of the data written.
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_INVALID_PARAM
MMAC_CSI_NOT_OPEN
MMAC_CSI_WRITE_TIMEOUT_ERROR
MMAC_CSI_FAIL
MMAC_CSI_NOT_INITIALISED
Description
This function writes up to [Link] bytes to the CSI hardware from the buffer pointed to by
[Link].
If an error code is returned by this function more information about the error can be retrieved from
the driver using the MMAC_CSI_Cntrl( ) function with the MMAC_CSI_GET_ERROR operation.
See Also
MMAC_CSI_Open( )
MMAC_CSI_Close( )
MMAC_CSI_Read( )
MMAC_CSI_Cntrl( )
Sample Code
[Link] = sendBuffer;
[Link] = sizeof( sendBuffer );
if( MMAC_CSI_Write( &writeIopb ))
{
/* Report Error */
12 / 16
}
13 / 16
MMAC_CSI_Cntrl
Function Prototype
MMAC_CSI_RESULT_CODE MMAC_CSI_Cntrl (MMAC_CSI_CNTRL_IOPB *iopb);
Inputs
iopb
This points to an MMAC_CSI_CNTRL_IOPB structure. This structure is used to pass the
following parameters:
operation
An operation for the control function to perform. Allowable operations are:
MMAC_CSI_RESET Reset the CSI hardware.
MMAC_CSI_GET_PARAMS Return the current configuration for the CSI, read
and write timeout.
MMAC_CSI_SET_PARAMS Set the configuration for the CSI, read and write
timeout.
MMAC_CSI_GET_ERROR Return and clear the last internal error.
params
New configuration for the CSI driver, read and write timeouts, valid when operation
is MMAC_CSI_SET_PARAMS.
Outputs
params
Used to return the current CSI configuration, valid when operation is MMAC_CSI_GET_
PARAMS.
error
Used to return the last CSI internal error, valid when operation is MMAC_CSI_GET_
ERROR..
Event Notification
N/A
Returns
MMAC_CSI_OK
MMAC_CSI_FAIL
MMAC_CSI_INVALID_PARAM
MMAC_CSI_NOT_OPEN
MMAC_CSI_NOT_INITIALISED
Description
This function is used to configure the CSI driver. The read and write timeouts can be set/read by
calling this function with the operation in the iopb set to MMAC_CSI_SET_PARAMS or MMAC_
CSI_GET_PARAMS. This function can be used to reset the driver and hardware if the operation in the
iopb is set to MMAC_CSI_RESET. It can also be used to get the last internal error generated by the
device if the operation in the iopb is set to MMAC_CSI_GET_ERROR.
14 / 16
See Also
MMAC_CSI_Open( )
MMAC_CSI_Close( )
MMAC_CSI_Read( )
MMAC_CSI_Write( )
Sample Code
[Link] = MMAC_CSI_GET_PARAMS;
if( MMAC_CSI_Cntrl( &cntrlIOPB ) )
{
/* Report Error */
}
[Link] = MMAC_CSI_SET_PARAMS;
[Link] = 100;
if( MMAC_CSI_Cntrl( &cntrlIOPB ))
{
/* Report Error */
}
15 / 16
4 Revision History
Title: API – Clocked Serial Interface (CSI)
Ref: API_CSI.doc
Date Issue Details of change Ref.
2002-19-13 0.01 First draft based on EMMA2 API doc. M-JD
2002-09-17 0.02 Edits following proof reading M-DS
2002-12-18 0.03 Doc layout reorganised. M-RJI
2003-01-16 0.04 Minor format edits. M-RJI
2003-04-30 0.05 Added missing return codes. M-MMH
2003-07-02 0.06 Doc number added. M-RJI
Function descriptions re-organised.
2004-02-16 1.0 This document made common across all EMMA2 devices – replaces M-RJI
previous API_IRR doc and issued at ver 1.0.
16 / 16