User’s Manual

EMMA2 API

RTOS Interface

CONTENTS

1 Introduction ....................................................................................................................... 3
1.1 Purpose ................................................................................................................ 3
1.2 Scope ................................................................................................................... 3
1.3 Definitions ............................................................................................................. 4
1.4 References ........................................................................................................... 4
2 Architecture....................................................................................................................... 5
3 Function Prototypes .......................................................................................................... 7
MMAC_RTOS_Initialise ................................................................................................7
MMAC_RTOS_Close....................................................................................................8
MMAC_RTOS_CreateSemaphore ...............................................................................9
MMAC_RTOS_InitSemaphore....................................................................................10
MMAC_RTOS_DeleteSemaphore..............................................................................11
MMAC_RTOS_AcquireSemaphore ............................................................................12
MMAC_RTOS_ReleaseSemaphore ...........................................................................13
MMAC_RTOS_SemaphoreCount...............................................................................14
MMAC_RTOS_Sleep..................................................................................................15
MMAC_RTOS_GetTickPeriod ....................................................................................16
MMAC_RTOS_GetTick...............................................................................................17
MMAC_RTOS_SetTick ...............................................................................................18
MMAC_RTOS_CreateMemoryPool............................................................................19
MMAC_RTOS_DeleteMemoryPool ............................................................................20
MMAC_RTOS_AllocMemory ......................................................................................21
MMAC_RTOS_FreeMemory.......................................................................................22
MMAC_RTOS_AllocMemorySection ..........................................................................23
MMAC_RTOS_FreeMemorySection ..........................................................................24
MMAC_RTOS_CreateMessageQueue.......................................................................25

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

© 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_RTOS_ResetMessageQueue ........................................................................26
MMAC_RTOS_DeleteMessageQueue .......................................................................27
MMAC_RTOS_SendMessageQueue .........................................................................28
MMAC_RTOS_ReceiveMessageQueue ....................................................................29
MMAC_RTOS_InstallInterruptHandler .......................................................................30
MMAC_RTOS_GetInterruptMask ...............................................................................31
MMAC_RTOS_SetInterruptMask ...............................................................................32
MMAC_RTOS_DisableInterrupts................................................................................33
MMAC_RTOS_EnableInterrupts ................................................................................34
MMAC_RTOS_TaskCreate ........................................................................................35
MMAC_RTOS_TaskStart............................................................................................36
MMAC_RTOS_TaskStop............................................................................................37
MMAC_RTOS_GetTaskId ..........................................................................................38
MMAC_RTOS_TaskDestroy.......................................................................................39
MMAC_RTOS_CurrentTaskId ....................................................................................40
MMAC_RTOS_SetTaskPriority...................................................................................41
MMAC_RTOS_Reboot ...............................................................................................42
MMAC_RTOS_Wait....................................................................................................43
MMAC_RTOS_WakeUp .............................................................................................44
MMAC_RTOS_ProcessMask .....................................................................................45
MMAC_RTOS_IsWakeUpPending .............................................................................46
MMAC_RTOS_AttachTaskMemory............................................................................47
MMAC_RTOS_RetrieveTaskMemory.........................................................................48
MMAC_RTOS_EnableTaskPreemption .....................................................................49
MMAC_RTOS_TimerCreate .......................................................................................50
MMAC_RTOS_TimerDelete .......................................................................................52
MMAC_RTOS_TimerCntrl ..........................................................................................53
MMAC_RTOS_EventCreate .......................................................................................54
MMAC_RTOS_EventDelete .......................................................................................55
MMAC_RTOS_EventRetrieve ....................................................................................56
MMAC_RTOS_SetEvent ............................................................................................57
4 Data Structures ............................................................................................................... 58
5 Revision History .............................................................................................................. 62

2
1 Introduction

1.1 Purpose

This document defines the RTOS independent interface provided for use by the MMAC drivers.

1.2 Scope

This document defines a set of ‘C’ functions that are used to abstract a set of operating system services:
• Semaphores
• Time
• Memory
• Message Queues
• Interrupt Handling
The interface meets all the requirements defined in [1]
The API for each RTOS service is defined in terms of a set of functions.
The return code from all driver functions indicates success or failure of the operation. The driver functions
always return the value 0 on success and > 0 on failure. The actual value of the return code indicates the
error.
A standard naming convention has been adopted for function names:
MMAC_RTOS_YyyyZzzz();
where:
YyyyZzzz = operation
e.g.
MMAC_RTOS_CreateSemaphore();
A standard naming convention has been adopted for return code types:
MMAC_XXXX_RESULT_CODE;
where:
XXXX = RTOS service
e.g.
MMAC_RTOS_MEMORY_RESULT_CODE

3
A standard set of base types are defined for the RTOS Interface in order to facilitate portability:

MMAC Base ANSI Base Type No. of Bits Range Alignment

Type
I8 signed char 8 -27 to 27-1 8
8
UI8 unsigned char 8 0 to 2 -1 8
15 15
I16 short int 16 -2 to 2 -1 16
16
UI16 unsigned short int 16 0 to 2 -1 16
31 31
I32 int 32 -2 to 2 -1 32
32
UI32 unsigned int 32 0 to 2 -1 32
63 63
I64 long long 64 -2 to 2 -1 64
64
UI64 unsigned long long 64 0 to 2 -1 64

A further set of MMAC extended types are defined:

Extended Type Type No. of Bits Range Alignment

MMAC_BOOL UI8 8 MMAC_FALSE 8
and
MMAC_TRUE

The MMAC base and extended types are defined in the file “mmac/types.h”.

1.3 Definitions

MMAC MultiMedia Applications Centre

RTOS Real Time Operating System

1.4 References

[1] MMAC RTOS Interface Requirements.

4
2 Architecture
The RTOS Interface API provides an RTOS independent set of routines for managing system functions
such as message queues, memory allocation, time, timers, semaphores and interrupt control.

Initialisation
The RTOS Interface API requires initialisation to establish internal data structures and install the system-
wide interrupt handler.
Several RTOS modules require that MMAC_RTOS_Initialise() be called before using them.
The initialisation process allocates the RTOS system heap to a defined section from the memory layout file,
which can then be accessed with the RTOS memory manipulation functions.
The RTOS system heap is used by the MMAC API for ALL memory allocations. The heap can be used to
allocate partitions or other memory pools, in either cached or non-cached memory.
To close the RTOS Interface, call MMAC_RTOS_Close() which releases the internal data storage, and
disables the interrupt service routine.

