User’s Manual

EMMA2 API

PCI

CONTENTS

1 Introduction ....................................................................................................................... 3
1.1 Example of PCI API Use....................................................................................... 6
2 Function Prototypes .......................................................................................................... 8
MMAC_PCI_Initialise ....................................................................................................8
MMAC_PCI_ConfigureInitiatorWindow.........................................................................9
MMAC_PCI_MemoryWrite..........................................................................................10
MMAC_PCI_MemoryRead .........................................................................................11
MMAC_PCI_IoWrite....................................................................................................12
MMAC_PCI_IoRead ...................................................................................................13
MMAC_PCI_ConfigWrite ............................................................................................14
MMAC_PCI_ConfigRead ............................................................................................15
MMAC_PCI_DmaWrite ...............................................................................................16
MMAC_PCI_DmaRead...............................................................................................17
MMAC_PCI_MemoryReadMultiple.............................................................................18
MMAC_PCI_MemoryReadLine ..................................................................................19
MMAC_PCI_SetEndianOptions ..................................................................................20
MMAC_PCI_GetEndianOptions .................................................................................21
MMAC_PCI_SetRetryOptions.....................................................................................22
MMAC_PCI_GetRetryOptions ....................................................................................23
MMAC_PCI_SetErrorAddressCaptureOptions...........................................................24
MMAC_PCI_GetErrorAddressCaptureOptions ..........................................................25
MMAC_PCI_SetSerrOptions ......................................................................................26
MMAC_PCI_GetSerrOptions ......................................................................................27
MMAC_PCI_SetInternalErrorOptions .........................................................................28
MMAC_PCI_GetInternalErrorOptions.........................................................................29

Book No: S16753EE1V0UM00 Doc No: MMAC0029, 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.
 MMAC_PCI_GetLastErrorInformation ........................................................................30
MMAC_PCI_EnableInterrupt ......................................................................................31
MMAC_PCI_DisableInterrupt......................................................................................32
MMAC_PCI_InstallCallback........................................................................................33
MMAC_PCI_DeleteCallback.......................................................................................34
MMAC_PCI_InterfaceReset........................................................................................35
3 Data Structures ............................................................................................................... 36
4 Revision History .............................................................................................................. 40

2
1 Introduction
This section defines the API for the MMAC PCI interface driver.
The EMMA2 PCI interface is a 33MHz, 32bit controller compliant with PCI Local Bus Specification 2.1.
The function MMAC_PCI_Initialise() must be called before any other PCI function is called. This
initialises system resources and internal data structures of the PCI driver, and also sets up the default
arbiter mode (internal or external) of the interface via a definition is mmac_config.h. Outbound PCI
windows should then be initialised using MMAC_PCI_ConfigureInitiatorWindow() before the PCI
interface can be used as an initiator. Note that there is no provision in the API for the initialisation of
inbound (target) PCI windows, as this should be done via configuration cycles from a second PCI master.
The transfer functions within the PCI module can then be used to perform various transactions across the
PCI bus.
The remaining functions in the API are used to control the operational characteristics of the PCI interface.
These are initialised to a default state at reset, which should be sufficient for most implementations.
However in certain circumstances it may be necessary to change some of these characteristics ‘on the fly’,
such as the endian options, so the provision is made in the API to do this.
The PCI API provides the following functions:
Function Name Description
MMAC_PCI_Initialise Initialise system resources and internal data
structures of PCI API driver.
MMAC_PCI_ConfigureInitiatorWindow Configure a PCI initiator window.
MMAC_PCI_MemoryWrite Perform a write to PCI memory space.
MMAC_PCI_MemoryRead Perform a read from PCI memory space.
MMAC_PCI_IoWrite Perform a write to PCI I/O space.
MMAC_PCI_IoWrite Perform a read from PCI I/O space.
MMAC_PCI_ConfigWrite Perform a write to PCI configuration space.
MMAC_PCI_ConfigRead Perform a read from PCI configuration space.
MMAC_PCI_DmaWrite Perform a DMA write to PCI memory space.
MMAC_PCI_DmaRead Perform a DMA read from PCI memory space.
MMAC_PCI_MemoryReadMultiple Perform a Memory Read Multiple read from PCI
memory space.
MMAC_PCI_MemoryReadLine Perform a Memory Read Line read from PCI
memory space.
MMAC_PCI_SetEndianOptions Configure the endian mode and byte swapping
functions of the PCI interface.
MMAC_PCI_GetEndianOptions Read the endian mode and byte swapping
configuration of the PCI interface.
MMAC_PCI_SetRetryOptions Configure the Retry options of the PCI interface.
MMAC_PCI_GetRetryOptions Read the PCI interface Retry options configuration.
MMAC_PCI_ Configure which PCI errors cause the error
SetErrorAddressCaptureOptions address to be captured.
MMAC_PCI_ Read which PCI errors cause the error address to
GetErrorAddressCaptureOptions be captured.
MMAC_PCI_SetSerrOptions Configure which PCI errors cause #SERR to be
asserted.
MMAC_PCI_GetSerrOptions Read which PCI errors cause #SERR to be
asserted.

