User’s Manual

EMMA2 API

Debug

Contents

1 Introduction ....................................................................................................................... 2
2 Function Prototypes .......................................................................................................... 5
MMAC_DEBUG_Initialise .............................................................................................5
MMAC_DEBUG_Level..................................................................................................6
MMAC_DEBUG_Mode .................................................................................................7
MMAC_DEBUG_Print...................................................................................................9
MMAC_DEBUG_GetChar...........................................................................................10
MMAC_DEBUG_DumpLog.........................................................................................11
MMAC_DEBUG_AddressCheck.................................................................................12
MMAC_DEBUG_ProfileStart ......................................................................................13
MMAC_DEBUG_ProfileAddUserEventType...............................................................14
MMAC_DEBUG_ProfileAddSysEventType ................................................................15
MMAC_DEBUG_ProfileAddTask................................................................................16
MMAC_DEBUG_ProfileMarkEvent.............................................................................17
MMAC_DEBUG_ProfileReport ...................................................................................18
MMAC_DEBUG_ProfileStop.......................................................................................20
MMAC_DEBUG_RenameTask...................................................................................21
3 Data Structures ............................................................................................................... 22
4 Revision History .............................................................................................................. 24

Book No: S16753EE1V0UM00 Doc No: MMAC0012, Issue: 1.2

© NEC Electronics Corporation 2002, 2003 Publication Date: 2003-06-26
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 debug driver. The MMAC debug driver allows MMAC API
users to enable/disable debugging and dynamically configure the level of debug output. All debug output
messages have a task identifier in order to facilitate multi-tasking debugging. The
MMAC_DEBUG_Print() function is semaphore protected so only one task at a time can print.

The debug driver has two modes:

Mode 1: The output is printed via printf(), this allows a user to add their own printf into a system and use
it to direct the debug output anywhere they wish. If they do not define any ‘printf’ then the standard
system ‘printf’ is used. In our case, the data is sent to the in/out window in the Greenhills MULTI
debugger. This is the default mode, MMAC_DEBUG_SERIAL must NOT be defined. The input is
performed using getchar().
Mode 2: The output is printed via MMAC_UART_Write(). This mode is enabled by compiling the
driver with MMAC_DEBUG_SERIAL defined. The input is performed using MMAC_UART_Read().
During system start up the function MMAC_DEBUG_Initialise() must be called before any debugging is
output. The function MMAC_DEBUG_Level() is used to set the level of debug output. Only levels that
are set are output, if no level is set then no debug is output, this is the default.
In Mode 2, the debug output is through one of the MMAC UART channels. The channel is set at compile
time by a define in the debug.c source file, see below. The default is MMAC_UART_1.
This means that debug is output through UART channel 1. The define can be –1, 0,1 or 2. The –1 means
that no debug channel is active, 0-2 specifies the device number for a UART channel.
The debug module keeps a circular buffer, which is used to save data in time critical sections of code that
cannot be blocked while waiting on a serial print. Data is printed to this log if MMAC_DEBUG_Print()
is called with the level set to MMAC_DEBUG_LOG. The log can be configured so that it is stops adding
data when it is full or it can be configured so that it over writes old entries when it is full.
The function MMAC_DEBUG_DumpLog() is used to print the log.
The DEBUG module provides functions to allow the user to produce profile information for sections of
application code. To enable profiling within both the OS and the application, MMAC_DEBUG_PROFILE
must be defined in the build file and the files api\debug\tcc.c and api\debug\[Link] must be included in
the build file.
The function MMAC_DEBUG_ProfileStart() is used to initiate the profiler. The function
MMAC_DEBUG_ProfileAddUserEvent() is used to register user events with the profiler. The function
MMAC_DEBUG_ProfileUpdate() can be placed throughout the application code to log the time when
these user events occur. The function MMAC_DEBUG_ProfileReport() is used to display the contents
of the profile log.
The functions MMAC_DEBUG_ProfileAddSysEvent() and MMAC_DEBUG_ProfileAddTask() are
called from within the OS providing profile information on task switching and system events.
The MMAC RTOS Interface must be initialised by calling MMAC_RTOS_Initialise() before using this
module.
To use the profiler to benchmark a section of code, do:
{
UI32 userEventId[2];
/* Start the profiler and set-up two user events */
MMAC_DEBUG_ProfileStart(MMAC_TIMER_0, 256);
MMAC_DEBUG_ProfileAddUserEvent(&userEventId[0], “Start Event”);
MMAC_DEBUG_ProfileAddUserEvent(&userEventId[1], “End Event”);
MMAC_DEBUG_ProfileUpdate(userEventId[0], param);
/* Section of Application Code to benchmark */
……

2
 MMAC_DEBUG_ProfileUpdate(userEventId[1], param2);
/* Halt the Profiler and display the results */
MMAC_DEBUG_ProfileStop();
MMAC_DEBUG_ProfileReport();
}

