MMAC

Software Group

API – Record

EMMA2 Software User’s Manual

Contents

1 Introduction .....................................................................................................................................2
1.1 Overview...............................................................................................................................2
1.2 Description............................................................................................................................2
2 Architecture .....................................................................................................................................3
2.1 Return Codes .......................................................................................................................3
2.2 Includes ................................................................................................................................4
2.3 Initialisation ...........................................................................................................................4
2.4 Configuration ........................................................................................................................4
2.5 Type Definitions ....................................................................................................................5
2.6 Sample Code ........................................................................................................................9
3 Function Prototypes ......................................................................................................................12
MMAC_RECORD_Initialise ................................................................................................12
MMAC_RECORD_Close....................................................................................................13
MMAC_RECORD_OpenDevice .........................................................................................14
MMAC_RECORD_CloseDevice.........................................................................................15
MMAC_RECORD_AllocatePIDFilter ..................................................................................16
MMAC_RECORD_SetPIDFilter .........................................................................................18
MMAC_RECORD_FreePIDFilter .......................................................................................20
MMAC_RECORD_EnablePIDFilter....................................................................................21
MMAC_RECORD_DisablePIDFilter...................................................................................22
MMAC_RECORD_SetPacketControl.................................................................................23
MMAC_RECORD_TriggerNullInsert ..................................................................................25
MMAC_RECORD_Start .....................................................................................................26
MMAC_RECORD_Stop......................................................................................................28
MMAC_RECORD_InstallCallback......................................................................................29
4 Revision History ............................................................................................................................31

Book No: n/a (shared document) Doc No: MMAC0156, Issue: 1.11
© NEC Electronics Corporation 2003, 2004 Date: 2004-02-18

The information is this document is subject to change without notice – it is the reader’s responsibility to check that this is the current version.
This document includes company confidential information. It should only be released to third parties under a Non-Disclosure Agreement.
1 Introduction

1.1 Overview
The Record functionality is dependent upon the underlying hardware. The hardware functionality is
reported in the hardware capabilities structure.
Multiple streams may be recorded simultaneously.
The RECORD API is implemented as a extension functions of the DEMUX API. It is necessary to set
up the DEMUX API before the RECORD API functions are called.
The input stream to be recorded must be made available to the SRU via the DEMUX API. A Demux
device must therefore be opened before a record device. The demux device handle is passed the
RECORD API when a record device is opened.
The RECORD API provides the ability to edit, replace or insert packets in a recording transport
stream. These features can be specified for each PID filter.
The edit feature overwrites the packet data from a definable offset to the end of the packet using a
user configured byte pattern.
The RECORD API also provides the application software with the ability to create space within a
recording transport stream by inserting NULL packets. These may then be edited before transfer to
file.

1.2 Description
The record driver can work in one of three modes. The first mode provides a mechanism for recording
input streams to long term memory storage (normally HDD) via the MMAC_FILE API. In this mode,
it is the responsibility of the application to open/create a file and pass its fileId to the RECORD API
at the start of a recording. If a NULL file ID is given, the RECORD API will not attempt to transfer
the data out of the buffers.
The second mode does not pass any data to MMAC_FILE API but will provide pointers to the data
collected in SDRAM for the application to use.
The third mode has the same callback functionality as the second mode but this mode allows the
complete PACK stream generated by the MPEG encode to be output to the record buffer.
The RECORD module uses a system of cyclic buffers split into segments. The buffers are filled by
the TS or PS data captured by the SRU filters. A transfer request interrupt is set at the end of the first
segment. It is triggered as the buffer fills passed this point. Depending on the mode, the driver will
then copy this segment data to file or pass a pointer to the segment via a callback function to the
application. The transfer request interrupt is moved to the end of the next segment and the process
continues.
The memory buffers used for recording may be allocated either by the RECORD API or by the
application. If the buffers are to be allocated by the API then the size of the buffers and the number of
segments these buffers are split into, is defined in the file api.h. If the buffer memory is allocated by
the host then the details of the buffer to be used must be passed into the function
MMAC_RECORD_Start( ).

2 / 31
2 Architecture

2.1 Return Codes