3
 Function Name Description
MMAC_PCI_SetInternalErrorOptions Configure which PCI errors cause the PCI internal
error to be asserted.
MMAC_PCI_GetInternalErrorOptions Read which PCI errors cause the PCI internal error
to be asserted.
MMAC_PCI_InterfaceReset Reset selected components of the PCI interface.

Result Codes
The meanings of the various result codes returned by the API are described in the following table:
Result Code Description
MMAC_PCI_OK A PCI operation has successfully completed.
MMAC_PCI_FAIL A PCI operation has failed.
MMAC_PCI_NOT_INITIALISED The PCI driver has not been initialised.
MMAC_PCI_ALREADY_INITIALISED The PCI driver has been previously initialised.
MMAC_PCI_INVALID_PARAM A parameter passed is invalid, it is out of range or
a NULL pointer has been passed.
MMAC_PCI_WINDOW_NOT_CONFIGURED The given PCI initiator window has not been
configured.
MMAC_PCI_CYCLE_BARRED The given cycle type is not allowed in this initiator
window.

Includes
In order to use this API, the following header files must be included, in the following order:
#include “mmac/types.h”
#include “mmac/rtos.h”
#include “mmac/mmac_config.h”
#include “mmac/pci.h”

Initialisations
Prior to using any functions of the PCI API, the following functions must be called:
MMAC_RTOS_Initialise()

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

/****************************************************************/
/* */
/* MMAC PCI SETUP */
/* */
/****************************************************************/

These options are:

Define Default Meaning
MMAC_PCI_EMMA2_IS_ MMAC_YES Sets whether to compile the build if
TARGET_DEVICE EMMA2 is a target device on the
bus. If EMMA2 is a target device,
then it is assumed that EMMA2 will
need to be released from its
suspended power-up state. This
define is also used to set the
EMMA2 arbiter mode (see below).
MMAC_PCI_ARBITER_MODE MMAC_PCI_ARBITER_ Sets the arbiter mode of the PCI
EXTERNAL interface. This define is
automatically set by the target
device define (see above).
MMAC_PCI_ACCESS_ MMAC_RTOS_MAX_TIMEOUT Sets the timeout for acquiring the
CONTROL_WAIT_TIME PCI register access semaphore.
MMAC_PCI_DMA_SYNC_ MMAC_RTOS_MAX_TIMEOUT Sets the timeout for acquiring the
WAIT_TIME DMA synch semaphore.
MMAC_PCI_PARAMETER_ Undefined When defined, enables API level
CHECKING range checking and validation.

5
1.1 Example of PCI API Use

/* intialise the PCI initiator windows */

/*
* window 0 : mapped to 0x40000000 on the PCI bus, barred
* to memory cycles
*/
if(MMAC_PCI_ConfigureInitiatorWindow(
MMAC_PCI_INIT_WINDOW_0,
0x40000000,
MMAC_PCI_CYCLE_TYPE_IO |
MMAC_PCI_CYCLE_TYPE_CONFIG
) != MMAC_PCI_OK)
{
return MMAC_FALSE;
}
/*
* window 1 : mapped to 0x60000000 on the PCI bus, memory cycles only
*/
if(MMAC_PCI_ConfigureInitiatorWindow(
MMAC_PCI_INIT_WINDOW_1,
0x60000000,
MMAC_PCI_CYCLE_TYPE_MEMORY |
MMAC_PCI_CYCLE_TYPE_DMA
) != MMAC_PCI_OK)
{
return MMAC_FALSE;
}
/*
* perform a config read to the VEN/DEV ID register
* of PCI device #3
*/
MMAC_PCI_ConfigRead(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_VENDOR_LOW,
MAC_PCI_SIZE_32BIT,
&venDevId);
/*
* size BAR0
*/
MMAC_PCI_ConfigWrite(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_0,
MMAC_PCI_SIZE_32BIT,
0xffffffff);