This example code assumes that MMAC_DEBUG_Initialise() and MMAC_RTOS_Initialise() have

already been called.

Return Codes
The meanings of the various result codes returned by the driver are described in the following table:

Result Code Description

MMAC_DEBUG_OK A DEBUG operation has successfully completed.
MMAC_DEBUG_FAIL A DEBUG operation has not completed.
MMAC_DEBUG_ALREADY_INITIALISED The DEBUG driver has already been initialised.
MMAC_DEBUG_NOT_INITIALISED The DEBUG driver has not been initialised.
MMAC_DEBUG_INVALID_SECTION The DEBUG driver has been asked to perform an
address check on an address that does not fall
inside any valid memory section.
MMAC_DEBUG_TIMER_ALREADY_OPEN The DEBUG driver’s module profiler has been
started for a timer that is already running.
MMAC_DEBUG_RESOURCE_UNAVAILABLE The DEBUG driver was unable to allocate
sufficient memory to complete the operation.
MMAC_DEBUG_EVENT_TYPES_EXHAUSTED The DEBUG driver’s module profiler is already
profiling the maximum permissible number of
tasks.
MMAC_DEBUG_PROFILE_OVERFLOW The profile buffer for a particular task has been
filled.
MMAC_DEBUG_PROFILE_NOT_STARTED The profile timer passed has not been started.
MMAC_DEBUG_PROFILE_NOT_INITIALISED The DEBUG driver has not been initialised.

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

/******************************************************************/
/* */
/* MMAC DEBUG SETUP */
/* */
/******************************************************************/

These options are:

Define Default Meaning
MMAC_DEBUG_ACCESS_ MMAC_RTOS_MAX_ The number of ticks a calling task is
CONTROL_WAIT_TIME TIMEOUT blocked waiting on this device.
MMAC_DEBUG_LOG_SIZE 100 The number of entries in the debug
log.
MMAC_DEBUG_LOG_ENTRY_ 128 The maximum size, in bytes, for each
MSG_SIZE message in the debug log.
MMAC_DEBUG_LOG_
OVERWRITE MMAC_FALSE Defines if the log is overwritten when
full.
MMAC_DEBUG_CHANNEL MMAC_UART_1 Defines the MMAC UART channel that
debug is output to when
MMAC_DEBUG_SERIAL is defined.
MMAC_DEBUG_DEFAULT_ MMAC_UART_BR_19200 Defines the default baud rate to be
BAUDRATE used with the API driver.
MMAC_DEBUG_DEFAULT_ DSI_BR_19200 Defines the default baud rate to be
DSI_BAUDRATE used with the DSI driver.

Note: The default size of the debug log is 1024 entries, each entry is approximately 140 bytes this means
that the debug log is around 140 Kbytes in size.

4
2 Function Prototypes

MMAC_DEBUG_Initialise

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_Initialise (void);

Includes
#include “mmac/debug.h”

Inputs
None.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_RESOURCE_UNAVAILABLE
MMAC_DEBUG_ALREADY_INITIALISED