Semaphores
Semaphores are used to perform task synchronisation. The function MMAC_RTOS_CreateSemaphore()
is called to create and initialise a counting semaphore. A semaphore must be created before it can be used.
The function MMAC_RTOS_AcquireSemaphore() causes a task to block on a semaphore if the
semaphore’s value is zero. The task blocks until another task releases the semaphore. If the semaphore’s
value is greater than zero the value is decrement and the semaphore is acquired.
The function MMAC_RTOS_ReleaseSemaphore() increments the value of a semaphore. If tasks are
blocking on the semaphore then the task with the highest priority is scheduled to run.

Message Queues
Message queues are used to pass messages between tasks. Message queues are of fixed length and each
queue supports fixed length messages only. The length of the messages is defined when the queue is
created.
The system can manage a finite number of queues. The number of queues supported is defined in
MMAC_RTOS_MAX_QUEUES. A message queue must be created before a message can be sent, using
MMAC_RTOS_CreateMessageQueue().A message is sent on the queue using MMAC_RTOS_
SendMessageQueue() and received using MMAC_RTOS_ReceiveMessageQueue(). A message queue
may be reset, in which case all entries are discarded, by a call to MMAC_RTOS_ResetMessageQueue().
The routine MMAC_RTOS_Initialise() must be called prior to using any of the message queue functions.

Memory
Memory is allocated by first creating a pool using MMAC_RTOS_CreateMemoryPool(), then allocating
portions from the pool using MMAC_RTOS_AllocMemory(). To release memory back to the pool the
function MMAC_RTOS_FreeMemory() is used. Memory pools are deleted by calling MMAC_RTOS_
DeleteMemoryPool().

Interrupt Handling
The interrupt handling API calls provides a means to install interrupt handlers for specific EMMA devices
using MMAC_RTOS_InstallInterruptHandler(). Masking and unmasking interrupts is done using
MMAC_RTOS_SetInterruptMask(), and their state read by calling MMAC_RTOS_
GetInterruptMask().
It is essential to have made a call to MMAC_RTOS_Initialise() before using any of the interrupt API
calls.

5
Application Timers
RTOS provides programmable timers for applications. These timers execute a specific user-supplied
routine when they expire. More than one timer may expire at the same time and in order to service all the
expired timers in timely fashion, self-suspension requests are not allowed. Additionally, processing should
be kept to a minimum.

Ticks
A tick is the basic unit of time for all RTOS timer facilities. Each tick corresponds to a single hardware
timer interrupt. The amount of actual time a tick represents is user-programmable.

Margin of Error
A timer request may be satisfied as much as one tick early in actual time. This is because a tick can occur
immediately after the timer request. Therefore, the first tick of a timer request represents an actual time
ranging from zero to the rate of the hardware timer interrupt. For example, the amount of actual time
expired for a request of n ticks falls between the actual time n and n-1 ticks represent.

Re-Scheduling
When a timer expires, the prescribed expiration routine is executed. After execution is complete, the timer
is either dormant or rescheduled depending on the mode of operation. If the timer’s mode of operation is
‘single shot’, it is dormant after the initial expiration. However, if the timer’s mode of operation is
‘continuous’, it is rescheduled to expire at that interval.

Enable/Disable
Timers are enabled and disabled dynamically.

Dynamic Creation
RTOS application timers are created and deleted dynamically. There is no preset limit on the number of
timers an application may have. Each timer requires a control block. The memory for this is allocated by
the RTOS.

Determinism
Processing time required to create/enable/disable application timers is constant. However, processing time
required to execute the user-supplied expiration routines depends on the expiration routines themselves
and the number of timers they expire simultaneously.

6
3 Function Prototypes

MMAC_RTOS_Initialise

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_Initialise( void );

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_ALREADY_INITIALISED

Description
Initialises internal structures used by other RTOS functions. This routine should be called before using any
other RTOS functions. It installs an interrupt handler to which user defined handlers can be attached using
MMAC_RTOS_InstallInterruptHandler().
A system heap is created as a memory pool, and the pointer to the pool is stored in RTOS_systemHeap, it
must be positioned by defining the section MMAC_SECTION_RTOS_HEAP in the system link file, giving
it an address and a size, e.g.
MMAC_SECTION_RTOS_HEAP 0x8000000 pad(0x100000 ):

The RTOS can only be initialised once, otherwise the value MMAC_RTOS_ALREADY_INITIALISED is
returned. If memory cannot be allocated, the result MMAC_RTOS_FAIL is returned.

See Also
MMAC_RTOS_Close

Sample Code
< tba >

7
MMAC_RTOS_Close

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_Close(void);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_ALREADY_CLOSED

Description
Closes and de-allocates internal structures used by the RTOS functions. This routine should be called
before using any other RTOS functions. It also deactivates the interrupt handler, and de-allocates the
system heap.
If an attempt to close the RTOS is made having not initialised it, the value MMAC_RTOS_ALREADY_
CLOSED is returned.

See Also
MMAC_RTOS_Close

Sample Code
< tba >

8
MMAC_RTOS_CreateSemaphore

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_CreateSemaphore(
I8 *name,
UI32 count,
MMAC_RTOS_SEMAPHORE *semaphoreId
);

Includes
#include “mmac/rtos.h”

Inputs
name A symbolic name for the semaphore, up to MMAC_RTOS_NAME_LEN bytes.
count The initial count value for the semaphore.

Outputs
semaphoreId A pointer to a unique semaphore identifier.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Creates a counting semaphore. The value MMAC_RTOS_OK is returned if the semaphore is successfully
created, otherwise the value MMAC_RTOS_FAIL is returned.

See Also
MMAC_RTOS_DeleteSemaphore
MMAC_RTOS_AcquireSemaphore
MMAC_RTOS_ReleaseSemaphore

Sample Code
< tba >

9
MMAC_RTOS_InitSemaphore

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_InitSemaphore(
MMAC_RTOS_SEMAPHORE semaphoreId,
UI32 count
);

Includes
#include “mmac/rtos.h”

Inputs
semaphoreId A pointer to a unique semaphore identifier.
count The initial count value for the semaphore.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Initialises the semaphore semaphoreId to the value count.

See Also
MMAC_RTOS_DeleteSemaphore
MMAC_RTOS_AcquireSemaphore
MMAC_RTOS_ReleaseSemaphore

Sample Code
< tba >

10
MMAC_RTOS_DeleteSemaphore

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_DeleteSemaphore(
MMAC_RTOS_SEMAPHORE semaphoreId
);

