User’s Manual

EMMA2 API

Miscellaneous

CONTENTS

1 Introduction ....................................................................................................................... 2
2 Function Prototypes .......................................................................................................... 4
MMAC_MISC_SetCacheState......................................................................................4
MMAC_MISC_FlushCache...........................................................................................5
MMAC_MISC_FlushCacheAddress .............................................................................6
MMAC_MISC_GetSoftwareVersion..............................................................................7
MMAC_MISC_GetHardwareVersion ............................................................................8
MMAC_MISC_GenerateRandomNumber ....................................................................9
MMAC_MISC_ReportFatalError .................................................................................10
MMAC_MISC_AllocAlignedBuffer ..............................................................................11
MMAC_MISC_FreeAlignedBuffer ...............................................................................12
3 Data Structures ............................................................................................................... 13
4 Revision History .............................................................................................................. 14

Book No. S16753EE1V0UM00 Doc No: MMAC0028, Issue: 1.2

© NEC Electronics Corporation 2002, 2003 Publication 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 MISC driver. The MISC driver is a collection of useful
functions that do not fit within the specification of any of the other standard API modules.
The MISC driver provides the following functionality:
• Software/Hardware Version retrieval
• Cache Flushing
• Random Number Generation
• Allocation of memory aligned to a specified multiple of 4 bytes.

Functions
The following functions are provided.
Function Name Description
MMAC_MISC_SetCacheState Enable/disable the EMMA cache (instruction and data).
MMAC_MISC_FlushCache Flush the EMMA CPU data cache.
MMAC_MISC_GenerateRandomNumber Flush a selected address from the EMMA CPU data
cache.
MMAC_MISC_GenerateRandomNumber Generate a random number.
MMAC_MISC_GetSoftwareVersion Get the API revision number.
MMAC_MISC_GetHardwareVersion Get the EMMA hardware version information.
MMAC_MISC_AllocAlignedBuffer Allocates memory aligned to a specified multiple of four
bytes.
MMAC_MISC_FreeAlignedBuffer Frees memory allocated using the function
MMAC_MISC_AllocAlignedBuffer().

The MMAC_MISC_FlushCache(), MMAC_MISC_FlushCacheAddress and MMAC_MISC_

SetCacheState() functions must reside in KSEG1 (uncached, no TLB). This is done by creating the
section ‘MMAC_MISC_NoCacheNoTLB’, and assigning it a specific address, in KSEG1, in a system link
file.

Result Codes
The meanings of the various result codes returned by the driver are described in the following table:
Result Code Description
MMAC_MISC_OK A MISC operation has successfully completed.
MMAC_MISC_FAIL A MISC operation has failed.
MMAC_MISC_INVALID_PARAM A MISC operation has been passed an invalid parameter.

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

/****************************************************************/
/* */
/* MMAC MISC SETUP */
/* */
/****************************************************************/

These options are:

Define Default Meaning
MMAC_MISC_REBOOT_ON_ MMAC_NO If set then reboot the box when a fatal error is
FATAL_ERROR reported.

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/rtos.h”
#include “mmac/misc.h”
#include “mmac/version.h”

Initialisations
No other API modules are required prior to utilizing the MISC API.

3
2 Function Prototypes

MMAC_MISC_SetCacheState

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_SetCacheState(
MMAC_MISC_CACHE_STATE state
);

Inputs
state The new EMMA cache state

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_MISC_OK

Description
If state is MMAC_MISC_CACHE_ENABLE the EMMA cache (instruction and data) is enabled, otherwise
the cache (instruction and data) is disabled.
The cache is not flushed before the operation is applied: this is left to the user to decide whether or not the
cache should be flushed before hand, using MMAC_MISC_FlushCache().
Always returns MMAC_MISC_OK.

See Also
MMAC_MISC_FlushCache
MMAC_MISC_FlushCacheAddress

Sample Code
< tba >