MMAC_PCI_ConfigRead(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_0,
MMAC_PCI_SIZE_32BIT,
&sizeMask0);
/*
* write out the address for BAR0
*/
MMAC_PCI_ConfigWrite(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_0,
MMAC_PCI_SIZE_32BIT,
CSR_PCI_MEM_BASE);
/*
* size BAR1
*/
MMAC_PCI_ConfigWrite(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_1,
MMAC_PCI_SIZE_32BIT,
0xffffffff);

6
MMAC_PCI_ConfigRead(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_1,
MMAC_PCI_SIZE_32BIT,
&sizeMask1);
/*
* write out the address for BAR1
*/
MMAC_PCI_ConfigWrite(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_BAR_1,
MMAC_PCI_SIZE_32BIT,
CSR_PCI_IO_BASE);
/*
* enable PCI device #3 in memory and I/O space
*/
MMAC_PCI_ConfigWrite(MMAC_PCI_INIT_WINDOW_0, 3, 0,
MMAC_PCI_CONFIG_COMMAND,
MMAC_PCI_SIZE_16BIT,
0x0003);
/*
* Read the Memory and I/O mapped registers of PCI device #3
*/
MMAC_PCI_MemoryRead(MMAC_PCI_INIT_WINDOW_1, CSR_PCI_MEM_OFFSET,
MMAC_PCI_SIZE_32BIT, &data0);

MMAC_PCI_IoRead(MMAC_PCI_INIT_WINDOW_0, CSR_PCI_IO_OFFSET,
MMAC_PCI_SIZE_32BIT, &data1);

7
2 Function Prototypes

MMAC_PCI_Initialise

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_Initialise (void)

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_ALREADY_INITIALISED
MMAC_PCI_FAIL

Description
This function initialises the system resources and internal data structures used by the PCI interface API
and configures the interface arbiter mode (internal or external arbiter) via the definition of
MMAC_PCI_DEFAULT_ARBITER_MODE in mmac_config.h.
This routine must be called before any other PCI API routines are used, and can be called only once. This
means that the arbiter mode cannot be changed once the API has been initialised.
If any of the initialisation tasks fail then the function will return MMAC_PCI_FAIL.
If the PCI API is already initialised then this function will do nothing and return
MMAC_PCI_ALREADY_INITIALISED

See Also
None

Sample Code
< tba >

8
MMAC_PCI_ConfigureInitiatorWindow

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_ConfigureInitiatorWindow (
MMAC_PCI_INIT_WINDOW windowId,
UI32 pciBaseAdrs,
UI32 accessControlMask
)

Inputs
windowId Determines which initiator window to configure
windowBase Determines the PCI base address of this initiator window
accessControl Determines the cycle types allowed to be initiated in this window

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
This routine is used to set the PCI base address of the given initiator window, i.e. the base address on the
PCI bus at which accesses within this window in local address space will be mapped. The
accessControlMask parameter specifies which PCI transaction types (memory, I/O or configuration cycles)
are valid in this window, and thus can be used to bar certain cycle types. For example, one of the windows
may be set as ‘memory cycles only’ to reduce the overhead involved in setting up the initiator register for
that window before each transaction to configure the cycle type.

See Also
None

Sample Code
< tba >

9
MMAC_PCI_MemoryWrite

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_MemoryWrite (
MMAC_PCI_INIT_WINDOW windowId,
UI32 offset,
MMAC_PCI_DATA_SIZE size,
UI32 data
);

Inputs
windowId The initiator window in which to perform the write
offset The offset address within this window at which to write
data The data to write
size The size of the data transfer (8, 16 or 32 bits)

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that memory cycles are barred then this function
will do nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI memory write within the specified initiator window. The write is of the
given size, with the given data, to the specified offset address within this window.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_MemoryRead

Sample Code
< tba >

10
MMAC_PCI_MemoryRead

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_MemoryRead (
MMAC_PCI_INIT_WINDOW windowId,
UI32 offset,
MMAC_PCI_DATA_SIZE size,
UI32 *data
);