Includes
#include “mmac/rtos.h”

Inputs
semaphoreId The identifier of the semaphore to be deleted.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_UNKNOWN_ID

Description
Deletes a semaphore. The value MMAC_RTOS_OK is returned if the semaphore is successfully deleted. If
the semaphoreId is not valid the value MMAC_RTOS_UNKNOWN_ID is returned.

See Also
MMAC_RTOS_CreateSemaphore
MMAC_RTOS_AcquireSemaphore
MMAC_RTOS_ReleaseSemaphore

Sample Code
< tba >

11
MMAC_RTOS_AcquireSemaphore

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_AcquireSemaphore(
MMAC_RTOS_SEMAPHORE semaphoreId,
UI32 timeout
);

Includes
#include “mmac/rtos.h”

Inputs
semaphoreId The identifier of the semaphore to be acquired.
timeout The number of system ticks before the semaphore acquire operation times out.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_UNKNOWN_ID

Description
Acquires a semaphore. The function blocks until the semaphore is acquired, or the timeout occurs. A
timeout value of MMAC_RTOS_SUSPEND means that the function blocks indefinitely. The value
MMAC_RTOS_OK is returned if the semaphore is successfully acquired. If the semaphoreId is not valid
the value MMAC_RTOS_UNKNOWN_ID is returned. If the acquire operation fails due to a timeout the
value MMAC_RTOS_FAIL is returned.

See Also
MMAC_RTOS_CreateSemaphore
MMAC_RTOS_DeleteSemaphore
MMAC_RTOS_ReleaseSemaphore

Sample Code
< tba >

12
MMAC_RTOS_ReleaseSemaphore

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_ReleaseSemaphore(
MMAC_RTOS_SEMAPHORE semaphoreId
);

Includes
#include “mmac/rtos.h”

Inputs
semaphoreId The identifier of the semaphore to be released.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_UNKNOWN_ID

Description
Releases a semaphore allowing tasks waiting on the semaphore to be dispatched by the operating system.
The value MMAC_RTOS_OK is returned if the semaphore is successfully released. If the semaphoreId is
not valid the value MMAC_RTOS_UNKNOWN_ID is returned.

See Also
MMAC_RTOS_CreateSemaphore
MMAC_RTOS_DeleteSemaphore
MMAC_RTOS_AcquireSemaphore

Sample Code
< tba >

13
MMAC_RTOS_SemaphoreCount

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SemaphoreCount(
MMAC_RTOS_SEMAPHORE semaphoreId,
I32 *count
);

Includes
#include “mmac/rtos.h”

Inputs
semaphoreId The identifier of the semaphore to be released.

Outputs
count The current value of semaphore count.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Examines the current state of the specified semaphore. If the semaphoreId is not valid the value
MMAC_RTOS_UNKNOWN_ID is returned, otherwise the value MMAC_RTOS_OK is returned. If no tasks
are waiting for the semaphore, then count returns the “true” semaphore count value (0 or positive number).
If there is one or more tasks waiting for the semaphore, then count will have the value of –1.

See Also
MMAC_RTOS_CreateSemaphore
MMAC_RTOS_AcquireSemaphore
MMAC_RTOS_ReleaseSemaphore

Sample Code
< tba >

14
MMAC_RTOS_Sleep

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_Sleep(UI32 ticks);

Includes
#include “mmac/rtos.h”

Inputs
ticks The number of system ticks to sleep.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
Suspends the calling task for ticks system ticks. Always returns MMAC_RTOS_OK.
The number of milliseconds per tick is defined by MMAC_RTOS_MSEC_PER_TICK in mmac_config.h.

See Also
N/A

Sample Code
< tba >

15
MMAC_RTOS_GetTickPeriod

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_GetTickPeriod(UI32 *uSecs);

Includes
#include “mmac/rtos.h”

Inputs
uSecs A pointer to a UI32 into which the current system tick period is copied.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
This function returns the current system tick period, MMAC_RTOS_OK is always returned.
The system tick period is in units of micro-seconds.

See Also
MMAC_RTOS_SetTickPeriod

Sample Code
< tba >

16
MMAC_RTOS_GetTick

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_GetTick(UI32 *ticks);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
ticks Current system tick value.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
Used to read the current RTOS tick timer value. Always returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_SetTick

Sample Code
< tba >

17
MMAC_RTOS_SetTick

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SetTick(UI32 ticks);

Includes
#include “mmac/rtos.h”

Inputs
ticks New system tick value.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
Used to set the current RTOS tick timer value. Always returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_SetTick

Sample Code
< tba >

18
MMAC_RTOS_CreateMemoryPool

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_CreateMemoryPool(
I8 *name,
void* startAddress,
UI32 size,
UI32 minBlockSize,
MMAC_RTOS_MEMORY_POOL *pool
);

Includes
#include “mmac/rtos.h”

Inputs
name A symbolic name for the memory pool, up to MMAC_RTOS_NAME_LEN bytes.
startAddress The start address for the memory pool.
size The size of the memory pool.
minBlockSize The size of the smallest block, in bytes, that can be allocated from the pool.

Outputs
pool A pointer to the memory pool.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_MEMORY_EXHAUSTED
MMAC_RTOS_NOT_INITIALISED

Description
Allocates a memory pool of a given size from which blocks of memory, at least of size minBlockSize, can
be allocated. If a memory pool is successfully created MMAC_RTOS_OK is returned. Otherwise, if no
memory exists MMAC_RTOS_MEMORY_EXHAUSTED is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_DeleteMemoryPool

Sample Code
< tba >

19
MMAC_RTOS_DeleteMemoryPool

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_DeleteMemoryPool(
MMAC_RTOS_MEMORY_POOL pool
);

Includes
#include “mmac/rtos.h”

Inputs
pool An identifier for the memory pool.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED

Description
Deletes a memory pool from the system. The value MMAC_RTOS_MEMORY_OK is returned if the
memory pool is successfully deleted. Otherwise, the value MMAC_RTOS_MEMORY_FAIL is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_MEMORY_NOT_INITIALISED
is returned.

See Also
MMAC_RTOS_CreateMemoryPool

Sample Code
< tba >

20
MMAC_RTOS_AllocMemory

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_AllocMemory(
MMAC_RTOS_MEMORY_POOL pool,
UI32 size,
void **memoryBlock
);

Includes
#include “mmac/rtos.h”

Inputs
pool An identifier for the memory pool.
size The size of the memory pool block to allocate.

