User’s Manual

EMMA2 API

GPIO

CONTENTS

1 Introduction ....................................................................................................................... 2
2 Architecture....................................................................................................................... 3
3 Function Prototypes ........................................................................................................ 10
MMAC_GPIO_Initialise ...............................................................................................10
MMAC_GPIO_Configure ............................................................................................11
MMAC_GPIO_Get ......................................................................................................13
MMAC_GPIO_Set.......................................................................................................14
MMAC_GPIO_SetWithMask.......................................................................................15
4 Data Structures ............................................................................................................... 16
5 Revision History .............................................................................................................. 18

Book No: S16753EE1V0UM00 Cod No: MMAC0024, Issue: 1.21

© NEC Electronics Corporation 2002 ~ 2004 Publication Date: 2004-02-18
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 Agreement.
1 Introduction
This document specifies the EMMA2 GPIO API. The API allows the manipulation of the EMMA2
Parallel IO hardware and does not target any set top box application in particular.
The GPIO API is used for controlling and manipulating the behaviour and data input/output of the 44
general-purpose parallel port pins of the EMMA2 hardware. The API provides an abstract layer to this
hardware, which controls and handles the hardware device. The API provides an interface to this abstract
layer by providing a set of functions. These functions will allow the API to be set up and configured in the
manner that the application software requires.

2
2 Architecture
This API is basic in its concept. During initialisation the API sets up interrupt handlers to manage the
hardware interrupts associated with the GPIO hardware. The API can be configured to callback this
function on user configurable events that occur on the pins of the parallel port. Each pin can be configured
to cause an event on a low level (zero volts) or an edge (transition from high level to low level or visa
versa). When an event occurs the callback function is called and a pin mask, defining the state of the pins
at the time of the interrupt, is passed as a parameter.
The application software can configure individually the direction of each parallel port pin to either input or
output. The application software can then read the state of the pins at any time or set the value of the pins
at any time. An event trigger can only be configured for a pin that is set to an input.
The parallel port pins are shared with other EMMA2 devices, it is the responsibility of the application
programmer to ensure that the parallel port does not conflict with these devices. The shared devices are
listed below:
External MPEG Interface
Timer Interface
External Video Input
External Teletext Interface
Clocked Serial Interface
IEEE1284 Interface
High Speed Data Interface
SmartCard Interface
I2C Interface
Video Output
General Bus IO Interface (Not GPIO)
UART 3
UART 2
FastUART 1
FastUART 0

Initialisation
Prior to using any of the functions in this document, it is necessary to initialise other API subsections that
this code depends on. This is:
MMAC_RTOS_Initialise()

The function MMAC_GPIO_Initialise() must be called before using any of the GPIO API calls. This
shall initialise the GPIO hardware and system resources ready for use by the GPIO API.

3
Functions
The GPIO API provides the following functions:
Function Name Description
MMAC_GPIO_Initialise Used to initialise the GPIO API subsystem.
MMAC_GPIO_Configure Configures the behaviour of each of the pins on the GPIO
interface.
MMAC_GPIO_Get Gets the state of the pins on the GPIO interface.
MMAC_GPIO_Set Sets the state of the pins on the GPIO interface.
MMAC_GPIO_SetWithMask Sets the state of the pins on the GPIO interface with mask.

Return Codes
The meanings of the various result codes returned by the driver are described in the following table:
Result Code Description
MMAC_GPIO_OK A GPIO operation has successfully completed.
MMAC_GPIO_FAIL A GPIO operation has not completed.
MMAC_GPIO_NOT_INITIALISED A call to a function without a prior call to
MMAC_GPIO_Initialise().
MMAC_GPIO_ALREADY_INITIALISED A second call to MMAC_GPIO_Initialise().
MMAC_GPIO_SEMAPHORE_UNAVAILABLE The GPIO API could not acquire the interface access
semaphore within the timeout period specified by
MMAC_GPIO_SEMAPHORE_TIMEOUT.
MMAC_GPIO_INVALID_PARAM A parameter passed is invalid, it is out of range or a
NULL pointer has been passed.

Configuration
A number of configurable options, in the form of “#define”s are defined in the GPIO section of the
mmac_config.h source file clearly marked by the comment:

/****************************************************************/
/* */
/* MMAC GPIO SETUP */
/* */
/****************************************************************/

These options are:

Define Default Meaning
MMAC_GPIO_SEMAPHORE_ MMAC_RTOS_MAX_ Specifies the maximum length of time (in
TIMEOUT TIMEOUT ticks) that the GPIO subsystem should
block a calling task while waiting for the
GPIO semaphore to become available.

4
Sample Code

/*************************************************************************
This example code will implement a clocked serial interface (CSI) on pins 0
and 1 of the 44 bit parallel port. It will clock in a byte at a time. Each
byte will be placed into a circular buffer from which the Main code can
retrieve it. The main waits for data to be placed into the buffer and
extracts them for processing. The main loop is looking for values between 1
and 10, and acts accordingly. The output CSI output is that of the previous
byte.
**************************************************************************
--- Note: This code only implements the CSI in slave mode.
**************************************************************************/

#include "gpio.h"
#include "rtos.h"
#include "types.h"

#define CSI_DATA_IN_PIN (0) /* Pin 0 is data in */

#define CSI_CLOCK_PIN (1) /* Pin 1 is clock */
#define CSI_DATA_OUT_PIN (2) /* pin 2 is data out */

#define CSI_DATA_IN_PIN_MASK (0x00000001)

#define CSI_CLOCK_PIN_MASK (0x00000002)
#define CSI_DATA_OUT_PIN_MASK (0x00000004)
#define BITS_IN_BYTE (8)
#define BIT_ZERO_MASK (0xfe)
#define BIT_ONE_MASK (0x01)
#define OUTPUT_BIT_ONE_MASK (0x80)
#define DATA_OUT_ONE_MASK (0x80000000)
#define DATA_OUT_ZERO_MASK (0x7fffffff)
#define BUFFER_SIZE (100)

typedef enum
{
WRITE_SUCCESS = 0,
WRITE_FAIL
}CIRC_BUFFER_WRITE_RESPONSE;

typedef enum
{
READ_SUCCESS = 0,
NO_DATA
}CIRC_BUFFER_READ_RESPONSE;

static MMAC_BOOL circBufferAFull = MMAC_FALSE;

static UI8 CSICircularBuffer[BUFFER_SIZE];
static UI8 CSIBufferWritePointer, CSIBufferReadPointer;
static MMAC_BOOL masterMode = MMAC_FALSE;

/* Forward declarations */
void CSI_ClockTransition(UI64 pinMask);
MMAC_GPIO_RESULT_CODE ParallelSetup(void);
CIRC_BUFFER_WRITE_RESPONSE WriteToCSIInputBuffer(UI8 *data);
CIRC_BUFFER_WRITE_RESPONSE ReadFromCSIInputBuffer(UI8 *data);

5
main()
{
UI8 inputByte = 0;
MMAC_RTOS_Initialise();
if (ParallelSetup() == MMAC_GPIO_OK)
{
While(1)
{
if(ReadFromCSIInputBuffer(&inputByte) == READ_SUCCESS)
{
switch(inputByte)
case 1:
/* Do Required Action */
case 2:
/* Do Required Action */
case 3:
/* Do Required Action */
case 4:
/* Do Required Action */
case 5:
/* Do Required Action */
case 6:
/* Do Required Action */
case 7:
/* Do Required Action */
case 8:
/* Do Required Action */
case 9:
/* Do Required Action */
case 10:
/* Do Required Action */
default:
/* No Required Action */

}
/* other main code */

}
}
}

/************************************************************************/
/* Function: ParallelSetup. */
/* This function called to set the parallel port up to use as a clocked */
/* serial interface. */
/************************************************************************/