4
MMAC_MISC_FlushCache

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_FlushCache(void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_MISC_OK

Description
Flushes the EMMA CPU data cache.
Always returns MMAC_MISC_OK.

See Also
MMAC_MISC_SetCacheState
MMAC_MISC_FlushCacheAddress

Sample Code
< tba >

5
MMAC_MISC_FlushCacheAddress

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_FlushCacheAddress(
UI32 address
);

Inputs
address The address to flush from the data cache.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_MISC_OK

Description
Flushes a given address from the data cache.
Always returns MMAC_MISC_OK.

See Also
MMAC_MISC_SetCacheState
MMAC_MISC_FlushCache

Sample Code
< tba >

6
MMAC_MISC_GetSoftwareVersion

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_GetSoftwareVersion( UI16 *apiVersion );

Inputs
None.

Outputs
apiVersion MMAC API version number.

Event Notification
N/A

Return Codes
MMAC_MISC_OK
MMAC_MISC_INVALID_PARAM

Description
This function returns the MMAC API version number and the EMMA hardware version number.
The API version number is statically defined at compile time. The API version is formatted as a decimal
number, the actual API version number is given by:
actual software version = apiVersion / 100
E.g. for apiVersion = 101, the actual API version is Version 1.01.

See Also
N/A

Sample Code
< tba >

7
MMAC_MISC_GetHardwareVersion

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_GetHardwareVersion(
UI32 *hardwareVersion
);

Inputs
None

Outputs
hardwareVersion EMMA hardware version number.

Event Notification
N/A

Return Codes
MMAC_MISC_OK
MMAC_MISC_INVALID_PARAM

Description
This function returns the EMMA BHIF version number. The hardware version is read from the EMMA
hardware,

See Also
N/A

Sample Code
< tba >

8
MMAC_MISC_GenerateRandomNumber

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_GenerateRandomNumber(
UI16 *randomNumber
);

Inputs
None.

Outputs
randomNumber A random number.

Event Notification
N/A

Return Codes
MMAC_MISC_OK

Description
This function generates a random number using hardware facilities. The function can take up to 400 m.s.
The function can be used to generate a seed value for the ANSI ‘C’ functions srand() and rand().
*randomNumber is set to a random value, in the range 0..(2^15)-1 in compliance with the ANSI standard.
Always returns MMAC_MISC_OK.

See Also
N/A

Sample Code
< tba >

9
MMAC_MISC_ReportFatalError

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_ReportFatalError(
MMAC_MISC_FATAL_ERROR error
);

Inputs
None.

Outputs
error A fatal error code.

Event Notification
N/A

Return Codes
None, this function never returns.

Description
The function prints a fatal error message based on the error code passed in. If the define
MMAC_MISC_REBOOT_ON_FATAL_ERROR is set in the mmac_config.h file then the function will not
return and will reboot the system, otherwise the function will block the system from running.

See Also
N/A

Sample Code
< tba >

10
MMAC_MISC_AllocAlignedBuffer

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_AllocAlignedBuffer(
MMAC_RTOS_MEMORY_POOL pool,
UI32 size,
UI8 alignment,
void **alignedBuffPtr
);

Inputs
pool The RTOS memory pool from which the memory is to be allocated.
size The size of the memory allocation required (in bytes).
alignment The byte alignment necessary. This must be a multiple of 4-bytes.
(e.g. 4 = 4 byte aligned, 8 = 8 byte aligned, 12 = 12 byte aligned, etc.)

Outputs
alignedBuffPtr Returned pointer to the byte-aligned start address of the allocated memory.

Event Notification
N/A

Return Codes
MMAC_MISC_OK
MMAC_MISC_FAIL

Description
The function provides a wrapper to the RTOS function called MMAC_RTOS_AllocMemory(). It allows
the caller to obtain an ‘alignment’ byte-aligned buffer (as some registers within the EMMA2 hardware
require addresses that are aligned to a set number of bytes).
The alignment must be a multiple of four bytes.
If the alignment specified is invalid (i.e. not a multiple of four), or if there is insufficient memory
remaining within the specified memory pool to make the allocation, the function will return
MMAC_MISC_FAIL.
If the allocation is made successfully, the function sets alignedBuffPtr to the byte-aligned address of the
start of the memory allocated, and returns MMAC_MISC_OK.
Note: It is important that memory allocated using this function is subsequently freed by calling the
function MMAC_MISC_FreeAlignedBuffer().

See Also
MMAC_MISC_FreeAlignedBuffer

Sample Code
< tba >

11
MMAC_MISC_FreeAlignedBuffer

Function Prototype
MMAC_MISC_RESULT_CODE MMAC_MISC_FreeAlignedBuffer(
void *alignedBuffPtr
);

Inputs
alignedBuffPtr Pointer to start of the aligned buffer which is to be freed. This is the same pointer
that was returned by the function MMAC_MISC_AllocAlignedBuffer().

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_MISC_OK
MMAC_MISC_FAIL

Description
The function frees an aligned buffer that was previously allocated by the function
MMAC_MISC_AllocAlignedBuffer().
If the function is passed a NULL pointer, or if the memory cannot be freed, the function returns the code
MMAC_MISC_FAIL.
If the function is able to free the memory successfully, the code MMAC_MISC_OK is returned.

See Also
N/A

Sample Code
< tba >

12
3 Data Structures

Includes

#include “mmac/misc.h”

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

typedef enum
{
MMAC_MISC_OK,
MMAC_MISC_INVALID_PARAM,
MMAC_MISC_FAIL
}MMAC_MISC_RESULT_CODE;

Cache States
The following cache states are defined:

typedef enum
{
MMAC_MISC_CACHE_DISABLE,
MMAC_MISC_CACHE_ENABLE
}MMAC_MISC_CACHE_STATE;

Fatal Error Codes

The following enum defines all available fatal errors:

typedef enum
{
MMAC_MISC_OUT_OF_MEM,
MMAC_MISC_NULL_POINTER,
MMAC_MISC_RTOS_FAILURE
}MMAC_MISC_FATAL_ERROR;

13
4 Revision History
Title: API Specification: Miscellaneous
Ref: API_MISC.doc

Date Doc API Details of change Ref.

Ver. Ver.
0.01 Initial Revision – from V3.0 EMMA 1 API M-JD
0.02 Removed MMAC_MISC_AllocateSection M-JD
2001-02-12 0.03 Added functions MMAC_MISC_AllocAlignedBuffer() and M-RV
MMAC_MISC_FreeAlignedBuffer().
2002-08-01 0.04 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.04 M-RI
2003-03-27 1.1 Corrected MMAC_MISC_GetHardwareVersion() M-MMH
2003-06-27 1.2 Doc number added. M-RJI

14