Description
This function initialises the MMAC debug driver. This function must be called before any other debug
functions. If the MMAC debug port is configured in the “debug.h” header file, a MMAC_UART_Open()
call is made from this function to initialise the given port. The initialise function sets the initial DEBUG
level to be MMAC_DEBUG_NONE, the initial DEBUG mode to be MMAC_DEBUG_MODE_DEFAULT.
If the driver is already initialised then MMAC_DEBUG_ALREADY_INITIALISED is returned. If RTOS
cannot create the read or write access semaphores or the appropriate output channel cannot be configured,
MMAC_DEBUG_RESOURCE_UNAVAILABLRE. Otherwise, MMAC_DEBUG_OK is returned.

See Also
MMAC_DEBUG_Level
MMAC_DEBUG_Mode

Sample Code
< tba >

5
MMAC_DEBUG_Level

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_Level (MMAC_DEBUG_LEVEL level);

Includes
#include “mmac/debug.h”

Inputs
level The desired level of debug output.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED

Description
This function sets the required level of debug output. The possible levels are:
MMAC_DEBUG_NONE Output no debug, default.
MMAC_DEBUG_MSG General helpful output.
MMAC_DEBUG_WARN Warning of possible problem.
MMAC_DEBUG_ERROR Non fatal problem encountered.
MMAC_DEBUG_FATAL Fatal problem encountered.
MMAC_DEBUG_LOG Write message to log buffer.
MMAC_DEBUG_REPORT Test report level message.
MMAC_DEBUG_ALL Output all debug.
The level values are bit-wise fields so that any subset of the levels can be selected:
e.g.
MMAC_DEBUG_Level (MMAC_DEBUG_FATAL | MMAC_DEBUG_WARN);

If the debug access semaphore cannot be acquired then MMAC_DEBUG_FAIL is returned. If the driver is
not initialised then MMAC_DEBUG_NOT_INITIALISED is returned. Otherwise, MMAC_DEBUG_OK is
returned.

See Also
MMAC_DEBUG_Initialise

Sample Code
< tba >

6
MMAC_DEBUG_Mode

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_Mode (MMAC_DEBUG_MODE mode);

Includes
#include “mmac/debug.h”

Inputs
mode The desired mode of operation for the debug output.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_RESOURCE_UNAVAILABLE
MMAC_DEBUG_NOT_INITIALISED

Description
This function sets the mode of operation for the debug output. The possible modes of operation are:
MMAC_DEBUG_MODE_DEFAULT Default Mode.
MMAC_DEBUG_MODE_NEWLINE_OFF Turn auto-newline off.
MMAC_DEBUG_MODE_PREAMBLE_OFF Turn message preamble off.
MMAC_DEBUG_MODE_NONBLOCKING Make getchar non-blocking.
MMAC_DEBUG_MODE_RAW Output characters in raw mode.
MMAC_DEBUG_MODE_PROFILE_SINGLE_SHOT Profile Single Shot Mode.
The mode values are bit-wise fields so that any subset of the modes can be selected:
e.g.
MMAC_DEBUG_Mode (MMAC_DEBUG_MODE_PREAMBLE_OFF |
MAC_DEBUG_MODE_NEWLINE_OFF);

The default debug mode is auto-newline enable, message preamble enabled, GetChar blocking and raw
character output disabled.
When MMAC_DEBUG_MODE_RAW is selected, the current DEBUG UART channel is closed and the
DSI functions are initialised for use by the DEBUG output.
When MMAC_DEBUG_MODE_NONBLOCKING mode is selected, MMAC_DEBUG_GetChar() will
return immediately whether a character is available or not.
When MMAC_DEBUG_MODE_PROFILE_SINGLE_SHOT mode is selected, the profiler will stop once
the profile event buffer is full. If it is not selected then the profiler will wrap-around when it reaches the
end of the buffer, and any information, not yet displayed, will be lost.
If the debug access semaphore cannot be acquired or the UART channel cannot be closed, if required, then
MMAC_DEBUG_FAIL is returned. If the UART channel cannot be initialised, if required,
MMAC_DEBUG_RESOURCE_UNAVAILABLE is returned. If the driver is not initialised then
MMAC_DEBUG_NOT_INITIALISED is returned. Otherwise, MMAC_DEBUG_OK is returned.