The meanings of the various return codes are as follows:
Return Code Description
MMAC_RECORD_OK Function completed OK.
MMAC_RECORD_NOT_INITIALISED The Record API has not been initialised.
MMAC_RECORD_ALREADY_ The Record API has already initialised.
INITIALISED
MMAC_RECORD_INVALID_DEVICE_ID Invalid Record device ID passed.
MMAC_RECORD_INVALID_FILTER_ID An invalid filter ID passed.
MMAC_RECORD_INVALID_WDOFFSET An invalid word offset passed.
MMAC_RECORD_INVALID_NULL_NUM An invalid NULL packet insert number passed.
MMAC_RECORD_RECORD_NOT_ The Record channel is not currently running.
STARTED
MMAC_RECORD_DEVICE_NOT_OPEN The specified record device is not open.
MMAC_RECORD_DEVICE_ALREADY_ The specified record device is already open.
OPEN
MMAC_RECORD_DEVICE_ACTIVE The specified record device is active recording.
MMAC_RECORD_DEVICE_NOT_ The specified record device is not active recording.
ACTIVE
MMAC_RECORD_FAILED_TO_SET_ The function was unable to set the hardware as
HARDWARE requested.
MMAC_RECORD_SEMAPHORE_ERROR The function timed out acquiring/releasing a
semaphore.
MMAC_RECORD_QUEUE_ERROR The function failed to create/access an RTOS queue.
MMAC_RECORD_MEMORY_ALLOC_ The function failed to allocate the required memory.
FAIL
MMAC_RECORD_TASK_CREATE_FAIL The function failed to create a task.
MMAC_RECORD_FAILED_TO_FREE_ The function failed to free a system resource.
RESOURCE
MMAC_RECORD_NO_FREE_SCRAMBLE_ There are no available PES level de-scramble filters.
FILTERS
MMAC_RECORD_NO_FREE_EVENT_ There are no free ELU PES Event filters.
FILTERS
MMAC_RECORD_NO_FREE_FILTERS No more PID filters are available.
MMAC_RECORD_INVALID_PARAMETER A parameter passed to the function is not valid.
MMAC_RECORD_HARDWARE_FAIL The function was not completed successfully due to a
low level interface failure.
MMAC_RECORD_FAILED The function failed.
MMAC_RECORD_NOT_SUPPORTED The attempted action is not supported by the hardware.

3 / 31
2.2 Includes
In order to use this API, the following header files must be included in order:

#include “mmac/types.h”
#include “mmac/mmac_config.h”
#include “mmac/mmac_common.h”
#include “mmac/rtos.h”
#include “mmac/demux.h”
#include “mmac/file.h”
#include “mmac/record.h”

2.3 Initialisation
Prior to using any other functions of the Record API, the following function must be called:
MMAC_RECORD_Initialise( )

2.4 Configuration
A number of configurable options, in the form of ‘#define’s are given in the RECORD section of the
mmac_config.h source file marked by the comment:

/************************************************************/
/* */
/* MMAC RECORD SETUP */
/* */
/************************************************************/

These options are:

Define Default Meaning
MMAC_RECORD_ 0x00075800 Define the size of the recording
BUFFER_SEGMENT buffer segment for internal
allocation.
MMAC_RECORD_BUFFER_SI 0x001D6000 Define the size of the recording
ZE buffer for internal allocation.
MMAC_RECORD_PARAMETE MMAC_YES Define to enable parameter
R_CHECKING checking in the record API.
MMAC_RECORD_DEBUG_EN MMAC_NO Define to enable debug output
ABLE from the record API.

4 / 31
2.5 Type Definitions

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

typedef enum
{
MMAC_RECORD_OK = 0,
MMAC_RECORD_NOT_INITIALISED,
MMAC_RECORD_ALREADY_INITIALISED,
MMAC_RECORD_INVALID_DEVICE_ID,
MMAC_RECORD_INVALID_FILTER_ID,
MMAC_RECORD_INVALID_WDOFFSET,
MMAC_RECORD_INVALID_NULL_NUM,
MMAC_RECORD_DEVICE_NOT_OPEN,
MMAC_RECORD_DEVICE_ALREADY_OPEN,
MMAC_RECORD_DEVICE_ACTIVE,
MMAC_RECORD_DEVICE_NOT_ACTIVE,
MMAC_RECORD_FAILED_TO_SET_HARDWARE,
MMAC_RECORD_SEMAPHORE_ERROR,
MMAC_RECORD_QUEUE_ERROR,
MMAC_RECORD_MEMORY_ALLOC_FAIL,
MMAC_RECORD_TASK_CREATE_FAIL,
MMAC_RECORD_FAILED_TO_FREE_RESOURCE,
MMAC_RECORD_NO_FREE_SCRAMBLE_FILTERS,
MMAC_RECORD_NO_FREE_EVENT_FILTERS,
MMAC_RECORD_NO_FREE_FILTERS,
MMAC_RECORD_FILTER_NOT_SET,
MMAC_RECORD_INVALID_PARAMETER,
MMAC_RECORD_HARDWARE_FAIL,
MMAC_RECORD_FAILED,
MMAC_RECORD_NO_FREE_ELU_FILTERS,
MMAC_RECORD_NOT_SUPPORTED
} MMAC_RECORD_RESULT_CODE;

PID Identifier & SID Identifier

PID values are specified using 13 bits. SID values are specified using 8 bits.

typedef UI16 MMAC_RECORD_PID_TYPE;

Use the following definition when referring to filterId parameters

typedef UI32 MMAC_RECORD_FILTER_ID;

Use the following definition when referring to recordId parameters

typedef UI32 MMAC_RECORD_HANDLE;

5 / 31
Record Capabilities
The following structure containing the capabilities of the underlying hardware.
typedef struct
{
UI32 numberOfRecordingDevices;
UI32 numberOfBuffersPerDevice;
MMAC_BOOL recModeTsPacket;
MMAC_BOOL recModeTsPacketWithTimestamp;
MMAC_BOOL recModePsPesPacket;
MMAC_BOOL recModePsPack;
MMAC_BOOL recModeElementary;
MMAC_BOOL recModeAllData;

MMAC_BOOL pesScramble;
MMAC_BOOL eluEvent;
MMAC_BOOL eluVideoEvent;

MMAC_BOOL packetReplace;
MMAC_BOOL packetInsert;
MMAC_BOOL packetEdit;
MMAC_BOOL mirrorDevice;
UI32 bufferAddressAlignMask;
UI32 bufferSizeAlignMask;

} MMAC_RECORD_CAPABILITIES;