Inputs
WindowId The initiator window in which to perform the read
Offset The offset address within this window at which to read
Size The size of the data transfer (8, 16 or 32 bits)

Outputs
Data Pointer to the data read

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that memory cycles are barred then this function
will do nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI memory read within the specified initiator window. The read is of the given
size from the specified offset address within this window, and returns the data read back.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_MemoryWrite

Sample Code
< tba >

11
MMAC_PCI_IoWrite

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_IoWrite (
MMAC_PCI_INIT_WINDOW windowId,
UI32 offset,
MMAC_PCI_DATA_SIZE size,
UI32 data
);

Inputs
WindowId The initiator window in which to perform the write
Offset The offset address within this window at which to write
data The data to write
size The size of the data transfer (8, 16 or 32 bits)

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that I/O cycles are barred then this function will do
nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI I/O write within the specified initiator window. The write is of the given size,
with the given data, to the specified offset address within this window.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_IoRead

Sample Code
< tba >

12
MMAC_PCI_IoRead

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_IoRead (
MMAC_PCI_INIT_WINDOW windowId,
UI32 offset,
MMAC_PCI_DATA_SIZE size,
UI32 *data
)

Inputs
WindowId The initiator window in which to perform the read
Offset The offset address within this window at which to read
Size The size of the data transfer (8, 16 or 32 bits)

Outputs
Data Pointer to the data read

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that I/O cycles are barred then this function will do
nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI I/O read within the specified initiator window. The read is of the given size
from the specified offset address within this window, and returns the data read back.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_IoWrite

Sample Code
< tba >

13
MMAC_PCI_ConfigWrite

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_ConfigWrite (
MMAC_PCI_INIT_WINDOW windowId,
UI32 device,
UI32 function,
UI32 reg,
MMAC_PCI_DATA_SIZE size,
UI32 data
);

Inputs
WindowId The initiator window in which to perform the write
Device The PCI target device
function The function of the target device to write to
reg The register of the target device/function to write to
data The data to write
size The size of the data transfer (8, 16 or 32 bits)

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that configuration cycles are barred then this
function will do nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI configuration write to the specified device. The write is of the given size,
with the given data, to the specified function and reg within the target device.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_ConfigRead

Sample Code
< tba >

14
MMAC_PCI_ConfigRead

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_ConfigRead (
MMAC_PCI_INIT_WINDOW windowId,
UI32 device,
UI32 function,
UI32 reg,
MMAC_PCI_DATA_SIZE size,
UI32 *data
);
Inputs
WindowId The initiator window in which to perform the read
Device The PCI target device
function The function of the target device to be read
reg The register of the target device/function to read
size The size of the data transfer (8, 16 or 32 bits)

Outputs
Data Pointer to the data read

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL
MMAC_PCI_WINDOW_NOT_CONFIGURED
MMAC_PCI_CYCLE_BARRED

Description
If the PCI API is not initialised then this function will do nothing and return
MMAC_PCI_NOT_INITIALISED.
If the given initiator window has not been configured then this function will do nothing and return
MMAC_PCI_WINDOW_NOT_CONFIGURED.
If the given initiator window has been configured such that configuration cycles are barred then this
function will do nothing and return MMAC_PCI_CYCLE_BARRED
This function performs a PCI configuration read from the specified device. The read is of the size given
from the specified function and reg within the target device.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_ConfigWrite

Sample Code
< tba >

15
MMAC_PCI_DmaWrite

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_DmaWrite (
MMAC_PCI_INIT_WINDOW windowId,
UI32 *src,
UI32 *dst,
UI32 size,
MMAC_PCI_DMA_CALLBACK callback
)

Inputs
windowId The initiator window in which to perform the write
src Pointer to the source data in memory
dst Pointer to the destination address on PCI
size The size of the transfer
callback Optional transfer completion callback function

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function performs a DMA write of the given size from the specified C-BUS src address to the
specified PCI bus dst address.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_DmaRead

Sample Code
< tba >

16
MMAC_PCI_DmaRead

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_DmaRead (
MMAC_PCI_INIT_WINDOW windowId,
UI32 *src,
UI32 *dst,
UI32 size,
MMAC_PCI_DMA_CALLBACK callback
)

Inputs
windowId The initiator window in which to perform the read
src Pointer to the source data on PCI
dst Pointer to the destination address in memory
size The size of the transfer
callback Optional transfer completion callback function

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function performs a DMA read of the given size from the specified PCI bus src address to the
specified C-BUS dst address.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_DmaWrite