MMAC_GPIO_RESULT_CODE ParallelSetup(void)
{
MMAC_GPIO_RESULT_CODE resultCode = MMAC_GPIO_OK;
MMAC_GPIO_CONFIG gpioConfig;
UI8 pin;

/* Ensure all pins are initially disabled... */

for( pin=0; pin<MMAC_GPIO_NUMBER_OF_PINS; pin++ )
{
[Link][pin].interruptMode = MMAC_GPIO_DISABLED;
}

6
 /* Configure the direction of the three pins to be used */
[Link][CSI_CLOCK_PIN].direction = MMAC_GPIO_WRITE;
[Link][CSI_DATA_OUT_PIN].direction = MMAC_GPIO_WRITE;
[Link][CSI_DATA_PIN].direction = MMAC_GPIO_READ;

if( masterMode == MMAC_FALSE )

{
/* Only the slave needs to generate an interrupt on the clock pin */
[Link][CSI_CLOCK_PIN].interruptMode =
MMAC_GPIO_RISING_EDGE;
}

if( MMAC_GPIO_Initialise() != MMAC_GPIO_FAIL )

{
if( MMAC_GPIO_Configure( &gpioConfig,
CSI_ClockTransition ) != MMAC_GPIO_OK )
{
resultCode = MMAC_GPIO_FAIL;
}
}
else
{
resultCode = MMAC_GPIO_FAIL;
}
return resultCode;
}

/************************************************************************/
/* Function: CSI_ClockTransition. */
/* This function called on each edge of the clock input. A bit is read */
/* from the data in pin on every edge. A bit from the previous byte is */
/* sent out of the data out pin on every edge. When a whole byte has */
/* been received it is stored in the input buffer */
/************************************************************************/

void CSI_ClockTransition(UI64 pinMask)

{
/* This Function receives MSB first */
static UI8 bitCount = 0;
static UI8 saveByte = 0;
static UI8 outputByte = 0;
UI64 parallelPort = 0;

if(([Link] & CSI_DATA_IN_PIN_MASK ) == 0)

{
/* input data bit equals low */
saveByte = saveByte & BIT_ZERO_MASK;
}
else
{
saveByte = saveByte | BIT_ONE_MASK;
}
MMAC_GPIO_Get(&parallelPort);
if(outputByte & OUTPUT_BIT_ONE_MASK != 0)
{
[Link] = [Link] | DATA_OUT_ONE_MASK;
}
else
{
[Link] = [Link] & DATA_OUT_ZERO_MASK;
}
MMAC_GPIO_Set(parallelPort);
bitCount++;
if(bitCount == BITS_IN_BYTE)

7
 {
WriteToCSIInputBuffer(&saveByte);
outputByte = saveByte;
bitCount = 0;
}
else
{
saveByte = saveByte << 1;
outputByte = outputByte <<1;
}
}

/************************************************************************/
/* Function: WriteToCircBuffer. */
/* This function called to save a byte to a circular byte buffer. */
/************************************************************************/

CIRC_BUFFER_WRITE_RESPONSE WriteToCSIInputBuffer(UI8 *data)

{
CIRC_BUFFER_WRITE_RESPONSE response = WRITE_SUCCESS;

if( ((CSIBufferWritePointer+1) == CSIBufferReadPointer) ||

(((CSIBufferWritePointer+1) == BUFFER_SIZE) &&
(CSIBufferReadPointer == 0)) )
{
response = WRITE_FAIL;
}
else
{
CSICircularBuffer[CSIBufferWritePointer] = *data;
CSIBufferWritePointer++;
if( CSIBufferWritePointer == BUFFER_SIZE )
{
CSIBufferWritePointer = 0;
}
}
return(response);
}

/************************************************************************/
/* Function: ReadFromCircBuffer. */
/* This function called to read a byte from a circular byte buffer. */
/************************************************************************/
CIRC_BUFFER_WRITE_RESPONSE ReadFromCSIInputBuffer(UI8 *data)
{
CIRC_BUFFER_READ_RESPONSE response = READ_SUCCESS;

if( CSIBufferWritePointer == CSIBufferReadPointer )

{
response = NO_DATA;
}
else
{
*data = CSICircularBuffer[CSIBufferReadPointer];
CSIBufferReadPointer++;
if( CSIBufferReadPointer == BUFFER_SIZE )
{
CSIBufferReadPointer = 0;
}
}
return(response);
}

8
9
3 Function Prototypes

MMAC_GPIO_Initialise