7
See Also
MMAC_DEBUG_Initialise

Sample Code
< tba >

8
MMAC_DEBUG_Print

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_Print (
MMAC_DEBUG_LEVEL level,
I8 *format,
…
);

Includes
#include “mmac/debug.h”

Inputs
level Indicates the level of the debug message.
format The output string and formatting string, in the style of printf.
… A variable argument list, in the style of printf.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED

Description
If the level has been enabled, this function prints a debug message of the given level using the selected
method of output, or if the level is MMAC_DEBUG_LOG the data is written to the debug log in memory
instead of the debug port. This function is semaphore protected so multiple tasks can call the function.
The output string contains a task identifier.
If debug driver hasn’t been initialised then MMAC_DEBUG_NOT_INITIALISED will be returned. If the
given debug level is not active, or there is a problem acquiring the debug access semaphore, MMAC_
DEBUG_FAIL is returned. Otherwise, MMAC_DEBUG_OK is returned.

See Also
None

Sample Code
< tba >

9
MMAC_DEBUG_GetChar

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_GetChar (UI8 *ch);

Includes
#include “mmac/debug.h”

Inputs
None

Outputs
ch The character read in.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED

Description
This function is used to read input from the debug channel using the selected method of input, using
MMAC_UART_Read() or getchar(). This function will either block until a character arrives or will
return immediately if the debug mode has been set to non-blocking. The result code
MMAC_DEBUG_FAIL is returned if the [Link] is zero, or there is a problem acquiring the
debug access semaphore. Otherwise, MMAC_DEBUG_OK is returned and the data in ch is the next
character in the debug UART input buffer. In all cases unless the result code MMAC_DEBUG_OK is
returned, it should be assume that ch will be invalid. If the access semaphore cannot be obtained then
MMAC_DEBUG_FAIL is returned.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned.

See Also
MMAC_DEBUG_Mode
MMAC_DEBUG_Print

Sample Code
< tba >

10
MMAC_DEBUG_DumpLog

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_DumpLog (void);

Includes
#include “mmac/debug.h”

Inputs
None

Outputs
None

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED

Description
This function prints the debug log buffer using the selected output method. The function blocks until all
data is output. If the DEBUG driver has not been initialised then MMAC_DEBUG_NOT_INITIALISED is
returned, otherwise the return code MMAC_DEBUG_OK is returned. If there is a problem acquiring the
debug access semaphore then MMAC_DEBUG_FAIL is returned.

See Also
MMAC_DEBUG_Level

Sample Code
< tba >

11
MMAC_DEBUG_AddressCheck

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_AddressCheck (
UI32 address,
MMAC_DEBUG_ADDRESS_INFO *ainfo
);

Includes
#include “mmac/debug.h”

Inputs
address The address to be checked against the memory map.

Outputs
ainfo This points to an MMAC_DEBUG_ADDRESS_INFO structure.
This structure is used to pass out the following parameters:
sectionStartAddress Start address of the section containing address.
sectionEndAddress End address of the section containing address.
sectionName Name of the section containing address.
sectionFlags Section Flags:
Flag Description
MMAC_DEBUG_SECTION_NONE Not located in a valid section.
MMAC_DEBUG_SECTION_TEXT Location in a text section.
MMAC_DEBUG_SECTION_DATA Location in a data section.
MMAC_DEBUG_SECTION_BSS Location in a BSS section.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_INVALID_SECTION

Description
This function is used to check the supplied address against the current memory map that is in use. The
function calculates which section of the memory map the address falls into and then puts the information
into the data structure MMAC_DEBUG_ADDRESS_INFO.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the access
semaphore cannot be obtained then MMAC_DEBUG_FAIL is returned. If the address falls outside any
valid section, then MMAC_DEBUG_INVALID_SECTION is returned.

See Also
None.

Sample Code
< tba >

12
MMAC_DEBUG_ProfileStart

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileStart (
MMAC_TIMER_DEV_NUM timer,
UI32 profileSize
);