Sample Code
< tba >

17
MMAC_PCI_MemoryReadMultiple

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_MemoryReadMultiple (
MMAC_PCI_INIT_WINDOW windowId,
UI32 *src,
UI32 *dst,
UI32 size,
MMAC_PCI_DMA_CALLBACK callback
)

Inputs
windowId The initiator window in which to perform the read
src Pointer to the source data on PCI
dst Pointer to the destination address in memory
size The size of the transfer
callback Optional transfer completion callback function

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function performs a Memory Read Multiple (MRM) command on the PCI bus, using the DMA to
read memory of the given size from the specified PCI bus src address to the specified C-BUS dst address.
The MRM command is semantically identical to the Memory Read command except that it additionally
indicates that EMMA2 intends to fetch more than one cacheline before disconnecting from the PCI bus.
This function is intended to be used with bulk sequential data transfers.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_DmaRead
MMAC_PCI_MemoryReadLine

Sample Code
< tba >

18
MMAC_PCI_MemoryReadLine

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_MemoryReadLine (
MMAC_PCI_INIT_WINDOW windowId,
UI32 *src,
UI32 *dst,
UI32 size,
MMAC_PCI_DMA_CALLBACK callback
)

Inputs
windowId The initiator window in which to perform the read
src Pointer to the source data on PCI
dst Pointer to the destination address in memory
size The size of the transfer
callback Optional transfer completion callback function

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function performs a Memory Read Line (MRL) command on the PCI bus, using the DMA to read
memory of the given size from the specified PCI bus src address to the specified C-BUS dst address.
The MRL command is semantically identical to the Memory Read command except that it additionally
indicates that EMMA2 intends to fetch a complete cacheline before disconnecting from the PCI bus. This
function is intended to be used with bulk sequential data transfers.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_DmaRead
MMAC_PCI_MemoryReadMultiple

Sample Code
< tba >

19
MMAC_PCI_SetEndianOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_SetEndianOptions (
MMAC_PCI_ENDIAN_IOPB *iopb
)

Inputs
iopb A pointer to a configuration structure for PCI endian options:
endianMode
reg1Swap
sdramSwap
window0Swap
window1Swap

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function configures the endian options for the PCI interface. The endianMode selects whether the
internal bus (TBUS) operates in little or big endian mode. The remaining parameters select whether byte
swapping is performed for transactions in each of the four PCI windows – two initiator, two target.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_GetEndianOptions

Sample Code
< tba >

20
MMAC_PCI_GetEndianOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetEndianOptions (
MMAC_PCI_ENDIAN_IOPB *iopb
)

Inputs
None.

Outputs
Iopb A pointer to a configuration structure for PCI endian options:
endianMode
reg1Swap
sdramSwap
window0Swap
window1Swap

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function reports the endian options for the PCI interface. The endianMode indicates whether the
internal bus (TBUS) is operating in little or big endian mode. The remaining parameters indicate whether
byte swapping is performed for transactions in each of the four PCI windows – two initiator, two target.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_SetEndianOptions

Sample Code
< tba >

21
MMAC_PCI_SetRetryOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_SetRetryOptions (
UI32 retryLimit
)

Inputs
retryLimit The retry limit for the PCI interface as initiator

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function configures the retry options of the PCI interface. The parameter specifies the retry limit, i.e.
the maximum number of times continuous retries can be accepted from a single PCI target.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_GetRetryOptions

Sample Code
< tba >

22
MMAC_PCI_GetRetryOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetRetryOptions (
UI32 *retryLimit
)

Inputs
None.

Outputs
retryLimit The retry limit for the PCI interface as initiator

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function reports the retry options of the PCI interface. The parameter indicates the retry limit, i.e. the
maximum number of times continuous retries can be accepted from a single PCI target.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_SetRetryOptions

Sample Code
< tba >

23
MMAC_PCI_SetErrorAddressCaptureOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_SetErrorAddressCaptureOptions (
MMAC_PCI_ERROR_ADRS_IOPB *iopb
)

Inputs
iopb A pointer to a configuration structure for PCI error address capture options:
targetAbort
masterAbort
retryLimit
dataParity
discardTimeout
internalBerr

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function specifies for which PCI error conditions the address at which the error occurred will be
captured.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_GetAddressCaptureOptions

