DOC

Opus_ApplicationGuidebook

By Alan Black,2014-04-23 17:23
11 views 0
Opus_ApplicationGuidebook

    OPUS Application

     Programmers Guide

    Version 00.04

    SW-OPUS_APP_GUIDE -02070111

    July 03, 2002

    Copyright ? 2002 by TECHFAITH Telecom Corp. All Right Reserved. This document and the information contained in it is CONFIDENTIAL INFORMATION of TechFaith Telecom, and shall not be used, or published, or disclosed, or disseminated outside of TechFaith Telecom in whole or in part without TechFaith telecom’s consent. This document contains trade secrets of TechFaith Telecom. Reverse engineering of any or all of the information in this document is prohibited. The copyright notice does not imply publication of this document.

    2 OPUS Application Programmers Guide REVISION HISTORY

    Version Date Name Reason 00.01 07/02/2002 Paul Seo Initial Creation

    00.02 07/02/2002 Jane Kim Add Event Manager technical description 00.03 07/03/2002 Stanley Park Merge AM/EM

    00.04 07/05/2002 Jane Kim Add system utility functions

     Revised OPUS_FOCUS_CUST_PAINT event Steven Lai introduction; add

    OPUS_FOCUS_CUST_APP_PAUSE,

    OPUS_FOCUS_PEN, OPUS_FOCUS_OPERATION;

SW-OPUS_APP_GUIDE-02070111 TechFaith Confidential Proprietary

    OPUS Application Programmers Guide 3 CONTENTS

    INTRODUCTION ............................................................................................................... 6 INTRODUCTION ............................................................................................................... 6 1.1 PURPOSE AND SCOPE ............................................................................................... 6 1.2 REFERENCES ........................................................................................................... 6 1.3 DEFINITIONS, ACRONYMS, AND ABBREVIATIONS.......................................................... 6 2 EVENT MANAGER ...................................................................................................... 7 3 OPUS EM DETAIL DESCRIPTION .............................................................................. 9 3.1 EVENT CATEGORY .................................................................................................... 9

    3.1.1 Description ................................................................................................................. 9

    3.1.2 Event Category Lists .................................................................................................. 9 3.2 EVENT ROUTING RULE ............................................................................................ 10 3.3 GENERAL EVENTS .................................................................................................. 10

    3.3.1 General description .................................................................................................. 10

    3.3.2 OPUS_FOCUS_KEYPAD ........................................................................................ 11

    3.3.3 OPUS_FOCUS_CUST_PAINT ................................................................................ 11

    3.3.4 OPUS_TIMER_KEYPRESS_REPEAT..................................................................... 13 3.4 HOW TO ADD NEW EVENT TO OPUS EM ................................................................. 15

    3.4.1 Add New Event ID ................................................................................................... 15

    3.4.2 Define New Event structure ..................................................................................... 15 3.5 INTERFACE BETWEEN APPLICATIONS ........................................................................ 16

    3.5.1 General Description ................................................................................................. 16

    3.5.2 Case 1. For startup new application ......................................................................... 16 4 INTERFACES ............................................................................................................. 18 4.1 SUMMARY OF INTERFACE ........................................................................................ 18 4.2 EVENT MANAGER FUNCTIONS ................................................................................ 18

    4.2.1 EM_Add_Event ........................................................................................................ 18

    4.2.2 OPUS_Send_Message ............................................................................................ 19

    4.2.3 OPUS_Send_Pri_Message...................................................................................... 19 4.3 OTHER OPUS FUNCTIONS ..................................................................................... 20

    4.3.1 OPUS_Start_Timer .................................................................................................. 20

    4.3.2 OPUS_Stop_Timer .................................................................................................. 21 4.4 OPUS SYSTEM UTILITY FUNCTIONS ......................................................................... 21 4.5 DEBUGGING METHOD ............................................................................................. 22

    4.5.1 Windows simulation environment ............................................................................. 22

    4.5.2 Target board environment ........................................................................................ 23 5 WRITING AN APPLICATION ..................................................................................... 23 TechFaith Confidential Proprietary SW-OPUS_APP_GUIDE-02070111

    4 OPUS Application Programmers Guide 5.1 CREATE APPLICATION ............................................................................................. 23 5.1.1 Create a directory and files for Application ............................................................... 23 5.1.2 Define Basic Interface for Application ....................................................................... 23 5.2 REGISTRATION OF APPLICATION .............................................................................. 26 5.2.1 Register Application to AM ....................................................................................... 26 5.2.2 Register Startup event of application to EM_Default_Handler .................................. 27