Function Prototype
MMAC_GPIO_RESULT_CODE MMAC_GPIO_Initialise( void );

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_GPIO_OK
MMAC_GPIO_ALREADY_INITIALISED
MMAC_GPIO_FAIL

Description
This function is used to initialise the GPIO subsystem. The function creates the GPIO interface access
semaphore, which is used to guard against simultaneous access to the GPIO hardware by more than one
thread of [Link] then marks the subsystem as being initialised,returning the value MMAC_GPIO_OK.
If the subsystem has already been initialised, the function returns the code MMAC_GPIO_ALREADY_
INITIALISED without performing any action.
If the function is unable to create the interface access semaphore, it returns the code MMAC_GPIO_FAIL
and the subsystem remains uninitialised.

See Also
None

Sample Code
< tba >

10
MMAC_GPIO_Configure

Function Prototype
MMAC_GPIO_RESULT_CODE MMAC_GPIO_Configure(
MMAC_GPIO_CONFIG *config
);

Inputs
config Pointer to a GPIO configuration structure:
pinConfig[ ] An array of structures which specify the configuration for each
of the 44 pins available on the GPIO interface. Each pin configuration comprises
the fields following:
direction This determines whether the pin will be used as a read or write
pin (i.e. to send data or to receive data). This field will have
either the value MMAC_GPIO_READ or
MMAC_GPIO_WRITE.
interruptMode This determines the type of interrupt that will be generated
when the pin state changes – one of the following:
MMAC_GPIO_DISABLED
MMAC_GPIO_RISING_EDGE
MMAC_GPIO_FALLING_EDGE
MMAC_GPIO_BOTH_EDGES
MMAC_GPIO_HIGH_LEVEL
MMAC_GPIO_LOW_LEVEL
callback The address of a callback function to be installed. This function
is called whenever a pin interrupt occurs. If no callback function is required, this
value may be set to NULL.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_GPIO_OK
MMAC_GPIO_INVALID_PARAM
MMAC_GPIO_NOT_INITIALISED
MMAC_GPIO_SEMAPHORE_UNAVAILABLE

Description
This function is used to configure the GPIO interface. The GPIO port provides 44 input/output pins.
Each pin is uniquely configurable:
Each pin may be set to be either an input or an output pin.
Each pin may be made to generate an interrupt if required. The manner in which the interrupt is generated
is also configurable (as outlined above in the possible values of the interruptMode field).
A callback function may also be installed, which is called if any pin generates an interrupt. When called,
the callback function will be passed a mask, indicating which pin or pins have generated the interrupt.
This function can be called multiple times to reconfigure the GPIO port.

11
See Also
None

Sample Code
< tba >

12
MMAC_GPIO_Get

Function Prototype
MMAC_GPIO_RESULT_CODE MMAC_GPIO_Get(UI64 *pinMask);

Inputs
None.

Outputs
pinMask A pointer to a mask indicating if a pin is high (bit set) or low (bit clear).

Event Notification
N/A

Return Codes
MMAC_GPIO_OK
MMAC_GPIO_SEMAPHORE_UNAVAILABLE
MMAC_GPIO_NOT_INITIALISED
MMAC_GPIO_INVALID_PARAM

Description
This function outputs a mask, to a variable that is pointed to by the output parameter pinMask, with the
current state of the GPIO port. The mask bit positions correspond to the bit position of the GPIO port,
where bit 0 represents pin 0 and bit 43 represents pin 43. If a bit is set the corresponding GPIO pin is high
else it is low. If pinMask is NULL, MMAC_GPIO_INVALID_PARAM is returned.

See Also
MMAC_GPIO_Set

Sample Code
< tba >

13
MMAC_GPIO_Set

Function Prototype
MMAC_GPIO_RESULT_CODE MMAC_GPIO_Set(UI64 pinMask);

Inputs
pinMask A mask indicating if a pin is to be set high (bit set) or low (bit clear).

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_GPIO_OK
MMAC_GPIO_FAIL
MMAC_GPIO_NOT_INITIALISED

Description
This function sets the state of the GPIO output pins. The pinMask represents each output pin of the GPIO
port, bit 0 represents pin 0, bit 43 represents bit 43. If a bit is set the output pin is set high and vice versa,
so long as the pin is enabled and configured as an output pin.