Includes
#include “mmac/debug.h”

Inputs
timer The ID of the timer to use for the periodic interrupt.
Must be either MMAC_TIMER_0 or MMAC_TIMER_1.
profileSize The size of the profile buffer.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_TIMER_ALREADY_OPEN
MMAC_DEBUG_RESOURCE_UNAVAILABLE

Description
This function is used to start the DEBUG module profiler. The function starts the timer timer and allocates
a buffer area with profileSize entries to store the profile events. The only Profile functions that can be used
before MMAC_DEBUG_ProfileStart() has been called are MMAC_DEBUG_ProfileAddSysEvent
Type() and MMAC_DEBUG_ProfileAddTask(). Whenever this function is called, the profile buffer is
reset.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the access
semaphore cannot be obtained then MMAC_DEBUG_FAIL is returned. If the timer is already in use then
MMAC_DEBUG_TIMER_ALREADY_OPEN is returned. If RTOS cannot allocate enough memory for the
profile information, or the idle task stack, or cannot create or resume the idle task,
MMAC_DEBUG_RESOURCE_UNAVAILABLE is returned.

See Also
MMAC_TIMER_Open

Sample Code
< tba >

13
MMAC_DEBUG_ProfileAddUserEventType

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileAddUserEventType (
UI32 *id,
char *name
);

Includes
#include “mmac/debug.h”

Inputs
name This is the name of the user event type.

Outputs
id This is a unique value generated by DEBUG used to identify the event type.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_EVENT_TYPES_EXHAUSTED
MMAC_DEBUG_PROFILE_NOT_INITIALISED

Description
This function is used to register a particular type of user event with the profiler. The event type called
name is given a unique id, which is used when calling the MMAC_DEBUG_ProfileUpdate function. User
events have ID values ranging from 0xFF800000 to 0xFFFFFFFF.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the access
semaphore cannot be obtained then MMAC_DEBUG_FAIL is returned. If the profiler has not been
initialised, MMAC_DEBUG_PROFILE_NOT_INITIALISED is returned. If the event buffer is full then
MMAC_DEBUG_EVENT_TYPES_EXHAUSTED is returned.

See Also
None.

Sample Code
< tba >

14
MMAC_DEBUG_ProfileAddSysEventType

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileAddSysEventType (
UI32 id,
char *name
);

Includes
#include “mmac/debug.h”

Inputs
id This is a unique value used to identify a system event type.
name This is the name of the event type.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_EVENTS_EXHAUSTED

Description
This function is used to register a particular type of system event with the profiler. The event type called
name is associated with the user-supplied id. This id is used when calling the
MMAC_DEBUG_ProfileUpdate function. This function is called from within the OS kernel and should
not be required by the user. System events have ID values ranging from 0xFF000000 to 0xFF7FFFFF.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the event
buffer is full then MMAC_DEBUG_EVENTS_EXHAUSTED is returned.

See Also
None.

Sample Code
< tba >

15
MMAC_DEBUG_ProfileAddTask

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileAddTask (
UI32 id,
UI32 priority,
char *name
);

Includes
#include “mmac/debug.h”

Inputs
id This is a unique value used to identify a task.
priority This is the priority of the task.
name This is the name of the task.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_EVENT_TYPES_EXHAUSTED

Description
This function is used to register a particular task with the profiler. The task called name is associated with
the supplied task id. This id is used when calling the MMAC_DEBUG_ProfileUpdate function. This
function is called from within the OS kernel and should not be required by the user. Tasks are identified
by id less than 0xFF000000.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the event
buffer is full then MMAC_DEBUG_EVENT_TYPES_EXHAUSTED is returned.

See Also
None.

Sample Code
< tba >

16
MMAC_DEBUG_ProfileMarkEvent

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileMarkEvent (
UI32 id,
UI32 param
);

Includes
#include “mmac/debug.h”

Inputs
id This identifies a unique event already set-up using MMAC_DEBUG_ProfileAddEvent.
param This parameter is added to the profile buffer.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_PROFILE_OVERFLOW
MMAC_DEBUG_PROFILE_NOT_STARTED