Reording Modes
The following enum is used to select the recording mode for each recording device.
typedef enum
{
MMAC_RECORD_TS_PACKET,
MMAC_RECORD_TS_PACKET_WITH_TIMESTAMP,
MMAC_RECORD_PS_PES_PACKET,
MMAC_RECORD_PS_PACK,
MMAC_RECORD_ELEMENTARY,
MMAC_RECORD_ALL_TS,
MMAC_RECORD_ALL_PACK,
MMAC_RECORD_ALL_DATA
} MMAC_RECORD_RECORDING_MODE;

PES types
The following enum is used to inform the record API what type of stream is to be filtered:
typedef enum
{
MMAC_RECORD_TS_PID,
MMAC_RECORD_PS_STREAM_ID,
MMAC_RECORD_PS_PRIVATE1,
MMAC_RECORD_PS_PRIVATE2
} MMAC_RECORD_TARGET_ID_TYPE;

Record Filter parameter block:

typedef struct
{
MMAC_RECORD_PID_TYPE pid;
MMAC_RECORD_FILTER_ID filterId;
MMAC_RECORD_EDIT_CONTROL_MODE editControlMode;

6 / 31
} MMAC_RECORD_FILTER_IOPB;

Filter Allocation parameter block

The following defines are flags for the filterCapabilities.
#define MMAC_RECORD_PES_SCRAMBLE (0x00000001UL)
#define MMAC_RECORD_ELU_VIDEO_EVENT (0x00000002UL)
#define MMAC_RECORD_ELU_EVENT (0x00000004UL)

typedef struct
{
MMAC_RECORD_HANDLE recordId;
MMAC_RECORD_TARGET_ID_TYPE targetIdType;
UI32 filterCapabilities;
MMAC_RECORD_FILTER_ID filterId;
} MMAC_RECORD_ALLOCATION_IOPB;

Edit control modes

typedef enum
{
MMAC_RECORD_TS_PACKET_UNTOUCHED,
MMAC_RECORD_EDIT_TS_PACKET,
MMAC_RECORD_REPLACE_TS_PACKET,
MMAC_RECORD_INSERT_TS_PACKET
} MMAC_RECORD_EDIT_CONTROL_MODE;

Edit Control parameter block

typedef struct
{
UI8 numberNullPackts;
UI8 pattern;
UI8 wordOffset;
} MMAC_RECORD_EDIT_CONTROL_IOPB;

Record Output Modes

typedef enum
{
MMAC_RECORD_MODE_FILE,
MMAC_RECORD_MODE_CALLBACK
} MMAC_RECORD_OUTPUT_MODE;

Record start parameter block

typedef struct

MMAC_RECORD_HANDLE recordId;
MMAC_RECORD_OUTPUT_MODE outputMode;
MMAC_FILE_HANDLE fileId;
UI64 fileSize;
} MMAC_RECORD_START_IOPB;

7 / 31
Record Driver Events
The following enum defines the events of which an application may be notified and the Record
channel for which the event occurred.

typedef enum
{
MMAC_RECORD_DISK_FULL,
MMAC_RECORD_FILE_WRITE_FAIL,
MMAC_RECORD_EOF_REACHED,
MMAC_RECORD_TRANSFER_REQUEST,
MMAC_RECORD_CRITICAL_FAIL,
MMAC_RECORD_STOPPED
} MMAC_RECORD_EVENT_TYPE;

The following structure defines the data transfer pointers that are passed in a record event message of
type MMAC_RECORD_TRANSFER_REQUEST. This message event will only occur if the
recordToFile parameter of MMAC_RECORD_START_IOPB is set to MMAC_FALSE.
typedef struct
{
UI8* dataStart;
UI8* dataEnd;
} MMAC_RECORD_DATA_POINTERS;

The following structure defines the message parameters that are passed to the callback function. If the
event is type MMAC_RECORD_TRANSFER_REQUEST then the flag lastTransferReq is valid. The
flag will always be MMAC_FALSE except for the last block of data for the current recording.

typedef struct
{
MMAC_RECORD_EVENT_TYPE event;
MMAC_RECORD_HANDLE recordId;
MMAC_RECORD_DATA_POINTERS dataPointers;
MMAC_BOOL lastTransferReq;
} MMAC_RECORD_EVENT_MESSAGE;

Record Driver Callback

The following type defines the callback function, which may be installed by the application. If
installed this function will be called when record events occur.

typedef void (*MMAC_RECORD_CALLBACK)(MMAC_RECORD_EVENT_MESSAGE *message);

8 / 31
2.6 Sample Code

/* Example for simple DVD-VR recording */

#include <stdio.h>
#include "mmac/types.h"
#include "mmac/rtos.h"
#include "mmac/mmac_config.h"
#include "mmac/demux.h"

#include "mmac/file.h"
#include "mmac/record.h"

#define RECORD_BUFF_SEGMENT_SIZE (0x91800)

#define NUM_RECORD_SEGMENT (4)

static MMAC_RECORD_HANDLE recordHandle;

