5500 SW 1

EVAL-5500
Reference Design
Software
Document number: 72-OEK-310-00

EVAL-5500 Reference Software STi5500-REF 1.1
Confidential
Information furnished is believed to be accurate and reliable. However, SGS-THOMSON Microelectronics assumes no
responsibility for the consequences of use of such information nor for any infringement of patents or other rights of third
parties which may result from its use. No license is granted by implication or otherwise under any patent or patent rights
of SGS-THOMSON Microelectronics. Specifications mentioned in this publication are subject to change without notice.
This publication supersedes and replaces all information previously supplied. SGS-THOMSON Microelectronics products
are not authorized for use as critical components in life support devices or systems without express written approval of
SGS-THOMSON Microelectronics.
© 1997 SGS-THOMSON Microelectronics - All Rights Reserved
 is a registered trademark of the SGS-THOMSON Microelectronics Group

SGS-THOMSON Microelectronics GROUP OF COMPANIES
Australia - Brazil - Canada - China - France - Germany - Hong Kong - Italy - Japan - Korea - Malaysia - Malta - Morocco -
The Netherlands - Singapore - Spain - Sweden - Switzerland - Taiwan - Thailand - United Kingdom - U.S.A.
Document number: 72-OEK-310-00

Contents
Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Programmable transport interface API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1 Library functions ......................................................................................... 3
2.2 Type declarations ....................................................................................... 5
2.3 Examples ................................................................................................... 6
3 Alphabetical list of PTI functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 Device driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

4.1 I2C bus interface ...................................................................................... 44
4.2 Non-volatile memory driver ...................................................................... 48
4.3 PWM/counter module .............................................................................. 56
4.4 PCR module ............................................................................................. 61
4.5 SmartCard interface ................................................................................. 66
4.6 UART asynchronous serial controller ...................................................... 78
4.7 MPEG decoder ........................................................................................ 84
5 The GPRIM library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

5.1 GPRIM concepts ...................................................................................... 97
5.2 Definition of fonts in the GPRIM system ................................................ 102
6 Alphabetical list of GPRIM functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Confidential 1

Contents
2 Confidential

1 Introduction
1 Introduction
This document describes the main software libraries supplied for application level
programming as part of the EVAL-5500 set top box reference design. The information
in this document is advance information and is subject to change.
The libraries described are as follows:
• The programmable transport interface library is described in Chapter 2 and the
functions are described alphabetically in Chapter 3.
• The device driver libraries for driving the I2C bus interfaces, the non-volatile
memory driver, the PWM/counter module, the PCR module, the SmartCard
interface, the UART drivers, and the MPEG A/V module are described in
Chapter 4.
• The GPRIM graphics primitives library is described in Chapter 5 and the
functions are listed alphabetically and described in detail in Chapter 6. These
functions are used to provide 2 dimensional on-screen graphics and text.
Confidential 1

1 Introduction
2 Confidential

2 Programmable transport interface API
2 Programmable transport interface

API
This chapter and Chapter 3 describes the programmable transport interface (PTI) API
interface driver. This is the standard interface to demultiplexing and section filtering
functionality.
Section 2.3 provides simple examples of the use of the libraries. Chapter 3 provides a
description of the API functions.
A particular implementation of the PTI API may not all support all features, depending
on the nature of the underlying hardware. For example, there may not be audio or
video DMA support for systems processing only data, or there may be no slots
reserved for audio or video. In some implementations there will be #define state-
ments that can be used to select the particular fixed slots or keys, e.g.
PTI_SLOT_VIDEO.
2.1 Library functions

The library functions are listed in functional groups in Table 2.1 to Table 2.6. The
functions are listed in alphabetical order and fully described in Chapter 3.
Initialization and test
Function Purpose
pti_init Initialize the PTI driver.
pti_test Return a test report for the PTI.
Table 2.1 Initialization and test functions
Slot and PID management
Function Purpose
pti_allocate_dynamic_slot Allocate a dynamic slot.
pti_deallocate_dynamic_slot Deallocate a dynamic slot.
pti_set_pid Set the PID for a slot.
pti_clear_pid Stop PID capture on a slot.
pti_query_pid Given a PID find which slot (if any) is being used to capture it.
Table 2.2 Slot and PID management functions
Confidential 3

PCR management
Function Purpose
pti_set_pcr_register_fn Register the function to be called when a new PCR is ob-
tained.
pti_set_pcr_pid Set a specific PID for PCR capture.
pti_clear_pcr_pid Clear the specific PID for PCR capture.
pti_set_stc_to_next_pcr Force the STC (System Time Clock) to be updated with the
value contained in the next PCR.
pti_get_pts Get the audio video presentation timestamps.
Table 2.3 PCR management functions
Audio, video and data DMA
Function Purpose
pti_audio_dma_reset Reset the audio DMA engine.
pti_video_dma_reset Reset the video DMA engine.
pti_data_dma_reset Reset the data DMA engine.
pti_audio_dma_state Set the state of the audio DMA engine.
pti_video_dma_state Set the state of the video DMA engine.
pti_data_dma_state Set the state of the data DMA engine.
Table 2.4 Audio, video and data DMA management functions
Buffer management
Function Purpose
pti_set_buffer Set up buffering for a slot.
pti_set_consumer_ptr Inform the PTI that data has been consumed from a buffer.
pti_copy_circular_to_linear A utility function to copy the contents of the circular buffer to
a linear buffer.
pti_copy_section_to_linear A utility function to copy a section in a circular buffer to a
linear buffer.
Table 2.5 Buffer management functions
4 Confidential

Special stream-related functions
Function Purpose
pti_allocate_dynamic_key Allocate a dynamic key.
pti_deallocate_dynamic_key Deallocate a dynamic key.
pti_associate_descramble_key Associate a descrambler key to a slot.
pti_disassociate_descramble_key Disassociate a descrambler key and a slot.
pti_set_descramble_key Specify a descrambler key to be used on a stream.
pti_allocate_dynamic_filter Allocate a dynamic section filter.
pti_deallocate_dynamic_filter Deallocate a dynamic section filter.
pti_associate_section_filter Associate a section filter to a slot.
pti_disassociate_section_filter Disassociate a section filter and a slot.
pti_set_section_filter Update the section filter to be used in filtering.
Table 2.6 Special stream-related functions
2.2 Type declarations

This is the list of type declarations used by the PTI library.
typedef unsigned int key_t;
typedef unsigned int filter_t;
typedef unsigned int slot_t;
typedef unsigned int pid_t;
typedef void (*pcr_register_fn_t)(unsigned int pcr_base,

unsigned int pcr_extension,
unsigned int pcr_arrival_time );
typedef enum { discard_data = 0, transfer_data = 1 } avddma_state_t;

typedef enum
{
stream_type_null, /* ignore data, - just used for PCR */
stream_type_adapt, /* Adaptation fields - signal every field */
stream_type_raw /* for diagnostic use - signal every packet */

stream_type_pes, /* PES - signal every complete pes packet*/
stream_type_depes, /* PES - Extract body of packet, signal */
stream_type_section, /* for section data - Signal every section */

/* copies 32 bit filter id followed by data */
stream_type_section_no_cc_check,
stream_type_video, /* PES but video - DMAed */

stream_type_audio, /* PES but audio - DMAed */
stream_type_data, /* PES but data - DMAed */
} stream_type_t;
typedef void *signal_t; /* Usually a semaphore * but may be different

in different operating system environments */
typedef struct
{
Confidential 5

unsigned char *filter_bytes; /* 8 byte filter (0,3..9) */

unsigned char *filter_masks; /* 8 byte masks (0,3..9) */
int not_equal_byte_index; /* index of != match, -1 => none */
} section_filter_t;
2.3 Examples
This section gives examples of using the API.
2.3.1 Initialization
In order to initialize the PTI:
boolean error;
error = pti_init();
if( error ) report( severity_error, "Failed to init PTI" );
2.3.2 Setting up data PID

In order to initialize a PID receiving PES packets:
#define BUFFER_SIZE0x4000
unsigned char buffer[BUFFER_SIZE];
semaphore_t got_some_data;
slot_t my_slot;
unsigned char *producer;
unsigned char *consumer;
semaphore_fifo_init( &got_some_data, 0 );
error = pti_allocate_dynamic_slot( &my_slot );

if( error ) report( severity_fatal, "Can’t get a slot" );
pti_set_buffer( my_slot,
stream_type_pes,
buffer,
BUFFER_SIZE,
&producer,
&consumer,
&got_some_data );
pti_set_pid( PTI_DATA_SLOT, 42 );
In order to loop collecting data from this PID:
while ( getting_data )
{
semaphore_wait( &got_some_data);
/* Note at this point pti has updated our producer/consumer

pointers to point at the correct places in the buffer */
/* Deal with data in circular buffer,

if producer < consumer then it loops
round the endof the buffer back to the front */
/* We must update consumer ptr to its value after

we have dealt with the data, if this is not equal to
6 Confidential

the producer pointer we will be signalled again */
pti_set_consumer_ptr( consumer );
}
2.3.3 Controlling video, audio and data

The initialization of video, audio and data is handled within the PTI. The only external
controls are the DMA state and reset functions, and the set and clear PID function.
2.3.4 Setting up a section filter

In order to set up to receive section filtered data:
#define BUFFER_SIZE 0x4000
unsigned char buffer[BUFFER_SIZE];
semaphore_t got_some_data;
filter_t filter_a, filter_b;
section_filter_t filter_data1, filter_data2;
slot_t section_slot;
unsigned char *producer;
unsigned char *consumer;
semaphore_fifo_init( &got_some_data, 0 );
error = pti_allocate_dynamic_slot( &section_slot );

if( error ) report( severity_fatal, "Can’t get a slot" );
pti_set_buffer( section_slot,
stream_type_section,
buffer,
BUFFER_SIZE,
&producer,
&consumer,
&got_some_data );
error = pti_allocate_dynamic_filter( &filter_a );

if( error ) report( severity_fatal, "Can’t get a filter" );
error = pti_allocate_dynamic_filter( &filter_b );
if( error ) report( severity_fatal, "Can’t get a filter" );
pti_associate_section_filter( section_slot, filter_a );

pti_associate_section_filter( section_slot, filter_b );
.
.
.
set up both filter values
.
.
.
pti_set_section_filter( filter_a, filter_data1 );
pti_set_section_filter( filter_b, filter_data2 );
pti_set_pid( section_slot, 42 );
.
.
Confidential 7

.
Same loop as before, but using pti_copy_section_to_linear to
copy the section and identify the filter that collected the packet
8 Confidential

3 Alphabetical list of PTI functions

The following pages list in alphabetical order the functions in the PTI library of
programmable transport interface functions. The uses of the functions, some
supporting information and examples of their use are given in Chapter 2.
Confidential 9

pti_allocate_dynamic_filter Allocate a dynamic

section filter
Synopsis:
boolean pti_allocate_dynamic_filter (filter_t *filter);
Arguments:
filter_t *filter The pointer to the returned identifier of the
allocated filter.
Description:
pti_allocate_dynamic_filter allocates one of the available section filters for
use on the specified slot, several filters may be used on one slot.
Results:
Returns false if no error has occurred, and true otherwise.
See also:
pti_deallocate_dynamic_filter
10 Confidential

pti_allocate_dynamic_key Allocate a dynamic key
Synopsis:
boolean pti_allocate_dynamic_key (key_t *key);
Arguments:
key_t *key The pointer to the returned number of the
allocated key.
Description:
pti_allocate_dynamic_key allocates one of the non-reserved descramble
keys for use.
Results:
See also:
pti_deallocate_dynamic_key
Confidential 11

pti_allocate_dynamic_slot Allocate a dynamic slot.
Synopsis:
boolean pti_allocate_dynamic_slot (slot_t *slot);
Arguments:
slot_t *slot The pointer to the returned allocated slot.
Description:
pti_allocate_dynamic_slot allocates one of the non-reserved PID slots for
use.
Results:
See also:
pti_deallocate_dynamic_slot
12 Confidential

pti_associate_descramble_key Associate a
descrambler key with a slot
Synopsis:
boolean pti_associate_descramble_key (slot_t slot,
key_t key_number);
Arguments:
slot_t slot The slot to be associated.
key_t key_number The key number and A/B field.
Description:
pti_associate_descramble_key ties a slot to use a particular descramble key.
Disassociation occurs automatically when the slot is deallocated, or when the key is
deallocated, or it can be done explicitly using pti_disassociate_descramble_
key.
Results:
See also:
pti_disassociate_descramble_key
pti_set_descramble_key
Confidential 13