Description
This function is used to record the time that a particular event or task switch occurred relative to the
profile timer. Each time this function is called, a new entry is added to the profile buffer. The profile
buffer entries contain the ID of the event, the time the event occurred and the value of param.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the profiler
has not been started, MMAC_DEBUG_PROFILE_NOT_STARTED is returned. If the access semaphore
cannot be obtained then MMAC_DEBUG_FAIL is returned. If the profile buffer is full on completion of
the update command then MMAC_DEBUG_PROFILE_OVERFLOW is returned and the buffer pointer is
reset to zero. (Note: further updates will cause data to be lost.)

See Also
MMAC_DEBUG_ProfileAddUserEventType
MMAC_DEBUG_ProfileAddSysEventType
MMAC_DEBUG_ProfileAddTask

Sample Code
< tba >

17
MMAC_DEBUG_ProfileReport

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileReport (void);

Includes
#include “mmac/debug.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_PROFILE_NOT_INITIALISED

Description
This function is used to display the collected profile information. The display produced is of the following
format:
++++MMAC_PROFILE_START_INDICATOR_STRING++++
6
Task_1 80234BFC 50 1 0 0
Task_2 80240F54 60 2 0 0
Semaphore_Create FF000002 0 1 0 0
Semaphore_Acquire FF000004 0 2 0 0
First_User_Event FFFF0000 0 1 0 0
Second_User_Event FFFF0001 0 1 0 0
8
0 80240F54 150 1
1 FF000002 205 0
2 FF000004 270 0
3 FFFF0000 515 FF
4 80234BFC 625 0
5 FF000004 630 0
6 80240F54 795 0
7 FFFF0001 815 2A

The Profile start indicator string is followed by the event information and the profile information. The
event information consists of the number of events and tasks followed by details of each event; the event
name, the event ID, the priority, the number of times it occurred, the stack size and the minimum stack size.
The profile information consists of the number of profile entries followed by details of each profile entry;
the entry number, the event ID, the number of milliseconds since the profiler started and a user supplied
parameter.
This information can be written to a .txt. file and then fed into the profile application to generate a profile
graph.
If the profiler is being operated in MMAC_DEBUG_MODE_PROFILE_SINGLE_STEP mode then
displaying the profile report automatically resets the profiler to the start of the buffer, and profiling starts

18
again. If continuous mode is in use it is recommended that the profiler is stopped using
MMAC_DEBUG_ProfileStop() before displaying the report.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the access
semaphore cannot be obtained then MMAC_DEBUG_FAIL is returned. If the profiler has not been started,
MMAC_DEBUG_PROFILE_NOT_STARTED is returned.

See Also
None.

Sample Code
< tba >

19
MMAC_DEBUG_ProfileStop

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_ProfileStop (void);

Includes
#include “mmac/debug.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL
MMAC_DEBUG_NOT_INITIALISED
MMAC_DEBUG_PROFILE_NOT_STARTED

Description
This function is used to stop the DEBUG module profiler. The function stops the timer but leaves the
profile buffer area intact. MMAC_DEBUG_ProfileUpdate() cannot be called after a stop command, but
all other profile commands can.
If the debug driver hasn’t been initialised, MMAC_DEBUG_NOT_INITIALISED is returned. If the access
semaphore cannot be obtained then MMAC_DEBUG_FAIL is returned. If the profiler has not been
initialised, MMAC_DEBUG_PROFILE_NOT_INITIALISED is returned.

See Also
None.

Sample Code
< tba >

20
MMAC_DEBUG_RenameTask

Function Prototype
MMAC_DEBUG_RESULT_CODE MMAC_DEBUG_RenameTask (UI32 id, UI8 *name);

Includes
#include “mmac/debug.h”

Inputs
id Task Id of task to rename
name: The new name to be given to the task, within the profiling system.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_DEBUG_OK
MMAC_DEBUG_FAIL