static UI8 *recordBuffer;
static MMAC_RECORD_FILTER_ID recFilterId[3];

void record_sample( MMAC_DEMUX_DEVICE_HANDLE demuxHandle )

{
MMAC_RECORD_BUFFER_PARAMS bufferParams;
MMAC_RECORD_ALLOCATION_IOPB allocParams;
MMAC_RECORD_FILTER_IOPB filterParams;
MMAC_RECORD_START_IOPB recordParams;

/**************************************************************************/
/* The DEMUX API MUST be initialised before initialising the RECORD API */
/**************************************************************************/

/* Initialise Record API */

MMAC_RECORD_Initialise();

/* Install callback function */

MMAC_RECORD_InstallCallback(MMAC_DVD_RecordCallback);

/* Allocate memory for the recording buffer */

MMAC_RTOS_AllocMemorySection(RECORD_BUFF_SIZE * NUM_RECORD_SEGMENT,
MMAC_FALSE,
&recordBuffer,
8);

/* buffer allocated - open record device */

[Link] = recordBuffer;
[Link] = RECORD_BUFF_SIZE * NUM_RECORD_SEGMENT;
[Link] = NUM_RECORD_SEGMENT;

MMAC_RECORD_OpenDevice(demuxHandle,
&bufferParams,
MMAC_RECORD_PS_PACK,
&recordHandle);

/* Allocate record filters */

[Link] = recordHandle;
[Link] = MMAC_RECORD_PS_STREAM_ID;
[Link] = 0;
MMAC_RECORD_AllocatePIDFilter(&allocParams);
recFilterId[0] = [Link];

[Link] = recordHandle;
[Link] = MMAC_RECORD_PS_PRIVATE1;
[Link] = 0;
MMAC_RECORD_AllocatePIDFilter(&allocParams);
recFilterId[1] = [Link];

9 / 31
 [Link] = recordHandle;
[Link] = MMAC_RECORD_PS_PRIVATE2;
[Link] = 0;
MMAC_RECORD_AllocatePIDFilter(&allocParams);
recFilterId[2] = [Link];

/* Set up record filters */

[Link] = 0xe0;
[Link] = recFilterId[0];
[Link] = MMAC_RECORD_TS_PACKET_UNTOUCHED;
MMAC_RECORD_SetPIDFilter(&filterParams);

[Link] = 0x80;
[Link] = recFilterId[1];
[Link] = MMAC_RECORD_TS_PACKET_UNTOUCHED;
MMAC_RECORD_SetPIDFilter(&filterParams);

[Link] = 0x50;
[Link] = recFilterId[2];
[Link] = MMAC_RECORD_TS_PACKET_UNTOUCHED;
MMAC_RECORD_SetPIDFilter(&filterParams);

/* Enable Filters */
MMAC_RECORD_EnablePIDFilter(recFilterId[0]);
MMAC_RECORD_EnablePIDFilter(recFilterId[1]);
MMAC_RECORD_EnablePIDFilter(recFilterId[2]);

/* Start recording */
[Link] = recordHandle;
[Link] = MMAC_RECORD_MODE_CALLBACK;
[Link] = 0;
[Link] = 0;
MMAC_RECORD_Start(&recordParams);

/**************************************************************************/
/* Set up the other API's then packets will be recorded */
/**************************************************************************/

/* Stop recording */
MMAC_RECORD_Stop(recordHandle);

/* Disable Filters */
MMAC_RECORD_DisablePIDFilter(recFilterId[0]);
MMAC_RECORD_DisablePIDFilter(recFilterId[1]);
MMAC_RECORD_DisablePIDFilter(recFilterId[2]);

/* Free Filters */
MMAC_RECORD_FreePIDFilter(recFilterId[0]);
MMAC_RECORD_FreePIDFilter(recFilterId[1]);
MMAC_RECORD_FreePIDFilter(recFilterId[2]);

/* Close recording device */

MMAC_RECORD_CloseDevice(recordHandle);
}

void MMAC_DVD_RecordCallback(MMAC_RECORD_EVENT_MESSAGE *message)

{
UI32 dataSize;
UI16 numSectors;

switch(message->event)
{
case MMAC_RECORD_TRANSFER_REQUEST:
/* record buffer segment full - transfer data to disc */
dataSize = (UI32)message->[Link]
- (UI32)message->[Link];
numSectors = dataSize / DEVICE_SECTOR_SIZE;
/* DEVICE_SECTOR_SEZE should be 2048 for DVD */

10 / 31
 /**************************************************************************/
/* Here the function, which sends the data in record buffer to the */
/* recording device, should be called. Also data modification might be */
/* done here if it's necessary. */
/**************************************************************************/

break;

case MMAC_RECORD_STOPPED:
break;

case MMAC_RECORD_CRITICAL_FAIL:
break;

default:
}
}

11 / 31
3 Function Prototypes