pti_associate_section_filter Associate a section filter

with a slot
Synopsis:
boolean pti_associate_section_filter (slot_t slot,
filter_t filter);
Arguments:
slot The slot to be associated.
filter The identifier of the filter to be associated.
Description:
pti_associate_section_filter defines a section filter to be used on a partic-
ular slot, the relationship is many to many. NOTE disassociation occurs automati-
cally when the slot is deallocated, or when the filter is deallocated, it can be also be
done explicitly using the following call.
Results:
See also:
pti_disassociate_section_filter
14 Confidential

pti_audio_dma_reset Reset the audio DMA engine
Synopsis:
boolean pti_audio_dma_reset (void);
Arguments:
None.
Description:
pti_audio_dma_reset causes the MPEG audio DMA engine to be reset, it will
also cause any associated internal DMA management process to be reset.
Results:
See also:
pti_audio_dma_state
pti_data_dma_reset
pti_video_dma_reset
Confidential 15

pti_audio_dma_state Set the state of the audio DMA engine
Synopsis:
boolean pti_audio_dma_state (avddma_state_t state);
Arguments:
avddma_state_t state The new state of the audio DMA engine.
Description:
pti_audio_dma_state controls whether audio data is transferred to the DMA
engine. The meanings of the possible values of the parameter state are given in
Table 3.1.
Value Meaning
discard_data Discard the audio data.
transfer_data Transfer the audio data to the DMA engine.
Table 3.1 Values of parameter state
Results:
See also:
pti_audio_dma_reset
pti_data_dma_state
pti_video_dma_state
16 Confidential

pti_clear_pcr_pid Clear the specific PID for PCR capture
Synopsis:
boolean pti_clear_pcr_pid (void);
Arguments:
None.
Description:
pti_clear_pcr_pid informs the PTI to stop collecting the PCR from the previ-
ously specified PID.
Results:
See also:
pti_set_pcr_pid
pti_set_pcr_register_fn
Confidential 17

pti_clear_pid Stop PID capture on a slot
Synopsis:
boolean pti_clear_pid (slot_t slot);
Arguments:
slot_t slot The slot to be cleared.
Description:
pti_clear_pid halts PID capture on the specified slot.
Results:
See also:
pti_query_pid
pti_set_pid
18 Confidential

pti_copy_circular_to_linear A utility function to copy

the contents of the circular buffer to a linear buffer
Synopsis:
boolean pti_copy_circular_to_linear (
unsigned char *circular_base,
unsigned int circular_size,
unsigned char **consumer,
unsigned char *producer,
unsigned char *linear_base,
unsigned int linear_size,
unsigned int *data_size);
Arguments:
unsigned char *circular_base The base of the circular buffer.
unsigned int circular_size The size of the circular buffer in bytes.
unsigned char **consumer A pointer to the returned updated
consumer pointer.
unsigned char *producer Producer pointer.
unsigned char *linear_base The base of the linear buffer.
unsigned char linear_size The size of the linear buffer in bytes.
unsigned char *data_size The returned number of bytes copied.
Description:
pti_copy_circular_to_linear is a utility function that copies a packet from a
circular buffer used by the PTI to a linear buffer for processing, after this function is
called, it is wise to call the pti_set_consumer_ptr function with the updated
consumer pointer as its parameter.
Results:
See also:
pti_copy_section_to_linear
pti_set_buffer
Confidential 19

pti_copy_section_to_linear A utility function to copy a

section in a circular buffer to a linear buffer
Synopsis:
boolean pti_copy_section_to_linear (
unsigned char *circular_base,
unsigned int circular_size,
unsigned char **consumer,
unsigned char *producer,
filter_t *filter,
unsigned char *linear_base,
unsigned int linear_size,
unsigned int *data_size);
Arguments:
unsigned char *circular_base The base of the circular buffer.
unsigned int circular_size The size of the circular buffer in bytes.
unsigned char **consumer A pointer to the returned consumer pointer.
unsigned char *producer Producer pointer.
filter_t *filter A pointer to the returned identifier of the
section filter that captured the packet.
unsigned char *linear_base The base of the linear buffer.
unsigned int linear_size The size of the linear buffer in bytes.
unsigned int *data_size The returned number of bytes copied.
Description:
pti_copy_circular_to_linear is a utility function that copies a packet from a
circular buffer used by the PTI to a linear buffer for processing, for a section. After
this function is called it is wise to call the pti_set_consumer_ptr function with
the updated consumer pointer as its parameter. NOTE this function copies only one
section from the buffer, and updates the consumer pointer to point after that section.
Results:
See also:
pti_copy_circular_to_linear
pti_set_buffer
20 Confidential

pti_data_dma_reset Reset the data DMA engine
Synopsis:
boolean pti_data_dma_reset (void);
Arguments:
None.
Description:
pti_data_dma_reset causes the data DMA engine to be reset. It will also cause
any associated internal DMA management process to be reset.
Results:
See also:
pti_audio_dma_reset
pti_data_dma_state
pti_video_dma_reset
Confidential 21

pti_data_dma_state Set the state of the data DMA engine
Synopsis:
boolean pti_data_dma_state (avddma_state_t state);
Arguments:
avddma_state_t state The new state of data DMA engine.
Description:
pti_data_dma_state controls whether data is transferred to the DMA engine.
The meanings of the possible values of the parameter state are given in Table 3.1.
Value Meaning
Results:
See also:
pti_audio_dma_state
pti_data_dma_reset
pti_video_dma_state
22 Confidential

pti_deallocate_dynamic_filter Deallocate a dynamic

section filter
Synopsis:
boolean pti_deallocate_dynamic_filter (filter_t filter);
Arguments:
filter_t filter The identifier of the filter to be deallocated.
Description:
pti_deallocate_dynamic_filter frees up a previously allocated section filter.
Results:
See also:
pti_allocate_dynamic_filter
Confidential 23

pti_deallocate_dynamic_key Deallocate a dynamic key
Synopsis:
boolean pti_deallocate_dynamic_key (key_t key);
Arguments:
key_t key The descramble key to be deallocated.
Description:
pti_deallocate_dynamic_key frees up a previously allocated descramble key.
Results:
See also:
pti_allocate_dynamic_key
24 Confidential

pti_deallocate_dynamic_slot Deallocate a dynamic slot.
Synopsis:
boolean pti_deallocate_dynamic_slot (slot_t slot);
Arguments:
slot_t slot The PID slot to be deallocated.
Description:
pti_deallocate_dynamic_slot frees up a previously allocated PID slot.
Results:
See also:
pti_allocate_dynamic_slot
Confidential 25

pti_disassociate_descramble_key Disassociate a
descrambler key and a slot
Synopsis:
boolean pti_disassociate_descramble_key (slot_t slot,
key_t key_number);
Arguments:
slot_t slot The slot to be disassociated.
key_t key_number The number of the key and A/B field to be
disassociated.
Description:
pti_disassociate_descramble_key disassociates a key from a slot, so this
key will no longer be used on data coming in on this slot.
Results:
See also:
pti_associate_descramble_key
pti_set_descramble_key
26 Confidential

pti_disassociate_section_filter Disassociate a
section filter and a slot
Synopsis:
boolean pti_disassociate_section_filter (slot_t slot,
filter_t filter);
Arguments:
slot_t slot The slot to be disassociated.
filter_t filter The identifier of the filter to be disassoci-
ated.
Description:
pti_disassociate_section_filter disassociates a section filter from a slot,
so this filter will no longer be used to filter data coming in on this slot.
Results:
See also:
pti_associate_section_filter
Confidential 27

pti_get_pts Get the audio video presentation timestamps
Synopsis:
boolean pti_get_pts (unsigned int *audio_pts,
unsigned int *video_pts);
Arguments:
unsigned int *audio_pts The pointer to the returned bottom 32 bits
of the audio PTS.
unsigned int *video_pts The pointer to the returned bottom 32 bits
of the video PTS.
Description:
pti_get_pts gets the presentation timestamps stored in the PTI block of some
hardware configurations.
Results:
See also:
pti_set_stc_to_next_pcr
28 Confidential

pti_init Initialize the PTI driver.
Synopsis:
boolean pti_init (void);
Arguments:
None.
Description:
pti_init initializes the PTI driver.
Results:
See also:
pti_test
Confidential 29

pti_query_pid Query which slot (if any) is being used to capture the
PID.
Synopsis:
boolean pti_query_pid (pid_t pid,
boolean *received,
slot_t *slot);
Arguments:
pid_t pid The PID.
boolean *received The pointer to the returned flag indicating if
anyone is capturing this PID.
slot_t slot The slot on which the PID is being
captured.
Description:
pti_query_pid tells the user if a PID is being captured, and if so on what slot.
Results:
See also:
pti_clear_pid
pti_set_pid
30 Confidential

pti_set_buffer Set up buffering for a slot
Synopsis:
boolean pti_set_buffer (slot_t slot,
stream_type_t stream_type,
unsigned char *buffer_memory,
unsigned int buffer_size,
unsigned char **producer_ptr,
unsigned char **consumer_ptr,
signal_t signal);
Arguments:
slot_t slot The slot to tie the buffer to.
stream_type_t stream_type The type of stream this buffer is used for.
unsigned char *buffer_memory The memory to be used for the buffers.
unsigned char buffer_size The size of the buffer in bytes, which must
be a power of 2.
unsigned char **producer_ptr A pointer to the producer pointer.
unsigned char **consumer_ptr A pointer to the consumer pointer.
signal_t signal A semaphore or its equivalent for the
relevant operating system.
Description:
pti_set_buffer initializes a circular buffer to be used for incoming data on a
stream. The size of the buffer in bytes must be a power of 2. The PTI maintains a
producer pointer into the buffer indicating where the next input data will be stored,
the consumer (or caller of this function) maintains a consumer pointer. The PTI can
be instructed to update its copy of the consumer pointer by calling
pti_set_consumer_ptr(). NOTE when a signal has been sent indicating the
buffer is non-empty, another signal will not be sent before the user has called
pti_set_consumer_ptr().
Results:
See also:
pti_set_consumer_ptr
Confidential 31

pti_set_consumer_ptr Inform the PTI that data has been

consumed from a buffer
Synopsis:
boolean pti_set_consumer_ptr (slot_t slot,
unsigned char *consumer_ptr);
Arguments:
slot_t slot The slot that data has been consumed on.
unsigned char *consumer_ptr The new value of the consumer pointer.
Description:
pti_set_consumer_ptr informs the PTI that data has been consumed from a
buffer.
Results:
See also:
pti_set_buffer
32 Confidential

pti_set_descramble_key Specify a descrambler key to be

used on a stream
Synopsis:
boolean pti_set_descramble_key (key_t key_number,
boolean valid,
unsigned char *key);
Arguments:
key_t key_number The key number and A/B field to be used.
boolean valid Whether the key is valid or not.
unsigned char *key A pointer to the returned new key.
Description:
pti_set_descramble_key sets the descramble key to be used by the specified
slot.
Results:
See also:
pti_associate_descramble_key
pti_disassociate_descramble_key
Confidential 33

pti_set_pcr_pid Set a specific PID for PCR capture
Synopsis:
boolean pti_set_pcr_pid (pid_t pid);
Arguments:
pid_t pid The PID on which to find a PCR.
Description:
pti_set_pcr_pid informs the PTI on which PID it should look to find a PCR.
Results:
See also:
pti_clear_pcr_pid
pti_set_pcr_register_fn
34 Confidential

pti_set_pcr_register_fn Register the function to be called

when a new PCR is obtained
Synopsis:
boolean pti_set_pcr_register_fn (
pcr_register_fn_t pcr_handler);
Arguments:
pcr_register_fn_t pcr_handler The name of the function to be called.
Description:
pti_set_pcr_register_fn registers the user function to be called whenever a
PCR is received.
Results:
See also:
pti_clear_pcr_pid
pti_set_pcr_pid
Confidential 35