Outputs
memoryBlock A pointer to the memory block.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_MEMORY_EXHAUSTED
MMAC_RTOS_NOT_INITIALISED

Description
Allocates a block of memory from a memory pool. If memory is available from the memory pool
MMAC_RTOS_OK is returned. If no memory is available the task will either block or return immediately,
with the value MMAC_RTOS_MEMORY_EXHAUSTED, depending on the value of the macro
MMAC_RTOS_MEMORY_BLOCKING defined in the file rtos.h.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_FreeMemory

Sample Code
< tba >

21
MMAC_RTOS_FreeMemory

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_FreeMemory (
void *memoryBlock
);

Includes
#include “mmac/rtos.h”

Inputs
memoryBlock A pointer to the memory block to free.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED

Description
Returns a memory block to its memory pool. If the memory is successfully freed the value MMAC_RTOS_
OK is returned. Otherwise, MMAC_RTOS_FAIL is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_AllocMemory

Sample Code
< tba >

22
MMAC_RTOS_AllocMemorySection

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_AllocMemorySection (
UI32 size,
MMAC_BOOL cached,
UI8 **address,
UI32 alignment
);

Includes
#include "mmac/mmac_config"
#include “mmac/rtos.h”

Inputs
size The size of the memory section to allocate
cached If this value is true the memory section is allocated from a cached section,
otherwise from a non-cached section.
alignment Specify the alignment of the memory section.

Outputs
address A pointer to a UI8 pointer is return as the start address to the memory section.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_NO_AVAILABLE_MEMORY

Description
This function is used to allocate a memory section for use by the API. A memory section of size size is
allocated from the RTOS system heap, using MMAC_RTOS_AllocMemory. The memory address is
allocated to the given alignment. The address is then converted to a cached address if cached is
MMAC_TRUE, otherwise it is converted to a non-cached address. The start address of the memory section
is then returned in *address.
The API can use these memory sections for various uses including creating new memory pools.
Note:
1. The system designer must make sure that the MMAC RTOS system heap is big enough to
accommodate all memory sections allocated from it.
2. Memory sections should normally only be allocated once at the start of day and should NOT normally
be “freed”.

See Also
MMAC_RTOS_FreeMemorySection

Sample Code
< tba >

23
MMAC_RTOS_FreeMemorySection

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_FreeMemorySection ( UI8 *address );

Includes
#include "mmac/mmac_config"
#include “mmac/rtos.h”

Inputs
address The address of the section to free (previously return by AllocMemorySection).

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_NO_AVAILABLE_MEMORY

Description
This function is used to free a memory section previously allocated by MMAC_RTOS_AllocMemory
Section

See Also
N/A

Sample Code
< tba >

24
MMAC_RTOS_CreateMessageQueue

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_CreateMessageQueue (
I8 *name,
UI16 maxElements,
UI16 elementSize,
MMAC_RTOS_MSG_QUEUE *msgQueueId
);

Includes
#include “mmac/rtos.h”

Inputs
name A symbolic name for the message queue,up to MMAC_RTOS_NAME_LEN bytes
maxElements Maximum number of entries in queue.
elementSize The number of UI32s (4 bytes) making up each entry.

Outputs
msgQueueId A pointer to a unique message queue identifier.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED

Description
Creates a message queue. If the queue is created successfully the value MMAC_RTOS_OK is returned.
Otherwise the value MMAC_RTOS_FAIL is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_DeleteMessageQueue
MMAC_RTOS_ResetMessageQueue
MMAC_RTOS_SendMessageQueue
MMAC_ROTS_ReceiveMessageQueue

Sample Code
< tba >

25
MMAC_RTOS_ResetMessageQueue

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_ResetMessageQueue(
MMAC_RTOS_MSG_QUEUE msgQueueId
);

Includes
#include “mmac/rtos.h”

Inputs
msgQueueId A pointer to the message queue identifier.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED

Description
Resets the message queue identified by msgQueueId. This operation will discard all messages currently in
the queue specified by msgQueueId. All tasks suspended on the queue will be resumed (see
MMAC_RTOS_ReceiveMessageQueue() and MMAC_RTOS_ReceiveMessageQueue() function calls).
If the queue reset operation was successful, then MMAC_RTOS_OK is returned, otherwise
MMAC_RTOS_FAIL.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_SendMessageQueue
MMAC_RTOS_ReceiveMessageQueue

Sample Code
< tba >

26
MMAC_RTOS_DeleteMessageQueue

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_DeleteMessageQueue(
MMAC_RTOS_MSG_QUEUE msgQueueId
);

Includes
#include “mmac/rtos.h”

Inputs
msgQueueId The message queue identifier of the message queue to be deleted.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED

Description
Deletes a message queue. If the queue is successfully deleted the value MMAC_RTOS_OK is returned.
Otherwise, the value MMAC_RTOS_FAIL is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_ NOT_INITIALISED is returned.

See Also
MMAC_RTOS_CreateMessageQueue

Sample Code
< tba >

27
MMAC_RTOS_SendMessageQueue

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SendMessageQueue(
MMAC_RTOS_MSG_QUEUE msgQueueId,
UI32 timeout,
void *msg ,
MMAC_BOOL priority
);

Includes
#include “mmac/rtos.h”

Inputs
msgQueueId A pointer to the message queue identifier.
timeout The number of system ticks before the message queue send operation times out.
msg A pointer to the message to send.
priority If MMAC_TRUE then the message is sent to the front of the queue.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_QUEUE_RESET
MMAC_RTOS_NOT_INITIALISED

Description
Sends a message on the given message queue. The send waits up to timeout system ticks attempting to
send the message. If timeout is MMAC_RTOS_SUSPEND the calling task is blocked forever or until the
send is complete.
If the message is successfully sent the value MMAC_RTOS_OK is returned. Otherwise, the value MMAC_
RTOS_FAIL is returned.
If priority is MMAC_TRUE then the message is sent to the front of the given queue.
The message is copied, so as soon as the send call returns the message can be deleted. If the queue has
been reset by a call to MMAC_RTOS_ResetMessageQueue(), then the call is terminated with a MMAC_
RTOS_QUEUE_RESET return code, i.e., the suspended task will get rescheduled.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_ReceivedMessageQueue
MMAC_RTOS_ResetMessageQueue

Sample Code
< tba >

28
MMAC_RTOS_ReceiveMessageQueue

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_ReceiveMessageQueue(
MMAC_RTOS_MSG_QUEUE msgQueueId,
UI32 timeout,
void *msg
);