Sample Code
< tba >

24
MMAC_PCI_GetErrorAddressCaptureOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetErrorAddressCaptureOptions (
MMAC_PCI_ERROR_ADRS_IOPB *iopb
)

Inputs
None.

Outputs
iopb A pointer to a configuration structure for PCI error address capture options:
targetAbort
masterAbort
retryLimit
dataParity
discardTimeout
internalBerr

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function indicates for which PCI error conditions the address at which the error occurred will be
captured.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_SetAddressCaptureOptions

Sample Code
< tba >

25
MMAC_PCI_SetSerrOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_SetSerrOptions (
MMAC_PCI_SERR_IOPB *iopb
)

Inputs
iopb A pointer to a configuration structure for PCI #SERR assertion options:
targetAbor
masterAbort
retryLimit
dataParity
discardTimeout
internalBerr

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function specifies for which PCI error conditions the #SERR signal will be asserted on the PCI bus.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_GetSerrOptions

Sample Code
< tba >

26
MMAC_PCI_GetSerrOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetSerrOptions (
MMAC_PCI_SERR_IOPB *iopb
)

Inputs
None.

Outputs
Iopb A pointer to a configuration structure for PCI #SERR assertion options:
targetAbort
masterAbort
retryLimit
dataParity
discardTimeout
internalBerr

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function indicates for which PCI error conditions the #SERR signal will be asserted on the PCI bus.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_SetSerrOptions

Sample Code
< tba >

27
MMAC_PCI_SetInternalErrorOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_SetInternalErrorOptions (
MMAC_PCI_INTERNAL_ERR_IOPB *iopb
);

Inputs
Iopb A pointer to a configuration structure for PCI internal error assertion options:
targetAbort
masterAbort
retryLimit
dataParity
discardTimeout
addressParity
internalBerr

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function specifies for which PCI error conditions the internal PCI error will be asserted.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_GetInternalErrorOptions

Sample Code
< tba >

28
MMAC_PCI_GetInternalErrorOptions

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetInternalErrorOptions (
MMAC_PCI_INTERNAL_ERR_IOPB *iopb
)
Inputs
None.

Outputs
Iopb A pointer to a configuration structure for PCI internal error assertion options:
targetAbort
masterAbort
retryLimit
dataParity
discardTimeout
addressParity
internalBerr

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function indicates for which PCI error conditions the internal PCI error will be asserted.

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow
MMAC_PCI_SetInternalErrorOptions

Sample Code
< tba >

29
MMAC_PCI_GetLastErrorInformation

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_GetLastErrorInformation (
MMAC_PCI_ERROR_INFO_IOPB *iopb
)

Inputs
None.

Outputs
Iopb A pointer to a configuration structure for PCI error information:
errorType
pciErrorAdrs
tbusErrorAdrs
cpuMaster

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_INVALID_PARAM

Description
This function used to retrieve information about the last error to occur in the PCI interface. This
information is updated by the error interrupt handler. The type of error (Target Abort, Master Abort etc.) is
specified by errorType, the PCI bus and T-BUS addresses recorded when the error occurred are specified
by pciErrorAdrs and tbusErrorAdrs respectively, and cpuMaster indicates if the CPU was the PCI master
when the error occurred.

See Also
MMAC_PCI_Initialise
MMAC_PCI_EnableInterrupt
MMAC_PCI_DisableInterrupt

Sample Code
< tba >

30
MMAC_PCI_EnableInterrupt

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_EnableInterrupt (
MMAC_PCI_INTERRUPT interrupt
)

Inputs
Interrupt The interrupt to enable

Outputs
None

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function enables the given internal PCI interrupt

See Also
MMAC_PCI_Initialise
MMAC_PCI_DisableInterrupt

Sample Code
< tba >

31
MMAC_PCI_DisableInterrupt

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_DisableInterrupt (
MMAC_PCI_INTERRUPT interrupt
)

Inputs
Interrupt The interrupt to disable

Outputs
None

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function disables the given internal PCI interrupt

See Also
MMAC_PCI_Initialise
MMAC_PCI_EnableInterrupt

Sample Code
< tba >

32
MMAC_PCI_InstallCallback

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_InstallCallback (
MMAC_PCI_INTERRUPT interrupt,
MMAC_PCI_INT_CALLBACK callback
)
Inputs
Interrupt The interrupt to install a callback function for
callback The callback function for this interrupt