pti_set_pid Set the PID for a slot
Synopsis:
boolean pti_set_pid (slot_t slot, pid_t pid);
Arguments:
slot_t slot The slot on which to capture this PID.
pid_t pid The PID to capture.
Description:
pti_set_pid specifies which PID is to be captured on the specified slot.
Results:
See also:
pti_clear_pid
36 Confidential

pti_set_section_filter Update the section filter to be used

in filtering
Synopsis:
boolean pti_set_section_filter (filter_t filter,
section_filter_t filter_data);
Arguments:
filter_t filter The identifier of the filter to be updated.
section_filter_t filter_data The new filter data to be used.
Description:
pti_set_section_filter sets the filter data to be used in section filtering on
the specified filter identifier.
Results:
See also:
pti_associate_section_filter
pti_disassociate_section_filter
Confidential 37

pti_set_stc_to_next_pcr Update the STC from the next

PCR
Synopsis:
boolean pti_set_stc_to_next_pcr (void);
Arguments:
None.
Description:
pti_set_stc_to_next_pcr forces the STC (System Time Clock) to be updated
with the value contained in the next PCR.
Results:
See also:
pti_get_pts
38 Confidential

pti_test Return a test report for the PTI.
Synopsis:
boolean pti_test (char *report, unsigned int report_length);
Arguments:
char *report The pointer to the string buffer to receive a
test report.
unsigned int report_length The size of the report buffer in bytes.
Description:
pti_test puts a test report in the report buffer. The size of the report is limited by
the buffer length supplied in the call.
Results:
See also:
pti_init
Confidential 39

pti_video_dma_reset Reset the video DMA engine
Synopsis:
boolean pti_video_dma_reset (void);
Arguments:
None.
Description:
pti_video_dma_reset causes the MPEG video DMA engine to be reset. It will
also cause any associated internal DMA management process to be reset.
Results:
See also:
pti_audio_dma_reset
pti_data_dma_reset
pti_video_dma_state
40 Confidential

pti_video_dma_state Set the state of the video DMA engine
Synopsis:
boolean pti_video_dma_state (avddma_state_t state);
Arguments:
avddma_state_t state The new state of video DMA engine.
Description:
pti_video_dma_state controls whether video data is transferred to the DMA
engine or discarded. The meanings of the possible values of the parameter state
are given in Table 3.1.
Value Meaning
Results:
See also:
pti_audio_dma_state
pti_data_dma_state
pti_video_dma_reset
Confidential 41

42 Confidential

4 Device driver functions

This chapter describes the device drivers for the simpler peripheral devices, namely
the I2C interfaces, Non-Volatile Memory driver, PWM/counter module, PCR module,
SmartCard interface, UART drivers, and MPEG A/V module . All the binary code is in
the library file drivers.lib.
Confidential 43

4.1 I2C bus interface

This section describes the functions used to drive a High-speed Synchronous Serial
Interface (SSC) to an I2C bus.
The driver uses an I2C interface identifier of type i2c_handle_t. The identifier is
passed into each function call that uses the I2C interface and identifies the definition
and all the state of the interface, including its address, interrupt handler, baud rate and
whether it is a master. This information is initialized by i2c_init using data passed
in as an i2c_params_t parameter input structure.
The header file for this structure and the function prototypes is i2c.h.
The functions provided to support the I2C bus interface are listed in Table 4.1.
Function Description
i2c_init Initialize the I2C interface.
i2c_read Read from the I2C bus.
i2c_write Write to the I2C bus.
Table 4.1 I2C interface driver functions
44 Confidential

i2c_init Initialize the I2C interface
Synopsis:
#include <i2c.h>
boolean i2c_init (i2c_params_t *params,

i2c_handle_t *handle)
Description:
Initialize the I2C semaphores, interrupt handlers, identifier and parameters from the
data supplied in the structure params.
Arguments:
i2c_params_t *params I2C initial parameter data.
i2c_handle_t *handle Returned initialized I2C interface identifier.
The i2c_params_t struct is defined in i2c.h and contains the fields shown in
Table 4.2.
Field Type Description
volatile Base address of the I2C interface.
i2c_base unsigned
int *
volatile Base address of the PIO.
pio_base unsigned
int *
i2c_interrupt int CPU interrupt number.
i2c_interrupt CPU interrupt level.
int
_level
master boolean true if the device is an I2C bus master or false otherwise.
baud_rate int The I2C bus baud rate.
max_retries int The maximum number of retries for a read or write.
Table 4.2 Fields of i2c_params_t parameter structure
Results:
Confidential 45

i2c_read Read from the I2C bus
Synopsis:
#include <i2c.h>
boolean i2c_read(i2c_handle_t handle, unsigned char address,

unsigned char *buffer, int maximum_length,
int *actual_length)
Description:
Read into buffer from a device on the I2C bus at address.
Arguments:
i2c_handle_t handle I2C interface identifier.
unsigned char address Address of the device on the I2C bus.
unsigned char *buffer A pointer to the returned input data.
int maximum_length The maximum number of bytes to read.
int *actual_length A pointer to the returned actual number of
bytes read.
Results:
46 Confidential

i2c_write Write to the I2C bus
Synopsis:
#include <i2c.h>
boolean i2c_write(i2c_handle_t handle, unsigned char address,

unsigned char *buffer, int length,
int *actual_length)
Description:
Send the data in buffer to the device on the I2C bus at address.
Arguments:
i2c_handle_t handle I2C interface identifier.
unsigned char address The address of the device on the I2C bus.
unsigned char *buffer The buffer containing the data to send.
int length The number of bytes to send.
int *actual_length A pointer to the returned actual number of
bytes sent.
Results:
Confidential 47

4.2 Non-volatile memory driver

This section describes the functions used to manage the memory in an EEPROM.
The driver has two modes of operation:
• direct access functions to read and write the EEPROM memory with no
imposed structure, and
• managed segments of memory with initialization, access and read/write func-
tions.
A managed segment uses a C interface identifier of type nvm_handle_t. The identi-
fier is obtained from an access function, and passed into read and write functions
addressing the memory. When using the managed approach to EEPROM memory the
driver must be initialized by calling nvm_init.
The header file for this structure and the function prototypes is nvm.h.
The functions provided to support the NVM driver are listed in Table 4.3.
nvm_access Gain access to, or create, a managed segment of NVM.
nvm_direct_read Perform a direct unmanaged read from NVM.
nvm_direct_write Perform a direct unmanaged write to NVM.
nvm_init Initialize managed access to NVM.
nvm_read Read from a managed segment of NVM.
nvm_test Provide a test report on a NVM driver.
nvm_write Write to a managed segment of NVM.
Table 4.3 NVM driver functions
48 Confidential

nvm_access Access or create an NVM region
Synopsis:
#include <nvm.h>
boolean nvm_access (unsigned int segment,

unsigned int length,
nvm_handle_t *segment_handle);
Description:
Gain access to, or create, a managed segment of NVM. Given a unique identifier of
an NVM region, nvm_access will return the handle. If the region does not exist it
will create it. This function will reset the NVM and raise a fatal error if the region
already exists but is not of the specified size.
Arguments:
unsigned int segment A unique segment identifier.
unsigned int length The length of the segment.
nvm_handle_t *segment_handle A pointer to the returned segment handle.
Results:
Returns true if the segment did not previously exist, or false otherwise.
Confidential 49

nvm_direct_read Perform direct NVM read
Synopsis:
#include <nvm.h>
boolean nvm_direct_read (unsigned int address,

unsigned int data_length,
unsigned char *data);
Description:
Perform an unmanaged read from EEPROM.
Arguments:
unsigned int address Address in EEPROM.
unsigned int data_length The number of bytes to be read.
unsigned char *data A pointer to the buffer for the received
data.
Results:
50 Confidential