Description
This function is used to rename a task within the profiling system. The MMAC_RTOS API automatically
assigns names to tasks so this can be used to give a more meaningful name to a task so that when a profile
is generated the more useful task names can be used to aid in the profile analysis.
If tid is invalid then MMAC_DEBUG_FAIL is returned.

See Also
None.

Sample Code
< tba >

21
3 Data Structures

Includes

#include “mmac/debug.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_DEBUG_OK,
MMAC_DEBUG_FAIL,
MMAC_DEBUG_ALREADY_INITIALISED,
MMAC_DEBUG_NOT_INITIALISED,
MMAC_DEBUG_INVALID_SECTION,
MMAC_DEBUG_TIMER_ALREADY_OPEN,
MMAC_DEBUG_RESOURCE_UNAVAILABLE,
MMAC_DEBUG_EVENT_TYPES_EXHAUSTED,
MMAC_DEBUG_PROFILE_OVERFLOW,
MMAC_DEBUG_PROFILE_NOT_STARTED,
MMAC_DEBUG_PROFILE_NOT_INITIALISED
}MMAC_DEBUG_RESULT_CODE;

Debug Levels
The following debug levels are defined.

typedef enum
{
MMAC_DEBUG_NONE = 0x00,
MMAC_DEBUG_MSG = 0x01,
MMAC_DEBUG_WARN = 0x02,
MMAC_DEBUG_ERROR = 0x04,
MMAC_DEBUG_FATAL = 0x08,
MMAC_DEBUG_LOG = 0x10,
MMAC_DEBUG_REPORT = 0x20,
MMAC_DEBUG_ALL = 0xFF
}MMAC_DEBUG_LEVEL;

Debug Modes
The following debug modes are defined.

typedef enum
{
MMAC_DEBUG_MODE_DEFAULT = 0x00,
MMAC_DEBUG_MODE_NEWLINE_OFF = 0x01,
MMAC_DEBUG_MODE_PREAMBLE_OFF = 0x02,
MMAC_DEBUG_MODE_NONBLOCKING = 0x04,
MMAC_DEBUG_MODE_RAW = 0x08,
MMAC_DEBUG_MODE_PROFILE_SINGLE_SHOT = 0x10
}MMAC_DEBUG_MODE;

22
Section Flags
typedef enum
{
MMAC_DEBUG_SECTION_NONE = 0x00,
MMAC_DEBUG_SECTION_TEXT = 0x20,
MMAC_DEBUG_SECTION_DATA = 0x40,
MMAC_DEBUG_SECTION_BSS = 0x80
}MMAC_DEBUG_SECTION_FLAGS;

Address Information

typedef struct
{
UI32 sectionStartAddress;
UI32 sectionEndAddress;
UI32 sectionFlags;
UI8 sectionName[8];
}MMAC_DEBUG_ADDRESS_INFO;

Debug Pins
These macros are used to toggle hardware pins on Emma so they can be used as a simple debug output.

#ifndef _hwfuart_h_
#include “mmac/hardware/hwfuart.h”
#endif

#define DEBUG_BIT(x) (x) ? emmaFastUART.PFUR_MCR &= 0x12 :

emmaFastUART.PFUR_MCR |= 0x01
#define DEBUG_BIT0(x) (x) ? emmaFastUART.PFUR_MCR &= 0x12 :
emmaFastUART.PFUR_MCR |= 0x01
#define DEBUG_BIT1(x) (x) ? emmaFastUART.PFUR_MCR &= 0x11 :
emmaFastUART.PFUR_MCR |= 0x02

23
4 Revision History
Title: API Specification: Debug
Ref: API_Debug.doc

Date Doc API Details of change Ref.

Ver. Ver.
2000-07-19 0.01 Initial Revision – from V3.0 EMMA 1 API.
2002-08-08 0.02 Doc reformatted. M-RJI
2002-10-01 0.03 Removed device applicability, modes supported and M-RKL
architectural overview sections.
2002-12-09 1.0 For release – same as v0.03. M-RJI
2003-03-26 1.1 Fixed function name for MMAC_DEBUG_RenameTask. M-NI
2003-06-26 1.2 Doc number added. M-RJI

24