Outputs
None

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED

Description
This function installs the given callback function for the specified PCI internal interrupt

See Also
MMAC_PCI_Initialise
MMAC_PCI_DeleteCallback
MMAC_PCI_EnableInterrupt
MMAC_PCI_DisableInterrupt

Sample Code
< tba >

33
MMAC_PCI_DeleteCallback

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_DeleteCallback (
MMAC_PCI_INTERRUPT interrupt,
MMAC_PCI_INT_CALLBACK callback
)

Inputs
Interrupt The interrupt to delete the callback function for

Outputs
None

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED

Description
This function deletes the callback function for the specified PCI internal interrupt

See Also
MMAC_PCI_Initialise
MMAC_PCI_InstallCallback
MMAC_PCI_EnableInterrupt
MMAC_PCI_DisableInterrupt

Sample Code
< tba >

34
MMAC_PCI_InterfaceReset

Function Prototype
MMAC_PCI_RESULT_CODE MMAC_PCI_InterfaceReset (
MMAC_PCI_RESET_IOPB *iopb
)

Inputs
Iopb A pointer to a configuration structure for PCI interface reset:
entireModule
pciCore
bhifInterface
cbusInterface
dmaInterface
internalArbiter
configInterface

Outputs
None

Event Notification
N/A

Return Codes
MMAC_PCI_OK
MMAC_PCI_NOT_INITIALISED
MMAC_PCI_FAIL

Description
This function is used to reset all of or individual components of the PCI interface

See Also
MMAC_PCI_Initialise
MMAC_PCI_ConfigureInitiatorWindow

Sample Code
< tba >

35
3 Data Structures

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

typedef enum
{
MMAC_PCI_OK = 0,
MMAC_PCI_FAIL,
MMAC_PCI_ALREADY_INITIALISED,
MMAC_PCI_NOT_INITIALISED,
MMAC_PCI_INVALID_PARAM,
MMAC_PCI_WINDOW_NOT_CONFIGURED,
MMAC_PCI_CYCLE_BARRED
}MMAC_PCI_RESULT_CODE;

Window Numbers
The following window numbers are assigned for the PCI initiator windows.

typedef enum
{
MMAC_PCI_INIT_WINDOW_0 = 0,
MMAC_PCI_INIT_WINDOW_1
}MMAC_PCI_INIT_WINDOW;

PCI Arbitration
The following modes are defined for PCI arbitration

typedef enum
{
MMAC_PCI_ARBITER_INTERNAL = 0,
MMAC_PCI_ARBITER_EXTERNAL
}MMAC_PCI_ARBITER_MODE;

Data Width
The following data widths are defined for PCI transfers.

typedef enum
{
MMAC_PCI_SIZE_8BIT = 1,
MMAC_PCI_SIZE_16BIT = 2,
MMAC_PCI_SIZE_32BIT = 4,
MMAC_PCI_SIZE_64BIT = 8
}MMAC_PCI_DATA_SIZE;

36
Error Type
The following error types are defined for PCI transfers.

typedef enum
MMAC_PCI_ERR_NO_ERROR = 0,
MMAC_PCI_ERR_TARGET_ABORT,
MMAC_PCI_ERR_MASTER_ABORT,
MAC_PCI_ERR_RETRY_LIMIT,
MMAC_PCI_ERR_READ_PARITY,
MMAC_PCI_ERR_WRITE_PARITY,
MMAC_PCI_ERR_DISCARD_TIMEOUT,
MMAC_PCI_ERR_TBUS_INTERNAL
}MMAC_PCI_ERROR_TYPE;

Interrupt Conditions
The following PCI interrupt conditions are defined

typedef enum
{
MMAC_PCI_INTERRUPT_SERR = 0x00000001,
MMAC_PCI_INTERRUPT_IERR = 0x00000002,
MAC_PCI_INTERRUPT_DMA_ADR = 0x00000004,
MMAC_PCI_INTERRUPT_DMA_BUSERR = 0x00000008,
MMAC_PCI_INTERRUPT_CBI_BUSERR = 0x00000010
}MMAC_PCI_INTERRUPT;

Callbacks
The following type defines an MMAC_PCI_DMA_CALLBACK.
typedef void(*MMAC_PCI_DMA_CALLBACK)(void);

The following type defines an MMAC_PCI_INT_CALLBACK.