Includes
#include “mmac/rtos.h”

Inputs
msgQueueId A pointer to the message queue identifier.
timeout The number of system ticks before the message queue send operation times out.
msg A pointer to an area of memory in which to return the messages.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_QUEUE_RESET
MMAC_RTOS_NOT_INITIALISED

Description
Checks the message queue, msgQueueId, for messages.
If a message is pending, it is returned in msg and the MMAC_RTOS_OK value is returned.
If no message is pending then the calling task is blocked up to timeout system ticks waiting for the
message. If timeout is MMAC_RTOS_SUSPEND the calling task is blocked forever or until a message is
received
The message is copied into the msg memory area. The calling task must ensure that the size of the msg
memory area is large enough to accommodate the message. If the queue has been reset by a call to
MMAC_RTOS_ResetMessageQueue(), then the call is terminated with a MMAC_RTOS_QUEUE_
RESET return code, i.e., the suspended task will get rescheduled.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_ResetMessageQueue
MMAC_RTOS_SendMessageQueue

Sample Code
< tba >

29
MMAC_RTOS_InstallInterruptHandler

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_InstallInterruptHandler(
MMAC_RTOS_VECTOR_HANDLER handler,
MMAC_RTOS_VECTORS vector,
MMAC_RTOS_VECTOR_HANDLER *oldHandler
);

Includes
#include “mmac/rtos.h”

Inputs
handler Pointer to interrupt handler function.
vector Vector number for an EMMA2 device.

Outputs
oldHandler Pointer to return previously installed handler.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_NOT_INITIALISED
MMAC_RTOS_UNKNOWN_VECTOR

Description
This function installs the interrupt handler for a device identified by vector. The previously installed
handler is returned via oldHandler. If oldHandler is NULL then no old handler is returned.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
N/A

Sample Code
< tba >

30
MMAC_RTOS_GetInterruptMask

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_GetInterruptMask(
MMAC_RTOS_VECTORS vector,
MMAC_BOOL *enabled
);

Includes
#include “mmac/rtos.h”

Inputs
vector The vector number for an EMMA2 device.

Outputs
enabled Whether or not the interrupt is enabled.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_NOT_INITIALISED

Description
Gets the interrupt enable mask for the EMMA2 device given in vector.
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_SetInterruptMask

Sample Code
< tba >

31
MMAC_RTOS_SetInterruptMask

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SetInterruptMask(
MMAC_RTOS_VECTORS vector,
MMAC_BOOL enable
);

Includes
#include “mmac/rtos.h”

Inputs
vector The vector number for an EMMA2 device.
enable Whether to enable or disable interrupts for this device.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_NOT_INITIALISED

Description
Used to enable/disable interrupts for the EMMA2 device specified in vector (see the list of EMMA device
vectors in MMAC_RTOS_InstallInterruptHandler() above).
If MMAC_RTOS_Initialise() was not called previously, MMAC_RTOS_NOT_INITIALISED is returned.

See Also
MMAC_RTOS_GetInterruptMask

Sample Code
< tba >

32
MMAC_RTOS_DisableInterrupts

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_DisableInterrupts(void);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
Disables all interrupts.

See Also
N/A

Sample Code
< tba >

33
MMAC_RTOS_EnableInterrupts

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_EnableInterrupts(void);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
Enables interrupts.

See Also
N/A

Sample Code
< tba >

34
MMAC_RTOS_TaskCreate

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TaskCreate (
MMAC_RTOS_TASK_ENTRY entryPoint,
MMAC_RTOS_TASK_ARG arg,
MMAC_RTOS_TASK_STACK stack,
UI32 stackSize,
UI8 priority,
MMAC_RTOS_TASK_ID *tid,
MMAC_BOOL start
);

Includes
#include “mmac/rtos.h”

Inputs
entryPoint A pointer to the entry point for the task.
arg An argument list to pass to the task.
stack A pointer to a memory area that can be used as a stack by the task.
stackSize The size of the stack memory area.
priority The task priority, from 10 highest to 255 lowest, priorities less than 10 are
reserved for system tasks.
start If this is true then the task is started immediately, otherwise it is not and
MMAC_RTOS_TaskStart() is used to start it.

Outputs
tid A pointer to a unique task identifier.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This function creates a task using the information provided. If the task creation fails then MMAC_RTOS
_FAIL is returned otherwise MMAC_RTOS_OK is returned.
If the underlying RTOS requires a task string identifier the string “taskX”, is automatically given, where X
is a unique number starting from 0.
If start is MMAC_FALSE then the task is not started immediately, otherwise it is.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining
USE_SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.

See Also
MMAC_RTOS_TaskDestroy

Sample Code
< tba >

35
MMAC_RTOS_TaskStart

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TaskStart ( MMAC_RTOS_TASK_ID tid );

Includes
#include “mmac/rtos.h”

Inputs
tid A unique task identifier.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_INVALID_PARAM

Description
This function starts a task running after it has been created but not started using MMAC_RTOS_
TaskCreate(), or after it has been stopped using MMAC_RTOS_TaskStop().
If the tid is invalid then MMAC_RTOS_FAIL is returned, otherwise MMAC_RTOS_OK is returned.
MMAC_RTOS_INVALID_PARAM is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.

See Also
MMAC_RTOS_TaskCreate
MMAC_RTOS_TaskStop

Sample Code
< tba >

36
MMAC_RTOS_TaskStop

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TaskStop ( MMAC_RTOS_TASK_ID tid );

Includes
#include “mmac/rtos.h”

Inputs
tid A unique task identifier.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_INVALID_PARAM

Description
This function stops a task running after it has been started using MMAC_RTOS_TaskCreate() or
MMAC_RTOS_TaskStart(). The task can then be restarted at the point it was stopped.
If the tid is invalid then MMAC_RTOS_FAIL is returned, otherwise MMAC_RTOS_OK is returned.
MMAC_RTOS_INVALID_PARAM is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.

See Also
MMAC_RTOS_TaskCreate
MMAC_RTOS_TaskStart

Sample Code
< tba >

37
MMAC_RTOS_GetTaskId

Function prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_GetTaskId(I8 *name);

Includes
#include “mmac/rtos.h”
Inputs
None.

Outputs
name null terminated string naming the current task.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Returns the name of the currently executing task. The string in name will be no more than
MMAC_RTOS_NAME_LEN + 1 characters in length, including the null terminator.

