User’s Manual
EMMA2 API
Real Time Clock
CONTENTS
1 Introduction ....................................................................................................................... 2
2 Function Prototypes .......................................................................................................... 4
MMAC_RTC_Initialise...................................................................................................4
MMAC_RTC_Open.......................................................................................................5
MMAC_RTC_Close ......................................................................................................6
MMAC_RTC_Read .......................................................................................................7
MMAC_RTC_Write .......................................................................................................8
MMAC_RTC_Cntrl ........................................................................................................9
3 Data Structures ............................................................................................................... 11
4 Revision History .............................................................................................................. 13
Book No: S16753EE1V0UM00 Doc No: MMAC0033, Issue: 1.1
© NEC Electronics Corporation 2002, 2003 Date: 2003-06-27
ration 2002
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 Real Time Clock (RTC) 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 RTC driver supports 1 RTC identified by a unique device number, MMAC_RTC_0.
The RTC is used to provide an accurate one day Real Time Clock with alarm mechanism.
Functions
The MMAC_RTC_Initialise() function is called to initialise any global data structure. This function must
be called before any other RTC function.
The MMAC_RTC_Open() function initialises and starts the given RTC.
The MMAC_RTC_Write() function is used to change the given RTC.
The MMAC_RTC_Read() function is used to read the value of the given RTC.
The MMAC_RTC_Cntrl() function is used to start, stop or reset a given RTC and to configure an alarm
callback function
The function MMAC_RTC_Close() is called to disable a given RTC driver and return system resources.
The real time clock is set up with an hour:minute:second: value by the MMAC_RTOS_Open() function
and is started immediately. This value can be changed using the MMAC_RTC_Write() function. The
RTC value can be read at any point using the MMAC_RTC_Read() function. The MMAC-RTC_
Cntrl() function is provided to get/set the RTC alarm configuration for a given channel and to start/stop/
reset the RTC.
Result Codes
The meaning of the various result codes returned by the driver is described in the following table:
Result Code Description
MMAC_RTC_OK A RTC operation has successfully completed.
MMAC_RTC_FAIL A RTC operation has not completed.
MMAC_RTC_ALREADY_OPEN The RTC driver has already been initialised.
MMAC_RTC_NOT_OPEN The RTC driver has not been initialised.
MMAC_RTC_INVALID_PARAM A parameter passed is invalid, it is out of range or a NULL
pointer has been passed.
MMAC_RTC_INVALID_DEVICE The device number is not within the range defined in
MMAC_RTC_DEV_NUM.
MMAC_RTC_UNSUPPORTED_TIME The requested RTC time is not supported.
The configuration of a RTC is changed using the MMAC_RTC_Cntrl() function using the operation
MMAC_RTC_GET_PARAMS and MMAC_RTC_SET_PARAMS. Alarm wakeup callback function can be
installed using this function.
To configure/use the RTC we can use:
{
MMAC_RTC_OPEN_IOPB openIOPB;
MMAC_RTC_CNTRL_IOPB cntrlIOPB;
/* Open the RTC port, setting time to 13:0:0 */
[Link] = MMAC_RTC_0;
[Link] = 13;
2
[Link] = 0;
[Link] = 0;
MMAC_RTC_Open( &openIOPB );
[Link] = MMAC_RTC_0;
[Link] = MMAC_RTC_GET_PARAMS;
MMAC_RTC_Cntrl( &cntrlIOPB );
[Link] = MMAC_RTC_STOP;
MMAC_RTC_Cntrl( &cntrlIOPB );
[Link] = MMAC_RTC_START;
MMAC_RTC_Cntrl( &cntrlIOPB );
[Link] = MMAC_RTC_SET_PARAMS;
[Link] = 14;
[Link] = 0;
[Link] = 0;
[Link] = myAlarmCallbackFunction;
MMAC_RTC_Cntrl( &cntrlIOPB );
}
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/rtc.h”
Initialisations
No other API modules are required prior to utilizing the MISC API.
API Configuration
A number of configurable options, in the form of “#define”s are defined in the RTC section of the
mmac/mmac_config.h source file clearly marked by the comment:
/****************************************************************/
/* */
/* MMAC RTC SETUP */
/* */
/****************************************************************/
These options are:
Define Default Meaning
N/A
3
2 Function Prototypes
MMAC_RTC_Initialise
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Initialise (void);
Inputs
None.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_FAIL
Description
This function initialises any global data structure for the MMAC_RTC driver.
See Also
MMAC_RTC_Open
MMAC_RTC_Close
Sample Code
< tba >
4
MMAC_RTC_Open
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Open (MMAC_RTC_OPEN_IOPB *iopb);
Inputs
iopb This points to an MMAC_RTC_OPEN_IOPB structure. This structure is used to
pass the following parameters:
deviceNumber The device number for the RTC open.
[Link] The initial RTC hour value in range 0-23.
[Link] The initial RTC minute value in range 0-59.
[Link] The initial RTC second value in range 0-59.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_INVALID_PARAM
MMAC_RTC_INVALID_DEVICE
MMAC_RTC_ALREADY_OPEN
MMAC_RTC_INVALID_TIME
Description
This function initialises, allocates system resources and starts the given RTC channel.
If the given iopb->time value is invalid then MMAC_RTC_INVALID_TIME is returned.
The RTC is set to the time given in iopb->time and started.
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_RTC_Close
MMAC_RTC_Read
MMAC_RTC_Write
MMAC_RTC_Cntrl
Sample Code
< tba >
5
MMAC_RTC_Close
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Close (MMAC_RTC_CLOSE_IOPB *iopb);
Inputs
iopb This points to an MMAC_RTC_CLOSE_IOPB structure. This structure is used
to pass the following parameters:
deviceNumber The device number for the RTC close.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_INVALID_PARAM
MMAC_RTC_INVALID_DEVICE
MMAC_RTC_NOT_OPEN
Description
This function stops and disables the given RTC 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_RTC_Open
MMAC_RTC_Read
MMAC_RTC_Write
MMAC_RTC_Cntrl
Sample Code
< tba >
6
MMAC_RTC_Read
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Read (MMAC_RTC_READ_IOPB *iopb);
Inputs
iopb This points to an MMAC_RTC_READ_IOPB structure. This structure is used to
pass the following parameters:
deviceNumber The device number for the RTC read.
Outputs
iopb This points to an MMAC_RTC_READ_IOPB structure. This structure is used to
pass out the following parameters:
time Current RTC time (hours:mins:secs)
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_INVALID_PARAM
MMAC_RTC_INVALID_DEVICE
MMAC_RTC_NOT_OPEN
MMAC_RTC_FAIL
Description
This function reads the current RTC value from the given RTC channel and returns it in iopb->time.
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_RTC_Open
MMAC_RTC_Close
MMAC_RTC_Write
MMAC_RTC_Cntrl
Sample Code
< tba >
7
MMAC_RTC_Write
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Write (MMAC_RTC_WRITE_IOPB *iopb);
Inputs
iopb This points to an MMAC_RTC_WRITE_IOPB structure. This structure is used
to pass the following parameters:
deviceNumber The device number for the RTC write.
[Link] The new RTC hour value in range 0-23.
[Link] The new RTC minute value in range 0-59.
[Link] The new RTC second value in range 0-59.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_INVALID_PARAM
MMAC_RTC_INVALID_DEVICE
MMAC_RTC_UNSUPPORTED_TIME
MMAC_RTC_FAIL
Description
This function writes a new value, iopb->time, to a given RTC channel.
If the given iopb->time value is invalid then MMAC_RTC_UNSUPPORTED_TIME is returned.
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_RTC_Open
MMAC_RTC_Close
MMAC_RTC_Read
MMAC_RTC_Cntrl
Sample Code
< tba >
8
MMAC_RTC_Cntrl
Function Prototype
MMAC_RTC_RESULT_CODE MMAC_RTC_Cntrl (MMAC_RTC_CNTRL_IOPB *iopb);
Inputs
iopb This points to an MMAC_RTC_WRITE_IOPB structure. This structure is used
to pass the following parameters:
deviceNumber The device number for the RTC cntrl.
operation An operation for the control function to perform. Allowable
operations are:
MMAC_RTC_START Start the given RTC.
MMAC_RTC_STOP Stop the given RTC.
MMAC_RTC_RESET Reset the given RTC.
MMAC_RTC_GET_PARAMS Read the alarm timeout value and callback
function address.
MMAC_RTC_SET_PARAMS Configure the alarm and install the
callback handler.
params A pointer to an MMAC_RTC_PARAMS structure which is used to pass the
alarm timeout and callback function, valid when [Link] is
MMAC_RTC_SET_PARAMS.
Outputs
params A pointer to an MMAC_RTC_PARAMS structure which is used to return the
alarm timeout and callback function, valid when [Link] is
MMAC_RTC_GET_PARAMS.
Event Notification
N/A
Return Codes
MMAC_RTC_OK
MMAC_RTC_FAIL
MMAC_RTC_INVALID_PARAM
MMAC_RTC_INVALID_DEVICE
MMAC_RTC_NOT_OPEN
Description
This function is used to configure or query the RTC driver and to reset the RTC.
If iop->operation is MMAC_RTC_START then the RTC counter is started, if it has been previously
stopped.
If iop->operation is MMAC_RTC_STOP then the RTC counter is stopped.
If iop->operation is MMAC_RTC_RESET then the RTC counter is reset.
If iop->operation is MMAC_RTC_SET_PARAMS then the RTC alarm time is set to iopb-
>[Link] and the callback function iopb->[Link] is installed. The RTC is not
stopped during this setup.
If iopb->operation is MMAC_RTC_GET_PARAMS then the RTC alarm time and the address of the
callback function are passed back in [Link].
9
See Also
MMAC_RTC_Open
MMAC_RTC_Close
MMAC_RTC_Read
MMAC_RTC_Write
Sample Code
< tba >
10
3 Data Structures
Includes
#include “mmac/rtc.h”
Result Codes
The following result codes are defined for the RTC device. The result code value 0 is reserved for
indication of a successful operation.
typedef enum
{
MMAC_RTC_OK,
MMAC_RTC_FAIL,
MMAC_RTC_INVALID_PARAM,
MMAC_RTC_INVALID_DEVICE,
MMAC_RTC_ALREADY_OPEN,
MMAC_RTC_NOT_OPEN,
MMAC_RTC_UNSUPPORTED_TIME
}MMAC_RTC_RESULT_CODE;
Device Numbers
The RTC driver supports one device. This has a device number (0), which is used to reference the RTC.
typedef enum
{
MMAC_RTC_0
}MMAC_RTC_DEV_NUM;
Callback
The following type defines an MMAC_RTC_CALLBACK.
typedef void(*MMAC_RTC_CALLBACK)( MMAC_RTC_DEV_NUM deviceNumber);
Time
The MMAC RTC time is defined as follows.
typedef struct
{
UI8 hours; /* 0-23 */
UI8 mins; /* 0-59 */
UI8 secs; /* 0-59 */
}MMAC_RTC_TIME;
MMAC_RTC_Open
The MMAC RTC driver open operation requires the following IOPB.
typedef struct
{
MMAC_RTC_DEV_NUM deviceNumber;
MMAC_RTC_TIME time;
}MMAC_RTC_OPEN_IOPB;
11
MMAC_RTC_Close
The MMAC RTC driver close operation requires the following IOPB.
typedef struct
{
MMAC_RTC_DEV_NUM deviceNumber;
}MMAC_RTC_CLOSE_IOPB;
MMAC_RTC_Read
The MMAC RTC driver read operation requires the following IOPB.
typedef struct
{
MMAC_RTC_DEV_NUM deviceNumber;
MMAC_RTC_TIME time;
}MMAC_RTC_READ_IOPB;
MMAC_RTC_Write
The MMAC RTC driver write operation requires the following IOPB.
typedef struct
{
MMAC_RTC_DEV_NUM deviceNumber;
MMAC_RTC_TIME time;
}MMAC_RTC_WRITE_IOPB;
MMAC_RTC_Cntrl
The MMAC RTC driver control operation requires the following types and IOPB.
typedef enum
{
MMAC_RTC_START,
MMAC_RTC_STOP,
MMAC_RTC_RESET,
MMAC_RTC_GET_PARAMS,
MMAC_RTC_SET_PARAMS
}MMAC_RTC_OPERATION;
typedef struct
{
MMAC_RTC_TIME time;
MMAC_RTC_CALLBACK callback;
}MMAC_RTC_ALARM;
typedef struct
{
MMAC_RTC_ALARM alarm;
}MMAC_RTC_PARAMS;
typedef struct
{
MMAC_RTC_DEV_NUM deviceNumber;
MMAC_RTC_OPERATION operation;
MMAC_RTC_PARAMS params;
}MMAC_RTC_CNTRL_IOPB;
12
4 Revision History
Title: API Specification: Real Time Clock
Ref: API_RTC.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 Changed the operation of MMAC_RTC_Cntrl – added start, M-IM
stop and reset and changed the alarm interface
2002-08-12 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
13