SW-OPUS_APP_GUIDE-02070111 TechFaith Confidential Proprietary

    OPUS Application Programmers Guide 5 Tables

    

............................................................ 9

Figures

    

.................................... 7
........................................................ 8 TechFaith Confidential Proprietary SW-OPUS_APP_GUIDE-02070111

6 OPUS Application Programmers Guide

    Introduction

1.1 Purpose and Scope

    This document is a guideline for application programmer in OPUS platform. This document is to help

    application writer to understand the OPUS system especially the Application Manager and Event

    Manager.

1.2 References

    The following documents were used in developing this standard. Where referenced, the documents

    number will be given in brackets like [X].

    [1] OPUS Architecture Document (power point version) v1.00

    [2] GSM Man-Machine Interface Application Programming Interface, Software

    Programmer’s Reference Manual, Conexant, August 2000

1.3 Definitions, Acronyms, and Abbreviations

    AM Application Manager

    Application Application Program module in OPUS architecture. refer OPUS architecture doc

    DS Display System

    EM Event Manager

    HMI Human Machine Interface

    OPUS Optimal Platform Framework & User Interface System

    RM Resource Manager

    SP Service Provider

SW-OPUS_APP_GUIDE-02070111 TechFaith Confidential Proprietary

    OPUS Application Programmers Guide 7

    2 Event Manager

    OPUS EM System ArchitectureOPUS EM System ArchitectureGSM GLUE

    SIM CB FcnsEMAMGSM Line CB Fcnsevent to EM category 1HMI MBOXOPUSOPUSOPUS OPUSOPUSUH CB FcnsEM category 2eventEventEventEventEventEvent UK CB FcnsCall EM category NMMI_MSMMI_MSback GTYPEGTYPEGSM Timer CB FcnsDoEvent

    OPUS GPRS CB Fcnsevent to Internal QueueApp 1Monitor CB FcnsApp 2GSM App 3event

    MMI_MSGTYPEOPUSMMI_MSGTYPEOPUSOPUSOPUSEventEventEventEvent

    All Events from Engine are delivered to MMI MBOX when Event Callback function is called.

    The main goal of GSM GLUE is portability to replace it another MAs STUB.

    All GSM messages are re-mapped to OPUS event : applications refers only OPUS events. (transparent to engine)

    

The engine sends event via event call back function that is registered during OPUS system initialize.

    Each event call back function routes arrived events to HMI MBOX that is monitored by HMI task

    OPUS Event Manager.

The delivered MBOX events are engine dependent id, so all queued events shall be translated (re-

    mapper) to OPUS events. GLUE layer handle translation from Engine event to OPUS event or OPUS

    event to Engine event. For portability, the glue layer shall be replaced new one depends on MA

    including MBOX system that is a part of OS (RTXC) kernel.

OPUS Event Manager manages two different communication systems:

    ? MBOX is mainly used to communicate between engine and OPUS system. (Engine->OPUS)

    This system is provided by OS (RTXC) kernel.

    ? INTERNAL QUEUE system is mainly used for internal OPUS system communication

    system. (FIFO)

OPUS Event Manager keeps monitoring MBOX, and if any event is delivered then translates it to

    internal OPUS event and routes it to registered event handlers. If it is processed, then the event is

    consumed from system. (Message buffer freed by Event Manager) After processing MBOX event,

    the Event Manager shall check Internal Queue system that is added during processing MBOX event

    by application. Event Manager keeps processing Internal Queue until it empty. The Application

    designer should consider whether to use MBOX or Queue.

    TechFaith Confidential Proprietary SW-OPUS_APP_GUIDE-02070111

     OPUS Application Programmers Guide 8

    Event Manager manages multiple event category lists of routing stack. When an event is delivered,

    the EM extract category id and route it to appropriate routing stack lists until the event is consumed.

The following figure describes the event category when new mo call is requested during idle state.

    Event Manager Category (Idle & MO call)Event Manager Category (Idle & MO call)

    NFA: Non-Focus AppFA: Active Focus AppNew MO CallNew MO Call

    Event CategoryEvent CategoryCallCallCallCallStatus NFAStatus NFACall??

    Event Category

    Event CategoryFocusFocusFocusFocusidleidleCall??

    Event CategoryEvent Category

    InternalInternalInternalInternalCall??

    Event CategoryEvent Category

    SIMSIMSIMSIMSIM NFASIM NFA??

    Default HandleDefault Handle??

    

A: Event Manager manages multiple event category lists and each application defines which event

    categories should be monitored by it during registration.

B: Stats NFA is a permanent non-focus app that updates current service state. It acts as preprocessor

    for call (esp. line status) events.

