OPUS Application
Programmer’s 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 Programmer’s 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 Programmer’s 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 Programmer’s 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 Programmer’s Guide 5 Tables
Figures 6 OPUS Application Programmer’s 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 document’s 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 Programmer’s 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 MA’s 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 Programmer’s 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 Programmer’s 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 Programmer’s 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 ............................................................ 9