MMAC_RECORD_Initialise

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_Initialise (void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_ALREADY_INITIALISED

Description
This function configures the Record module ready for use. It initialises the hardware and sets up the
software prior to any other function RECORD API calls.
If the module is already initialised, the result code MMAC_RECORD_ALREADY_INITIALISED is
returned. If the subsystem is successfully initialised, the code MMAC_RECORD_OK is returned.

See Also
MMAC_RECORD_close( )

Sample Code
Refer to Section 2.6.

12 / 31
MMAC_RECORD_Close

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_Close (void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED

Description
This function releases the systems resources that were used during the operation of the RECORD
module. This function is called when the application has finished recording. A new call to MMAC_
RECORD_Initialise( ), is needed before any further recording is required.
The function checks to see if the record API is initialised and returns the result MMAC_RECORD_
NOT_INITIALISED if it is not.

See Also
MMAC_RECORD_Initialise( )

Sample Code
Refer to Section 2.6.

13 / 31
MMAC_RECORD_OpenDevice

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_OpenDevice (
MMAC_DEMUX_DEVICE_HANDLE deviceId
);

Inputs
deviceId
Handle for the record device to open.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_DEVICE_ALREADY_OPEN
MMAC_RECORD_FAILED_TO_SET_HARDWARE

Description
This function opens a record device. It initialises device hardware and allocates buffer memory from
the system heap. The buffer size is based on the parameters specified in the file mmac_config.h. This
memory will be freed when MMAC_RECORD_CloseDevice( ) is called.
If the function fails allocate hardware resources for this device then the code
MMAC_RECORD_FAILED_TO_SET_HARDWARE is returned.
If the device Id parameter passed is not a valid recording device then this function will do nothing and
return MMAC_RECORD_INVALID_DEVICE_ID.
If a record device has already been opened with this ID then
MMAC_RECORD_DEVICE_ALREADY_OPEN will be returned. The device will not be altered.
If the module is not initialised, the result code MMAC_RECORD_NOT_INITIALISED is returned.
If the record device is successfully opened, the code MMAC_RECORD_OK is returned.

See Also
MMAC_RECORD_CloseDevice( )

Sample Code
N/A

14 / 31
MMAC_RECORD_CloseDevice

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_CloseDevice (
MMAC_RECORD_HANDLE recordId
);

Inputs
recordId
The handle of the device to close.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_FAILED_TO_FREE_RESOURCE

Description
This function closes a record device. Any device specific system resources, such as buffer memory,
will be de-allocated. Before closing a record device, the device should be made inactive by a call to
MMAC_RECORD_Stop( ).
If the recordId passed does not correspond to an open record device this function will return MMAC_
RECORD_INVALID_DEVICE_ID.
If the function is unable to free the resources used by this device then the fail code MMAC_
RECORD_FAILED_TO_FREE_RESOURCE is returned.
If the module is not initialised, the result code MMAC_RECORD_NOT_INITIALISED is returned.
If the record device is successfully closed the code MMAC_RECORD_OK is returned.

See Also
MMAC_RECORD_OpenDevice( )

Sample Code
Refer to Section 2.6.

15 / 31
MMAC_RECORD_AllocatePIDFilter

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_AllocatePIDFilter(
MMAC_RECORD_ALLOCATION_IOPB *allocParams
);

Inputs
allocParams
A pointer to a structure in which the following fields are used as input:
recordId
Record device that the filter is to be applied to.
targetIdType
Specifies the target ID type allocated filter will be used for.
filterCapabilities
UI32 value which contains the capabilities of recording filter to be allocated.

Outputs
allocParams
filterId
Identifier for the filter.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_NO_FREE_FILTERS
MMAC_RECORD_NO_FREE_EVENT_FILTERS
MMAC_RECORD_NO_FREE_SCRAMBLE_FILTERS
MMAC_RECORD_NO_FREE_ELU_FILTERS
MMAC_RECORD_SEMAPHORE_ERROR
MMAC_RECORD_NOT_SUPPORTED

Description
This function reserves a PID filter for later use. All enhanced features should be specified by setting
the appropriate flag for filterCapabilities at allocation time.
This function sets up a filter for record device deviceId. If the deviceId passed does not correspond to
an open record device then MMAC_RECORD_INVALID_DEVICE_ID is returned.
The function returns a unique identifier – filterId. This is used subsequently on this filter, e.g. to set
up the PID filter parameters.
The allocated recording filter can be used for the MPEG2-TS and MPEG2-PS (if the recording is
supported by the hardware). For MPEG2-TS, the recording filters are working as recording PID
filters, and for MPEG2-PS, they are working as recording Stream ID filters or as recording Sub-
Stream ID filters. One of the following types should be selected by using parameter targetIdType.
MMAC_RECORD_TS_PID Allocates a filter as PID filter.

16 / 31
 MMAC_RECORD_PS_STREAM_ID Allocates a filter as Stream ID filter.
MMAC_RECORD_PS_PRIVATE1 Allocates a filter as Sub Stream ID filter for
private_stream_1.
MMAC_RECORD_PS_PRIVATE2 Allocates a filter as Sub Stream ID filter for
private_stream_2.
If the specified target ID type is not supported by the hardware, MMAC_RECORD_NOT_
SUPPORTED will be returned.
By some EMMA devices, the number of recording PID filters which has extra functions are limited.
For efficient allocation of recording PID filters, the capabilities required for the recording PID filter
must be specified at the allocation time. The following flags can be set as recording PID filter
capabilities.
MMAC_RECORD_PES_SCRAMBLE Set if PES de-scramble facility required
MMAC_RECORD_ELU_VIDEO_EVENT Set if ELU Extended Events facility required
MMAC_RECORD_ELU_EVNET Set if an ELU compatible filter is required
(refer to the ELU API specification MMAC_ELU_SetEventMask( ) function description).
If there are no available PID filters, then the function returns MMAC_RECORD_NO_FREE_
FILTERS
If MMAC_RECORD_PES_SCRAMBLE is set and there are no more filters with this facility then
MMAC_RECORD_NO_FREE_SCRAMBLE_FILTERS will be returned.
If MMAC_RECORD_ELU_EXT_EVENT is set and there are no more filters with this facility then
MMAC_RECORD_NO_FREE_EVENT_FILTERS will be returned.
If MMAC_RECORD_ELU_EVNET is set and there are no more filters with this facility then MMAC_
RECORD_NO_FREE_ELU_FILTERS will be returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_SetPIDFilter( )
MMAC_RECORD_Start( )
MMAC_RECORD_Stop( )

Sample Code
Refer to Section 2.6.

17 / 31
MMAC_RECORD_SetPIDFilter

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_SetPIDFilter(
MMAC_RECORD_FILTER_IOPB *filterParams
);

Inputs
filterParams
A pointer to a structure in which the following fields are used as input:
pid
A 13 bit packet ID for MPEG2 TS or an 8 bit stream ID for MPEG PS.
filterId
Identifier for the filter.
editControlMode
Packet edit control mode to be applied.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_FILTER_ID
MMAC_RECORD_DEVICE_ACTIVE
MMAC_RECORD_HARDWARE_FAIL
MMAC_RECORD_NO_FREE_SCRAMBLE_FILTERS

Description
The filterId allocated by using MMAC_RECORD_AllocatePIDFilter( ) should be passed to this
function to select a recording PID filter where the function to be operated on. If the passed filterId is
not correct, MMAC_RECORD_INVALID_FILTER_ID is returned.
Note that all the PID filters for a record device should be set up before the MMAC_RECORD_
Start( ) is called. If a call to MMAC_RECORD_SetPIDFilter( ) is made when a device is active
recording, the result code MMAC_RECORD_DEVICE_ACTIVE is returned.
The parameter pid is used to set target ID value. Depending on the target ID type specified by
MMAC_RECORD_AllocatePIDFilter( ), this is automatically treated as 8bit stream ID or sub
stream ID for MPEG-PS.
The PID filter must be set to one of the four edit modes:
• Output (PID) packet untouched
• Replace specific (PID) packet with a null packet
• After specific (PID) packet, insert one or two null packets
• Edit specific (PID) by overwriting bytes. See MMAC_RECORD_SetPacketControl( ).

18 / 31
The editControlMode parameter should be set to a MMAC_RECORD_EDIT_CONTROL_MODE type
enumerator for the desired function of the packet insertion/replacement unit.
Note that these modes may not be supported by all hardware. If the hardware does not support the
specified functionality then the code MMAC_RECORD_NOT_SUPPORTED will be returned. The
hardware support for this functionality is indicated in the getCapabilities structure. See MMAC_
RECORD_GetCapabilities( ).
Note Calling this function does not automatically enable the filter filterId. To activate the filter a
call to MMAC_RECORD_EnablePIDFilter( ) must be made.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_FreePIDFilter( )
MMAC_RECORD_SetPacketControl( )
MMAC_RECORD_Start( )
MMAC_RECORD_Stop( )
MMAC_RECORD_AllocatePIDFilter( )
MMAC_RECORD_EnablePIDFIlter( )

Sample Code
Refer to Section 2.6.

19 / 31
MMAC_RECORD_FreePIDFilter

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_FreePIDFilter (
MMAC_RECORD_FILTER_ID recordFilterId
);

Inputs
recordfilterId
The identifier for the PID filter.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_FILTER_ID
MMAC_RECORD_DEVICE_ACTIVE
MMAC_RECORD_SEMAPHORE_ERROR
MMAC_RECORD_FAILED

Description
This function cancels a PID filter identified by the unique filter identifier recordFilterId.
Note that the record device should be disabled from recording, by a call to the function MMAC_
RECORD_Stop( ), before any of the PID filters are cancelled, else the result code MMAC_
RECORD_DEVICE_ACTIVE will be returned.
If the PID filter specified by recordFilterId is invalid, then the result MMAC_RECORD_INVALID_
FILTER_ID shall be returned.
If writing to the SRU hardware fails, then the result MMAC_RECORD_FAILED shall be returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_SetPIDFilter( )
MMAC_RECORD_Start( )
MMAC_RECORD_Stop( )

Sample Code
Refer to Section 2.6.

20 / 31
MMAC_RECORD_EnablePIDFilter

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_EnablePIDFilter (
MMAC_RECORD_FILTER_ID recordFilterId
);

Inputs
recordFilterId
The filter identifier.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_FILTER_ID
MMAC_RECORD_FILTER_NOT_SET
MMAC_RECORD_DEVICE_ACTIVE
MMAC_RECORD_SEMAPHORE_ERROR
MMAC_RECORD_HARDWARE_FAIL

Description
This function enables a specific PID filter identified by recordFilterId.
Note that the record device for which the filter is applied, should be stopped from recording by a call
to the function MMAC_RECORD_Stop( ), before the filter can be disabled, otherwise the return
code MMAC_RECORD_DEVICE_ACTIVE will be returned.
If the PID filter specified by recordFilterId is invalid, then the result MMAC_RECORD_INVALID_
FILTER_ID shall be returned.
If the PID filter specified by recordFilterId has not be set, then the result
MMAC_RECORD_FILTER_NOT_ SET shall be returned.
If writing to the SRU hardware fails, then the result MMAC_RECORD_HARDWARE_FAIL shall be
returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_SetPIDFilter( )
MMAC_RECORD_Start( )
MMAC_RECORD_Stop( )

Sample Code
Refer to Section 2.6.

21 / 31
MMAC_RECORD_DisablePIDFilter

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_DisablePIDFilter (
MMAC_RECORD_FILTER_ID recordFilterId
);

Inputs
recordFilterId
The filter identifier.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_FILTER_ID
MMAC_RECORD_DEVICE_ACTIVE
MMAC_RECORD_SEMAPHORE_ERROR
MMAC_RECORD_HARDWARE_FAIL

Description
This function disables a specific PID filter identified by recordFilterId.
Note that the device for which the filter is applied, should be stopped from recording by a call to the
function MMAC_RECORD_Stop( ), before the filter can be disabled, otherwise the return code
MMAC_RECORD_DEVICE_ACTIVE will be returned.
If the PID filter specified by recordFilterId is invalid, then the result MMAC_RECORD_INVALID_
FILTER_ID shall be returned.
If writing to the SRU hardware fails, then the result MMAC_RECORD_HARDWARE_FAIL shall be
returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_SetPIDFilter( )
MMAC_RECORD_Start( )
MMAC_RECORD_Stop( )

Sample Code
Refer to Section 2.6.

22 / 31
MMAC_RECORD_SetPacketControl

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_SetPacketControl(
MMAC_RECORD_EDIT_CONTROL_IOPB *editParams
);

Inputs
editParams
A pointer to a structure in which the following fields are used as input:
numberNullPackets
The number of NULL packets to be inserted into the streams.
pattern
The pattern used to overwrite bytes in packet edit mode.
wordOffset
The word offset count for packet edit mode.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_WDOFFSET
MMAC_RECORD_INVALID_NULL_NUM
MMAC_RECORD_HARDWARE_FAIL
MMAC_RECORD_NOT_SUPPORTED

Description
This function sets up the RECORD packet edit control and NULL packet insertion control. If the
hardware does not support this functionality then the code MMAC_RECORD_NOT_SUPPORTED
will be returned. The hardware support for this functionality is indicated in the getCapabilities
structure. See MMAC_RECORD_GetCapabilities( ).
The number of NULL packets to be inserted into the recording transport streams is determined by
numberNullPackets. If the number of null packets specified (normally 1 or 2) is greater than that
permitted by the hardware then the code MMAC_RECORD_INVALID_NULL_NUM is returned.
pattern is the byte value used during packet edit mode to overwrite all bytes in the TS packet from the
word specified by wordOffset to the end of the packet.
wordOffset is the word offset count from which to replace the transmitted contents of the TS packet
with the pattern byte during packet edit mode.
The maximum allowable value of wordOffset is 63, else MMAC_RECORD_INVALID_WDOFFSET
is returned. The offset numbering starts from 0, which would mean every byte in the TS packet would
be replaced with the pattern byte including the sync_byte (this is not advisable). If the word offset is
set as 1 then the last 184 bytes are replaced leaving the four byte header.

23 / 31
Pattern Insert start Byte position = 4 * wordOffset
(Transport Packet byte positions numbered 0 to 187)
If writing to the SRU hardware fails, the result MMAC_RECORD_FAILED shall be returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
None.

Sample Code
N/A

24 / 31
MMAC_RECORD_TriggerNullInsert

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_TriggerNullInsert(
MMAC_DEMUX_DEVICE_HANDLE recordId
);

Inputs
recordId
The record device for which Null Packets will be inserted into the Transport Stream.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_HARDWARE_FAIL

Description
This function triggers a single shot NULL packet insertion of numberNullPackets into the recording
Transport Stream Channel specified by deviceId.
The NumberNullPackets can be set by a call to MMAC_RECORD_SetPacketControl( ).
The insert takes place after the next transport packet is sent to Write buffer. If the next filtered
transport packet sent to the buffer has an edit control mode set other than MMAC_RECORD_
OUTPUT_TS_PACKET_UNTOUCHED then the insertion by this function is delayed until a normal
packet is sent to the queue.
If the deviceId passed does not match an open device then MMAC_RECORD_INVALID_
DEVICE_ID is returned.
If writing to the SRU hardware fails, the result MMAC_RECORD_FAILED shall be returned.
The RECORD must have been initialised via a call to MMAC_RECORD_Initialise( ). If not, this
function shall return the result MMAC_RECORD_NOT_INITIALISED.

See Also
MMAC_RECORD_SetPacketControl( )

Sample Code
N/A

25 / 31
MMAC_RECORD_Start

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_Start (
MMAC_RECORD_START_IOPB *recordParams
);

Inputs
recordParams
A pointer to a structure in which the following fields are used as input:
recordId
The record device to enable recording.
outputMode
The output mode for this recording.
fileId
The file ID of the file to record to.
fileSize
The size of the specified file.
Note: If outputMode ! = MMAC_RECORD_MODE_FILE then the parameters fileId and
fileSize are ignored and may be left NULL

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_DEVICE_ACTIVE
MMAC_RECORD_HARDWARE_FAIL
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_SEMAPHORE_ERROR

Description
This function enables the record device specified by recordId to begin capturing data from its
associated input stream to memory.
If the recordId passed is invalid then MMAC_RECORD_INVALID_DEVICE_ID will be returned.
If outputMode is set to MMAC_RECORD_MODE_FILE, the record module will transfer data to the
file specified by fileId.
If outputMode is set to MMAC_RECORD_MODE_CALLBACK, the record module will not attempt to
transfer data from buffer memory to file. Instead the details of the buffer segment filled will be passed
to the host via the call back function.
Note: The parameters fileId and fileSize are ignored for all modes other than MMAC_RECORD_
MODE FILE.

26 / 31
If recording has already been started on the device deviceId, then the function will return MMAC_
RECORD_DEVICE_ACTIVE.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.
MMAC_RECORD_HARDWARE_FAIL is returned if the function was not able to set the hardware
successfully.

See Also
MMAC_RECORD_Stop( )

Sample Code
Refer to Section 2.6.

27 / 31
MMAC_RECORD_Stop

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_Stop (
MMAC_RECORD_HANDLE recordId
);

Inputs
recordId
The record device to stop recording.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED
MMAC_RECORD_DEVICE_NOT_ACTIVE
MMAC_RECORD_HARDWARE_FAIL
MMAC_RECORD_INVALID_DEVICE_ID
MMAC_RECORD_SEMAPHORE_ERROR

Description
This function stops the device recordId recording.
If the device is not currently recording then the code MMAC_RECORD_DEVICE_NOT_ACTIVE is
returned.
The RECORD API must have been initialised via a call to MMAC_RECORD_Initialise( ). If not,
this function shall return the result MMAC_RECORD_NOT_INITIALISED.
MMAC_RECORD_HARDWARE_FAIL is returned if the function was not able to set the hardware
successfully.
If an invalid recordId is passed, MMAC_RECORD_INVALID_DEVICE_ID is returned.
Note: if recordParams->recordToFile == MMAC_TRUE when calling MMAC_RECORD_Start( )
then the host should be aware that data may still be written to the file up to the point that a callback
event of type MMAC_RECORD_STOPPED is received.

See Also
MMAC_RECORD_Start( )

Sample Code
Refer to Section 2.6.

28 / 31
MMAC_RECORD_InstallCallback

Function Prototype
MMAC_RECORD_RESULT_CODE MMAC_RECORD_InstallCallback(
MMAC_RECORD_CALLBACK recordCallback
);

Inputs
recordCallback
The function to call when record events occur.

Outputs
None.

Event Notification
N/A

Returns
MMAC_RECORD_OK
MMAC_RECORD_NOT_INITIALISED

Description
This function installs a callback function. The specified function will be called when the following
events occur:
MMAC_RECORD_DISK_FULL
A record device has reached the end of the disk.
MMAC_RECORD_FILE_WRITE_FAIL
A record device was unable to write to the file.
MMAC_RECORD_EOF_REACHED
A record device has reached the end of the file.
MMAC_RECORD_TRANSFER_REQUEST
A buffer segment has been filled and the record to file flag is set to false. Therefore the
collected data pointers are attached in the MMAC_RECORD_DATA_POINTERS structure.
The MMAC_RECORD_EVENT_MESSAGE structure also contains a Boolean flag
lastTransferReq. When a recording is stopped this Flag is set to indicate the last transfer
request for that recording.
MMAC_RECORD_STOPPED
If a recording is started with recordParams->recordToFile set to MMAC_TRUE, then this
event will be triggered at the end of a recording to inform the application that this API has
finished writing to the file.
MMAC_RECORD_CRITICAL_FAIL
A critical failure has occurred on the record device. The record device will be closed and its
resources freed.
The callback function will be passed a pointer to a MMAC_RECORD_EVENT_MESSAGE structure
that contains the deviceId for which the event occurred and the event type.
If the subsystem has not been initialised, the code MMAC_RECORD_NOT_INITIALISED will be
returned.

29 / 31
See Also
None.

Sample Code
Refer to Section 2.6.

30 / 31
4 Revision History
Title: API – Record
Ref: API_Record.doc

Date Doc Details of change Ref.

Ver.
2002-11-12 0.01 First Draft based on EMMA2 API. M-NI
2003-01-06 0.02 Removed DES encryption related I/F. M-NI
2003-01-09 0.03 Doc layout reorganised. M-RJI
2003-01-16 0.04 Minor formatting edits. M-RJI
2003-03-24 0.05 Minor corrections M-JSA
2003-04-08 0.06 Modified open device function to support all packet recording M-NI
2003-07-02 0.07 Document numbers added. M-RJI
Function descriptions reorganised.
2004-02-16 1.0 Document made common across multiple devices. M-RJI
2004-02-18 1.1 Removed GetCapabilities from EMMA2 & 2+ M-RT
2004-02-18 1.11 Checked for release. M-RJI

31 / 31