User’s Manual
EMMA2 API
Timers
CONTENTS
1 Introduction ....................................................................................................................... 2
2 Function Prototypes .......................................................................................................... 5
MMAC_TIMER_Initialise...............................................................................................5
MMAC_TIMER_Open ...................................................................................................6
MMAC_TIMER_Close...................................................................................................7
MMAC_TIMER_Read ...................................................................................................8
MMAC_TIMER_Write ...................................................................................................9
MMAC_TIMER_Cntrl ..................................................................................................10
3 Data Structures ............................................................................................................... 12
4 Revision History .............................................................................................................. 15
Book No: S16753EE1V0UM00 Doc No: MMAC0041, Issue: 1.1
© NEC Electronics Corporation 2002, 2003 Date: 2003-06-27
The information is this document is subject to change without notice – it is
the reader’s responsibility to check that this is the latest available version.
This document includes company confidential information. It should only be
released to third parties under a Non-Disclosure Agreemant.
1 Introduction
This section defines the API for the MMAC TIMER 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.
The timer driver supports 3 separate timers each identified by a unique device number. MMAC_TIMER_0
and MMAC_TIMER_1 have interrupt handlers, MMAC_TIMER_2 is a free running timer and so does not.
MMAC_TIMER_0 and MMAC_TIMER_1 can thus be used to provide a periodic function call, and
MMAC_TIMER_2 can be used only as a reference timer.
Functions
The MMAC_TIMER_Initialise() function is called to initialise any global data structures and any
hardware common between the timers. This function must be called before any other timer function.
The MMAC_TIMER_Open() function initialises and starts a given timer.
The MMAC_TIMER_Write() function is used, in the case of MMAC_TIMER_0 and MMAC_TIMER_1,
to write a new timeout value to a given timer. This has the effect of restarting the timer. For
MMAC_TIMER_2 this function has no effect, as the timer is reference only.
The MMAC_TIMER_Read() function is used to read the value of a given timer.
The MMAC_TIMER_Cntrl() function is used to start, stop or reset a given timer and to get/set
configuration parameters for the timer.
The MMAC_TIMER_Close() function is used to disable a given timer driver and return system resources.
Function Name Description
MMAC_TIMER_Initialise This function is used to initialise any system resource required by
the Timer API.
MMAC_TIMER_Open This function opens and starts a given timer.
MMAC_TIMER_Write This function changes the time of a given timer.
MMAC_TIMER_Read This function reads the current time of a given timer.
MMAC_TIMER_Cntrl This function is used to start, stop or reset a given timer.
MMAC_TIMER_Close This function closes and stops a given timer.
When each timer is initialised a callback function is defined for it, with the exception of MMAC_TIMER_2
which is an elapse timer to be used only for time reference measurement. The callback function is called
each time the timer expires. The callback function can be NULL in which case no function is called on
timer expiration.
MMAC_TIMER_0 and MMAC_TIMER_1 can have two modes of operation:
MMAC_TIMER_SINGLE_SHOT: when timer expires it is not restarted. The timer can be restarted by
issuing a MMAC_TIMER_Write() command for that timer or by issuing a MMAC_TIMER_RESET
command using the MMAC_TIMER_Cntrl() function.
MMAC_TIMER_RESTART: when timer expires it is automatically restarted.
The MMAC RTOS Interface must be initialised by calling MMAC_RTOS_Initialise() before using this
module.
When the timer is opened it will be passed a tick period, in ms. If the given tick period is not supported
then an error is returned. The current tick period for a given timer can be retrieved using the
MMAC_TIMER_Cntrl function.
If a given timeout cannot be exactly set then an error code will be returned.
2
Result Codes
The meanings of the various result codes returned by the driver are described in the following table:
Result Code Description
MMAC_TIMER_OK A TIMER operation has successfully completed.
MMAC_TIMER_FAIL A TIMER operation has not completed.
MMAC_TIMER_ALREADY_OPEN The TIMER driver has already been initialised.
MMAC_TIMER_NOT_OPEN The TIMER driver has not been initialised.
MMAC_TIMER_INVALID_PARAM A parameter passed is invalid, it is out of range or a
NULL pointer has been passed.
MMAC_TIMER_INVALID_DEVICE The device number is not within the range defined in
MMAC_TIMER_DEV_NUM.
MMAC_TIMER_UNSUPPORTED_TIMEOUT The requested timeout value is not supported.
MMAC_TIMER_INVALID_COUNT The timer has been initialised with an unsupported
timeout value.
The configuration of a timer is changed using the MMAC_TIMER_Cntrl() function using the operation
MMAC_TIMER_GET_PARAMS and MMAC_TIMER_SET_PARAMS.
To create then change a timer we can do something like:
{
MMAC_TIMER_OPEN_IOPB openIOPB;
MMAC_TIMER_CNTRL_IOPB cntrlIOPB;
/* Open the TIMER port */
[Link] = MMAC_TIMER_0;
[Link] = 10; /* ms */
[Link] = MMAC_TIMER_RESTART;
[Link] = MyCallbackFunction;
MMAC_TIMER_Open( &openIOPB );
[Link] = MMAC_TIMER_GET_PARAMS;
MMAC_TIMER_Cntrl( &cntrlIOPB );
[Link] = MMAC_TIMER_SET_PARAMS;
[Link] = MMAC_TIMER_SINGLE_SHOT;
[Link] = 100; /* ms */
MMAC_TIMER_Cntrl( &cntrlIOPB );
}
Note: If the mode of a timer is changed to MMAC_TIMER_SINGLE_SHOT this mode change takes effect
when the timer is restarted, either explicitly or implicitly at the end of the current timeout.
3
Includes
In order to use this API, the following header files must be included, in the following order:
#include “mmac/types.h”
#include “mmac/mmac_config.h”
#include “mmac/timer.h”
Initialisation
No other API modules are required prior to using the timer API.
A number of configurable options, in the form of “#define”s are defined in the timer section of the
mmac_config.h source file clearly marked by the comment:
/****************************************************************/
/* */
/* MMAC TIMER SETUP */
/* */
/****************************************************************/
These options are:
Define Default Meaning
MMAC_TIMER_ACCESS_ MMAC_RTOS_MAX_ The number of ticks that a calling task is
CONTROL_WAIT_TIME TIMEOUT blocked waiting for access to the driver.
4
2 Function Prototypes
MMAC_TIMER_Initialise
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Initialise (void);
Inputs
None.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_FAIL
Description
This function initialises and global data structure for the MMAC_TIMER driver and any shared hardware
configuration.
See Also
MMAC_TIMER_Open
MMAC_TIMER_Close
Sample Code
< tba >
5
MMAC_TIMER_Open
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Open (MMAC_TIMER_OPEN_IOPB *iopb);
Inputs
iopb: This points to an MMAC_TIMER_OPEN_IOPB structure. This structure is used
to pass the following parameters:
deviceNumber The device number for the TIMER open.
timeout The time at which the timer should expire.
callback A pointer to a callback function for timer expiration notification.
mode Single shot or restart.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_INVALID_PARAM
MMAC_TIMER_INVALID_DEVICE
MMAC_TIMER_ALREADY_OPEN
MMAC_TIMER_UNSUPPORTED_TIMEOUT
Description
This function initialises, allocates system resources for, and starts the given timer channel.
If the mode is set to MMAC_TIMER_RESTART, when the timer expires it is automatically restarted and
the callback function invoked.
If the mode is set to MMAC_TIMER_SINGLE_SHOT, when the timer expires it is disabled and the
callback function invoked.
The timer is set to expire after iopb->timeout ms. If the timeout value is too large, or cannot be produced
exactly, this function returns MMAC_TIMER_UNSUPPORTED_TIMEOUT.
The timer device number is passed into the callback function.
The timeout, callback and mode parameters are ignored for the elapse timer (MMAC_TIMER_2).
The parameters passed into the driver and the driver state are checked and if any problems are found then
the appropriate return code is returned.
See Also
MMAC_TIMER_Close
MMAC_TIMER_Read
MMAC_TIMER_Write
MMAC_TIMER_Cntrl
Sample Code
< tba >
6
MMAC_TIMER_Close
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Close (MMAC_TIMER_CLOSE_IOPB *iopb);
Inputs
iopb: This points to an MMAC_TIMER_CLOSE_IOPB structure. This structure is
used to pass the following parameters:
deviceNumber The device number for the TIMER close.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_INVALID_PARAM
MMAC_TIMER_INVALID_DEVICE
MMAC_TIMER_NOT_OPEN
Description
This function disables the given timer channel and returns allocated system resources.
The parameters passed into the driver and the driver state are checked and if any problems are found then
the appropriate return code is returned.
See Also
MMAC_TIMER_Open
MMAC_TIMER_Read
MMAC_TIMER_Write
MMAC_TIMER_Cntrl
Sample Code
< tba >
7
MMAC_TIMER_Read
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Read (MMAC_TIMER_READ_IOPB *iopb);
Inputs
iopb This points to an MMAC_TIMER_READ_IOPB structure. This structure is used
to pass the following parameters:
deviceNumber The device number for the TIMER read.
Outputs
iopb This points to an MMAC_TIMER_READ_IOPB structure. This structure is used
to pass out the following parameters:
time Current timer value in m.s.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_INVALID_PARAM
MMAC_TIMER_INVALID_DEVICE
MMAC_TIMER_NOT_OPEN
MMAC_TIMER_FAIL
MMAC_TIMER_INVALID_COUNT
Description
This function reads the current timer value from the given timer channel.
The system timers have incremental counters which will count up until they reach the timeout value set by
MMAC_TIMER_Open() or MMAC_TIMER_Write(). If MMAC_TIMER_Write() has been
previously called with an unsupported timeout value then this function will return MMAC_TIMER_
INVALID_COUNT.
The elapse timer has a free running incremental counter.
The parameters passed into the driver and the driver state are checked and if any problems are found then
the appropriate return code is returned.
See Also
MMAC_TIMER_Open
MMAC_TIMER_Close
MMAC_TIMER_Write
MMAC_TIMER_Cntrl
Sample Code
< tba >
8
MMAC_TIMER_Write
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Write (MMAC_TIMER_WRITE_IOPB *iopb);
Inputs
iopb This points to an MMAC_TIMER_WRITE_IOPB structure. This structure is
used to pass the following parameters:
deviceNumber The device number for the to write.
timeout New timeout value for the given timer channel, in m.s.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_INVALID_PARAM
MMAC_TIMER_INVALID_DEVICE
MMAC_TIMER_NOT_OPEN
MMAC_TIMER_FAIL
MMAC_TIMER_UNSUPPORTED_TIMEOUT
Description
This function writes a new timeout value, in m.s, to a system timer channel. The timer is stopped before
writing the value and restarted afterwards. If the new timeout value is too large, or cannot be produced
exactly, this function returns MMAC_TIMER_UNSUPPORTED_TIMEOUT.
In the case of timer MMAC_TIMER_2 this function does nothing, as an elapse timer is reference only.
The parameters passed into the driver and the driver state are checked and if any problems are found then
the appropriate return code is returned.
See Also
MMAC_TIMER_Open
MMAC_TIMER_Close
MMAC_TIMER_Read
MMAC_TIMER_Cntrl
Sample Code
< tba >
9
MMAC_TIMER_Cntrl
Function Prototype
MMAC_TIMER_RESULT_CODE MMAC_TIMER_Cntrl (MMAC_TIMER_CNTRL_IOPB *iopb);
Inputs
iopb This points to an MMAC_TIMER_WRITE_IOPB structure. This structure is
used to pass in the following parameters:
deviceNumber The device number for the TIMER cntrl.
operation An operation for the control function to perform. Allowable
operations are:
MMAC_TIMER_STOP Stop a given timer channel.
MMAC_TIMER_START Restart a given timer channel.
MMAC_TIMER_RESET Reset a given timer channel. The timer
value will be reset to 0. The timer will
continue in the state it was in before the
reset, i.e. running or stopped.
MMAC_TIMER_GET_PARAMS Return current values of expiration mode
and callback function.
MMAC_TIMER_SET_PARAMS Set the timer expiration mode and callback
function.
params A pointer to an MMAC_TIMER_PARAMS structure which is
used to pass the mode and callback function, valid when
[Link] is MMAC_TIMER_SET_PARAMS.
Outputs
iopb This points to an MMAC_TIMER_WRITE_IOPB structure. This structure is
used to pass out the following parameters:
params A pointer to an MMAC_TIMER_PARAMS structure which is
used to return the mode and callback function, valid when
[Link] is MMAC_TIMER_GET_PARAMS.
Event Notification
N/A
Return Codes
MMAC_TIMER_OK
MMAC_TIMER_FAIL
MMAC_TIMER_INVALID_PARAM
MMAC_TIMER_INVALID_DEVICE
MMAC_TIMER_NOT_OPEN
Description
This function is used to configure or query the timer driver, start, stop or restart a given timer.
If [Link] is MMAC_TIMER_STOP the timer for the given channel, [Link] is stopped.
If [Link] is MMAC_TIMER_START the timer for the given channel, [Link] is started.
If it has been stopped and not reset it continues to run from stopped point.
10
If [Link] is MMAC_TIMER_RESET the timer for the given channel, [Link] is reset.
The timer counter value is set to 0 and if the timer was running it continues to do so, otherwise it is
stopped and must be manually restarted.
If [Link] is MMAC_TIMER_GET_PARAMS then the configuration of the timer driver is passed
back in [Link].
If [Link] is MMAC_TIMER_SET_PARAMS then the configuration of the timer driver is changed
according to the values in [Link].
The parameters passed into the driver and the driver state are checked and if any problems are found then
the appropriate return code is returned.
See Also
MMAC_TIMER_Open
MMAC_TIMER_Close
MMAC_TIMER_Read
MMAC_TIMER_Write
Sample Code
< tba >
11
3 Data Structures
Includes
#include “mmac/timer.h”
Result Codes
The following result codes are defined for the timer device. The result code value 0 is reserved for
indication of a successful operation.
typedef enum
{
MMAC_TIMER_OK,
MMAC_TIMER_FAIL,
MMAC_TIMER_INVALID_PARAM,
MMAC_TIMER_INVALID_DEVICE,
MMAC_TIMER_ALREADY_OPEN,
MMAC_TIMER_NOT_OPEN,
MMAC_TIMER_UNSUPPORTED_TIMEOUT,
MMAC_TIMER_INVALID_COUNT
}MMAC_TIMER_RESULT_CODE;
Time Modes
The timer expiration modes are defined below.
typedef enum
{
MMAC_TIMER_RESTART,
MMAC_TIMER_SINGLE_SHOT
}MMAC_TIMER_MODE;
Device Numbers
The timer driver supports three devices. Each has a device number (0 – 2), which is used to reference the
particular timer.
typedef enum
{
MMAC_TIMER_0,
MMAC_TIMER_1,
MMAC_TIMER_2
}MMAC_TIMER_DEV_NUM;
Callback
The following type defines an MMAC_TIMER_CALLBACK.
typedef void(*MMAC_TIMER_CALLBACK)( MMAC_TIMER_DEV_NUM deviceNumber);
12
MMAC_TIMER_Open
The MMAC Timer driver open operation requires the following IOPB.
typedef struct
{
MMAC_TIMER_DEV_NUM deviceNumber;
UI32 timeout;
MMAC_TIMER_MODE mode;
MMAC_TIMER_CALLBACK callback;
}MMAC_TIMER_OPEN_IOPB;
MMAC_TIMER_Close
The MMAC Timer driver close operation requires the following IOPB.
typedef struct
{
MMAC_TIMER_DEV_NUM deviceNumber;
}MMAC_TIMER_CLOSE_IOPB;
MMAC_TIMER_Read
The MMAC Timer driver read operation requires the following IOPB.
typedef struct
{
MMAC_TIMER_DEV_NUM deviceNumber;
UI32 time;
}MMAC_TIMER_READ_IOPB;
MMAC_TIMER_Write
The MMAC Timer driver write operation requires the following IOPB.
typedef struct
{
MMAC_TIMER_DEV_NUM deviceNumber;
UI32 timeout;
}MMAC_TIMER_WRITE_IOPB;
MMAC_TIMER_Cntrl
The MMAC Timer driver control operation requires the following types and IOPB.
typedef enum
{
MMAC_TIMER_STOP,
MMAC_TIMER_START,
MMAC_TIMER_RESET,
MMAC_TIMER_GET_PARAMS,
MMAC_TIMER_SET_PARAMS
}MMAC_TIMER_OPERATION;
13
typedef struct
{
MMAC_TIMER_MODE mode;
MMAC_TIMER_CALLBACK callback;
}MMAC_TIMER_PARAMS;
typedef struct
{
MMAC_TIMER_DEV_NUM deviceNumber;
MMAC_TIMER_OPERATION operation;
MMAC_TIMER_PARAMS params;
}MMAC_TIMER_CNTRL_IOPB;
14
4 Revision History
Title: API Specification: Timers
Ref: API_Timers.doc
Date Doc API Details of change Ref.
Ver. Ver.
0.01 Initial Revision – from V3.0 EMMA 1 API M-JD
2000-10-19 0.02 Added MMAC_TIMER_INVALID_COUNT return code. M-IM
MMAC_TIMER_Initialise() now also returns
MMAC_TIMER_FAIL.
Clarified distinction between elapse and system timers.
2002-08-09 0.03 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.03 M-RI
2003-06-27 1.1 Doc number added. M-RJI
15