See Also
N/A

Sample Code
< tba >

38
MMAC_RTOS_TaskDestroy

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TaskDestroy (
MMAC_RTOS_TASK_ID tid
);

Includes
#include “mmac/rtos.h”

Inputs
tid A unique task identifier.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_INVALID_PARAM

Description
This function deletes a task from the system. If the tid is invalid then MMAC_RTOS_FAIL is returned,
otherwise MMAC_RTOS_OK is returned.
MMAC_RTOS_INVALID_PARAM is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.

See Also
MMAC_RTOS_TaskCreate

Sample Code
< tba >

39
MMAC_RTOS_CurrentTaskId

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_CurrentTaskId (
MMAC_RTOS_TASK_ID *tid
);

Includes
#include “mmac/rtos.h”

Inputs
None

Outputs
tid The current task id.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK

Description
This function returns, via tid, the current task identifier for the calling task. This function always returned
MMAC_RTOS_OK.

See Also
MMAC_RTOS_TaskCreate
MMAC_RTOS_TaskDestroy

Sample Code
< tba >

40
MMAC_RTOS_SetTaskPriority

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SetTaskPriority (
I16 delta,
UI8 *newPriority
);

Includes
#include “mmac/rtos.h”

Inputs
delta An increment/decrement to be made to the tasks current priority.

Outputs
newPriority The tasks new priority.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Changes the current tasks priority, by delta, i.e.
newPriority = currentPriority + delta;
(where delta can be negative).
If the newPriority is not between 0 and 255 the priority is not changed and MMAC_RTOS_FAIL is
returned, otherwise MMAC_RTOS_OK is returned.

See Also
MMAC_RTOS_TaskCreate
MMAC_RTOS_TaskDestroy

Sample Code
< tba >

41
MMAC_RTOS_Reboot

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_Reboot (void);

Includes
#include “mmac/rtos.h”
The code for this function is included in the nucleus library (nucleus<_optional suffix>.mip).

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
Never returns.

Description
Forces the board to perform a warm reset, the performs a function call to the label EntryPoint(), which is
at the start of the system in [Link].

See Also
N/A

Sample Code
< tba >

42
MMAC_RTOS_Wait

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_Wait (void);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
The current task is suspended until an MMAC_RTOS_WakeUp() call is made for that task.
If the task wake up mask is set, using MMAC_RTOS_ProcessMask(), then a flag is set to say that a
wake up call has been made, so if the task performs an MMAC_RTOS_Wait() operation the task will not
sleep but will continue running, the wake up flag is cleared.

See Also
MMAC_RTOS_WakeUp
MMAC_RTOS_IsWakeUpPending
MMAC_RTOS_ProcessMask

Sample Code
< tba >

43
MMAC_RTOS_WakeUp

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_WakeUp ( MMAC_RTOS_TASK_ID tid );

Includes
#include “mmac/rtos.h”

Inputs
tid The task identifier for the task to wake up.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_INVALID_PARAM

Description
If the task is waiting then it is removed from the list of waiting tasks and allowed to run as normal.
If the task is not waiting then if the wake up mask for the task is set then a flag is set to record the fact that
a wake up operation was requested, so any subsequent MMAC_RTOS_Wait() operations will result in
the task being allowed to continue.
MMAC_RTOS_INVALID_PARAM is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.
If tid is invalid returned MMA_EXT_RTOS_FAIL otherwise returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_Wait
MMAC_RTOS_IsWakeUpPending
MMAC_RTOS_ProcessMask

Sample Code
< tba >

44
MMAC_RTOS_ProcessMask

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_ProcessMask( MMAC_BOOL state );

Includes
#include “mmac/rtos.h”

Inputs
state The currents tasks new wake up mask state.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Sets the current tasks wake up mask to state. If a tasks wake up mask is set to MMAC_TRUE then if a
MMAC_RTOS_WakeUp() call is made when the task is running a flag us set to record this event. When
a subsequent MMAC_RTOS_Wait() call is made no wait takes place and the task is allowed to run.

See Also
MMAC_RTOS_WakeUp
MMAC_RTOS_IsWakeUpPending
MMAC_RTOS_WakeUp

Sample Code
< tba >

45
MMAC_RTOS_IsWakeUpPending

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_IsWakeUpPending (void);

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
If an automatic wake up is pending then MMAC_RTOS_OK is returned, otherwise MMAC_RTOS_FAIL is
returned.

See Also
MMAC_RTOS_WakeUp
MMAC_RTOS_ProcessMask
MMAC_RTOS_WakeUp

Sample Code
< tba >

46
MMAC_RTOS_AttachTaskMemory

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_AttachTaskMemory (
MMAC_RTOS_TASK_MEMORY taskMemory
);

Includes
#include “mmac/rtos.h”

Inputs
taskMemory A pointer to a block of memory.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This function is used to provide a task with an area of memory. It associates the taskMemory pointer with
the current task. Only one pointer can be associated with a given task.
MMAC_RTOS_INVALID_FAIL is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.
Otherwise returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_RetrieveTaskMemory

Sample Code
< tba >

47
MMAC_RTOS_RetrieveTaskMemory

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_RetrieveTaskMemory(
MMAC_RTOS_TASK_MEMORY *taskMemory,
MMAC_RTOS_TASK_ID tid
);

Includes
#include “mmac/rtos.h”

Inputs
tid Task identifier of task of which the memory pointer is to be retrieved.

Outputs
taskMemory A pointer to a block of memory.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
Returns, via taskMemory, the memory associated with the current task, if no is associated the NULL is
returned.
MMAC_RTOS_INVALID_FAIL is returned if the specified task could not be found.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.
Otherwise returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_AttachTaskMemory

Sample Code
< tba >

48
MMAC_RTOS_EnableTaskPreemption

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_EnableTaskPreemption( MMAC_BOOL state );

Includes
#include “mmac/rtos.h”

Inputs
state If MMAC_TRUE preemption is turned on for the calling task, else it’s turned off.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
If state is MMAC_TRUE pre-emption is turned on for the calling task, else it’s turned off.
MMAC_RTOS_FAIL will be returned if semaphore protection is enabled by defining USE_
SEMAPHORE_PROTECTION_FOR_TASKINFO, and the semaphore cannot be acquired.
Otherwise returns MMAC_RTOS_OK.

See Also
MMAC_RTOS_AttachTaskMemory

Sample Code
< tba >