typedef void(*MMAC_PCI_INT_CALLBACK)(UI32 intReg);

Transaction Type Access Control

The following definitions are used to create a mask indicating which PCI transactions are allowed in a
given initiator window.

#define MMAC_PCI_CYCLE_TYPE_MEMORY 0x00000001

#define MMAC_PCI_CYCLE_TYPE_IO 0x00000002
#define MMAC_PCI_CYCLE_TYPE_CONFIG 0x00000004
#define MMAC_PCI_CYCLE_TYPE_DMA 0x00000008

MMAC_PCI_Set/GetEndianOptions
The following definitions are required by the PCI interface Endian Options functions.

typedef enum
{
MMAC_PCI_LITTLE_ENDIAN,
MMAC_PCI_BIG_ENDIAN
}MMAC_PCI_ENDIAN_MODE;

37
typedef struct
{
MMAC_PCI_ENDIAN_MODE endianMode;
MMAC_BOOL reg1Swap;
MMAC_BOOL sdramSwap;
MMAC_BOOL window0Swap;
MMAC_BOOL window1Swap;
}MMAC_PCI_ENDIAN_IOPB;

MMAC_PCI_Set/GetEndianOptions
The following definitions are required by the PCI interface Retry Options functions.

typedef struct
{
UI32 retryLimit;
}MMAC_PCI_RETRY_IOPB;

MMAC_PCI_Set/GetErrorAddressCaptureOptions
The following definitions are required by the PCI interface Error Address Capture functions.

typedef struct
{
MMAC_BOOL targetAbort;
MMAC_BOOL masterAbort;
MMAC_BOOL retryLimit;
MMAC_BOOL dataParity;
MMAC_BOOL discardTimeout;
MMAC_BOOL internalBerr;
}MMAC_PCI_ERROR_ADRS_IOPB;

MMAC_PCI_Set/GetSerrOptions
The following definitions are required by the PCI interface #SERR Options functions.

typedef struct
{
MMAC_BOOL targetAbort;
MMAC_BOOL masterAbort;
MMAC_BOOL retryLimit;
MMAC_BOOL dataParity;
MMAC_BOOL discardTimeout;
MMAC_BOOL addressParity;
MMAC_BOOL internalBerr;
}MMAC_PCI_SERR_IOPB;

MMAC_PCI_Set/GetInternalErrorOptions
The following definitions are required by the PCI interface internal error Options functions.

typedef struct
{
MMAC_BOOL targetAbort;
MMAC_BOOL masterAbort;
MMAC_BOOL retryLimit;
MMAC_BOOL dataParity;
MMAC_BOOL discardTimeout;
MMAC_BOOL addressParity;
MMAC_BOOL internalBerr;
}MMAC_PCI_INTERNAL_ERR_IOPB;

38
MMAC_PCI_GetLastErrorInformation
The following definitions are required by the PCI interface error retrieval function.

typedef struct
{
MMAC_PCI_ERROR_TYPE errorType;
UI32 pciErrorAdrs;
UI32 tbusErrorAdrs;
MMAC_BOOL cpuMaster;
}MMAC_PCI_ERROR_INFO_IOPB;

MMAC_PCI_InterfaceReset
The following definitions are required by the PCI Interface Reset functions.

typedef struct
{
MMAC_BOOL entireModule;
MMAC_BOOL pciCore;
MMAC_BOOL bhifInterface;
MMAC_BOOL cbusInterface;
MMAC_BOOL dmaInterface;
MMAC_BOOL internalArbiter;
MMAC_BOOL configInterface;
}MMAC_PCI_RESET_IOPB;

39
4 Revision History
Title: API Specification: PCI
Ref: API_PCI.doc

Date Doc API Details of change Ref.

Ver. Ver.
0.01 Initial Revision ICM
0.02 Changes following review. Initialise() function now only sets ICM
up internal data structures and arbiter mode. Added
Configure Window routine
0.03 Updated PCI access routine prototypes to pass parameters ICM
directly instead of using an indirect IOPB structure.
0.04 Added code example ICM
0.05 Added new error handling/interrupt functions ICM
0.06 Added new MRM & MRL functions NJP
2002-02-26 0.07 Added new define M-MH
MMAC_PCI_EMMA2_IS_TARGET_DEVICE
2002-08-06 0.08 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.08 M-RI
2003-06-27 1.1 Doc number added. M-RJI

40