C: Idle app is a permanent focus app that is created on normal power up. It displays current line status

    or idle screen.

D: SIM NFA is a permanent non-focus app that controls SIM related events.

E: If an event is not consumed to the end of the link lists, then it is handled by default handler that

    mainly launches new app. (handle startup events)

F: When new MO call is setup by the user, then call app is added to event category lists. To add new

    application to the routing stack, it inserted as routing stack priority as below except Focus category.

NFA/HIGH > NFA/NORMAL > FA/HIGH > FA/NORMAL > FA/LOW > NFA/LOW

G: Focus event category inserts new app to the first place of the list to latest focus app handles event

    SW-OPUS_APP_GUIDE-02070111 TechFaith Confidential Proprietary

    OPUS Application Programmers Guide 9

    first.

3 OPUS EM Detail Description

    3.1 Event Category

    3.1.1 Description

    Event Category is a group of events that have similar characteristic. When a new event is

    occurred, it is dispatched only to linked application lists of appropriate event category.

    Application designer should define which event category shall be monitored during application is

    exist.

    Event Category mechanism is introduced to reduce the routing stack depth. If 10 Apps exist, and only

    3 Apps are linked to CALL event category, then it traverse only 3 application handler rather than

    dispatch it to all existing application.

3.1.2 Event Category Lists

     Category Name Category Description Remark 0 OPUS_EVENT_GROUP_SIM This is SIM related event category that reports SIM

    status, PIN checking including ATK request/result

    events.

    1 OPUS_EVENT_GROUP_CALL CALL event category contains current network

    status, call request result, SMS event and

    supplementary service result.

    2 OPUS_EVENT_GROUP_DATA DATA event category is a group of data call related

    event.

    3 OPUS_EVENT_GROUP_AUDIO AUDIO event category a set of audio request result

    event.

    4 OPUS_EVENT_GROUP_VOICE VOICE event category contains speech recognition

    and voice recording related event.

    5 OPUS_EVENT_GROUP_UHW User Hardware event category controls peripheral

    device (handsfree, headset) handle, periodic tick

    report and annunciator.

    6 OPUS_EVENT_GROUP_AT AT event category is AT commands related event

    group.

    7 OPUS_EVENT_GROUP_MONITOR Monitor event category is for debugging. 8 OPUS_EVENT_GROUP_UK User Key event (TBD) 9 OPUS_EVENT_GROUP_GPRS GPRS related event group 10 OPUS_EVENT_GROUP_TIMER TIMER event category contains all timeout events

    that triggered by HMI task itself.

    11 OPUS_EVENT_GROUP_CUST CUST event category (TBD) 12 OPUS_EVENT_GROUP_INTERNAL Internal event category is a group of newly defined

    events for communication between applications. 13 OPUS_EVENT_GROUP_FOCUS Focus event category is to handle user interface such

    as user key input or refresh display area.

    

    Note : Events are defined in OPUS_events.h

TechFaith Confidential Proprietary SW-OPUS_APP_GUIDE-02070111

     OPUS Application Programmers Guide 10

    3.2 Event Routing Rule

    HMI task is in wait-for-event state after initialization. HMI EM keeps monitoring MBOX queue system that contains en-queued events generated by engine side. If any event is occurred, it routes it through its event category routing stack until it is consumed. If it is not consumed it shall be processed by general default handler and then freed.

    The default handler mainly controls start up application events. EM shall request to create new application to AM when new app launch event is detected.

    During processing new event, the application can generates some new events to interface to other applications. EM shall handle all internal queued events before it goes back to wait-for-MBOX event state.

    3.3 General Events

    3.3.1 General description

    Description:

    Each application handler use three parameters:

    ? Event : OPUS event id defined in OPUS_events.h

    ? *PMess : sub message body pointer depends on the event id. The receiver converts

    the message body to interface data structure pointer and then use it. Do not free

    pMess parameter because it shall be freed in EM.

    ? *Handle : Boolean value whether this event is processed this handler or not.

Prototype:

void app_ handler

    (

     OPUS_EVENT_ENUM_TYPE event,

     void *pMess,

     OP_BOOLEAN *handle

    )

    {

     *handle = OP_TRUE;

     switch(event)

     {

     case event1 :

     st_type1_ptr = (st_type1 *)pMess;

     data = (st_type1_ptr->data1);

     do action1;

     break;

     case event2 :

     do action 2;

     break;

     default :

    SW-OPUS_APP_GUIDE-02070111 TechFaith Confidential Proprietary

Report this document

For any questions or suggestions please email
cust-service@docsford.com