See Also
MMAC_GPIO_Get

Sample Code
< tba >

14
MMAC_GPIO_SetWithMask

Function Prototype
MMAC_GPIO_RESULT_CODE MMAC_GPIO_SetWithMask(
UI64 value,
UI64 mask
);

Inputs
value A 64 bit value which will be used to set the state of the 44 bits of the GPIO
interface.
mask A 64 bit number which will be used to preserve the bits not to be affected by
value.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_GPIO_OK
MMAC_GPIO_SEMAPHORE_UNAVAILABLE
MMAC_GPIO_NOT_INITIALISED

Description
This function sets the state of the GPIO output pins. formula is as follow.
(GPIO port) &= (~mask);
(GPIO port) |= (value);

See Also
MMAC_GPIO_Get

Sample Code
< tba >

15
4 Data Structures

Includes

#include “gpio.h”

Result Codes
The following result codes are defined for the GPIO API. The result code value 0 is reserved for indication
of a successful operation.

typedef enum
{
MMAC_GPIO_OK = 0,
MMAC_GPIO_NOT_INITIALISED,
MMAC_GPIO_ALREADY_INITIALISED,
MMAC_GPIO_INVALID_PARAM,
MMAC_GPIO_FAIL,
MMAC_GPIO_SEMAPHORE_UNAVAILABLE
}MMAC_GPIO_RESULT_CODE;

Pin direction
The following enum is used to indicate the direction of a pin – i.e. whether it is being used to receive data
(READ) or to send data (WRITE).

typedef enum
{
MMAC_GPIO_READ = 0,
MMAC_GPIO_WRITE
}MMAC_GPIO_DIRECTION;

Pin interrupt mode

The following enum is used to indicate the manner in which a pin interrupt is generated.

typedef enum
{
MMAC_GPIO_DISABLED = 0,
MMAC_GPIO_RISING_EDGE,
MMAC_GPIO_FALLING_EDGE,
MMAC_GPIO_BOTH_EDGES,
MMAC_GPIO_HIGH_LEVEL
MMAC_GPIO_LOW_LEVEL
}MMAC_GPIO_INTERRUPT_MODE;

Pin configuration
The following structure is used to determine the configuration of a pin on the GPIO interface.

typedef struct
{
MMAC_GPIO_INTERRUPT_MODE interruptMode;
MMAC_BOOL interruptStatus;
MMAC_GPIO_DIRECTION direction;
}MMAC_GPIO_PIN_CONFIG;

16
GPIO configuration
The following structure is used to configuration the GPIO interface. It comprises of an array of pin
configurations (with an entry for each pin), and a callback function.

typedef struct
{
MMAC_GPIO_PIN_CONFIG pinConfig[MMAC_GPIO_NUMBER_OF_PINS];
MMAC_GPIO_CALLBACK callback;
}MMAC_GPIO_CONFIG;

GPIO callback function

The following type defines a GPIO callback function.

typedef void(*MMAC_GPIO_CALLBACK)(UI64 pinMask);

This function is called whenever a GPIO pin interrupt is generated. The parameter pinMask represents the
44 GPIO pins, bit 0 represents pin 0, bit 43 represents pin 43. If a pin has generated an interrupt this
function is called and the corresponding bit in the bit mask is set (1), all other bits are cleared (0).
It is possible for multiple bits to be set when the interrupt handler is called.

Defines

#define MMAC_GPIO_NUMBER_OF_PINS (44)

17
5 Revision History
Title: API Specification: GPIO
Ref: API_GPIO.doc

Date Doc API Details of change Ref.

Ver. Ver.
0.1 First Draft M-AH
0.3 Revised API specification M-RV
0.31 Added result code M-RV
MMAC_GPIO_ALREADY_INITIALISED
2001-08-09 0.32 Updated ‘See Also’ references in function descriptions M-RV
2002-08-09 0.4 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.4 M-RI
2003-06-27 1.1 Doc number added. M-RJI
2004-02-18 1.2 Added MMAC_GPIO_SetWithMask HG-RT
2004-02-18 1.21 Checked for release M-RJI

18