nvm_direct_write Perform direct NVM write
Synopsis:
#include <nvm.h>
boolean nvm_direct_write (unsigned int address,

Description:
Perform an unmanaged write to EEPROM.
Arguments:
address The address in the EEPROM.
unsigned int data_length The number of bytes to be written.
unsigned char *data A pointer to the data to be written.
Results:
Confidential 51

nvm_init Initialize managed NVM driver
Synopsis:
#include <nvm.h>
boolean nvm_init (void);
Description:
Initialize the managed NVM data structures.
Arguments:
None.
Results:
52 Confidential

nvm_read Read from a managed NVM segment
Synopsis:
#include <nvm.h>
boolean nvm_read (nvm_handle_t segment_handle,

unsigned int segment_offset,
Description:
Read from a managed segment of NVM.
Arguments:
nvm_handle_t segment_handleThe unique segment identifier.
unsigned int segment_offsetThe offset into the segment.
unsigned int data_length The number of bytes to be read.
unsigned char *data A pointer to the buffer for the returned
data.
Results:
Confidential 53

nvm_test Give a test report
Synopsis:
#include <nvm.h>
boolean nvm_test (char *report_buffer,

unsigned int buffer_length );
Description:
Return a test report. The report will be truncated to buffer_length bytes if
necessary.
Arguments:
char *report_buffer A pointer to the buffer to store returned
report.
unsigned int buffer_length The size of the buffer in bytes.
Results:
54 Confidential

nvm_write Write to a managed segment of NVM
Synopsis:
#include <nvm.h>
boolean nvm_write (nvm_handle_t segment_handle,

unsigned int segment_offset,
Description:
Write to a managed segment of NVM.
Arguments:
nvm_handle_t segment_handle A unique segment identifier.
unsigned int segment_offset The offset into the segment.
unsigned int data_length The number of bytes to be written.
unsigned char *data A pointer to the data to be written.
Results:
Confidential 55

4.3 PWM/counter module

This section describes the functions used to drive the PWM/counter capture module
on the ST20.
The header file for this structure and the function prototypes is pwm.h.
The functions provided to support the PWM module are listed in Table 4.4.
pwm_dump_filter Display the state of the PWM.
pwm_filter Simple filter.
pwm_init Initialize the PWM module.
pwm_reset Reset the PWM module.
Table 4.4 PWM module driver functions
56 Confidential

pwm_dump_filter Display the state of the PWM
Synopsis:
#include <pwm.h>
void pwm_dump_filter (void)
Description:
Display the values in the filter context data structure for debugging purposes.
Arguments:
None.
Results:
None.
Confidential 57

pwm_filter Simple filter
Synopsis:
#include <pwm.h>
void pwm_filter (unsigned int pcr,

unsigned int capture_clock)
Description:
Perform a simple filter function. The function decides on an appropriate control
value given the latest difference value.
Arguments:
unsigned int pcr Current system clock.
unsigned int difference Capture clock value.
Results:
None.
58 Confidential

pwm_init Initialize the PWM module
Synopsis:
#include <pwm.h>
boolean pwm_init (void)
Description:
Initialize the filter context data structure and reset the PWM module hardware. This
function is for use when the ST20 is reset.
Arguments:
None.
Results:
Returns false if pwm_init has already been run, true otherwise.
Confidential 59

pwm_reset Reset the PWM module
Synopsis:
#include <pwm.h>
void pwm_reset (void)
Description:
Restart the synchronizing of the PWM filter. This function is usually used when
changing channels.
Arguments:
None.
Results:
None.
60 Confidential

4.4 PCR module

This section describes the functions used to drive the PCR on the ST20.
This module manages collection of the PCR, management of the PWM functions and
provision of an up-to-date system clock.
The header file for this structure and the function prototypes is pcr.h.
Functions supported are listed in Table 4.5
pcr_current_studio_clock Return current system clock.
pcr_init Initialize the PCR driver.
pcr_start_capturing Start capturing PCRs.
pcr_stop_capturing Stop capturing PCRs.
Table 4.5 PCR driver functions
Confidential 61

pcr_current_studio_clock Give the current system clock
Synopsis:
#include <pcr.h>
boolean pcr_current_studio_clock (unsigned int *clock_value);
Arguments:
unsigned int *clock_value Clock value.
Description:
Give the current system clock in clock_value.
Results:
Returns true if no valid PCR is available on which to base the system clock,
false otherwise.
62 Confidential

pcr_init Initialize the PCR driver
Synopsis:
#include <pcr.h>
boolean pcr_init (void)
Arguments:
None.
Description:
Initializes the PCR driver.
Results:
Confidential 63

pcr_start_capturing Start capturing PCRs
Synopsis:
#include <pcr.h>
boolean pcr_start_capturing (void);
Arguments:
None.
Description:
Starts capturing PCRs. Before PCR capture is started the function
pcr_current_studio_clock always returns true.
Results:
64 Confidential

pcr_stop_capturing Stop capturing PCRs
Synopsis:
#include <pcr.h>
boolean pcr_stop_capturing (void);
Arguments:
None.
Description:
Stops capturing PCRs. This will invalidate the currently held PCR and
pcr_current_studio_clock will return true until capturing is restarted and a
new PCR has been captured.
Results:
Confidential 65

4.5 SmartCard interface

This section describes the functions used to drive a SmartCard interface on the ST20
for smart cards compliant with the ISO7816-3 standard. NDC extensions to the
ISO7816-3 are also supported. The SmartCard interface includes a UART to commu-
nicate with the SmartCard and a PIO to control the state of the other connections to
the SmartCard.
The driver uses a SmartCard interface identifier of type smart_handle_t. The iden-
tifier is called the SmartCard handle. It is returned when the interface is initialized and
then passed into each function call that uses that SmartCard interface. The handle
structure identifies the definition and all the state of the interface, including the base
addresses, interrupt handlers and speeds. This information is initialized by
smart_init using data passed in as a smart_params_t parameter input structure.
The header file for this structure and the function prototypes is smart.h.
The functions provided to support the SmartCard interface are listed in Table 4.6.
smart_deactivate Deactivate the SmartCard interface.
smart_get_procedure_byte Read procedure byte from the SmartCard interface.
smart_init Initialize the SmartCard interface.
smart_pts Perform a protocol type selection on the SmartCard.
smart_receive Read from the SmartCard interface.
smart_reset Reset the SmartCard interface.
smart_send Write to the SmartCard interface.
smart_status
smart_to_command Issue a protocol T=0 command on the SmartCard interface.
Table 4.6 SmartCard interface driver functions
66 Confidential

smart_deactivate Disable the smart card
Synopsis:
#include "smart.h"
boolean smart_deactivate (smart_handle_t handle)
Description:
Deactivate the smart card, removing the power supply and all other connections.
Arguments:
smart_handle_t handle Identifier handle to access the SmartCard.
Results:
Errors:
An error code of true is returned if an invalid handle is used.
Confidential 67

smart_get_procedure_byte Get procedure bytes
Synopsis:
#include "smart.h"
boolean smart_get_procedure_byte (smart_handle_t iohandle,

unsigned char INS,
unsigned char reply[2],
int *reply_length_p)
Description:
Read one or two procedure bytes, when using protocol T=0.
Smart cards reply to a command sent from the interface with a procedure byte, as
defined in ISO 7816-3. The instruction code is the second byte of the 5-byte
command. The function discards NULL characters that are sent by the card.
Arguments:
unsigned char INS The instruction code for which we are
getting the procedure byte.
unsigned char reply[2] Returned reply from the SmartCard inter-
face.
int *reply_length Returned reply length.
Results:
Errors:
An error code of true is returned if:
• an invalid handle is used,
• bad characters are received or
• a communication error is detected.
See also:
smart_t0_command
68 Confidential

smart_init Initialize the smart card
Synopsis:
#include "smart.h"
boolean smart_init(smart_params_t *params,

smart_handle_t *handle_p)
Description:
Perform all the actions needed to initialize the ST20 hardware in order to drive a
smart card. smart_init also registers and installs the appropriate interrupt
handler.
Arguments:
smart_params_t *params A pointer to a structure containing all the
smart card parameters.
smart_handle_t *handle_p A pointer to the returned identifier handle
to access the SmartCard.
The parameters structure smart_params_t is defined in smart.h and contains
the fields shown in Table 4.7.
The SmartCard interface must supply a clock during reset, called the initial clock.
The initial clock is described by the Fs_xxx fields in the parameters structure.The
smart card may have an internal clock for subsequent use, in which case
ext_clock should be set to false. Otherwise an external subsequent clock is
needed, so ext_clock should be set to true and the external clock should be
described by the Fs_xxx fields in the parameter structure.

smart_base unsigned int* Base address of the smart card register.
Base address of the UART associated with Smart-
ASC_base unsigned int*
Card.
PIO_base unsigned int* Base address of the PIO associated with SmartCard.
smart_detect_ CPU interrupt number for the PIO.
short
interrupt
smart_detect_ CPU interrupt level for the PIO.
short
interrupt_level
ASC_interrupt short CPU interrupt number for the UART.
ASC_interrupt_level short CPU interrupt level for the UART.
cpu_frequency int CPU frequency in Hz.
false if the SmartCard has an internal clock, or
ext_clock boolean
true if the card needs an external clock after reset.
Table 4.7 Fields of smart_params_t structure
Confidential 69


true indicates an external clock connected to pin
Fi_clock_source boolean PIO bit 2 will be used as the initial clock, and false
indicates the CPU clock will be used.
The initial clock divider. The initial input clock frequen-
Fi_clock_divider short
cy is divided by twice this value.
Initial clock frequency in Hz supplied to the Smart-
Fi_clock unsigned int
Card.
true indicates an external clock connected to pin
PIO bit 2 will be used as the subsequent clock, and
Fs_clock_source boolean
false indicates the CPU clock will be used. This
parameter is only used if ext_clock is true.
The subsequent clock divider. The subsequent input
Fs_clock_divider short clock frequency is divided by twice this value. This
parameter is only used if ext_clock is true.
Subsequent clock frequency in Hz supplied to the
Fs_clock unsigned int SmartCard. This parameter is only used if
ext_clock is true.
true if the driver supports the NDC extension to the
ndc boolean
ISO-7816 standard, or false otherwise.
Table 4.7 Fields of smart_params_t structure

Results:
Errors:
An error code of true is returned if a memory allocation failure occurs.
70 Confidential

smart_pts Perform a PTS request
Synopsis:
#include "smart.h"
boolean smart_pts (smart_handle_t handle,

unsigned char *pts_request)
Description:
Perform a smart card protocol selection.
Arguments:
unsigned char *pts_request Up to three byte array which holds the PTS
request without the first byte (0xFF) and
the check character.
Results:
Errors:
An error code of true is returned if protocol errors occurs.
Confidential 71

smart_receive Read data from the smart card
Synopsis:
#include "smart.h"
booleansmart_receive (smart_handle_t iohandle,

unsigned char*buffer,
int len,
int *actlen)
Description:
Receive a block of data bytes from the smart card using the current parameters.
Arguments:
unsigned char *buffer Data buffer where the returned read data
will be put.
int len Number of bytes wanted.
int *actlen Pointer to the returned number of bytes
actually read.
Results:
Errors:
An error code of true is returned if using an invalid handle or on receiving error
See also:
smart_send
72 Confidential

smart_reset Reset the smart card
Synopsis:
#include "smart.h"
boolean smart_reset (smart_handle_t handle,

unsigned char *atr,
int *atr_size);
Description:
Perform the smart card reset phase, getting the Answer-to-reset from the card.
Arguments:
smart_handle_t handle The identifier handle to access the Smart-
Card.
unsigned char *atr A buffer where the Answer to reset is
returned.
int *atr_size A pointer to the returned length of the
Answer to reset buffer.
Results:
Errors:
An error code of true is returned if no answer is received from the card.
Confidential 73

smart_send Send data to the smart card
Synopsis:
#include "smart.h"
boolean smart_send (smart_handle_t handle,

unsigned char *buffer,
int len,
int *actlen)
Description:
Send a block of bytes to the smart card using the current parameters.
Arguments:
unsigned char *buffer The data buffer.
int len The data buffer length.
int *actlen A pointer to the returned number of bytes
actually sent.
Results:
Errors:
An error code of true is returned if an invalid handle is used or if transmission
errors are detected.
See also:
smart_receive
74 Confidential

smart_status Return the smart card status
Synopsis:
#include <smart.h>
boolean smart_status (iohandle_t handle,

smart_status_t *status);
Description:
Return the current status of the smart card driver.
Arguments:
iohandle_t handle Identifier handle to access the SmartCard.
smart_status_t *status Output parameter to return the smart card
status.
The smart_status_t structure are defined in smart.h and contains the fields
shown in Table 4.8. The error codes are defined in smart.h and are shown in
Table 4.9.
inserted boolean true if the smart card is inserted and false otherwise.
smart_operation The code of the last error that occurred. The codes are listed in
error
_error_t Table 4.9.
Table 4.8 smart_status_t status structure
Error code Description

SMART_NO_ERROR No error.
SMART_WRONG_TS_CHAR Got the wrong TS during ATR.
SMART_TOO_MANY_RETRIES The byte has been resent too many times.
SMART_OVERRUN_ERROR A byte has been received before reading the previous.
SMART_PARITY_ERROR Parity error during communication.
SMART_FRAME_ERROR Frame error during communication.
SMART_PTS_NOT_SUPPORTED The card does not support PTS.
SMART_NO_ANSWER Procedure byte has not been received.
SMART_INVALID_STATUS_BYTES_SEQ Invalid byte sequence while getting the procedure byte.
UENCE
SMART_UNSUPPORTED_CLASS The card does not support the instruction class.
SMART_INVALID_CODE The card does not support the instruction code.
SMART_INCORRECT_REFERENCE The reference in the command was incorrect.
Table 4.9 SmartCard status error codes
Confidential 75

Error code Description

SMART_INCORRECT_LENGTH The length in the command is incorrect.
SMART_UNKNOWN_ERROR Unknown error in the command.
SMART_NOT_INSERTED The card is not inserted.
SMART_NOT_RESET The card has not yet been reset.
SMART_INVALID_PROTOCOL The protocol selected is different from protocol 0.
SMART_USER_ABORT The operation has been aborted by the user.
SMART_BAD_COMMAND The command sent to the card is badly formed.
Table 4.9 SmartCard status error codes

Results:
Returns true if an error has occurred, and false otherwise.
Errors:
An error code of true is returned if an invalid handle is used.
76 Confidential

smart_t0_command Perform a command
Synopsis:
#include "smart.h"
boolean smart_t0_command (smart_handle_t handle,

unsigned char *command,
unsigned char *reply,
int *reply_length_p)
Description:
Execute a protocol T=0 command on the smart card, getting the reply from the card.
Subsequent procedure bytes can be obtained using smart_get_procedure_
byte.
Arguments:
smart_handle_t handle The identifier handle to access the Smart-
Card.
unsigned char *command A 5-byte array containing the command to
be sent to the card.
unsigned char *reply A pointer to the returned reply from the
card.
int *reply_length A pointer to the returned length of the
reply.
Results:
Errors:
An error code of true is returned if
• an invalid handle is used,
• the command is badly formed or
• a communication error is detected.
See also:
smart_get_procedure_byte, smart_send, smart_receive
Confidential 77

4.6 UART asynchronous serial controller

This section describes the functions used to drive a general purpose UART asynchro-
nous serial controller (ASC) on the ST20.
The driver uses a UART interface identifier of type uart_handle_t. The identifier is
passed into each function call that uses the UART interface and identifies the defini-
tion and the state of the interface, including the mode, base address, interrupt handler,
speed, parity and stop bits. This information is initialized by uart_init and may be
changed by uart_setparams. The definition data is passed into uart_init or
uart_setparams in the form of a uart_params_t parameter input structure.
The header file for this structure and the function prototypes is uart.h.
The functions provided to support the UARTs are listed in Table 4.10.
uart_flush_buffer Flush the UART input buffer
uart_init Initialize a UART
uart_read Read from a UART
uart_setparams Change the parameters for a UART
uart_status Get the status of a UART
uart_write Write to a UART
Table 4.10 UART driver functions
78 Confidential

uart_flush_buffer Initialize a UART
Synopsis:
#include <uart.h>
boolean uaer_flush_buffer (uart_handle_t handle)
Description:
Flush from the UART read-ahead buffer any characters stored there.
Arguments:
uart_handle_t handle UART identifier.
Results:
Confidential 79

uart_init Initialize a UART
Synopsis:
#include <uart.h>
boolean uart_init (uart_params_t *params,

uart_handle_t *handle)
Description:
Initialize the UART semaphores, interrupt handler, buffers, identifier and parameters
from the parameters in params.
Arguments:
uart_params_t *params UART initial parameters.
uart_handle_t *handle Returned UART identifier.
The uart_params_t struct is defined in uart.h and contains the fields shown in
Table 4.11. See uart.h for the possible values of stop_bits and parity.

volatile unsigned Base address of UART interface.
uart_base
int *
uart_interrupt int CPU interrupt number.
uart_interrupt_level int CPU interrupt level.
baud_rate int UART transmission baud rate.
stop_bits int Stop bits.
parity int What parity checking is to be used.
flow_control boolean Whether flow control is enabled.
loopback_test boolean Whether test mode is enabled.
Table 4.11 Fields of uart_params_t parameter structure
Results:
80 Confidential

uart_read Read from a UART
Synopsis:
#include <uart.h>
boolean uart_read (uart_handle_t handle,

int maximum_length, int *actual_length,
int timeout_period)
Description:
Read up to maximum_length bytes from the UART into buffer.
Arguments:
unsigned char *buffer Buffer for input data.
int maximum_length Maximum number of bytes of input data.
int *actual_length Actual number of bytes of input data.
int timeout_period Time-out in units of 10msecs. Zero means
no time-out.
Results:
Confidential 81

uart_setparams Change the parameters for a UART
Synopsis:
#include <uart.h>
boolean uart_setparams (uart_handle_t handle,

uart_params_t *params)
Description:
Change the parameters for a UART without resetting it.
Arguments:
uart_params_t *params New UART parameters.
Results:
82 Confidential

uart_write Write to a UART
Synopsis:
#include <uart.h>
boolean uart_write (uart_handle_t handle,

int length, int *actual_length)
Description:
Write length bytes from buffer to the UART.
Arguments:
unsigned char *buffer Buffer containing output data.
int length Number of bytes to send.
int *actual_length Returned actual number of bytes sent.
Results:
Confidential 83

4.7 MPEG decoder

NOTE: This is an interim release of the MPEG driver library for EVAL-5500
Reference Software Release STi5500-REF 1.1 .
84 Confidential

mpeg_channel_change Decode a new channel
Synopsis:
#include <st_api.h>
boolean mpeg_channel_change (pid_t pidVideo,

pid_t pidAudio,
pid_t pidPcr)
Arguments:
pid_t pidVideo pid containing video.
pid_t pidAudio pid containing audio.
pid_t pidPcr pid containing PCR.
Results:
Returns false if no error, true otherwise.
Description:
mpeg_channel_change is the highest level function for starting decoding on a
new channel. It initialises and starts full decoding with the given pids.
Confidential 85

mpeg_disable Disable full decode
Synopsis:
#include <st_api.h>
void mpeg_disable (void)
Arguments:
None.
Description:
Turns off the display and calls mpeg_disable_video_decode and
mpeg_disable_audio_decode.
Note: If separate treatment is needed for audio and video, use
mpeg_disable_video_decode and mpeg_disable_audio_decode directly.
See also:
mpeg_disable_video_decode, mpeg_disable_audio_decode
86 Confidential

mpeg_disable_audio_decode Disable audio decoding
Synopsis:
#include <st_api.h>
void mpeg_disable_audio_decode (void)
Arguments:
None.
Description:
Mutes audio and resets the decoding task.
Note: mpeg_disable_audio_decode should be used only if a separate
treatment is needed for audio and video; if this is not the case mpeg_disable
should be used.
See also:
mpeg_disable
Confidential 87

mpeg_disable_video_decode Disable video decoding
Synopsis:
#include <st_api.h>
void mpeg_disable_video_decode (void)
Arguments:
None.
Description:
Freezes the display on the last I or P picture (top field), and resets the decoding task
and the decoder (Soft Reset + PES parser).
Note: mpeg_disable_video_decode should be used only if a separate
treatment is needed for audio and video; if this is not the case mpeg_disable
should be used.
See also:
mpeg_disable
88 Confidential

mpeg_enable Enable full decode
Synopsis:
#include <st_api.h>
void mpeg_enable (boolean enable_video, boolean enable_audio)
Arguments:
boolean enable_video Whether the function actually enables
video decode.
boolean enable_audio Whether the function actually enables
audio decode.
Description:
Resets the decoder and calls mpeg_enable_video_decode and
mpeg_enable_audio_decode.
Note: If separate treatment is needed for audio and video, use
mpeg_enable_video_decode and mpeg_enable_audio_decode directly.
See also:
mpeg_enable_video_decode, mpeg_enable_audio_decode
Confidential 89

mpeg_enable_audio_decode Enable audio decoding
Synopsis:
#include <st_api.h>
void mpeg_enable_audio_decode (boolean enable_audio)
Arguments:
boolean enable_audio Whether the function actually enables
audio decode.
Description:
Resets, initialises and starts the decoding task.
Note: mpeg_enable_audio_decode should be used only if a separate treatment
is needed for audio and video; if this is not the case mpeg_enable should be used.
See also:
mpeg_enable
90 Confidential

mpeg_enable_video_decode Enable video decoding
Synopsis:
#include <st_api.h>
void mpeg_enable_video_decode (boolean enable_video)
Arguments:
boolean enable_video Whether the function actually enables
video decode.
Description:
Resets, initialises and starts the decoding task.
Note: mpeg_enable_video_decode should be used only if a separate treatment
is needed for audio and video; if this is not the case mpeg_enable should be used.
See also:
mpeg_enable
Confidential 91

mpeg_live_reset_process Do a live reset of decode process
Synopsis:
#include <st_api.h>
void mpeg_live_reset_process (void)
Arguments:
None.
Description:
Stops and immediately restarts the decoding process. This is used to reset the
process without stopping the decoder when a serious error is encountered.
92 Confidential

mpeg_mute_audio Disable sound
Synopsis:
#include <st_api.h>
void mpeg_mute_audio (void)
Arguments:
None.
Description:
Disables audio output.
Confidential 93

mpeg_set_audio_volume Set the audio volume
Synopsis:
#include <st_api.h>
void mpeg_set_audio_volume (unsigned int volume)
Arguments:
unsigned int volume Value between 0 and 63.
Description:
Sets the volume of the audio output of the decoder. 0 is lowest volume, 63 is highest
volume.
94 Confidential

mpeg_unmute_audio Enable sound
Synopsis:
#include <st_api.h>
void mpeg_unmute_audio (void)
Arguments:
None.
Description:
Enables audio output.
Confidential 95

96 Confidential

5 The GPRIM library
5 The GPRIM library

The GPRIM library provides an on-screen graphics capability for the EVAL-5500
reference design. This document details the implementation for the STi5500 MPEG
decoder chip.
This chapter is split into sections. Section section 5.1 provides a description of GPRIM
concepts. Readers familiar with 2D computer graphics systems may choose to skip
these sections. Section section 5.2 provides an explanation of the text font format.
Detailed descriptions of the GPRIM library functions in an alphabetical listing can be
found in Chapter 12.
5.1 GPRIM concepts

GPRIM provides a set of graphical primitive functions and attribute functions for
production of on-screen graphics using the STi5500 MPEG2 video decoder.
GPRIM graphical primitive functions are those functions that define the geometric
components of a picture. The graphics primitive functions defined in the CGI standard
fall into the following categories:
• line;
• marker;
• text;
• filled area;
• image;
• generalized drawing primitive (GDP).
GPRIM attribute functions determine the appearance of the graphical primitive func-
tions. Attributes are either individual or ‘bundleable’. This means that either an
attribute must be applied individually, or it may be combined with others and then
applied. In addition there are two functions to control the mixing of video data and on-
screen graphics.
Confidential 97

5 The GPRIM library
5.1.1 The GPRIM library

The GPRIM functions are supplied in source form, in the files listed in Table 5.1 and
Table 5.2. Table 5.3 to Table 5.10 summarize the GPRIM functions available. The main
header file gprim.h should be included in the application code.
Source file Contents
circleN.c Arc and circle drawing and filling.
copyN.c Copying.
gprim.c Line drawing functions.
gprimglb.c Global variables used by the library functions.
generalN.c Short library utilities.
linestyN.c Styled lines.
otextN.c Overlaid text.
paintN.c Filling and searching.
palette.c Palette control.
pelN.c Pel drawing.
region.c Region management
rtextN.c Rotated text.
text.c & textN.c Unrotated text.
Table 5.1 Source files
Header file Contents
colours.h RGB color values.
fontxx.h Fonts of different sizes.
gprim.h Main header file.
gprimi.h & Headers used internally in the libraries.
gprimiN.h
gprimlib.h Prototypes and xterms for fonts.
gprimtyp.h Types.
memory.h Define memory available to implementation
textN.h Macros for text functions.
Table 5.2 Header files
98 Confidential

5 The GPRIM library
Line functions
gprim_line Draw a straight line.
gprim_styled_line Draw a line at an angle with specified pixel values.
gprim_rect Draw a rectangle outline.
gprim_polyline Draw consecutive line segments.
gprim_disjpolyline Draw straight line segments.
gprim_polygon Draw a polygon outline.
gprim_circle Draw an ellipse outline.
gprim_arc Draw a partial ellipse outline.
gprim_arcc Draw a closed partial ellipse outline.
gprim_dot Plot a single point.
Table 5.3 Line functions
Text functions
gprim_max_chars_in_width Truncate string to pixel width.
gprim_text Print text at position.
gprim_textsize Find width of text in pixels.
gprim_addtext Add text at current position.
gprim_rotatedtext Print text at an angle.
gprim_overstrike_addtext Add text at current position preserving background.
gprim_overstrike_text Print text preserving background.
gprim_chrbegin Set character position.
gprim_chrspace Set character spacing.
gprim_setfont Set up the current character font.
Table 5.4 Text functions
Filled area functions
gprim_cls Clear the screen.
gprim_frect Draw a filled rectangle.
gprim_fcircle Draw a filled ellipse.
gprim_paint Flood fill an area.
Table 5.5 Filled area functions
Confidential 99

5 The GPRIM library
Image functions
gprim_getimage Save image copy.
gprim_putimage Put image copy.
gprim_copy Copy region of a screen.
gprim_search Search for color change.
gprim_setpel Set custom pel pattern.
gprim_setpelstyle Set custom pel pattern.
gprim_pel Put pel on screen.
Table 5.6 Image functions
Graphic/video mixing functions
gprim_set_colour_mixing_mask Specify which colors to mix with video.
gprim_set_colour_mixing_weight Specify how colors are mixed with video.
Table 5.7 Graphic/video mixing functions
Color specification and selection
gprim_setbcol Specify the background color.
gprim_setfcol Specify the foreground color.
gprim_setpalette Set palette entry.
Table 5.8 Color specification and selection
Control functions
gprim_init Initialize GPRIM system.
gprim_reset Reset GPRIM, delete all regions.
gprim_standby Set OSD in standby mode.
gprim_out_of_standby Take OSD out of standby mode.
gprim_display Enable/disable OSD.
gprim_query Discover dimensions of current region.
gprim_create_region Create a drawable region.
gprim_set_draw_region Specify region to draw to.
gprim_display_region Add region to, or remove from, display list.
gprim_move_region_to Update the display position of a region.
Table 5.9 Control functions
5.1.2 Initializing GPRIM

The GPRIM system must be initialized by gprim_init before any other GPRIM
functions are called. It may be re-initialized by calling gprim_reset.
100 Confidential

5 The GPRIM library
5.1.3 Screen
All GPRIM operations are performed onto the current drawable region in sti5500
memory, there is no default region, regions must be created by the application, and
selected for drawing. The entire on-screen display (OSD) is enabled or disabled by the
function gprim_display, and regions may be added to, or removed from, the display
by use of the gprim_display_region function. The function gprim_set_draw_
region selects the region where the drawing will take place. These functions can be
used together to control whether or not the graphics are displayed while drawing is
being done.
The display can be put in standby mode by gprim_standby and returned to normal
by gprim_out_of_standby. Initially the display is in standby mode.
5.1.4 Coordinates
Graphics and text elements can be placed anywhere within a region. The coordinates
for placing the elements are shown in Figure 5.1, with the origin at the top left corner
of the region. The first coordinate is the horizontal distance in pixels from the left side
and the second coordinate is the vertical distance in pixels down from the top of the
region. Regions may have different sizes, and a different number of bits per pixel.
(0, 0)
y pixels
(x, y)
x pixels
Figure 5.1 Screen coordinates
5.1.5 Color
Drawing, filling and text are all in the foreground color, possibly mixed with the under-
lying video data. The foreground color is set by gprim_setfcol. The background
Confidential 101

5 The GPRIM library
color is used to fill the region when the region is cleared, possibly mixed with the
underlying video data, and is set by gprim_setbcol.
The OSD implementation of GPRIM uses 4/8-bit pixels, resulting in regions containing
up to 15/255 different colors plus transparent. Pixel values are used to address a color
palette, which is a table to generate for each pixel value the actual display color from a
possibly larger range. Each entry in the color palette is defined by using the function
gprim_setpalette.
In the STi5500, on-screen graphics can be mixed with video. The default is that an on-
screen pixel non-zero value completely overwrites the underlying video data. However
some or all of the palette colors can be mixed with underlying video data to produce
semi-transparent graphics or text. The two graphic/video mixing functions specify the
palette entries that are to be combined and the weighting of the resultant mix toward
video or OSD data.
5.1.6 Pel drawing

A pel is a two-dimensional pattern of pixel values. The pel pattern is established with
gprim_setpel and plotted in the screen region using the gprim_pel function. Pels
are useful for repeatedly plotting customized shapes such as cursors, bullet marks,
icons, buttons, or rounded corners for rectangles.
5.1.7 Text
A current text position in a region is maintained, which is the coordinates of the top left
corner of the next text character. This is initialized by some text drawing functions or it
can be initialized explicitly by gprim_chrbegin. It is updated whenever text is drawn,
allowing for the width of the characters, the spacing between characters and the angle
of the text line. The text is drawn in the foreground color using the current font.
Defining the current font is described in section section 5.2. NOTE the position is lost
when you switch to a new drawable region.
5.2 Definition of fonts in the GPRIM system

Text fonts are specified to GPRIM with gprim_setfont. This defines bitmaps for the
various character cells that make up the font. Because the GPRIM system stores a
pointer to the font, it should reside in code space as constant static data. Only one font
is known by GPRIM at a time; if an application requires the use of multiple fonts then it
will have to load each one as and when needed.
A default font is supplied with the GPRIM software. It contains a variable width ASCII
character set defined within a sixteen by sixteen pixel character cell. This is set up
during the call to gprim_init. It is also available by including the file font16.h,
which contains the font. This font can be specified with the following statement:
gprim_setfont(font16, font16_width,
font16_NCHARS, font16_FAMW, font16_FAMH,
font16_FWPC, font16_FLPW);
102 Confidential

5 The GPRIM library
A font may have a fixed character width or a variable character width, in which case
the width is different for each character. Variable character widths are defined as an
array parameter to gprim_setfont. If the character widths are set to NULL then a
fixed character width is used. The inter-character spacing for a fixed character width
font, both vertical and horizontal, is defined by gprim_chrspace. This writes the
fixed width into each element of the font width array.
When specifying a font, the gprim_setfont function requires various font character-
istics to be defined, as shown in Table 5.10. These specify, for example, the number of
32-bit words used to hold the bit pattern of a single character cell.
Font parameter Purpose
font Actual character bitmaps
font_width Array containing width for each character
nchars Number of characters in the font
famw Font area memory width (in bits)
famh Font height (in rows)
fwpc Number of 32-bit words per character
flpw Number of character lines per 32-bit word
Table 5.10 Font characteristics
If necessary, the programmer can define additional fonts or convert existing fonts from
some other environment into this format.
Confidential 103

5 The GPRIM library
104 Confidential

6 Alphabetical list of GPRIM functions

The following pages list the functions in the GPRIM library of graphics primitives. The
use of all these functions is described in Chapter 5.
Confidential 105

gprim_addtext Append text at the current character position
Synopsis:
void gprim_addtext (int n, char *str)
Arguments:
int n Number of characters to plot.
char *str Character string.
Description:
gprim_addtext plots n characters from the character string str according to the
current font description. Characters are plotted at the current character position
which is then incremented. If the font is a variable width font then only the X position
is incremented by the width of the character. If the font is not variable width then the
X and Y positions are incremented by the inter-character spacing distances
specified to gprim_chrspace. The current character position after the operation
completes is offset from the last character plotted by these distances.
Characters are reproduced at the size of the current font, as set by
gprim_setfont. Bits set in the font description are plotted in the foreground color,
set using gprim_setfcol. Clear bits are plotted in the background color, set by
gprim_setbcol.
Diagram:
str[0] str[1] str[2] str[3]
= current character position

= Individual character widths/current inter-character spacing
See also:
gprim_overstrike_addtext gprim_chrspace gprim_setfont
gprim_setfcol gprim_setbcol
106 Confidential

gprim_arc Outline part of an axis-aligned ellipse
Synopsis:
void gprim_arc (int Xc, int Yc, int A, int B,
int start_angle, int end_angle)
Arguments:
int Xc,int Yc Centre coordinates.
int A Length of X direction semi axis.
int B Length of Y direction semi axis.
int start_angle Angle of start of arc.
int end_angle Angle of end of arc.
Description:
gprim_arc plots part of the outline of an axis-aligned ellipse centered at (Xc,Yc)
and with semi-axis lengths of A and B pixels. Both A and B must be positive; the
larger of the two values is the semi-major axis length, while the smaller specifies the
semi-minor axis length.
start_angle and end_angle define which portion of the circle/ellipse to draw.
These angles are normalized so that 0x10000 represents 360 degrees, and the arc
is drawn anti-clockwise from the right hand horizontal semi-axis of the ellipse. For
example the following diagram shows an arc of an ellipse with start angle 0xe000
and end angle 0x2000.
Diagram:
X
Y
start_angle
A end_angle
(Xc,Yc)
A = X direction semi axis

B = Y direction semi axis
Confidential 107

gprim_arcc Outline part of an axis-aligned ellipse, closed with a chord or

segment line
Synopsis:
void gprim_arcc (int Xc, int Yc, int A, int B,
int start_angle, int end_angle,
int CloseMode)
Arguments:
int start_angle Angle of start of arc.
int end_angle Angle of end of arc.
int CloseMode Close mode.
Description:
gprim_arcc plots part of the outline of an axis aligned ellipse centered at
(Xc,Yc) and with semi-axis lengths of A and B pixels. Both A and B must be
positive; the larger of the two values is the semi-major axis length, while the smaller
specifies the semi-minor axis length.
start_angle and end_angle define which portion of the circle/ellipse to draw.
These angles are normalized so that 0x10000 represents 360 degrees, and the arc
is drawn anti-clockwise from the right hand horizontal semi-axis of the ellipse. For
example the following diagram shows an arc of an ellipse with start angle 0xe000
and end angle 0x2000.
The partial outline is closed with either:
• a single chord line, joining the two end points, or
• a pair of segment lines, connecting each end point to the centre of the ellipse
at (Xc,Yc).
The value of CloseMode determines which method is used. Valid values are given
in the following table:
CloseMode Comment
CM_CHORD Close outline with a chord line
CM_SEGMENT Close outline with two segment lines
108 Confidential

Diagram:
X
Y
start_angle
A end_angle
(Xc,Yc)

B = Y direction semi axis CloseMode = CM_CHORD
Y
start_angle
A end_angle
(Xc,Yc)

B = Y direction semi axis CloseMode = CM_SEGMENT
See also:
gprim_arc gprim_circle
Confidential 109

gprim_chrbegin Set the current character display position
Synopsis:
void gprim_chrbegin (int X, int Y)
Arguments:
int X,int Y Character position coordinates.
Description:
gprim_chrbegin sets the current character position to (X,Y). The next text
operation will start plotting characters at this position. All text operations update the
current character position as characters are plotted.
110 Confidential

gprim_chrspace Set the current inter-character spacing for a fixed

width font
Synopsis:
void gprim_chrspace (int dX, int dY)
Arguments:
int dX X axis character spacing distance.
int dY Y axis character spacing distance.
Description:
gprim_chrspace sets the current inter-character spacing distances. These values
are used to increment the current character position, in the X and Y axis directions,
after each character is plotted from a fixed width font. dX specifies the inter-
character spacing distance in the X axis direction, dY specifies the Y axis distance.
See also:
gprim_setfont
Confidential 111

gprim_circle Outline an axis-aligned ellipse
Synopsis:
void gprim_circle (int Xc, int Yc, int A, int B)
Arguments:
Description:
gprim_circle plots the outline of an axis aligned ellipse centered at (Xc,Yc)
and with semi-axis lengths of A and B pixels. Both A and B must be positive, the
larger of the two values is the semi-major axis length, while the lesser specifies the
semi-minor axis length. If A and B are equal, an outline of a circle is plotted with a
diameter equal to either A or B.
Diagram:
X
(Xc,Yc) A

112 Confidential

gprim_cls Clear the screen
Synopsis:
void gprim_cls (int color)
Arguments:
int color Color.
Description:
gprim_cls clears the entire screen area to the color specified by color.
Confidential 113

gprim_copy Copy a region of one screen to another region of the same or

the other screen
Synopsis:
void gprim_copy (gprim_screen_t source,
int xstart, int ystart, int xsize, int ysize,
gprim_screen_t destination,
int xdstart, int ydstart)
Arguments:
gprim_region_t source Source region.
int xstart, int ystart Coordinates of region to be copied.
int xsize Width of region to be copied.
int ysize Height of region to be copied.
gprim_region_t destination Destination region.
int xdstart, int ydstart Coordinates of destination.
Description:
gprim_copy provides a function for copying rectangular regions around and
between the regions defined by calls to gprim_create_region, supplying NULL
as a region will result in a copy to/from the current drawable region.
114 Confidential

gprim_create_region Create a drawable region
Synopsis:
#include "gprim.h"
boolean gprim_create_region (gprim_region_t *region,

int xstart,
int ystart,
int xend,
int yend,
int bits_per_pixel);
Description:
Create a region suitable for drawing into, and optionally displaying. The function
takes co-ordinates for display based on a notional screen (PAL 720x625) (NTSC
720x525). When drawing in the region, top left is (0,0).
Arguments:
gprim_region_t *region Pointer to returned region id.
int xstart X coordinate of starting corner of region.
int ystart Y coordinate of starting corner of region.
int xend X coordinate of ending corner of region.
int yend X coordinate of ending corner of region.
int bits_per_pixelPixel size, 4/8 bits
Results:
Returns true if an error has occurred, false otherwise
Diagram:
X
(xstart, ystart)
(xend, yend)
Confidential 115

gprim_disjpolyline Draw a sequence of disjoint lines
Synopsis:
void gprim_disjpolyline (int n, int *points)
Arguments:
int n Number of (X, Y) points.
int *points List of line start and end points.
Description:
gprim_disjpolyline draws a sequence of disjoint (unconnected) straight lines
between points defined by the integer vector points.
The points listed in points are alternately a start point followed by an end point. The
lines are drawn from each start point to the immediately following end point. Each
coordinate is used only once, as either a line start point or as an end point. The first
coordinate contained in points is always treated as a line start point and the next
its corresponding end point. The ith line is drawn from the point (points[4*i],
points[(4*i)+1]) to the point (points[(4*i)+2], points[(4*i)+3]).
The number of points is given by n which will usually be even, because a line is
described by two points. If n is odd a single point is plotted instead of the last line. If
n is 1 only a single point is plotted.
Diagram:
X
(points[0], points[1])
Y
n=4
116 Confidential

gprim_display Enable or disable the OSD display
Synopsis:
boolean gprim_display (gprim_enable_disable_t flag)
Arguments:
gprim_enable_disable_t flag OSD_enable or OSD_disable flag.
Description:
gprim_display enables or disables the OSD.
Confidential 117

gprim_display_region Add/remove region from/to display list
Synopsis:
boolean gprim_display_region (gprim_region_t region,
gprim_enable_disable_t flag)
Arguments:
gprim_region_t region Region to add or remove
gprim_enable_disable_flag flagAdd or remove?
Description:
gprim_display_region Is used to dynamically add or remove regions to or from
the screen.
See also:
gprim_display for enabling and disabling the display of OSD screens.
gprim_set_draw_region for controlling which region is currently being drawn to.
118 Confidential

gprim_dot Plot a point
Synopsis:
void gprim_dot (int X, int Y)
Arguments:
int X, int Y Coordinates of point.
Description:
gprim_dot plots a single point at (X,Y).
Diagram:
(X,Y)
Confidential 119

gprim_fcircle Draw a filled, axis-aligned, ellipse
Synopsis:
void gprim_fcircle (int Xc, int Yc, int A, int B)
Arguments:
int Xc,int Yc Centre coordinate.
Description:
gprim_fcircle plots a filled, axis aligned, ellipse centered at (Xc,Yc) and with
semi-axis lengths of A and B pixels. Both A and B must be positive; the larger of the
two values is the semi-major axis length, while the lesser specifies the semi-minor
axis length. A filled circle is plotted with a diameter equal to either A or B, if they
have identical values.
Diagram:
A
(Xc,Yc)

120 Confidential

gprim_frect Draw a filled, axis-aligned, rectangle
Synopsis:
void gprim_frect (int X0, int Y0, int X1, int Y1)
Arguments:
int X0,int Y0 Corner point coordinate.
int X1,int Y1 Opposite point coordinate.
Description:
gprim_frect plots a filled, axis aligned, rectangle between two diagonally
opposite points specified by the coordinates (X0,Y0) and (X1,Y1).
Diagram:
(X0,Y0)
Y
(X1,Y1)
Confidential 121

gprim_getimage Save a region of the screen to the image buffer
Synopsis:
void gprim_getimage (int XS, int YS, int XE, int YE)
Arguments:
int XS,int YS Top left hand coordinate of screen region.
int XE,int YE Bottom right hand coordinate of screen
region.
Description:
gprim_getimage copies a region of the screen memory to the image buffer, this
allows saving of screen regions when an alert box needs to be displayed, or the
copying of regions about the screen.
See also:
gprim_putimage
122 Confidential

gprim_init Initialize the GPRIM library
Synopsis:
boolean gprim_init (void)
Arguments:
none
Description:
gprim_init initializes the GPRIM system to the following state:
• Setup default variable width16-bit text font
• No current pel style
• No palette
• Clear screen
• Set OSD in standby
Confidential 123

gprim_line Draw a straight line between two points
Synopsis:
void gprim_line (int X0, int Y0, int X1, int Y1)
Arguments:
int X0,int Y0 Start point coordinate.
int X1,int Y1 End point coordinate.
Description:
gprim_line plots a straight line between two points specified by the coordinates
(X0,Y0) and (X1,Y1).
Diagram:
(X1,Y1)
Y
(X0,Y0)
124 Confidential

gprim_max_chars_in_width Fit string to pixel width
Synopsis:
int gprim_max_chars_in_width (int max_number_of_chars,
const char *text,
unsigned int width,
unsigned int *trimmed_width)
Arguments:
int max_number_of_chars Number of characters in the string.
const char *text String to be fitted.
unsigned int width Maximum line length in pixels.
unsigned int *trimmed_width Returned fitted line length in pixels.
Description:
gprim_max_chars_in_width takes a string of length max_number_of_chars
and returns the number of characters that will fit in a space of width pixels. The
string is not changed.
Confidential 125

gprim_out_of_standby Bring the OSD hardware out of standby

mode
Synopsis:
boolean gprim_out_of_standby (void)
Arguments:
none
Description:
gprim_out_of_standby performs any required hardware functions to take the
OSD hardware out of standby mode. This leaves the OSD disabled, since it may not
be required to display anything.
See also:
gprim_standby
126 Confidential

gprim_overstrike_addtext Append text at the current

character position
Synopsis:
void gprim_overstrike_addtext (int n, char *str)
Arguments:
Description:
gprim_overstrike_addtext plots n characters from the character string str
according to the current font description. Characters are plotted at the current
character position which is then incremented. If the font is a variable width font then
only the X position is incremented by the width of the character. If the font is not
variable width then the X and Y positions are incremented by the inter-character
spacing distances specified to gprim_chrspace. The current character position
after the operation completes is offset from the last character plotted by these
distances.
Characters are reproduced at the size of the current font, as set by
set using gprim_setfcol. This function differs from gprim_addtext in that clear
bits retain the background values of the current draw screen. This function is much
slower than gprim_addtext and it should be used sparingly.
See also:
gprim_addtext gprim_chrspace gprim_setfont gprim_setfcol
Confidential 127

gprim_overstrike_text Plot text at a specified position,

preserving the background
Synopsis:
void gprim_text (int X, int Y, int n, char *str)
Arguments:
int X,int Y Start coordinate.
Description:
gprim_overstrike_text plots n characters from the character string str
according to the current font description. Characters are plotted at the current
character position which is then incremented. If the font is a variable width font then
only the X position is incremented by the width of the character. If the font is not
variable width then the X and Y positions are incremented by the inter-character
spacing distances specified to gprim_chrspace. The current character position
after the operation completes is offset from the last character plotted by these
distances.
Characters are reproduced at the size of the current font which is set using
set by gprim_setfcol. This function differs from gprim_text in that clear bits
retain the background values of the current draw screen. This function is much
slower than gprim_text and it should be used sparingly.
See also:
gprim_text gprim_chrspace gprim_setfont gprim_setfcol
128 Confidential

gprim_paint Paint (flood fill) a bounded region
Synopsis:
void gprim_paint (int Xs, int Ys, int Bcol)
Arguments:
int Xs,int Ys Interior point coordinate.
int Bcol Boundary color.
Description:
gprim_paint flood fills a bounded region. The region is specified by a boundary of
constant color Bcol and filling starts at an interior point given by the coordinate
(Xs,Ys). If the pixel at this point already has the value Bcol then no filling occurs.
The current foreground color may be equal to the defined boundary color if required.
The fill region is clipped to the screen.
Diagram:
(Xs,Ys)
Bcol
Confidential 129

gprim_pel Plot a pel
Synopsis:
void gprim_pel (int X, int Y)
Arguments:
int X, int Y Coordinates of pel.
Description:
gprim_pel plots a pel, placing its origin at (X,Y).
Diagram:
Different shadings represent

different colours in the pel
130 Confidential

gprim_polygon Outline a polygon
Synopsis:
void gprim_polygon (int n, int *points)
Arguments:
int n Number of (X,Y) points.
int *points List of polygon vertex points.
Description:
gprim_polygon plots the outline of a polygon by drawing a sequence of
connected, straight lines, between its vertex points. The polygon’s last vertex point
is connected to its first to complete the outline. The coordinate of the point i is given
by the integer pair (points[2*i], points[(2*i)+1]) taken from the vector
points. The number of points is specified by n. Lines are drawn in the same order
as they are listed in points. If only one coordinate is present, or if all the points are
coincident, then a single point is plotted.
Diagram:
X (points[2],points[3])
Y(points[0],points[1])
(points[4],points[5])
n=5 (points[6],points[7])
Confidential 131

gprim_polyline Draw a sequence of connected lines
Synopsis:
void gprim_polyline (int n, int *points)
Arguments:
int n Number of (X,Y) points.
int *points List of line start and end points.
Description:
gprim_polyline draws a sequence of straight lines connecting the points defined
by the integer vector points. The number of points is specified by n. The coordi-
nate of the ith point are given by the integer pair (points[2*i],
points[(2*i)+1]). A line is drawn between each pair of coordinates and the
following pair. The drawing order is defined by the order of the coordinates in
points. The resulting continuous line is called a polyline.
Diagram:
X
(points[0],points[1]) (points[4],points[5])
(points[8],points[9]) (points[6],points[7])
n=5
132 Confidential

gprim_putimage Copy the contents of the image buffer to the screen
Synopsis:
void gprim_putimage (int X, int Y)
Arguments:
int X,int Y Top left hand coordinates of where to put
the buffer on screen.
Description:
gprim_putimage copies the contents of the image buffer to the screen.This allows
restoration of screen regions after display of an alert box, using (XS,YS) supplied
to gprim_getimage as (X,Y) for gprim_putimage, or the copying of previously
saved regions about the screen by supplying the destination as (X,Y) for
gprim_putimage, see gprim_getimage.
Confidential 133

gprim_query Discover the dimensions of the current draw screen region
Synopsis:
void gprim_query (int *xsize, int *ysize)
Arguments:
int *xsize Returned width of drawable area.
int *ysize Returned height of drawable area.
Description:
gprim_query provides information about the current region allowing graphics to
be sized based on the size of the current draw region.
134 Confidential

gprim_rect Outline an axis-aligned rectangle
Synopsis:
void gprim_rect (int X0, int Y0, int X1, int Y1)
Arguments:
int X0,int Y0 Corner point coordinates.
int X1,int Y1 Opposite point coordinates.
Description:
gprim_rect plots an outline of an axis aligned rectangle between two diagonally
opposite points specified by the coordinates (X0,Y0) and (X1,Y1).
Diagram:
(X0,Y0)
Y
(X1,Y1)
Confidential 135

gprim_reset Reset GPRIM, delete all regions
Synopsis:
#include "gprim.h"
boolean gprim_reset (void);
Arguments:
none.
Results:
Returns true if an error is detected, false otherwise
136 Confidential

gprim_rotatedtext Plot text at a specified position, and at a

specified angle to the horizontal
Synopsis:
void gprim_text (int X, int Y, int angle, int n, char *str)
Arguments:
int X,int Y Start coordinates.
int angle Angle from horizontal.
Description:
gprim_rotatedtext plots n characters from the character string str according
to the current font description. Characters are plotted at an angle from the current
character position which is then incremented. The angle is normalized so that
0x10000 represents 360 degrees, and 0 gives normal horizontal text.
Characters are reproduced at the size of the current font which is set by
gprim_setfont. Bits set in the font description are plotted in the foreground color;
set by gprim_setfcol. Clear bits are plotted in the background color, set by
gprim_setbcol.
Diagram:
X
Y str[3]
str[2]
str[1]
str[0]
(X, Y)
n=4
Confidential 137

gprim_search Scan a horizontal line segment for color change
Synopsis:
int gprim_search (int Xs, int Ys,
int Bcol, int sense, int direction)
Arguments:
int Xs,int Ys Search point coordinate.
int Bcol Color transition.
int sense Search criterion S_WHILENOT or
S_WHILEGOT.
int direction Search direction S_LEFT or S_RIGHT.
Results:
gprim_search returns xposn.
Description:
gprim_search is used to discover where on a horizontal line, a particular color
change occurs. The start point for the search is specified by the coordinate
(Xs,Ys), and the search occurs along a horizontal line drawn through that point.
The search proceeds in one of two directions - either to the left of the start point, or
to its right, as specified by direction. Valid search direction values for
direction are given in the following table:
Search direction value Meaning
S_LEFT Search left of start point
S_RIGHT Search right of start point
If sense is set to S_WHILENOT then searching continues until a pixel of the transi-
tion color Bcol is discovered. If sense is set to S_WHILEGOT then searching
continues until a pixel of some other color is found. The search criterion sense
defines which method to use. Valid search criterion values are given in the following
table:
Search test value Meaning
S_WHILENOT Search until a pixel of color Bcol is discovered
S_WHILEGOT Search until a pixel not equal in color to Bcol is discovered
138 Confidential

Diagram:
Current drawable
X
S_LEFT (Xs,Ys) S_RIGHT
Confidential 139

gprim_set_colour_mixing_mask Specify which colors are

to be mixed with video to produce the final TV display
Synopsis:
void gprim_set_colour_mixing_mask (unsigned int *mask)
Arguments:
unsigned int *mask Pointer to bit mask indicating colors to be
mixed.
Description:
gprim_set_colour_mixing_mask sets a mask indicating which colors, in the
palette, are to be mixed with the video signal on the TV display. Each palette entry
(1..15 for 4 bit, 1..255 for 8 bit) has an associated bit in the mask. If the mask bit is
set for a particular color, then that color will be mixed with the video according to the
value of the current mixing weight, set by gprim_set_colour_mixing_weight.
If a bit is not set for a particular color, then any pixels of that color on the display will
completely override the video display at that pixel. The bits in the mask are ordered
such that word 0 contains bits 0..31, word1 bits 32..63 etc.
140 Confidential

gprim_set_colour_mixing_weight Specify how

graphics and video pixels are to be mixed to produce the final TV display
Synopsis:
void gprim_set_colour_mixing_weight (unsigned int weight)
Arguments:
unsigned int weight Weight to be given to graphics pixels.
Description:
gprim_set_colour_mixing_weight specifies how video and graphic pixels,
that are to be mixed, are mixed. The weight may have a value between 0 and 15
inclusive. At 0 the video pixel completely overrides the graphic, while at 15 the
graphic pixel completely overrides the video. Between these values the two pixel
values are combined to form a composite pixel value according to the weighting
value. See gprim_set_colour_mixing_mask for controlling which colors are to
be mixed.
Confidential 141

gprim_set_draw_region Set the current draw region
Synopsis:
boolean gprim_set_draw_region (gprim_region_t region)
Arguments:
gprim_region_t region Region to select.
Description:
gprim_set_draw_region sets the current drawing area to be region, which
must have been created using gprim_create_region. All future calls to GPRIM
drawing primitives will take place on the specified screen until this routine is called
to select the other drawing screen.
Note: different draw screens may have different dimensions, and different numbers
of bits per pixel depending on the system configuration. See gprim_query for
discovering the current region dimensions.
See also:
gprim_display_region for controlling the display of this region.
142 Confidential

gprim_setbcol Set the current background color
Synopsis:
void gprim_setbcol (int Bcol)
Arguments:
int Bcol Background color.
Description:
gprim_setbcol sets the current background color to Bcol.
Confidential 143

gprim_setfcol Set the current foreground color
Synopsis:
void gprim_setfcol (int Fcol)
Arguments:
int Fcol Foreground color.
Description:
gprim_setfcol sets the current foreground color to Fcol.
144 Confidential

gprim_setfont Set the current text font
Synopsis:
BOOLEAN gprim_setfont (unsigned int *packfont,
unsigned char *charact_widths,
int nchars, int famw, int famh,
int fwpc, int flpw)
Arguments:
unsigned int *packfont Encoded font.
unsigned char *charact_widths Array containing individual character
widths, all set to NULL for a fixed width
font.
int nchars Number of characters in font.
int famw Width of unpacked character in bits.
int famh Height of unpacked character in bits.
int fwpc Number of 32-bit words per character.
int flpw Number of encoded rows per 32-bit word.
Results:
Returns FALSE if the font was loaded successfully, TRUE otherwise.
Description:
gprim_setfont records a font description into the GPRIM server. Only one font
may be active at any one instant so this operation will overwrite any existing font
description held by GPRIM. Since gprim_setfont records a pointer to the font
data the function needs no memory to store the font. Currently gprim_setfont
handles only 8- and 16-bit fonts; any other width will return an error status.
Fonts are described by an integer vector which contains a packed representation of
each character contained in the font, and for variable width fonts an array containing
the width of each character. A font can contain any number of characters.
A bit mask is used to represent each character cell; this has a constant width and
height for all the characters of the same font. Bits are listed in horizontal scan line
order for each character; a one bit represents a colored pixel and a zero bit the
background. The bit masks for each character are packed into a number of 32-bit
words, these are then concatenated to produce the packed font. The order defines
how characters are retrieved from the font; the integer value of a character is used
as the index of the corresponding character cell within the font array. If ASCII text
representation is required then the font should contain character descriptions at
positions that correspond to the ASCII encoding.
packfont is an integer vector that describes a font containing nchars characters.
character_widths is an array of unsigned bytes that define the width of each
Confidential 145

character for a variable width font; passing NULL in this parameter gives a fixed
width font of size 8 or 16, as passed in famw.
Character cells are described by the parameters famw, famh, fwpc and flpw. The
width of the bitmap is given by famw; this specifies the number of bits to use per
horizontal row. The height of the bitmap is given by famh; this gives the number of
rows per character in the font. Each bit defines whether a foreground or background
pixel is plotted. fwpc is the number of 32-bit words required to encode one
character cell and flpw is the number of horizontal rows encoded per word.
All text operations use the current font description.
Section 5.2 in Chapter 5 describes the defining of fonts in more detail.
146 Confidential

gprim_setpalette Set a palette entry
Synopsis:
boolean gprim_setpalette (int palette_index,
int red, int green, int blue)
Arguments:
int palette_index Entry in palette.
int red Red color value.
int green Green color value.
int blue Blue color value.
Description:
gprim_setpalette sets an entry in the color palette. palette_index is will be
used as a pixel value and must be in the range 1..15 for 4 bit regions, and 1..255 for
8 bit regions, since zero is reserved for transparent. The three color values must be
in the range 0..255. NOTE gprim_setpalette now only applies to the current
draw region.
Confidential 147

gprim_setpel Set the current customized pel style
Synopsis:
void gprim_setpel (const int pel_xsize, const int pel_ysize,
const gprim_pel_format_t pel_format,
const unsigned int *pel_data,
const unsigned char *pel_mask,
const int pel_xorig, const int pel_yorig)
Arguments:
const int pel_xsize Width of pel style in pixels.
const int pel_ysize Height of pel style in pixels.
const gprim_pel_format_t pel_format
Specify form of pel_data
const unsigned int *pel_data Pel style pixel data.
const unsigned char
*pel_mask Pel style pixel mask.
const int pel_xorig Horizontal offset from top left corner to
origin of pel.
const int pel_yorig Vertical downwards offset from top left
corner to origin of pel.
Description:
gprim_setpel sets the current pel style. Pel styles are represented by a two
dimensional pattern which can be plotted on the screen with gprim_pel.
The size of the pel pattern is given by pel_xsize pixels in the horizontal direction,
and pel_ysize pixels vertically.
The pel style is described by the vector pel_data, which should contain, in hori-
zontal row order, each row of pixels that make up the custom pel pattern, or a run
length encoding of the rows.
pel_format has two possible values (at this time):
• packed_pel
Data is stored in 32 bit words, i.e. each 4 bit pixel is stored as a nibble (4 bits)
of an unsigned integer with zero padding at the end of each row. For example,
a row of 11 pixels with values 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and 11 would be
packed as 0x12345678, 0x9ab00000, similarly for 8 bit pixels, but with each
word holding only 4 pixels.
• run_length_encoded_pel
Each row is encoded separately. The formats differ for 4- and 8-bit pels:-
• 4 Bit
A sequence of bytes where each byte has a count (top 4 bits), and a
148 Confidential

value (bottom 4 bits). If the count is zero then the value is shifted up by
4 and ORed with the next count field, allowing up to 255 pixels to be
specified in 2 bytes. The value field will be repeated count times.
• 8 Bit
A sequence of byte pairs where the first byte is the count and the
second is the value.
NOTE because of the above format differences 8- and 4-bit pels are not inter-
changeable.
The mask pel_mask allows pels to have a shape other than a rectangle by allowing
the background to show in some pixels. The mask has one bit for each pixel, in the
same order as the data, with each row padded to an 8 bit (byte) boundary. Bits set
to 1 set the corresponding pixel to the color of the pel while bits set to 0 set the
corresponding pixel to the color of the background. Unused pixels are set to 0. If the
mask is NULL then all pel pixels will be visible and the pel will be rectangular.
The pel style has a single point, located within its bulk, that identifies an origin. Pels
are plotted such that their origins are positioned at the coordinate of the replaced
point. (pel_xorig, pel_yorig) defines the origin of the pel style as an offset
from the base of its two dimensional pattern, which is at the top left hand corner.
pel_yorig Origin of pel
pel_ysize
pel_xorig
pel_xsize
Confidential 149

gprim_standby Set the OSD hardware into standby mode
Synopsis:
boolean gprim_standby (void)
Arguments:
none
Description:
gprim_standby disables the display, and performs any hardware related function
to set the OSD hardware into standby mode.
See also:
gprim_out_of_standby
150 Confidential

gprim_styled_line Plot a line at a specified position, and at a

specified angle to the horizontal, with supplied pixel data
Synopsis:
void gprim_styled_line (int X, int Y, int angle,
int n, unsigned int *data)
Arguments:
int X,int Y Start coordinates.
int angle Angle.
int n Number of pixels to plot.
unsigned int *data Pixel data values.
Description:
gprim_styled_line plots n pixels taking pixel values from memory pointed to by
data. The line is plotted at an angle from the horizontal. The angle is normalized so
that 0x10000 represents 360 degrees, and 0 gives normal horizontal line.
Confidential 151

gprim_text Plot text at a specified position
Synopsis:
void gprim_text (int X, int Y, int n, char *str)
Arguments:
int X,int Y Start coordinate.
Description:
gprim_text plots n characters from the character string str according to the
current font description. Characters are plotted at the current character position
which is then incremented. If the font is a variable width font then only the X position
is incremented by the width of the character. If the font is not variable width then the
X and Y positions are incremented by the inter-character spacing distances
specified to gprim_chrspace. The current character position after the operation
completes is offset from the last character plotted by these distances.
Characters are reproduced at the size of the current font which is set by
set by gprim_setfcol. Clear bits are plotted in the background color, set by
gprim_setbcol.
Diagram:
Y
(x,y)
str[0] str[1] str[2] str[3]
n = 4
= current character position
= Individual character widths/current inter-character spacing
152 Confidential

gprim_textsize Calculate the width of a text string for positioning

purposes
Synopsis:
int gprim_textsize (int n, char *str)
Arguments:
Results:
gprim_textsize returns the width of the text string str in pixels.
Description:
This function takes a string and calculates its width. It is provided to assist in the use
of variable width fonts and allows the user to center text on the screen.
Confidential 153

154 Confidential


5500 SW 1

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

5500 SW 1

Uploaded by

Copyright:

Available Formats

EVAL-5500

Document number: 72-OEK-310-00

 is a registered trademark of the SGS-THOMSON Microelectronics Group

Document number: 72-OEK-310-00

2 Programmable transport interface API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Alphabetical list of PTI functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Device driver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5 The GPRIM library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

6 Alphabetical list of GPRIM functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

2 Programmable transport interface

2.1 Library functions

Initialization and test

Special stream-related functions

2.2 Type declarations

typedef void (*pcr_register_fn_t)(unsigned int pcr_base,

typedef enum { discard_data = 0, transfer_data = 1 } avddma_state_t;

stream_type_raw /* for diagnostic use - signal every packet */

stream_type_section, /* for section data - Signal every section */

stream_type_video, /* PES but video - DMAed */

typedef void *signal_t; /* Usually a semaphore * but may be different

unsigned char *filter_bytes; /* 8 byte filter (0,3..9) */

2.3.2 Setting up data PID

error = pti_allocate_dynamic_slot( &my_slot );

/* Note at this point pti has updated our producer/consumer

/* Deal with data in circular buffer,

/* We must update consumer ptr to its value after

the producer pointer we will be signalled again */

2.3.3 Controlling video, audio and data

2.3.4 Setting up a section filter

error = pti_allocate_dynamic_slot( &section_slot );

error = pti_allocate_dynamic_filter( &filter_a );

pti_associate_section_filter( section_slot, filter_a );

3 Alphabetical list of PTI functions

pti_allocate_dynamic_filter Allocate a dynamic

pti_allocate_dynamic_key Allocate a dynamic key

pti_allocate_dynamic_slot Allocate a dynamic slot.

pti_associate_section_filter Associate a section filter

pti_audio_dma_reset Reset the audio DMA engine

pti_audio_dma_state Set the state of the audio DMA engine

pti_clear_pcr_pid Clear the specific PID for PCR capture

pti_clear_pid Stop PID capture on a slot

pti_copy_circular_to_linear A utility function to copy

pti_copy_section_to_linear A utility function to copy a

pti_data_dma_reset Reset the data DMA engine

pti_data_dma_state Set the state of the data DMA engine

pti_deallocate_dynamic_filter Deallocate a dynamic

pti_deallocate_dynamic_key Deallocate a dynamic key

pti_deallocate_dynamic_slot Deallocate a dynamic slot.

pti_get_pts Get the audio video presentation timestamps

pti_init Initialize the PTI driver.

pti_set_buffer Set up buffering for a slot

pti_set_consumer_ptr Inform the PTI that data has been

pti_set_descramble_key Specify a descrambler key to be

pti_set_pcr_pid Set a specific PID for PCR capture

pti_set_pcr_register_fn Register the function to be called

pti_set_pid Set the PID for a slot

pti_set_section_filter Update the section filter to be used

pti_set_stc_to_next_pcr Update the STC from the next

pti_test Return a test report for the PTI.

pti_video_dma_reset Reset the video DMA engine

pti_video_dma_state Set the state of the video DMA engine

4 Device driver functions

4.1 I2C bus interface

typedef void signal_t; / Usually a semaphore * but may be different

unsigned char filter_bytes; / 8 byte filter (0,3..9) */