49
MMAC_RTOS_TimerCreate

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TimerCreate (
I8 *name,
MMAC_RTOS_TIMER_FUNCTION callback,
UI32 arg,
UI32 expirationTime,
MMAC_RTOS_TIMER_MODE operatingMode,
MMAC_RTOS_TIMER_ID *timerId
);

Includes
#include “mmac/rtos.h”

Inputs
name A pointer to a string containing timer’s name.
callback Specifies the application routine to execute when the timer expires.
arg An UI32 element supplied to the expiration routine. The parameter may be used
to help identify timers that use the same expiration routine.
expirationTime Specifies number of ticks for timer expiration.
operatingMode If it is a ‘single shot’, timer expires only once. If it is ‘continuous’, timer is
rescheduled for another expiration.

Outputs
timerId A reference to an internally allocated timer control block. Note: all subsequent
requests made to the timer require this reference.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL
MMAC_RTOS_INVALID_PARAM

Description
This service creates an application timer. The specified expiration routine is executed each time the timer
expires. Application expiration routines should avoid task suspension operations. Suspension of the
expiration routine can cause delays in other application timer requests.
The timer created is in dormant state.
If any of the parameters passed to the function are invalid then MMAC_RTOS_INVALID_PARAM is
returned. If the function is unable to acquire any memory from the RTOS, MMAC_RTOS_MEMORY_
EXHAUSTED is returned.
If timer creation fails, MMAC_RTOS_FAIL is returned.
Otherwise MMAC_RTOS_OK is returned.

See Also
MMAC_RTOS_TimerDelete

50
Sample Code
< tba >

51
MMAC_RTOS_TimerDelete

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TimerDelete (
MMAC_RTOS_TIMER_ID timerId
);

Includes
#include “mmac/rtos.h”

Inputs
timerId A reference to an internally allocated timer control block.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_INVALID_PARAM
MMAC_RTOS_FAIL

Description
This service deletes a previously created application timer. The specified timer must be in dormant state
prior to this service request. The application must prevent the use of this timer during and after deletion.

See Also
MMAC_RTOS_TimerCreate

Sample Code
< tba >

52
MMAC_RTOS_TimerCntrl

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_TimerCntrl (
MMAC_RTOS_TIMER_ID timerId,
MMAC_RTOS_TIMER_CNTRL *iopb
);

Includes
#include “mmac/rtos.h”

Inputs
timerId A reference to an internally allocated timer control block.
iopb A pointer to a control structure.

Outputs
iopb If [Link] is MMAC_RTOS_TIMER_GET, then [Link] will contain the
current timer status.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_INVALID_PARAM
MMAC_RTOS_FAIL

Description
This service enables (puts the timer into active state) or disables (puts the timer into dormant state) the
application timer referenced by timerId. It also reads the current timer status when [Link] is set to
get the status.

See Also
MMAC_RTOS_TimerCreate
MMAC_RTOS_TimerDelete

Sample Code
< tba >

53
MMAC_RTOS_EventCreate

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_EventCreate ( MMAC_RTOS_EVENT *eventId );

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
eventId The event identified.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This is used to create an event.

See Also
N/A

Sample Code
< tba >

54
MMAC_RTOS_EventDelete

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_EventDelete ( MMAC_RTOS_EVENT eventId );

Includes
#include “mmac/rtos.h”

Inputs
None.

Outputs
eventId The event identified.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This is used to delete an event.

See Also
N/A

Sample Code
< tba >

55
MMAC_RTOS_EventRetrieve

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_EventRetrieve (
MMAC_RTOS_EVENT eventId,
UI32 timeout,
UI32 targetEvents,
UI32 *retrievedEvents,
MMAC_RTOS_EVENT_OPERATION operation
);

Includes
#include “mmac/rtos.h”

Inputs
eventId The event identified.
timeout Timeout for event retrieval (in milliseconds).
targetEvents: A set of or’d target values
retrievedEvents: A set of retrieved events
operation: The operation applied to the target events and actual events.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This is used to check for events for the eventId event. The operation is applied to the targetEvents and the
actual pending events. If an event is found then the retrievedEvents is set with the matching events and
those events cleared from the actual pending events. The operation can be MMAC_RTOS_EVENT_OP_
AND or MMAC_RTOS_EVENT_OP_OR.

See Also
N/A

Sample Code
< tba >

56
MMAC_RTOS_SetEvent

Function Prototype
MMAC_RTOS_RESULT_CODE MMAC_RTOS_SetEvent (
MMAC_RTOS_EVENT eventId,
UI32 bitMask,
MMAC_RTOS_EVENT_OPERATION operation
);

Includes
#include “mmac/rtos.h”

Inputs
eventId The event identified.
bitMask A set of events to set.
operation The operation to be applied to the set events.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_RTOS_OK
MMAC_RTOS_FAIL

Description
This is used to set an event for eventId. The operation is applied to the current pending events and the
bitMask and the result becomes the new set of current pending events.

See Also
N/A

Sample Code
< tba >

57
4 Data Structures

Result Codes
The following result codes are defined:

typedef enum
{
MMAC_RTOS_OK,
MMAC_RTOS_FAIL,
MMAC_RTOS_ALREADY_INITIALISED,
MMAC_RTOS_ALREADY_CLOSED,
MMAC_RTOS_NOT_INITIALISED,
MMAC_RTOS_UNKNOWN_VECTOR,
MMAC_RTOS_UNKNOWN_ID,
MMAC_RTOS_MEMORY_EXHAUSTED,
MMAC_RTOS_QUEUE_RESET,
MMAC_RTOS_INVALID_PARAM
} MMAC_RTOS_RESULT_CODE;

Semaphores
A semaphore is defined as:
typedef void * MMAC_RTOS_SEMAPHORE;

Message Queues
A message queue is defined as:
typedef void * MMAC_RTOS_MSG_QUEUE;

The allowable length of an RTOS name is RTOS dependent, and specified as:
#define MMAC_RTOS_NAME_LEN (8)

The minimum (none) and maximum (forever) suspension timeouts are defined as:
#define MMAC_RTOS_SUSPEND (0xFFFFFFFF)
#define MMAC_RTOS_NO_SUSPEND (0x00)

The maximum timeout for system operations is defined as:

#define MMAC_RTOS_MAX_TIMEOUT (MMAC_RTOS_SUSPEND)

The following queue modes are defined:

typedef enum
{
MMAC_RTOS_MSG_QUEUE_BLOCKING,
MMAC_RTOS_MSG_QUEUE_NON_BLOCKING
} MMAC_RTOS_MSG_QUEUE_MODE;

Memory Pools
A memory pool is defined as:
typedef void * MMAC_RTOS_MEMORY_POOL;

58
Task Entry Point
The following type defines the start point for a MMAC extended RTOS task:
typedef void * MMAC_RTOS_TASK_ENTRY;

Task Argument List

The following type defines the task argument list:
typedef void * MMAC_RTOS_TASK_ARG;

Task Stack
The following type defines the task stack:
typedef void * MMAC_RTOS_TASK_STACK;

Task Identifier
The following type defines the task identifier:
typedef void * MMAC_RTOS_TASK_ID;

User Tick Function

The following type defines a user tick function:
typedef void(* MMAC_RTOS_TICK_FUNCTION)(void);

Task Memory
The following type defines task memory:
typedef void * MMAC_RTOS_TASK_MEMORY;

Timer Identifier
The following type defines the application timer identifier:
typedef void * MMAC_RTOS_TIMER_ID;

Event Identifier
The following type defines the event identifier:
typedef void * MMAC_RTOS_EVENT;

Timer Expiration Function

The following type defines an application timer expiration routine:
typedef void(* MMAC_RTOS_TIMER_FUNCTION)(UI32);

Timer Mode of operation

The following type defines an application timer mode of operation:

typedef enum
{
MMAC_RTOS_TIMER_SINGLE_SHOT,
MMAC_RTOS_TIMER_CONTINUOUS
} MMAC_RTOS_TIMER_MODE;

59
Timer Control
The following type defines an application timer control state:

typedef enum
{
MMAC_RTOS_TIMER_SET,
MMAC_RTOS_TIMER_GET
} MMAC_RTOS_TIMER_OPERATION;
typedef enum
{
MMAC_RTOS_TIMER_DISABLE = 0,
MMAC_RTOS_TIMER_ENABLE
} MMAC_RTOS_TIMER_STATE;
typedef struct
{
MMAC_RTOS_TIMER_OPERATION operation;
MMAC_RTOS_TIMER_STATE state;
} MMAC_RTOS_TIMER_CNTRL;

Interrupt Vectors

typedef enum
{
MMAC_RTOS_END_OF_TABLE,
MMAC_RTOS_VECTOR_WMIF,
MMAC_RTOS_VECTOR_XDMA,
MMAC_RTOS_VECTOR_AUDIO,
MMAC_RTOS_VECTOR_MPEG,
MMAC_RTOS_VECTOR_SW0,
MMAC_RTOS_VECTOR_SW1,
MMAC_RTOS_VECTOR_VENC,
MMAC_RTOS_VECTOR_DISP,
MMAC_RTOS_VECTOR_BITBLT,
MMAC_RTOS_VECTOR_AVENC,
MMAC_RTOS_VECTOR_PCIIF,
MMAC_RTOS_VECTOR_IDE0,
MMAC_RTOS_VECTOR_IDE1
MMAC_RTOS_VECTOR_TS0,
MMAC_RTOS_VECTOR_TS1,
MMAC_RTOS_VECTOR_TS2,
MMAC_RTOS_VECTOR_TS3,
MMAC_RTOS_VECTOR_TS4,
MMAC_RTOS_VECTOR_TS5,
MMAC_RTOS_VECTOR_TS6,
MMAC_RTOS_VECTOR_TS7,
MMAC_RTOS_VECTOR_TS8,
MMAC_RTOS_VECTOR_TS9,
MMAC_RTOS_VECTOR_TS10,
MMAC_RTOS_VECTOR_TS11,
MMAC_RTOS_VECTOR_TS12,
MMAC_RTOS_VECTOR_TS13,
MMAC_RTOS_VECTOR_TS14,
MMAC_RTOS_VECTOR_TS15,
MMAC_RTOS_VECTOR_ZCCT0,
MMAC_RTOS_VECTOR_ZCCT1,
MMAC_RTOS_VECTOR_ZCCT2,
MMAC_RTOS_VECTOR_ZCCT3,
MMAC_RTOS_VECTOR_ZTMR0,
MMAC_RTOS_VECTOR_ZTMR1,
MMAC_RTOS_VECTOR_ZRTC,
MMAC_RTOS_VECTOR_ZJTAG,

60
 MMAC_RTOS_VECTOR_ZIRB0,
MMAC_RTOS_VECTOR_ZIRB1,
MMAC_RTOS_VECTOR_INTI,
MMAC_RTOS_VECTOR_ZPIO0,
MMAC_RTOS_VECTOR_ZPIO1,
MMAC_RTOS_VECTOR_ZPIO2,
MMAC_RTOS_VECTOR_OGIO,
MMAC_RTOS_VECTOR_PFUR0,
MMAC_RTOS_VECTOR_PFUR1,
MMAC_RTOS_VECTOR_PURT0,
MMAC_RTOS_VECTOR_PURT1,
MMAC_RTOS_VECTOR_PSCI0,
MMAC_RTOS_VECTOR_PSCI1,
MMAC_RTOS_VECTOR_PIIC0,
MMAC_RTOS_VECTOR_PIIC1,
MMAC_RTOS_VECTOR_PCIF,
MMAC_RTOS_VECTOR_PCSI,
MMAC_RTOS_VECTOR_PBRD,
MMAC_RTOS_VECTOR_PMM,
MMAC_RTOS_VECTOR_PMS0,
MMAC_RTOS_VECTOR_PMS1,
MMAC_RTOS_VECTOR_PSDM
}MMAC_RTOS_VECTORS;

The interrupt handlers are callback functions and defined as follows:

typedef void (* MMAC_RTOS_VECTOR_HANDLER)(void);

System Heap
The following variable will be assigned to the memory pool allocated as the system heap by MMAC_
RTOS_Initialise().

extern MMAC_RTOS_MEMORY_POOL RTOS_systemHeap;

Note: The size of position of this heap is defined in the link file.

Event Operations

typedef enum
{
MMAC_RTOS_EVENT_OP_AND,
MMAC_RTOS_EVENT_OP_OR
}MMAC_RTOS_EVENT_OPERATION;

61
5 Revision History
Title: API Specification: RTOS Interface
Ref: API_RTOS.doc

Date Doc API Details of change Ref.

Ver. Ver.
2000-11-13 0.01 Initial Revision M-JD
2002-08-13 0.02 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.02 M-RI
2003-03-26 1.1 Mismatches in function prototypes are fixed M-NI
2003-06-27 1.2 Doc number added. M-RJI

62