Home

Maui System Service User Manual

1. 10 3 2 ADM kal_adm_create Prototype KAL_ADM_ID kal_adm_create void mem adr kal_uint32 size kal_uint32 subpool_size kal_bool islogging Header file kal_release h Input mem_adoar is starting address of the memory pool size is total size of the memory pool subpool_size is an array which describe the total number of sub pools and its size islogging is logging flag guard pattern checking and operation logging will be enabled if itis KAL TRUE Output ID the created ADM Description This service aims for creating an ADM from the given memory pool ADM control block header and footer footprints must be taken into account while calculating the pool size Total overhead is the summation of the following Fixed size overhead 12 16 16 x number of sub pool entries Floating overhead 8B header for each allocation extra 16B overhead for footer if logging is enabled Default value will be adopted if subpool_size is NULL kal adm delete Prototype kal status kal_adm_delete KAL ADM ID adm di Header file kal release h MediaTek Confidential Revision 1 6 September 28 2006 Page 69 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Input adm _id is identity of an ADM to be deleted Output KAL_ADM_SUCCEED if operation successfully done KAL MEMORY NOT RELEASE if there are some me
2. free_local para Prototype void free_intlocal_para local_para_struct local_para_ptr kal_char file kal_uint32 line void free_int_local_para local_para_struct local_para_ptr Header file stack_lticom h MediaTek Confidential Revision 1 6 September 28 2006 Page 41 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Input local_para_ptris pointer of local_para_struct to be released Description If local_para_ptris not NULL then decrement the associated reference count ocal_para_ptr gt ref_count if it becomes zero system will free the buffer directly It is user s responsibility to reset the relative pointer kept in ilm_struct if needed Note There is another reentrant function free_int_local_para_r which has protection on access to reference count One who may have race condition problem of reference count could use the macro free_local_para r to avoid such error The usage is just the same as free_local_para free_peer buff Prototype void free_int_peer_buff peer_buff_struct pdu_ptr kal_char file kal_uint32 line void free_int_peer_buff peer_buff_struct pdu_ptr Header file stack_lticom h Input pdu ptris pointer of peer buff struct to be released Description H pdu_ptris not NULL then decrement the associated reference count pdu_ptr gt ref_count if it becomes zero
3. KAL Programming Guide Internal Design Data Types Data Structure APIs Examples MediaTek Confidential Revision 1 6 September 28 2006 Page 18 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 4 KAL An Overview KAL abbreviation of Kernel Adaptation Layer is an adaptation layer between Operating System OS and upper layer applications To keep it highly portable KAL defines its own APl set for each OS component including task management task synchronization task communication timer management and memory management Being a robust adaptation layer KAL is rich of amazing features y Entry of OS functions Y System call parameter checking Y System abruption tracking Y Tracking the peak consumption of system resource Among them debugging and profiling related features are well protected with compile option and could be optionally turned off if they are no longer needed Section 2 is general description of data types defined in KAL illustration of internal flow and API of each abovementioned component are provided in subsequent sections Notations Black bolded and italic wording is either a file name or file name with relative path Black bolded and underlined wording is a variable Black bolded underlined and quoted wording is a function Bolded and blue color word
4. MediaTek Maui System Service User Manual Interrupt Handler and KAL Programming Guide Document Number Preliminary Information Revision 1 6 Release Date September 28 2006 M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Legal Disclaimer BY OPENING OR USING THIS FILE BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES THAT THE SOFTWARE FIRMWARE AND ITS DOCUMENTATIONS MEDIATEK SOFTWARE RECEIVED FROM MEDIATEK AND OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON AN AS IS BASIS ONLY MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY INCORPORATED IN OR SUPPLIED WITH THE MEDIATEK SOFTWARE AND BUYER AGREES TO LOOK ONLY TO SUCH THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO MEDIATEK SHALL ALSO NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER S SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM BUYER S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK S ENTIRE AND CUMULATIVE LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE AT MEDIATEK S OPTION TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO MEDI
5. kal Lake mutex Prototype void kal_take_mutex kal_mutexid ext_mutex_id_ptr Header file kal_release h Input ext_mutex_id_ptris destination MUTEX to be taken Description This service obtains an instance of the specified MUTEX If the MUTEX is in KAL_MUTEX_TAKEN state before this call the service cannot be immediately satisfied and caller will be suspended endlessly Once the MUTEX is taken by a task its status will soon become KAL MUTEX_TAKEN and owner ID will be recorded in control block of the MUTEX kal_give_mutex Prototype void kal_give mutex kal_mutexid ext_mutex_id_ptr Header file kal_release h Input ext_mutex_id_ptris destination MUTEX to be given Description This service releases an instance of the MUTEX specified by the parameter ext_mutex_id_ptr If there are any tasks waiting to obtain the same MUTEX the first task waiting is given this instance of the MUTEX Otherwise if there are no tasks waiting for this MUTEX the internal counter is incremented by one Soon after giving the MUTEX the status will be updated as KAL_MUTEX_GIVEN Also in case of a MUTEX is not given and taken by the same task fatal error kal_give_mutex The mutex is taken by another task fatal error code 1 0x405 error code 2 ext_mutex_id_ptr will be taken place 7 3 2 Semaphore kal_create_sem Prototype kal_semid kal_create_sem kal_char sem name kal_uint32 initial_count Header file kal_release h Input sem_name is nam
6. ASSERT It is suggested that always keep the hardware de bouncing active hardware issues the EINT interrupt after 64ms de bouncing Any EINT interrupt is either positive KAL TRUE or negative KAL_FALSE level trigger and user should also specify the callback function as well as auto unmask flag EXTRA_EINT_Registration Prototype void EXTRA_EINT_Registration kal_uint8 eintno kal_bool ACT_Polarity void reg_hisr void kal_bool auto_umask Header file eint h Input eintno is channel of EINT to be registered ACT Polarity is the active polarity reg_hisr is callback function and auto_umask tells the system if it needs to unmask the interrupt at end of processing Description Some MTK BB chips provides 4 external interrupts with hardware de bounce supported besides configurable level or edge trigger external interrupts In addition to the 4 external interrupt source we have additional external interrupts multiplexed with UART2 RX UART2 TX UART3 RX and UART3 TX which also could be served as external interrupt sources without hardware de bounce capability and always level trigger This service specific for the registration of these additional 4 external interrupts Similar with EINT Registration any illegal EINT number will be rejected with an ASSERT Any EINT interrupt is either positive KAL_TRUE or negative KAL_FALSE level trigger and user should also specify the callback function as well as auto unmask flag Availability W05
7. free_ilm amp current_ilm Approach 2 System is responsible for maintaining local parameter pointer void receiver void ilm_struct current_ilm while 1 receive_msg_ext_q task_info_g INDX_RECEIVER task_ext_qid amp currentcilm switch current_ilm msg_id case MSG_ID_SENDER_TO_RECEIVER 4900006 free_ilm amp current_ilm MediaTek Confidential Revision 1 6 September 28 2006 Page 47 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 9 Timer Management There are 3 types of timers provided on MAUI they are KAL timer stack timerand scheduled event respectively Stack timer and scheduled event are for protocol stack also upper layer applications KAL timer is a wrapper of Nucleus Plus timer component H the most precise timer its call back function is done at HISR level therefore it is restricted for OS and driver layer only Any application violates the restriction may suffer from serous failure on mobility features On MAUI the minimal time tick is in terms of TDMA timer 4 615ms each unit 9 1 Descriptions 9 1 1 KAL timer Basically KAL timer is a wrapper of Nucleus Plus Timer Management It offers the most accurate timer period because the timeout handler is done by Timer HISR Inheriting from the design any callback function re
8. peer_buff_ptr gt free_header_space is less than header_len receive_msg_ext_q Prototype kal status receive_msg_ext_q kal_msgqid task evt old ilm_struct lm ptr Header file stack_Itlcom h Input task_ext_gid is ID of destination queue from which a message will be retrieved data packet will then be written to i m_ptr Output KAL_SUCCESS if message is retrieval is successfully done otherwise fatal error with error code 1 0x308 would be trapped Description This is the unified entrance for external queue message retrieval if the destination queue is empty caller would suspend it self endlessly Remark Unlike msg send ext queue the ILM pointer Im_ptris a privately maintained pointer which is not requested from the system MediaTek Confidential Revision 1 6 September 28 2006 Page 44 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide receive_msg_int_q Prototype kal_bool receive_msg_int_q task_indx_type task indx ilm_struct ilm_ptr Header file stack_lticom h Input task_indx is task ID while i m_ptr acts as storage Output KAL_FALSE if internal queue is empty otherwise KAL_TRUE Description Retrieving an ILM from task internal queue if there is an available ILM KAL_TRUE will be returned and the content is kept at Um or Remark Unlike msg send int_queue the IL
9. task_info q will be always be referenced to target the destination queue ID A task is in READY state soon after creation or ready to be executed and system schedules the highest priority task at the very first context switch During execution period it may be suspended for resource synchronization or communication Table 7 2 summarizes all possible task status MediaTek Confidential Revision 1 6 September 28 2006 Page 21 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice Maui System Service User Manual Interrupt Handler and KAL Programming Guide NU_READY Task is in ready state ready ro be scheduled and executed NU_SLEEP_SUSPEND Task is in sleeping state by calling kal_sleep_task NU_SEMAPHORE_SUSPEND 0 2 eee ee is suspended at queue will be awaken in case of messages arrival 6 7 Task is suspended at semaphore will return to READY state if semaphore becomes available NU_EVENT_SUSPEND Task is suspended and waiting the validity of an event Table 7 2 Task status Sub sections following show you the data structure and data type widely used in task management unit as well as task management related APIs MediaTek Confidential Revision 1 6 September 28 2006 Page 22 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Program
10. void kal_sleep_task kal_uint32 time_in_ticks Header file kal_release h Input time_in_ticks is sleeping duration each unit is 4 615ms Description Forcing a task to sleep for a duration which is expressed in terms of 4 615ms stack change priority by module ID Prototype kal_uint32 stack_change_priority_by_module_ID module_type mod ID kal_uint32 new_priority Header file kal_release h Input mod_ D is module ID of destination task whose priority is going to be adjusted new_priority is new priority number to be assigned Output Old priority setting Description This function also offers run time task priority switching its input argument is different from kal change priority where a task is targeted via module ID rather than task ID Users must be very careful in using the function otherwise deadlock may occur due to priority change MediaTek Confidential Revision 1 6 September 28 2006 Page 27 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 6 4 Customization A customer task must be specified in custom Comp config tbl definedin mcu custom system board version custom_config c which is an array of type comptask_info_struct lts existence could be identified by create function NULL if not exist In booting stage system will look into the table and determine its creation v
11. 36 and later EINT_Set_Polarity Prototype void EINT_Set_Polarity kal_uint8 eintno kal_bool ACT_Polarity Header file eint h Input eintno is the destination EINT channel ACT_Polarity is new polarity to be set Description This function is provided to set the polarity accordingly KAL_TRUE for positive level trigger and KAL_FALSE for negative level trigger The whole procedure is done under the protection of disabling interrupt EINT_Mask Prototype void EINT_Mask kal_uint8 eintno Header file eint h Input eintno is the destination EINT channel Description This function is provided for masking disabling the given EINT channel Again the action is done under the protection of disabling interrupt MediaTek Confidential Revision 1 6 September 28 2006 Page 15 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide EINT_UnMask Prototype void EINT_UnMask kal_uint8 eintno Header file eint h Input eintno is the destination EINT channel Description This function is provided for unmasking enabling the given EINT channel Again the action is done under the protection of disabling interrupt EINT_SW_Debounce Modify Prototype kal_int32 EINT_SW_Debounce_Modify kal_uint8 eintno kal_uint8 debounce_time Header file eint h Input eintno is the destination EINT channel debounce
12. ASSERT Prototype ASSERT expression Header file kal_release h Input expression is an expression Description If DEBUG_KALis defined ASSERT takes action if the expression evaluates to FALSE the embedded exception handler will then be invoked please refer to ExceptionHandling paf for more detailed Otherwise in RELEASE_KAL ASSERT does nothing EXT_ASSERT Prototype EXT_ASSERT expr el e2 e3 Header file kal_release h MediaTek Confidential Revision 1 6 September 28 2006 Page 77 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Input expression is an expression e1 e2 and e3 are three extended parameters with type of kal_uint32 Description Unlike ASSERT EXT_ASSERT always take action no matter DEBUG KAL or RELEASE_KAL in addition to expression users are given three extended parameters for tracking the violations EXT_ASSERT_DUMP Prototype EXT_ASSERT_DUMP expr e1 e2 e3 dump_param Header file kal_release h Input expression is an expression e1 e2 and e3 are three extended parameters with type of kal_uint32 dump_param is a pointer to a ASSERT_DUMP_PARAM_T structure Description EXT_ASSERT_DUMP is just like EXT_ASSERT except that it can dump at most 10 memory fragments in the exception log 224 bytes is reserved in the exception log Below is the ASSERT_DUMP_PARAM_T s
13. System Service User Manual Interrupt Handler and KAL Programming Guide void ssdbg2_start_base_timer void base_timer_ptr unsigned int time_out stack_start_timer stack_timer_struct base_timer_ptr 0 time_out return void ssdbg2_stop_base_timer void base_timer_pir stack_stop_timer stackstimer_struct base_timer_ptr return void ssdbg2_base_timer_timeout_hdler void msg_ptr reset saved event id to avoid the potential bug to cancel released event ssdbg2_context ssdbg2_event_id NULL ssdbg2_context ssdbg2_event_id evshed_set_event ssdbg2_context ssdbg2_event scheduler ptr kal_timer_func_ptr ssdbg2_base_timer_timeout_hdler NULL 200 MediaTek Confidential Revision 1 6 September 28 2006 Page 58 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 10 Memory Management On MAUI there is a variety of memory management schemes to meet the various requirements they are known as control buffer application dynamic memory ADM system specific memory and debug memory respectively Among them debug memory is needed if and only if DEBUG_KALis defined otherwise it will be excluded if RELEASE_KAL is applied 10 1 Descriptions 10 1 1 Control buffer Control buffer is fixed size buffer which offers not more than 2KB allocation assertion failure ctrl_buff_poo
14. associate with single module ID therefore entry MOD_CUSTOM1 in table custom_mod task q maps to task INDX_CUSTOM1 Also NDX_NIL must not be removed custom_task_indx_type custom_mod_task_g MAX_CUSTOM_MODS INDX_CUSTOM1 MOD_CUSTOM1 INDX_CUSTOM2 MOD_CUSTOM2 INDX_NIL Please end with INDX_NIL element 1 Step 3 Configure the task creation table Define the task configuration information in meu custom system board version custom_config c please refer to data type Comptask_info_struct for more detail MediaTek Confidential Revision 1 6 September 28 2006 Page 28 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide const comptask_info_struct custom_comp_config_tbl MAX_CUSTOM_TASKS INDX_CUSTOM1 CUST1 CUST1 Q 210 1024 10 O ifdef CUSTOM1_ EXIST custom1_create KAL_FALSE else NULL KAL_FALSE endif INDX_CUSTOM2 CUST2 CUST2 Q 211 1024 10 O ifdef CUSTOM2_EXIST custom2_create KAL_FALSE else NULL KAL_FALSE endif Step 4 Implement the task create function Implement the task create functions in mcu custom system board version custom1_create c please refer to data type comptask_handler_struct for more detail kal_bool custom1_create comptask_handler_ struct handle static const comptask_handler_struct cus
15. char display_str 128 ilm_struct current_ilm ssdbg1_localpara_struct paraptr ssdbg1_peerbuff_struct peerbufptr kal_uint8 pduptr kal_uint16 pdulength i initialize a stack timer as the base timer stack_init_timer amp ssdbg2_context ssdbg2_base_timer SSDBG2 Base Timer MOD_SSDBG2 create scheduled event ssdbg2_context ssdbg2_event_scheduler_ptr new_evshed amp ssdbg2_context ssdbg2_base_timer ssdbg2_start_base_timer ssdbg2 stop base Omer 0 kal_evshed_get_mem kal evshed_free mem 0 set event ssdbg2_context ssdbg2_event_id evshed_set_event ssdbg2_context ssdbg2_event_scheduler_ptr kal_timer_funcptr ssdbg2_base_timer_timeout_hdler NULL 200 while 1 Task_Time while receive_msg_int_q task_entry_ptr gt task_indx amp current_ilm switch current_ilm msg_id case MSG_ID_TIMER_EXPIRY check if the base timer is stopped or not if stack_is_time_out_valid amp ssdbg2_context ssdbg2_base_timer invoke event s timeout handler evshed_timer_handler ssdbg2_context ssdbg2_event_scheduler_ptr stack_process_time_out amp ssdbg2 context ssdbg2 base_timer break default break free _ilm amp current_ilm Inside the function it does nothing for a timer message MediaTek Confidential Revision 1 6 September 28 2006 Page 57 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui
16. find the first un aligned timer and system must wake up its timeout An un aligned timer is a timer whose timeout notification must not be delayed due to system sleep On the contrary an aligned timer allows the late timeout notification The parameter max_delay_ticks tells if it is an aligned timer it is extremely important for power saving issue When setting max_delay_ticks to zero the timer will be marked as an un aligned timer The timer will be marked as an aligned timer when the value of max_delay_ticks is 255 From 05C W05 13 specifying other values i e 1 254 will also mark the timer as an aligned timer But the timeout notification won t be delayed more than max_delay_ticks For example you set max_delay_ticks to 10 The timeout notification of the timer maybe delayed due to the sleep mode But the maximal delay will not exceed 10 ticks It is strongly suggested to call this function only in system initialization time and the related data allocated forthe event scheduler could not be freed once it s created MediaTek Confidential Revision 1 6 September 28 2006 Page 56 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 9 4 Examples Here is an integrated example of event scheduler and stack timer void ssdbg2_main task_entry_struct task_entry_ptr kal_uint32 Task_Time 0
17. message exchange and wait wake mechanisms MAUI is capable of offering a variety of solutions to the problem of task synchronization Message exchange system is categorized as Task Communication Management and will be described in next chapter This chapter focuses on wait wake based mechanism 7 1 Description By using event group a task can trigger an event someone who is waiting for the event would be waken up by the Operating System OS Also to protect a critical section users could rely on MUTEX or semaphore to achieve the goal MUTEX inherits from semaphore with initial courting value 1 The state of task exactly reveals the suspension type 7 1 1 Event group Event group provides a mechanism to indicate that a certain system event has occurred A single bitin an event group represents an event This bit is called an event flag There are 32 event flags in each event group Tables below collects the possible operations for event retrieval and event set respectively KAL_AND Indicate that al of the requested event flags are required KAL AND CONSUME Indicate that all of the requested event flags are required and CONSUME option automatically clears the event flags present on a successful request Indicate that one or more of the requested event flags is sufficient KAL_OR_CONSUME Indicate that one or more of the requested event flag is sufficient and CONSUME option automatically clears the event flags present on a su
18. system will free the buffer directly It is user s responsibility to reset the relative pointer kept in ilm_struct if needed Note There is another re entrant function free_int_peer buff r which has protection on access to reference count One who may have race condition problem of reference count could use the macro free _peer_buff_r to avoid such error The usage is justtthe same as free Geer but hold_local_para Prototype kal_bool hold_local_para local_para_struct local_para_ptr Header file stack_Iticom h Input local_para_ptris pointer of local_para_struct whose content is going to be reserved for some consumer Output KAL FALSE if local _para_ptris NULL pointer otherwise KAL_TRUE Description H local_para_ptris not NULL increment its reference counter local_para_ptr gt ref_count by 1 Note There is another re entrant function hold_local_para_r which has protection on access to reference count One who may have race condition problem of reference count could use this API to avoid such error The usage is just the same as hold_local_para get_local_para_ptr Prototype void get_local_para_ptr local_para_struct local_para_ptr kal uint16 local_para_len_ptr Header file stack_lticom h Input local_para_ptr is pointer of local_para_struct and ocal_para_len_ptrwill be used to return message length Output Pointer which targets at the starting address of local parameter buffer Description This function ca
19. this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide void construct_int_local_para kal_uint16 local_para_size kal_char file ptr kal_uint32 line if DEBUG_KAL is defined otherwise it is defined as void construct_int_local_para kal_uint16 local_para_size In construct int local para system will get buffer according to size specified in local_para_size if it is called by TST task system allocates buffer from 1ST buffer otherwise from control buffer The return buffer pointer will then be casted as pointer of local_para_struct the first byte of the buffer or ref_count will be initialized to 1 and the second 2 bytes of the buffer or msg_len would be filled as local_para_size From 06A w06 41 you can specify a TD_RESET in the au argument direction to let system do zero initialization for you For example construct_local_para sizeof my_ struct TD_RESET This will dear e buffer body to zero note not include the local parameter header Remark Be very careful that size of local_para_struct must be taken into account construct_peer buff Prototype void construct_peer_buff pdu_len header_len tail_len direction Header file app_Itlcom h Input pdu_len is size of peer buffer header_len is size of header buffer tai _len is size of tail buffer and direction is unused Output Void pointer Description This is macro of void construct_i
20. without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 8 2 Task Communication APIs allocate_ilm Prototype ilm_struct allocate_ilm module _type module id Header file stack_Itlcom h Input rmodule_id is source module ID which is going to deliver an ILM Output Pointer an ILM Description ILM storage for any message delivery must be allocated from an array pool of type ilm_struct namely module Um o by sender The array pool is indexed by sender s module ID In case of violation fatal error Send an un allocated ILM to external queue fatal error code 1 0x432 error code 2 pointer of ILM would be encountered On the contrary if sender attempts to send message before completeness of the previous delivery fatal error again ILM is already allocated fatal error code 1 0x431 error code 2 module ID append_to_peer_buff Prototype void append_to_peer_buff peer_buff_struct peer_buff_ptr void tail data_ptr kal_uint8 tail_len Header file stack_Itlcom h Input peer_buff_ptr is pointer of peer buff struct from where new data pointed by oi data ptr will be appended from end of pdu its length ail ent is given in units of Bytes Description As shown in Figure 1 a data record could be appended from tail of peer buffer after appending system will update the following information peer_buff_ptr sfreestail_space peer_buff_ptr gt free_tail_space tail_len peer buff _
21. 6 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 1 Introduction of External Interrupt Handler MTK base band chips provide external interrupt EINT forthe interrupt triggering from external device This document subjects to give the processing flow customization and interface of externalinterrupt interface 1 1 Overview Table 2 1 gives the total number of EINT offered on the MTK base band chips Number of channels MT6205B MT6217 MT6218 MT6219 External Interrupt EINT 3 4 4 4 Dual mode interrupt nIRQ 1 1 1 1 Total number 4 5 5 5 Table 2 1 Total number of external interrupts channels Features of EINT as below 1 Selectable edge or level sensitivity 2 Selectable negative or positive polarity 3 Flexible de bounce time in terms of 32KHz the maximal de bounce time is 64ms 2048 x 31 254s Features of nIRQ 1 Itis a dual mode GPIO acts as interrupt source if it is configured as nIRQ signal 2 Configurable as edge sensitivity with active LOW or level sensitivity with active LOW MT6205B MT6217 MT621 MT6219 Interrupt code EI 11 GPIO number for nIRQ GPIO 21 GPIO 41 GPIO 41 GPIO 41 GPIO number for nFIQ X GPIO 42 GPIO 42 GPIO 42 Table 2 2 Interrupt code on a series of MTK base band chips MediaTek Confidenti
22. 8 islogging KAL TRUE if buffer logging is enabled reserved2 3 Reserved field for alignment KAL_ADM_ID Identity ofan ADM it is type of void MediaTek Confidential Revision 1 6 September 28 2006 Page 68 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 10 3 Memory management APIs 10 3 1 Control buffer get_ctrl_buffer Prototype void get_ctrl_buffer size Header file app_alloc buff h Input size is size of buffer to be allocated Output Buffer pointer is returned in the manner of void any unsuccessful operation will be re directed to system error Description This is common interface for allocating a buffer from the smallest fit control buffer free_ctrl_buffer Prototype void free_ctrl_buffer void ptr Header file app_alloc_buff h Input ptris buffer pointer to be released Description This is common interface for returning a buffer pointer to the system kal_query_ctrlbuf_max_consumption Prototype kal_bool kal_query_ctrlbuf_max_consumption kal_uint32 ptr Header file kal_release h Input ptris an array which is used to return values Output KAL_FALSE if DEBUG_KAL is not defined otherwise KAL_TRUE Description This service is provided for querying currently maximum consumption on each control buffer which is totally RPS CREATED CTRL_BUFF_POOLS
23. ATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED INACCORDANCE WITH THE LAWS OF THE STATE OF CALIFORNIA USA EXCLUDING ITS CONFLICT OF LAWS PRINCIPLES MediaTek Confidential Revision 1 6 September 28 2006 Page 2 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Revision History Date Comments mm dd yyyy 01 Span Crue 02 03 04 08 07 GSM_GPRS_System_Configuration document Karen Hsu Add new description to free_local_para free peer but hold_peer_buff hold_local_para for re entrantable new API MACRO 0 Add limitation descriptions for all resource related create init APIs Remove the APIs kal_delete_timer stack_deinit_timer 09 28 2006 CC Hwang Support zero initialization of local parameter MediaTek Confidential Revision 1 6 September 28 2006 Page 3 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Table of Contents Legal DiSClaimer aE A O g O A A o a 2 Revision History TEEN a E Lech cc uff E 3 Table of Contents gt RU AA cc 98 coccion 4 1 Introduction of External Interrupt Handler cecceseeseseeseeesseeeseeeeseeesseeseseesseeeeseeeaseesneeesseesaseesse
24. Data Types 2 a M AAA 37 8 1 1 Access behavior of local parameter and peer buffer eu EEEEEEEREENNEEENREEENN nae 39 8 2 Task Communication Als nam A Ee A occ 40 A ee a Oh ROA ARA 40 append To Deer Duff T A B D e 40 cancel AA O o A cc rn 40 e dv CHILE BETEN D Wf A0 CONSTrUCT_Peer_D Psi vi eg 41 A WT EA ARA 41 MediaTek Confidential Revision 1 6 September 28 2006 Page 5 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide CEA AAA Ez A SA CA 41 free_peer AAA A NL erh ARMMM naana aaa aaa 42 TK CT OA 0 bh rre E 42 get_local_para _ptr ssnssnnsennnnnnnnnnnnnennan nn e A eit rc EE IO cc 42 AAA NN AA AAA ee RSS 42 hold_peer_buff ef A ARA occ mt cocer 43 msg_gelleX QUEUE Wfo ch A TT 43 msg_get_ext_queue_length occinncnnccnnnnnonicnnccncc annen nnna na 43 MSI BET CN A e 43 ETE E AAA AAA 43 E GSN QU CU ii VTT VE 44 prepend_to_peer_ DU oonconononnnncnnnnnnnoranc ran oran rnnc oran crac rn raro rra raro O A A teen 44 receive OA AAA EA se AA 44 CAM AAA A A ARMA W I ae 45 remove_hdr_of peer buft ccseneeeaggeresese GA ga O cananea 45 remove_tail_of_peer_buff AM a pff O cacao race rana enanos 45 update _peer_bufft hdr MAMA occ occ cnc crearan 45 8 3 ISCH A MA MM A AAA 46 9 Timer Managemen
25. HISR The lowest priority HISR however it still takes priority than tasks KAL_PRIORITY CLASSO Reserved for system usage only gt it is suggested that KAL_PRIORITY_CLASS18 customer tasks must not use the priority within the range KAL_PRIORITY_CLASS18 1 For tasks which are timing critical like BMT Battery KAL_PRIORITY_CLASS19 9 Management Task AUX and OBEX KAL_PRIORITY_CLASS20 Applications like MMI WAP and JAVA occupy priority KAL_PRIORITY_CLASS21 9 Within the range KAL_PRIORITY_CLASS22 For tasks which have rather lower priority and to be KAL_PRIORITY_CLASS24 9 scheduled when the system is free for instance 2 a NVRAM and TST tasks KAL_PRIORITY_CLASS25 For very low priority tasks for example priority KAL_PRIORITY_CLASS25 5 KAL_PRIORITY_CLASS25 5 is reserved of IDLE E task Table 7 1 Convention of priority coverage There are three possible boot modes META USB or normal boot mode Different tasks are created for differenct boot mode they are pre defined in a constant array of type comptask_info_struct namely sys comp config tbl for normal boot mode on the other hand customer defined tasks are defined in custom comp config tbl At booting stage system is responsible to identify the exact boot mode furthermore copy the tasks information onto global array known as task_info_g which is an important reference pool in run time task management For instance in message passing
26. M pointer i m_ptr is a privately maintained pointer which is not requested from e system remove hdr_of peer buff Prototype void remove_hdr_of peer buff peer_buff_struct peer_buff_ptr kal_uint8 hdr_len Header file stack_lticom h Input peeer_buff_ptris destination peer buffer whose peer data is going to be removed from header by hdr_len Bytes Description Contrary to prepend to peer buff this function aims to remove peer data from header of peer buffer total number of data to be removed is expressed in hdr_len After removing system updates the peer buffer structure as below peer_buff_ptr gt free_header_space peer_buff_ptr gt free_header_space hdr_len peer_buff ptr gt pdu_len peer buff ptr gt pdu len hdr_len remove tail_of_peer buff Prototype void remove_tail_of peer_buff peer buff_struct peer_buff_ptr kal_uint8 tail_len Header file stack com bh Input peeer_buff_ptris destination peer buffer whose peer data is going to be removed from tail by tail_len Bytes Description Contrary to append to peer buff this function aims to remove peer data from tail of peer buffer total number of data to be removed is expressed in tail_len After removing system updates the peer buffer structure as below peer_buff_ptr gt free_tail_space peer_buff_ptr gt free_tail_space tail_len peer_buff_ptr gt pdu_len peer_buff_ptr gt pdu_len tail_len update_peer_buff_hdr Prototype void update_peer_buff_hdr p
27. SR Description This function is special for disabling all interrupt sources by setting I bit besides return the current value of CPSR It must be used in paired with RestorelRQMaskK RestorelRQMask Prototype void RestorelRQMask kal_uint32 value Header file intrCtrl h Input value is CPSR value to be restored Description Restore the I bit once it is turned off It must be used in paired with SaveAndSetIRQMask Example kal_uint32 CriticalFunction void kal_uint32 savedMask 1 bit should be turned off at this critical path savedMask SaveAndSetIRQMask 04990000 RestorelRQMask savedMask MediaTek Confidential Revision 1 6 September 28 2006 Page 14 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 3 2 EINT EINT_Registration Prototype void EINT_Registration kal_uint8 eintno kal bool Dbounce En kal_bool ACT Polarity void reg_hisr void kal_bool auto_umask Header file eint h Input eintno is channel of EINT to be registered Dbounce_En tells if hardware de bounce time need to be enabled ACT_Polarity is the active polarity reg_hisris callback function and auto_umask tells the system if it needs to unmask the interrupt at end of processing Description This service provides the registry function for EINT any illegal EINT number will be rejected with an
28. SR void IRQMask IRQ_DMA_CODE kal_activate_hisr dma_hisr 1 kal_change_priority Prototype kal_uint32 kal_change_priority kal_taskid taskid kal_uint32 new_priority Header file kal_release h Input taskid is destination task new priority is new priority number to be assigned Output Old priority setting Description This function offers run time task priority switching users must be very careful in using the function otherwise deadlock may occur due to priority change kal_create_hisr Prototype kal_hisrid kal_create_hisr kal_char her name kal_uint8 priority kal_uint32 stack_size kal_hisr_func_ptr entry_func kal_uint8 options Header file kal_release h Input hisr_name is name of HISR to be created priority tells the HISR priority either 1 or 2 stackesize is stack size associates with this HISR which is in terms of bytes if options is KAL_FALSE stack will be allocated from internal SRAM otherwise from external SRAM Only timing critical HISR is suggested to put its stack at internal SRAM Finally entry_func tells the HISR entry function Output ID of the HISR Description Function used to create an HISR It is strongly suggested to call this function only at system initialization stage and the HISR related data elements could not be freed once it s created Remark Priority number 0 is strictlyprohibited which is specially reserved for the highest priority HISR kal_get_my_task_index Prot
29. T2 hold having successfully retrieved the event flags they will be cleared to zero kal_retrieve_eg_events SAMPLE_Events SET_BITO SET_BIT2 KAL_AND_CONSUME amp flags KAL_SUSPEND 9490008 kal status SAMPLE_consumer void kal_uint32 flags 0 9490008 Consumer will be resumed if and only if event flags SET_BIT1 is satisfied having successfully retrieved the event flag it will remain 1 kalretrieve_eg events SAMPLE_Events SET_BIT1 KAL_OR amp flags KAL_SUSPEND 9900008 MediaTek Confidential Revision 1 6 September 28 2006 Page 36 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 8 Task Communication Management Basically MAUI is a message passing system any communication between two tasks or HISR and task are accomplished via message passing The fundamental message packet is known as Inter Layer Message abbreviated as ILM To prevent infinitive message delivery each module is associated an ILM storage Users must ensure he she would not trigger message sending before the completeness of the previous request Conventionally user should allocate ILM in advanced and put their data onto the storage once delivered the ILM storage will be released by the system Subsections following will give the detail description about data structure data types and messa
30. TRL_BUFF_POOL_SIZE2048 8 NUM_CTRL_BUFF_POOL_SIZE4096 0 NUM_CTRL_BUFF_POOL_SIZE8192 0 NUM_CTRL_BUFF_POOL_SIZE16384 0 NUM_CTRL_BUFF_POOL_SIZE32768 0 NUM_CTRL_BUFF_POOL_SIZE60000 0 NUM_CTRL_BUFF_POOL_SIZE08 50 NUM_CTRL_BUFF_POOL_SIZE16 50 NUM_CTRL_BUFF_POOL_SIZE32 50 NUM_CTRL_BUFF_POOL_SIZE64 30 NUM_CTRL_BUFF_POOL_SIZE128 244 NUM_CTRL_BUFF_POOL_SIZE256 30 NUM_CTRL_BUFF_ POOL SIZE512 21 NUM_CTRL BUFF POOL SIZE1024 17 NUM CTRL_BUFFPOOL_SIZE2048 8 NUM_CTRL_BUFF_POOL_SIZE4096 0 NUM CTRL_BUFF POOL SIZE8192 0 NUM_CTRL_BUFF_POOL_SIZE16384 0 NUM_ CTRL BUFF_POOL_SIZE32768 0 NUM_CTRL_BUFF_POOL_SIZE60000 0 Lett num but Gool size ctrl_num_buff_pool_size MediaTek Confidential Revision 1 6 September 28 2006 Page 59 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide void custom_config_ctrl_buff_info void These constants defined in adaptation include ctrl_buff_pool h ctrl_buff_pool_info_g 0 size CTRL_BUFF_POOL SIZE08 ctrl_buff_pool_info_g 0 no_of_buff NUM_CTRL_BUFF_POOL_SIZE08 ctrl_buff_pool_info_g t size CTRL_BUFF_POOL SIZE16 ctrl_buff_pool_info g 1 no of_buff NUM_CTRL_BUFF POOL_SIZE16 ctrl_buff_pool_info_g 2 size CTRL_BUFF POOL SIZE32 ctrl_buff pool_info_g 2 no_of buff NUM _C
31. TRL_BUFF_POOL_SIZE32 ctrl_buff_pool_info_g 3 size CTRL_BUFF_POOL_SIZE64 ctrl_buff_poolsinfo_g 3 no_of_buff NUM_CTRL_BUFF_POOL_SIZE64 ctrl_buff_pool_info_g 4 size CTRL_BUFF_POOL_SIZE128 ctrl_buff_pool_info_g 4 no_of_buff NUM_CTRL_BUFF_POOL_SIZE128 ctrl_buff_pool_info_g 5 size CTRL_BUFF_POOL_SIZE256 ctrl_buff_pool_info_g 5 no_of_buff NUM_CTRL_BUFF_POOL_SIZE256 ctrl_buff_pool_info_g 6 size CTRL_BUFF POOL SIZE512 ctrl_buff_pool_info_g 6 no_of_buff NUM_CTRL_BUFF_POOL_SIZE512 ctrl_buff_pool info_g 7 siz CTRL BUFF POOL SIZE1024 ctrl_bUff_pool info g 7 no_of_buff NUM_CTRL BUFF_POOL_SIZE1024 ctrl_buff_pool_info_g 8 size CTRL_BUFF_POOL_SIZE2048 ctrl_buff pool_info_g 8 no_of_buff NUM_CTRL_BUFF_POOL_SIZE2048 ctrl_buff_pool_info_g 9 size CTRL_BUFF_POOL_SIZE4096 ctrl_buff_pool_info_g 9 no_of_buff NUM_CTRL_BUFF_POOL_SIZE4096 ctrl_buff_pool_info_g 10 size CTRL_BUFF_POOL_SIZE8192 ctrl_buff_pool_info_g 10 no_of_buff NUM_CTRL_BUFF_POOL_SIZE8192 ctrl_buff_pool_info_g 11 size CTRL_BUFF_POOL_SIZE16384 ctrl_buff_pool_info_g 11 no_of_buff NUM_CTRL_BUFF_POOL_SIZE16384 ctrl_buff_pool_info_g 12 size CTRL_BUFF_POOL_SIZE32768 ctrl_buff_pool_info_g 12 no_of_buff NUM_CTRL_BUFF_POOL_SIZE32768 ctrl_buff_pool info_ g 13 size CTRL_BUFF_POOL_SIZE65536 ctrl_buff_pool info _g 13 no_of_ buff NUM_CTRL_BUFF_POOL_SIZE60000 MediaTek Confidential Revision 1 6 Septe
32. The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 8 1 1 Access behavior of local parameter and peer buffer A local parameter or peer buffer is normally created by provider which is a task in charge of constructing buffer and will be consumed by one or many consumers Provider and or consumer may call hold local parat or hold peer buff to increment the variable before propagation value decrementing ought to be done at consumer site in paired by calling free_local_para or free peer but For local parameter data is fixed once constructed But peer buffer offers two appending manners either growing up from head prepend to peer buff or down from tail append to peer buff Figures below show the two appending schemes peer buff pdu_len pdu_len pdu_len ref_count ref_count ref_count pb_reserved pb_reserved pb_reserved free_header_space le free_header_space Le Tree header_space wa free_tail_space free tail space gt free_tail_space free head free head free head e valid data valid data valid data Data appending at front and tail of a peer buffer free tail MediaTek Confidential Revision 1 6 September 28 2006 Page 39 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified
33. _ ptr local_para_struct local_data sender_ilm peer_buff_ptr 0 msg_send_ext_queue sender_ilm MediaTek Confidential Revision 1 6 September 28 2006 Page 46 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice My Maui System Service User Manual Interrupt Handler and KAL Programming Guide B Receiver processes an ILM There are two alternative approaches in processing local parameter or peer buffer free _local_para is called artificially in approach 1 whilst local parameter is totally in charged by system in approach 2 Note that if free local para is called be ensured that local parameter point is reset to NULL by the last consumer otherwise in free_ilm it may get the pointer which might be owned by others and finally mistakenly updates others buffer Programmers could transfer the ILM manipulation to system by simply calling free_ilm where system will reset the local parameter pointer and peer buffer pointer to NULL automatically if they are freed Approach 1 Manually maintain local parameter pointer void receiver void ilm_struct current_ilm while 1 receive_msg_ext_q task_info_g INDX_RECEIVER task_ext_qid amp current_ilm switch current_ilm msg_id case MSG_ID_SENDER_TO_RECEIVER OOOO O08 free_local_para current_ilm local_para_ptr current_ilm local para ptr NULL Necessary if it is the last consumer
34. _MEM_SIZE sizeof kal_uint32 Tables below are components list of system and debug memory kal task ype Task s stack Task dependent minimal requirement Task dependent minimal requirement 240B 240B kal_hist_type MediaTek Confidential Revision 1 6 September 28 2006 Page 62 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide HISR s stack HISR dependent minimal requirement HISR dependent minimal requirement 240B 240B kal_queue_type 76 80 Queue pool Size of ilm_struct x number of queue Size of ilm_struct x number of queue entries entries kal_mutex_type kal_sem_type kaltimertype Le a eventscheduler le LI e kal_pool_type 60 Kal internal pool stalisties OP E Total number of entries x 4x2 buffer size Total number of entries x 4x6 buffer size Table 11 2 Occupiers of system memory kal_buff_stat_type 92 This is storage of buffer historical records and each buffer entry occupies 92B kal_queue_stat_type 4 kal_mutex_stat_type 8 EAT O O Table 11 3 Occupiers of debug memory To meet the timing critical requirements system memory is further divided into internal system memory and system memory the former is linked at internal SRAM whilst the later at external SRAM Since the internal SRAM is too limited the internal system memory is
35. _send_int queue Prototype kal_bool msg_send_int_queue ilm_struct ilm_ptr Header file stack_lticom h Input ilm_ptris pointer of ILM which is going to be delivered Output KAL TRUE if message is delivered successfully otherwise return KAL_FALSE Description This is an exported function for message delivery destination is always internal queue of task specified in ilm_ptr gt dest_mod_id If the destination task has no internal queue fatal error would be trapped Soon after delivery the ILM structure which is previously get via allocate_ilm will be returned to the system prepend_to peer buff Prototype void prepend_to_peer_buff peer_buff_struct peer_buff ptr void header_data_ptr kal ui header_len Header file stack_lticom h Input peer_buff ptris pointer of peer buff struct from where new data pointed by header_data_ptr will be appended at front of pdu its length header_len is given in units of Bytes Description As shown in Figure 1 a data record could be appended at head of peer buffer after appending system will update the following information peer_buff_ptr gt free_header_space peer_buff_ptr gt free_header_space header_len peer buff_ptr gt pdu_len peer_buff_ptr gt pdu_len header_len Remark Fatal error prepend_to_peer_buff insufficient header memory fatal error code 1 0x10 error code 2 0x02 happens if either conditions holds 4 peer_buff_ptris NULL 5 header_len is zero 6
36. _strncpy char to const char from int n Header file kal_release h Input to and from are destination and source double characters string respectively n is total number of wide characters to be copied Output The double characters string being copied Description This function copies up to n wide characters from the double characters string pointed to by from into the array pointed to by to kal_dchar_strcmp Prototype int kal_dchar_strcmp const char si const char s2 Header file kal_release h Input s1 and s2 are two double characters strings to be compared Output O if the two double characters strings are exactly identical lt 0 if s1 is less than s2 gt 0 if s1 is greater than s2 Description This function lexicographically compares two double characters strings kal dchar strncmp Prototype int kal_dchar_strncmp const char s1 const char s2 int n Header file kal_release h Input s1 and s2 are two double characters strings to be compared nis total number of wide characters to be compared Output 0 if the two double characters strings are exactly identical lt 0 if s1 is less than s2 gt 0 if s1 is greater than s2 Description This function lexicographically compares two double characters strings not more than n wide characters kal_dchar_strcat Prototype char kal_dchar_strcat char s1 const char s2 Header file kal_release h Input s1 and s2 are two double characters strings to be concatenate
37. _time is the new de bounce time Output 1 if the given EINT channel is illegal 1 if the function is completely done Description This function call aims at dynamically modifying de bouncing time of the given EINT channel Note that the initial de bounce time is specified at custom eint sw debounce time delay but it could be adjusted at run time This function is also done under the protection of disabling interrupt 3 3 nIRQ nIRQ_init Prototype kal bool nIRQ_init void Header file isrentry h Output KAL_TRUE if operation successfully done otherwise KAL_FALSE will be returned Description This service aims at configuring GPIO mode please refer to Table 2 2 for the GPIO mapping Remark It must be called after Drv_Init which is called from Application_Initialize Initialize otherwise the value will be overwritten nIRQ_Registration Prototype void niRQ_Registration kal_bool edge void reg_hisr void kal_bool auto_unmask Header file isrentry h Input edge is the polarity reg_hisris callback function and auto_umask tells the system if it needs to unmask the interrupt and end of processing Description This service provides the registry function for nIRQ it is either falling edge trigger KAL_TRUE or negative level trigger KAL_FALSE and user should also specify the callback function and auto unmask flag 3 4 nFIQ nFIQ_Init Prototype kal bool nFIQ_init void hisr_callback void kal_bool enable kal_bo
38. al Revision 1 6 September 28 2006 Page 11 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 2 internal Design of External Interrupts Both EINT and nIRQ are central controlled by system service EINT channel within range could be registered through EINT_Registration repetitive registration is allowed but only the latest will take effect However system could have at most one nIRQ source once it is registered all the registry following will be blocked with fatal error re register nIRQ HISR error code 1 0x218 error code 2 0 To protect the system from the intervention of instable external interrupt software de bouncing time is applied to provide further protection Sub sections following illustrate the software de bouncing EINT and nIRQ processing flow in detailed 2 1 Software De bouncing In addition to hardware embedded de bounce time 64ms 2048 x 31 25us a software de bounce time is embedded on each EINT channel Any level triggered interrupt should hold the state over the pre defined software de bounce time otherwise its callback function would not be activated The software de bounce time are customizable at mculcustomidrvimisc drvlboard versionleint_def c entries of array custom eint sw debounce time delay is consistent with total number of EINT channels The setting is i
39. ar kal_dchar_strrchr const char ep int ch Header file kal_release h Input stris pointer of double characters string ch is wide character to be searched Output Double characters string Description This function returns a pointer to the last occurrence of the ch in the double characters string pointed to by str kal_dchar2char Prototype void kal dchar char WCHAR outstr char tostr Header file kal_release h Input outstris pointer of wide character string and tostris double character string Description This function is used to convert a wide character string to a single character string kal_wsprintf Prototype void kal_wsprintf WCHAR outstr char fmt Header file kal_release h Description Identical to sprintf except that input string is a wide character string kal_wstrlen Prototype int kal_wstrlen const WCHAR wat Header file kal_release h Input wstris pointer of wide character string Output Length of a wide character string in terms of WCHAR Description This function returns the length of the null terminated string pointed to by wstr For wide character string null terminator is 0x0000 and is not counted kal_wstrepy Prototype WCHAR kal_wstrcpy WCHAR to const WCHAR from MediaTek Confidential Revision 1 6 September 28 2006 Page 75 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service Us
40. ate Status of the semaphore either in KAL_SEM_GIVEN or KAL_SEM_TAKEN kal_mutex_state Status of a MUTEX KAL_MUTEX_GIVEN ifitis in given state or KAL_MUTEX_TAKEN if it is in TAKEN state kal_mutexid Identity of a MUTEX which is internally equivalent to kalsinternal_mutexid Status of a semaphores KAL_SEM_GIVEN ifitis in given state or KAL_SEM_TAKEN if it is in TAKEN state Identity of a semaphore which is internally equivalent to kal_internal_semid kal_eventgrp type Alias of NU_EVENT_GROUP kal_internal_eventgrpid Pointer of type NU EVENT GROUP which is used for internal processing kal_evenigrpid Identity of an event group which is internally equivalent to kal_internal_eventgrpid MediaTek Confidential Revision 1 6 September 28 2006 Page 32 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 7 3 Task Synchronization APIs 7 3 1 MUTEX kal_create_mutex Prototype kal_mutexid kal_create mutex kal_char mutex_name Header file kal_release h Input mutex_name is name of the MUTEX to be created Output Pointer of the created MUTEX Description This function call is dedicated for creating a MUTEX It is strongly suggested to call this function only inssystem initialization time and the related data allocated for the MUTEX could not be freed once it s created
41. ay a om A ih MediaTek idential Revision 1 6 September 28 2006 Page 79 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice
42. c_ptr task_reset_func Task s reset function duplicated from comp_create_func of comptask_info_struct task_end_func_ptr task_end_func Task s end function duplicated from comp_create_func of comptask_info_siruct kal_uint8 task_ext_qsize Total number of external queue entries copied from comp_ext_qsize of comptask_info_ struct kal_uint8 task_int_qsize Total number of internal queue entries copied from comp_int qsize of comptask info_struct kal_bool task_internal_ram_stack lf internal SRAM SYS_INTERN_RAM _ is defined a task stack could be selectively created at internal or external SRAM Itis not suggested that customers create their tasks stack at internal SRAM Description Defines the task control block slightly different if DEBUG_KAL is defined light yellow background color Data Type Element Description kal_os_task_type Inherits from Nucleus Plus task control block task_name Name of the task kal_char Description Defines the HISR control block slightly different if DEBUG_KAL is defined light yellow background color Data Type Element Description kal_os_hisr_type task_id Inherits from Nucleus Plus HISR control block UC LEAD E er ore HA MediaTek Confidential Revision 1 6 September 28 2006 Page 24 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guid
43. ccessful request Table 8 1 Operations on retrieving event group KAL_AND Causes the event flags specified to be ANDed with the current event flags in the group Causes the event flags specified to be ORed with the current event flags in the group Note Event flags can be cleared with the NU_AND option Table 8 2 Operations on setting event group MediaTek Confidential Revision 1 6 September 28 2006 Page 31 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 7 2 Data structures and Data Types Description This data structure aims at tracking the owner and status of a MUTEX Description Defines the control block of a MUTEX slightly different if DEBUG_KAL and DEBUG_ITC are defined light yellow backgrouna Data Type Element Description kal_os_mutex_type mutex_id Inherits from semaphore of Nucleus Plus kal_mutex_state mutex_state Status of the MUTEX either in KAL_MUTEX_GIVEN kal_os_task_type owner_task Owner of the MUTEX which e expressed with task identity or KAL_MUTEX_TAKEN H OIE l Description Defines the control block of a MUTEX slightly different if DEBUG_KAL and DEBUG_ITC are defined light yellow background Data Type Elemet Description kal_os_sem_type sem_id Inherits from semaphore of Nucleus Plus kal_sem_state sem_st
44. ck_timer_struct stack_timer kal_char timer_name module_type mod_id Header file stack_timer h Input stack_timer_struct is the stack timer control block provided by the users timer_name is the name of the stack timer and mod_id is the module ID of the owner to which an expiry ILM will be delivered Description This function provides the facility of initializing a stack timer it is the users responsibility to provide stack timer control block Soon after creation its status remains at STACK_TIMER_INITIALIZED or STACK_TIMER_NOT RUNNING It is strongly suggested to call this function only at system initialization stage and the related data allocated for the stack timer could not be freed once it s created MediaTek Confidential Revision 1 6 September 28 2006 Page 53 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide stack_is_time_out_valid Prototype kal bool stack_is_time_out_valid stack_timer_struct stack timer Header file stack_timer h Input stack_timer is the destination stack timer being queried Output KAL_FALSE if the KAL timer id associated is NIL or the stack timer has ever been stopped or cancelled before expiration otherwise KAL_TRUE Description This function is used for tracking the validity of a timeout notification if it returns KAL_FALSE the timeout handler sh
45. d Output Double characters string being concatenated Description This function concatenates a copy of s2to s1 and terminates s1 with a 0x00 0x00 The null terminator 0x0000 originally ending s1 is overwritten by the first character of s2 kal_dchar_strncat MediaTek Confidential Revision 1 6 September 28 2006 Page 74 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Prototype char kal_dchar_strncat char s1 const char s2 int n Header file kal_release h Input s1 and s2 are two double characters strings to be concatenated this action will be taken on n wide characters Output Double characters string being concatenated Description This function concatenates notmore than n wide characters of the double characters string pointed to by s2 to the double characters string pointed to by s1 and terminates s1 with 0x0000 The null terminator 0x00 0x00 originally ending s7 is overwritten by the first character of s2 kal_dchar strchr Prototype char kal_dchar_strchr const char e int c Header file kal_release h Input sis pointer of double characters string cis wide character to be searched Output Double characters string Description This function returns a pointer to the first occurrence of the cin the double characters string pointed to by s kal_dchar_strrchr Prototype ch
46. d Soon after delivery the ILM structure which is previously get via allocate Um will be returned to the system msg_send_ext_queue_to_head Prototype kal_bool msg_send_ext_queue_to_head ilm_struct ilm_ptr Header file stack_lticom h Input ilm_ptris pointer of ILM which is going to be delivered Output KAL_TRUE if message is delivered successfully otherwise return KAL_FALSE Description This isan exported function for message delivery destination is always external queue of task specified in ilm_ptr gt dest_mod_id Destination task s external queue is targeted through the statement below task_info_g mod_task_g ilm_ptr gt dest_mod_id task_ext_qid MediaTek Confidential Revision 1 6 September 28 2006 Page 43 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Soon after delivery the ILM structure which is previously get via allocate ilm will be returned to the system It is different from msg_send_ext_queue in manner of message delivery behavior API msg_send_ext_queue always sends a message to end of queue forming the last in last out behavior While msg_send_ext_queue_to_ head always sends a message to front of queue forming the last in first out behavior Users may take such feature to force the early process of a high priority message Remark Available from W05 32 msg
47. de Description Defines statistical as well as the historical data of a control buffer Data Type Element Description Description Defines the control block of a control buffer slightly different if DEBUG_KAL DEBUG_BUF and DEBUG_BUF2 are defined Co yellow 1 n color Data DataType O Description kal_os_pool_ type il aE identity inherits from partitioned pool of Nucleus Lemmer Description Defines the structure of KAL buffer header please refer to Figure 2 for the exact layout It is valid if and only if DEBUG_KAL DEBUG_BUF and DEBUG_BUF3 are defined Description Defines the control block of message queue slightly different if DEBUG_KAL and DEBUG_ITC are defined light yellow background color Data Type Element Description kal_poolid pool id Pool identify assigned by the system during creation kal_uint32 size Control buffer size kal_uint16 of Total number of buffer entries kal_uint32 num ol misses Total number of misses for control buffer it is always zero because system would never return NULL pointer on MAUI MediaTek Confidential Revision 1 6 September 28 2006 Page 66 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_poolid Identity of a control buffer which is internally equivalent to kal_internal_poolid kal_buff_state Enumeration type
48. e task_init_func_ptr Function pointer for task initialization function with task_indx_type as input argument and output type is kal_bool task_end_func_ptr Function pointer for task end function with task_indx_type as input argument and output type is kal_bool task_reset_func_ptr Function pointer for task reset function with task indx_type as input argument and output type is kal_bool task_cfg_func_ptr Function pointer for task configuration function with task_indx_type as input argument and output type is kal_bool kal_create_func_ ptr Function pointer with comptask handler_struct as input argument and return type kal_bool which is used for task creation function task_info_g Array of task_info_struct number of the entries is determined by enum of task ID plus 16 customer defined tasks MediaTek Confidential Revision 1 6 September 28 2006 Page 25 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 6 3 Task Management API kal_activate_hisr Prototype void kal_activate_hisr kal sid evt bier Header file kal release h Input hisrid is destination HISR to be activated Description This function call is widely used to activate an HISR once it is activated system will pick up the highest priority HISR in the next scheduling Example static kal_hisrid dma_hisr void DMA_LI
49. e User Manual Interrupt Handler and KAL Programming Guide stack_timer_status Prototype stack_timer_status_type stack_timer_status stack_timer_struct stack_timer kal_uint32 time_remaining Header file stack_timer h Input stack_timer is the destination stack timer being queried and time remaining is used for returning the remaining timeout period Output Current status of the stack timer Description This function is used in retrieving the most updated status of the given stack timer if the timer is being set and not yet timeout system returns STACK_TIMER_NOT_TIMED_OUT otherwise STACK_TIMER_TIMED_OUT 9 3 3 Event scheduler evshed_cancel_event Prototype kal_int32 evshed_cancel_event event_scheduler es eventid eid Header file event_sched h Input es is pointer of an event scheduler eid is the pointer to event ID Output Time difference between current time and event scheduled time in units of timeticks Description This service is called for canceling an event system would reset the event ID eid to NULL before returning however caller should pay attention to its privately saved event id evshed_delete_all_events Prototype void evsbed delete al events event_scheduler es Header file event_sched h Input es is pointer of an event scheduler Description This function aims for removing all events from the double linked list of an event scheduler evshed_get_rem_time Prototype kal_uint32 evshed_g
50. e h Input sis pointer of wide character string cis wide character to be searched Output Wide character string Description This function returns a pointer to the first occurrence of the c in the wide character string pointed to by s kal_wstrrchr Prototype WCHAR kal_wstrrchr const WCHAR str int ch Header file kal_release h Input stris pointer of wide character string chis wide character to be searched Output Wide character string Description This function returns a pointer to the last occurrence of the ch in the wide character string pointed to by Str 11 4 Reentrance functions kal_strtok_r Prototype kal_char kal_strtok_r kal_char sting const kalchar seperators kal_char ppLast Header file kal_release h Input string is string to be tokenized separators tells the separator while ppLast serves as string index Output Pointer to the first character of a token Description This is a re entrance function where more than one caller could tokenize the same source string with individual string index kal_gmtime r Prototype struct tm kal_gmtime_r const time_t timer struct tm t Header file kal_release h Input timer is time to be converted tis pointer for returning the conversion result Output The broken down form of timer it is same with t Description This is a re entrance function used for returning the broken down form of timer in the form of a tm structure 11 5 Exception handling
51. e of the semaphore to be created whose initial value is stated in initial_count Output Pointer of the created semaphore Description This service creates a counting semaphore semaphore values can range from 0 through 4 294 967 294 It is strongly suggested to call this function only in system initialization time and the related data allocated for the semaphore could not be freed once it s created kal_take_sem Prototype kal_status kal_take_sem kal_semid ext_sem_id_ptr kal_wait_mode wait model MediaTek Confidential Revision 1 6 September 28 2006 Page 33 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Header file kal_release h Input ext_mutex_id_ptr is destination semaphore to be taken and wait mode aims for specifying the waiting style KAL_INFINITE_WAIT triggers endless suspension otherwise KAL_NO_WAIT Output KAL_SUCCESS if the operation is done successfully KAL SEM_NOT_AVAILABLE if the semaphore is unavailable Description This service obtains an instance of the specified semaphore Since the instances are implemented with an internal counter obtaining a semaphore translates into decrementing the semaphore s internal counter by one If the semaphore counter reaches zero before this call the service cannot be immediately satisfied The waiting style determines if a task waits infin
52. eeaseessennsenees 11 1 1 NETA MA 99 A SAA 11 2 Internal Design of External Interrupts ccccssecssesseeesseesseeesseeeneeessesaseeeneeeseeesaseesseeeseeesseeesseeseneeaseessenenenes 12 2 1 E 1 5 ES danisistavaayde estes hist E E E eee 12 2 2 Vatenal pyo essing flow of EINT EE 12 2 3 Internal processing flow Of nl 13 3 MA OA ai 14 3 1 ele genug e TT Ban Pere eat has 14 ROMs Kai EN Y o C et 14 AAA A A NA MA A AAA 14 SaveAndSetlROMASK mmmmiiccionincocccc ec 14 TE e E EEN A sch rc cc en 14 3 2 AAA Y AAA A ANA A RA 15 EINT Registration c connncnninnnicncacccc aae D naaa anana nnnannannannnannnannannannnannannnannannnnnnannnanaannnannannnannann nn 15 EXTRA ENN Registration EA BI occ rr 15 EINT_Set Polarity at A EE 15 ENT A a 15 EN o 16 EINT SW D bou nce Modify coi enanar aaan aerae arae aaa Seada ling tevin ace cove deceatesiacnteed eeeetamiatereeeee eines iias 16 3 3 o a ae E 16 PURO WIE A A A A A A 16 NIRQ_ReGistration onnnncnnnncnnnnnncnnccrr nann MA n G A Olaann nnnnnannannnnnnannaannannns 16 3 4 A A JI CA NA AMM y ee 16 AAA YAA A AA AAA 16 4 KAL An Overview cocoicccoiccorcccc O A oc O cacon coronar 19 5 Fundamental Data Types sis c ssssccsscttestescsssssssssssnsanesesssasescacensnesnessseesssaenneaesecassesaseceaseneassaessessaneesaseneaneaesnsaees 20 6 Task EI FEA A ASCAM A SAA 21 6 1 A A AM A O SAA 21 6 2 DajajStuctures apdaDlala ES WEE 23 6 3 Task Mana TIA EE 26 LORIG Ed O
53. eer_buff_struct peer_buff_ptr kal_uint8 new_hdr_len kal_uint16 new_pdu_len kal_uint8 new lt tail_len Header file stack_Itlcom h Input peer_buff_ptris pointer of peer buff struct its pdu length free space of buffer header and tail are going to be replaced with new_pdu_len new_hdr_len and new_tail_len respectively Description Reinitialize peer buffer length including header and tail free space together with pdu length MediaTek Confidential Revision 1 6 September 28 2006 Page 45 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 8 3 Example A typical message passing flow is illustrated as following A Sender allocates packs and delivers anILM typedef struct kal_uint8 ref_count kal_uint16 msg_len kal_uint8 access_ id kal_uint8 file_idx kal_uint16 para sender buffer_struct void sender void ilm_struct sender_ilm allocate_ilm MOD_SENDER Necessary sender_buffer_struct local_data local_data sender_buffer_struct construct_local_para sizeof sender_buffer_struct TD_CTRL local_data gt access_id 0 local_data gt file_idx SENDER_ID FILE local_data gt para 1 Sender ilm src_mod_id MOD_SENDER sender_ilm dest_mod_id MOD_RECEIVER sender_ilm msg_id MSG_ID_SENDER_TO_RECEIVER sender_ilm sap_id NULL sender_ilm local_para
54. efinitely MOD_TIMER dest mod jd stack timer gt dest_mod_id The destination module ID is specified on stack timer control block MSG_ID_TIMER_EXPIRY lt is the constant mesasge ID STACK_TIMER_SAP It is the constant SAP ID local_para_ptr stack_timer Packing the stack timer control block as local parameter It MediaTek Confidential Revision 1 6 September 28 2006 Page 48 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide is not allowed to hold the local parameter of a stack timer timeout message because there is no local parameter header in the stack timer structure peer_buff_ptr NULL Peer buffer is always excluded from the stack timer timeout message On expiration stack timer timeout handler will be waken up by the timer HISR it posts the expiry ILM to the destination task via timeout ILM finally the task being notified will be scheduled by the OS and start to process the expiry ILM However if the task stops the timer before receiving expiry ILM the task shouldn t process the expiry ILM anymore To cover the circumstance two function calls are provided to determine if the expiry message should be taken they are stack is time out valid and_stack process time out Note that they must be called in paired Please refer to their APIs and example on section 6 4 1 for m
55. em handles the EINT unmasking if auto_unmask is set to KAL TRUE 2 3 Internal processing flow of nIRQ nIRQ LISR Mask the nIRQ Activate an HISR nIRQ HISR Servicing callback function Unmask the nIRQ source Processing How or nIRQ It is different from EINT that no de bouncing e done on software level the very first LISR will be serviced and the correspondence callback function is done at HISR level MediaTek Confidential Revision 1 6 September 28 2006 Page 13 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 3 API Below are APIs for interrupts controller EINT and nIRQ 3 1 Interrupt Controller IRQMask Prototype void IRQMask kal_uint8 no Header file intrCtrl h Input no is interrupt source to be disabled please refer to datasheet of related base band chip for number and index of interrupt sources Description This function serves for disabling dedicated interrupt IRQUnmask Prototype void IRQUnmask kal_uint8 no Header file intrCtrl h Input no is interrupt source to be enabled please refer to datasheet of related base band chip for number and index of interrupt sources Description This function serves for enabling dedicated interrupt SaveAndSetIRQMask Prototype kal_uint32 SaveAndSetIRQMask void Header file intrCtrl h Output Current value of CP
56. er Manual Interrupt Handler and KAL Programming Guide Header file kal_release h Input to and from are destination and source wide character string respectively Output The wide character string being copied Description This function call aims to copy the content of wide character string frominto wide character string to kal_wstrncpy Prototype WCHAR kal_wstrncpy WCHAR to const WGHAR from int n Header file kal_release h Input to and from are destination and source wide character string respectively nis total number of wide characters to be copied Output The wide character string being copied Description This function copies up to n wide characters from the wide character string pointed to by from into the array pointed to by to kal_wstrcmp Prototype int kal_wstrcmp const WCHAR ei const WCHAR s2 Header file kal_release h Input s1 and s2 are two wide character strings to be compared Output 0 if the two wide character strings are exactly identical lt 0 if s1 is less than s2 gt 0 if s1 is greater than s2 Description This function lexicographically compares two wide character strings kal_wstrncmp Prototype int kal_wstrncmp const WCHAR ert const WCHAR ez int n Header file kal_release h Input ST and s2 are two wide character strings to be compared n is total number of wide characters to be compared Output 0 if the two wide character strings are exactly identical lt 0 if s1 is less tha
57. est_mod_id Destination module ID sap mee sap_id SAP ID msg_id Message ID Description Data structure dedicated for queue information including number of pending messages and total number of queue entries Data Type Element Description kal_uint32 pending_msgs Number of pending messages kal_uint32 max_msgs Total number of queue entries Description This data structure aims at tracking the statistical data of currently pending as well as maximal number of pending messages It is valid if and only if DEBUG_KAL together with DEBUG_ITC are defined Data Type kal_uint16 kal_uint16 Description Defines the control block of message queue slightly different if DEBUG_KAL and DEBUG_ITC are defined light yellow background color Data Type a ee kal oe oueue type Inherits from Nucleus Plus Queue control block Kal_uint16 max_msg_size Maximal message size in terms of Bytes which is now always equal to size of ilm_struct kal_internal_queue_ statistics Pointer of queue statistical record Enumeration type of SAP ID Enumeration type of message ID must be leading with MSG_ID_ kal_msgqid Identity of a message queue which is internally equivalent to kal_internal_msgqid module_ilm_g Array of ilm_struct number of the entries is determined by enum of module ID plus 16 customer defined tasks MediaTek Confidential Revision 1 6 September 28 2006 Page 38 of 79 2004 2006 MediaTek Inc
58. et_rem_time event_scheduler es eventid eid Header file event_sched h Input es is pointer of an event scheduler and es is pointer of event ID Output The remaining time ticks Description This function used to return the remaining time ticks of the dedicated event ID evshed_resume_all_ events Prototype void evshed_resume_all_events event_scheduler es Header file event_sched h Input es is pointer of an event scheduler Description This function aims to resume all of the events registered on an event scheduler evshed_set_event Prototype eventid evshed_set_event event_scheduler es kal_timer_func_ptr event bt void event_hf_param kal_uint32 elapse_time Header file event_sched h MediaTek Confidential Revision 1 6 September 28 2006 Page 55 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Input es is pointer of an event scheduler event_hfis the event timeout handler event Dt Garam points to event timeout handler s parameter and elapse_time tells the total elapse time in ticks Output Pinter to the event ID Description This service is provided for setting an eventto an event scheduler system would allocate memory for event id and return to the caller If caller need to save such event id please remember to reset it when cancel the event or oniits expiration because
59. ey system is in META or factory mode USBMS_BOOT if the system is in USB boot mode NORMAL_BOOT if the system is in normal power on mode UNKNOWN_BOOT_MODE if the system not yet known its boot mode Description This service aims at providing boot mode information to caller it is available for LISR HISR task level query in system boot up stage UNKNOWN BOOT MODE will probably get 113 Multi bytes string processing kal_dchar_strlen Prototype _ int kal_dchar_strlen const char wstr Header file kal_release h Input wstr is pointer of string Output Length of a double character string in terms of Bytes MediaTek Confidential Revision 1 6 September 28 2006 Page 73 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Description This function returns the length of the null terminated double character string pointed to by wstr For double character string null terminator is 0x00 0x00 and are not counted kal_dchar_strcpy Prototype char kal_dchar_strcpy char o const char from Header file kal_release h Input to and from are destination and source string respectively Output The double characters string being copied Description This function call aims to copy the content of double characters string from into double characters string to kal_dchar_strncpy Prototype char kal_dchar
60. fixed for each base band chip Before W04 41 system memory configuration follows convention illustrated in Table 11 4 Otherwise Table 11 5 will be followed o d Y System Memory External RAM 300K 560K Internal System Memory Internal RAM Table 11 4 Internal system memory size configuration before W04 41 MediaTek Confidential Revision 1 6 September 28 2006 Page 63 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Table 11 5 Internal system memory size configuration W04 41 and later MediaTek Confidential Revision 1 6 September 28 2006 Page 64 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 10 2 Data Structures and Data Types 10 2 1 Control buffer Tables below illustrate the data structures and data types commonly used in managing control buffer Description Defines the statistical content of certain size of control buffer the record is valid if and only if compile option DEBUG_BUF is defined Data Type kal_uint16 kal_uint16 kal_uint16 current_allocation kal_uint16 max_num_allocated kal_uint16 Description Total number of the buffer entries which is consistent with the configured number Buffer size in te
61. for stack timer management Data Type Element Description module 18 Sieg E sack imer Saus he kal_uint8 invalid_time_out_count Number of cancellation before the processing of MediaTek Confidential Revision 1 6 September 28 2006 Page 50 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide expiry message It is used in the functions stack_process timeout and stack_stop_timer Both of these functions are supposed to be called by the modules of the same task for the same stack timer There will be race conditions in caseof concurrentaccess from multiple tasks stack_timer_status_type ris an enumeration type of stack timer status STACK_TIMER_INITIALIZED STACK TIMER NOT RUNNING STACK_TIMER_INITIALIZED STACK_TIMER_RUNNING STACK_TIMER_NOT_TIMED_OUT STACK_TIMER_RUNNING STACK_TIMER_EXPIRED STACK_TIMER_TIMED_OUT STACK_TIMER_EXPIRED STACK_TIMER_STOPPED 9 2 3 Event scheduler Tables below illustrate the data structure and data types used by an event scheduler Description Fundamental unit of double linked list abbreviated as led_ dll Data Type Element Description Pore of acual sage kd d node L pev fre previous pointer eddie ler enod pier Description Internal data structure for double linked list will allocation and de allocation handler Data Type Element De
62. ge passing flow 8 1 Data Structures and Data Types Tables below illustrate the data structure of an ILM in detailed Description Local parameter acts as extended storage of an ILM besides single local parameter may be propagated to more than one destination Therefore header of a local parameter consists of two elements ref_count tells the total number of consumers and msg len is used in tracking the storage length Data Typ jp Element Description kal_uint8 Number of references must not exceed 255 kal_uint16 msg_len Message length in terms of bytes Description Peer buffer which also serves as additional storage while message passing Similar with local parameter single peer buffer may be propagated to more than one destination therefore ref_count tells the total number of consumers and pdu_len is used in tracking the length of peer data pdu It is different from local parameter in the behavior of message accessing Further description could be found in the next sub section Data Type ua kant rant E E Description Fundamental unit of a message packet Data Type Element Deseription module_type Source module ID MediaTek Confidential Revision 1 6 September 28 2006 Page 37 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice My Maui System Service User Manual Interrupt Handler and KAL Programming Guide module module type d
63. gistered on KAL timer must take the processing latency into account the longer processing period delays the subsequent processes more A statistical data structure is integrated on KAL timer control block for the tracking of following items Ml Number of timer cancellations RW Number of timer expirations RW Timer status either KAL TIMER_CREATED KAL TIMER_SET KAL_TIMER_CANCELED or KAL_TIMER_EXPIRED Note that timer statistic is available if DEBUG_KAL and DEBUG_TIMER are defined 9 1 2 Stack timer Stack timer is the second accurate timer provided on the system It is designed to relieve system loading on processing KAL timer timeout handler also the concurrent programming issues Stack timer is different from KAL timer in the behavior of handling timeout procedure The later is achieved by registering callback function on the dedicated KAL timer while the former is done by message delivery on stack timer timeout routine The timeout unit processes the correspondence procedure on its task context Obviously the accuracy of timeout notification is sacrificed on the flow of message delivery besides system scheduling status and scheduling overhead Each stack timer associates a KAL timer and it is more suitable for down counting timer rather than event that frequently happens in addition late timeout notification is allowed The typical ILM content of a stack timer timeout message as below src_mod_id MOD_TIMEr The source module ID is d
64. ia create function To keep the consistency customers are discouraged to create a task by calling kal_create_task directly Following is the step by step illustration about creating a customer task Step 1 Define task ID and module ID Task ID and module ID are two fundamental identifier of a task the former is widely used for targeting a task entry while the later is widely used in message passing They are defined in mculcustomisystemiboard version custom_config h typedef enum typedef enum INDX_CUSTOM1 RPS_CUSTOM_TASKS_ BEGIN MOD_CUSTOM1 MOD_CUSTOM_BEGIN INDX_CUSTOM2 MOD_CUSTOM2 RPS_CUSTOM_TASKS END MOD_CUSTOM_END custom_task_indx_type custom_module type The red bolded wordings must not be eliminated because system relies on them to restrict the number of customer tasks At most 16 customer defined task ID and 16 customer defined modules 1D are allowable nowadays In case of violation fatal error Customer creates too many tasks fatal error code 1 0x1501 error code 2 number of customer defined task and fatal error Customer defines too many module IDs fatal error code 1 0x1502 error code 2 number of customer defined module will be suffered respectively Step 2 Fill in module to task ID mapping table Complete the module ID to task ID mapping table it is defined in mcu custom system board version custom_config c Following the previous example both task INDX_CUSTOM1 and INDX_CUSTOM2
65. imer_handler In kal_cancel event 1 system releases memory by referencing the event ID henceforth users must ensure it is reset at the registered event timeout handler Otherwise users may accidentally cancel the event set by the new owner who set an event soon after the previous was timeout Function call evshed_timer_handler is dedicated for processing a series of timeout event registered on an event scheduler MediaTek Confidential Revision 1 6 September 28 2006 Page 49 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 9 2 Data Structures and Data Types 9 2 1 KAL timer Tables below illustrate the data structure and data types used by KAL timer Description KAL internal structure for tracking the statistical data of a KAL timer valid if both DEBUG_KAL and DEBUG_TIMER Description KAL internal structure for maintaining KAL timer among the elements timer_stat is valid if DEBUG_KAL and DEBUG_TIMER are defined nal tr ei kal_timer_state Tracking the KAL timer status either KAL_TIMER_CREATED KAL_TIMER_SET KAL_TIMER_CANCELED or KAL_TIMER_EXPIRED kal_timerid Timer ID of KAL timer which is internally equivalent to kal_internal_timerid 9 2 2 Stack timer Tables below illustrate the data structure and data types used by stack timer Description Internal data structure
66. ing is structure name MediaTek Confidential Revision 1 6 September 28 2006 Page 19 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M 5 Fundamental Data Types Maui System Service User Manual Interrupt Handler and KAL Programming Guide Table below summarizes all the fundamental data types provided by KAL they work if kal_release h is included Components abbreviated as NU_xxx are Nucleus Plus core related please referto Nucleus Plus documentation kal char Type of character kal os _task_type Equivalent to NU_TASK kal_int8 kal_uint8 kal_int16 kal_uint16 kal_int32 kal_uint32 kal_int64 kal_uint64 kal_bool kal_status MediaTek Confidential 8bits signed integer 8bit unsigned integer 16bits signed integer 16bit unsigned integer 32bits signed integer 32bit unsigned integer 64bits signed integer 64bit unsigned integer Boolean type typedef enum KAL_FALSE KAL_TRUE kal_bool typedef enum KAL_SUCCESS KAL ERROR KAL_Q_FULL KAL_Q_EMPTY KAL_SEM_NOT_AVAILABLE KAL_WOULD_BLOCK KAL_MESSAGE_TOO_BIG KAL_INVALID_ID KAL_NOT_INITIALIZED KAL_INVALID_LENGHT KAL_NULL_ADDRESS KAL_NOT_RECEIVE KAL_NOT_SEND KAL_MEMORY_NOT_VALID KAL_NOT_PRESENT KAL MEMORY_NOT_RELEASE kal_status kal_os_hisr_type kal_os_queue_type kal_os_mutex_type kal_os_sem_type kal_os_eventgrp_type kal_os_timer_type kal_os_poo
67. it is no longer valid evshed_suspend_all_events Prototype void evshed_suspend_all_events event_scheduler es Header file event_sched h Input es is pointer of an event scheduler Description This function aims to suspend all of the events registered on an event scheduler evshed timer handler Prototype void evshed_timer_handler event_scheduler es Header file event_sched h Input es is pointer of an event scheduler Description This is the unified entrance of the timeout handler of the given event scheduler new_evshed Prototype event_scheduler new_evshed void timer_id void start_timer void unsigned int void stop_timer void kal_uint32 fuzz malloc_fp_t alloc_fn_p free_fp_t free fn_p kal_uint8 max_delay_ticks Header file event sched h Input timer_id is the base timer pointer of an event scheduler s base timer pointer start_timer is the base timer start handler stop_timer acts as base timer stop handler fuzz is the event scheduler s event correction time offset alloc fn_p is the event allocation handler free_fn_p is the event free handler and max_delay_ticks tells if it is an aligned timer Output Pinter to the created event scheduler Description This function is called for creating an event scheduler users are responsible to provide timer start and stop handler memory allocation and de allocation function handlers To optimize power saving before system getting into sleep mode it will
68. itely or returns immediately kal_give sem Prototype void kal_give_sem kal_semid ei sem d ptr Header file kal_release h Input ext sem_id_ptris destination semaphore to be given Description This service releases an instance of the semaphore specified by the parameter ext_sem_id ptr If there are any tasks waiting to obtain the same semaphore the first task waiting is given this instance of the semaphore Otherwise if there are no tasks waiting for this semaphore the internal semaphore counter is incremented by one 7 3 3 Event group kal_create_event_group Prototype kal_eventgrpidkal_create event group kal char eventgrp_name Header file kal_release h Input eventgrp_name is name of the event group to be created Output Pointer of the created event group Description This service creates an event flag group each event flag group contains 32 event flags All event flags are initially set to 0 kal set eg events Prototype kal status kal sei eg events kal_eventgrpid eg d kal_uint32 events kal_uint8 operation Header file kal release h Input eg_id is destination event group to be set and events are event flags to be set while operation defines various operation mode either KAL_OR or KAL_AND Output KAL_SUCCESS if the operation is done successfully Description This service sets the specified event flags in the specified event group Any task waiting on the event group whose event flag request is satisfied b
69. kal_get_time remaining Prototype kal_uint32 kal_get_time remaining kalatimerid ext_timer_id Header file kal_release h Input ext_timer_id is identity of a KAL timer being queried Output Remaining timeout period expressed in 32bits unsigned integer Description This is used in retrieving the remaining timeout period also in units of time ticks kal_get_timer_statistics Prototype void kal_get_timer_statistics kal_timerid ext_timer_id kal_timer_statistics ext_timer_stat Header file kal_release h Input ext_timer_idis ID of KAL timer being queried and ext_timer_stat is used for returning the statistical record Description Users could use this function for retrieving the current statistical record kal_set_timer Prototype void kal_set_timer kal_timerid ext_t_id kal_timer_func_ptr handler_func_ptr void handler_param_ptr kal_uint32 delay kal_uint32 reshedule_time Header file kal_release h Input ext_t_idis identity of a KAL timer handler_func_ptris pointer of timeout handler handler_param_ptris pointer to timeout handler s parameter delay is timeout duration in terms of time ticks the maximum value is OxFFFFFFFF Argument reshedule_time is auto rescheduled time Description This function call offers the service of setting a timeout period to the given KAL timer In DEBUG_TIMER mode a timer switches to KAL_TIMER_SET once it is set 9 3 2 Stack timer stack_init_timer Prototype void stack_init_timer sta
70. l_info_g pool_indx pool_id will be trapped in case of exceeding It is internally inheritance from partitioned pool of Nucleus Plus the predefined pool size are 8 16 32 64 128 256 512 1024 and 2048Bytes System always assign the smallest met control buffer to the user for instance if 50Bytes buffer is required system will definitely allocate from 64B control buffer Although space wasting fragmentation issue is thoroughly eliminated In addition system triggers fatal error Buffer not available fatal error code 1 0x804 and error code 2 size of control buffer if the specific buffer size has been run out of free space in other words users of control buffer should be timing critical resource sensitive and may not have the capability of error handling The control buffer size and number of each entry are defined in mcu adaptation include ctrl_buff_pool h However customers could re define the number of entries according to their requirement except that system error may occur if the original requirement is no longer satisfied meu custom system board version custom_system c GPRS Class B Solution typedef enum GSM Only typedef enum NUM_ CTRL_BUFF_POOL SIZE08 85 NUM_CTRL BUFF_POOL SIZE16 85 NUM_CTRL_BUFF_POOL SIZE32 85 NUM_CTRL_BUFF_POOL_SIZE64 85 NUM_CTRL_BUFF_POOL_SIZE128 61 NUM_CTRL_BUFF_POOL_SIZE256 50 NUM_CTRL_BUFF_POOL_SIZE512 21 NUM_CTRL_BUFF_POOL_SIZE1024 17 NUM_C
71. l_type WCHAR kal_wait_mode KAL_ADM_ID Equivalent to NU_HISR Equivalent to NU_QUEUE Equivalent to NU_SEMAPHORE Equivalent to NU_SEMAPHORE Equivalent to NU_EVENT GROUP Equivalent to NU TIMER Equivalent to NU PARTITION_POOL 16bit unsigned short Waiting style typedef enum KAL_NO_WAIT KAL_INFINITE_WAIT kal_wait_mode Type of void Table 6 1 Fundamental data types Revision 1 6 September 28 2006 2004 2006 MediaTek Inc Page 20 of 79 The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 6 Task Management Task management unit is in charge of the creation of system and customer defined tasks besides scheduling the execution of tasks and High Level Interrupt Service Routine HISR 6 1 Description Basic execution unit on MAUI is either a task or HISR and could be interrupted Context switch takes place no matter system call is trapped or interrupts and scheduling scheme applied on the system is priority scheduling Table below states the priority coverage and their distribution convention Any two tasks or two HISRs which have identical priority are scheduled in sequential manner The highest priority HISR is always reserved for L1_HISR others are prohibited Otherwise fatal error would be encountered during HISR creation Fatal error code 1 0x213 code 2 0x04 The second highest priority
72. ll is useful in retrieving length of local parameter buffer and its start address get_pdu_ ptr Prototype void get_pdu ptr peer_buff_struct peer_buff_ptr kal_uint16 length_pir Header file stack_lticom h Input peer_buff_ptris pointer of peer buff struct and ength_ptr will be used to return length of current pdu Output Pointer which targets at the starting address of peer data MediaTek Confidential Revision 1 6 September 28 2006 Page 42 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Description This function call is useful in retrieving length of peer buffer and start address of peer data the later is obtained from kal_uint8 peer_buff_ptr sizeof peer_buff_ptr peer_buff_ptr gt free_header_space hold_peer_ buff Prototype kal bool hold_peer_buff peer_buff struct Geer buff_ptr Header file stack_lticom h Input peer_buff_ptris pointer of peer buff struct whose content is going to be reserved for some consumer Output KAL FALSE if peer_buff_ptris NULL pointer otherwise KAL_TRUE Description If peer_buff_ptris not NULL increment its reference counter peer_buff_ptr gt ref_count by 1 Note There is another re entrant function hold_peer_buff_r which has protection on access to reference count One who may have race condition problem of reference count could
73. mber 28 2006 Page 60 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide For easy debugging some detection mechanisms are associated on each buffer entry and they are isolated with compile options DEBUG_KAL and DEBUG_BUF Figure below shows the internal structure of a buffer entry 128B Control Butter pool 61 entries totally Buffer 0 next available pool_id Size required by the user Buffer 60 Internal structure of a buffer entry if DEBUG_KAL DEBUGSBUF and DEBUG_BUF2 are defined Corruption of either buffer header 0xF1F1F1F1 or footer OxF2F2F2F2 will block the normal execution and system error will be awakening instead Detection of buffer corruption is done during buffer allocation and de allocation Besides MAUI provides an easy approach to diagnose memory leak issue By monitoring operations on each buffer entry from specific control buffer size user could easily determine whether the system is suffering from memory leak Buffer monitoring would not work if either of the compile options DEBUG_KAL DEBUG_BUF and DEBUG_BUF2 is excluded Penalty of monitoring is more memory consumed and longer latency in allocating and releasing buffer because task ID file name line number and buffer size will be recorded onto buffer history each time operation is done Henceforth buffer moni
74. ming Guide 6 2 Data Structures and Data Types Tables following illustrate the general data structures and data types applied on task management unit Description Defines the task configuration component including task entrance initialization and others three optional functions configuration reset and end functions Data Type Element Description kal_task_func_ptr comp_entry_func Task entry function task_init_func_ptr comp_init_func Task initialization function optional task_cfg_func_ptr comp_cfg_func Task configuration function optional task_reset_func_ptr comp_reset_func Task reset function optional task_end_func_ptr Comp end Tune Task end function optional Description Constant type array it is used for task description the task would not be created if its create function is NULL Data Type Element Description kal_char Comp name Dir Task name kal_char comp_qname_ptr Name of external queue kal_uint32 comp_priority Task priority kal uint16 Comp stack size Stack size in terms of Bytes kal_uint8 comp_ext_qsize Number of external queue entries kal_uint8 comp_int_qsize Number of internal queue entries kal_create_func_pir comp_create_func Function pointer of creates function with comptask_handler_struct as input argument and return type is kal_bool kal_bool comp_internal_ram_stack Specify if the stack size to be created from internal SRAM it is not suggested that customers create their
75. mory block not yet returned Description This function call is specific for deleting an ADM kal_adm_alloc Prototype void kal_adm_alloc adm_ id size Header file kal_release h Input adm_id is destination ADM from where a memory piece will be allocated and size is the required memory size Output Pointer of the allocated memory piece if operation successfully done otherwise NULL Description This service aims at allocating a memory piece from the dedicated ADM Be very careful that if ADM logging is enabled extra memory space will be consumed It is excluded from the size specified in input parameter kal_adm_free Prototype void kal_adm_free KAL_ADM_ID adm_id void mem_addr Header file kal_release h Input adm_id is destination ADM to which the memory pointer mem_ador will be returned Description This function call aims at releasing a memory pointer to the dedicated ADM if ADM logging is turned on memory header and footer will be checked during pointer releasing kal_adm_get_max_alloc_size Prototype kal_uint32 kal_adm_get_max_alloc_size KAL_ADM_ID adm_id Header file kal_release h Input adm_id is destination ADM to be queried Output Maximal available memory size to be allocated Description This function is designed for querying the maximal available memory size that ADM is affordable If ADM logging is turned on the actual exercisable size should subtract the logging size of ADM_MB_LOG header
76. my_error_handler fail to create a dm pool MediaTek Confidential Revision 1 6 September 28 2006 Page 72 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 11 Utility APIs This chapter collects all the utility APIs which may be an inline function macro or the re written APIs to avoid re entrance problem 11 1 Memory operation kal_mem_cmp Prototype kal_int32 kal mem_cmp void src1 void src2 kal_uint32 size Header file kal_release h Description It is an inline function of mem_cmp it compares the first size Bytes of the arrays pointed to by src and src2 kal_mem_cpy Prototype void kal_mem_cpy void dest const void src kal_uint32 size Header file kal_release h Description It is an inline function of mem_cpy it copies size Bytes from the array pointed o by src into the array pointed to by dest If the arrays overlap the behavior is undefined kal_mem_set Prototype void kal mem set void dest kal_uint8 value kal_uint32 size Header file kal release h Description It is an inline function of mem set it copies value into the first size Bytes of the array pointed to by dest itreturns dest 11 2 Boot mode querying stack_query_boot_mode Prototype boot mode type stack_query_boot_mode void Header file kal_release h Output FACTORY_BOOT if th
77. n units of 10ms kal_uint8 custom_eint_sw_debounce_time_ delay EINT_MAX_CHANNEL 50 EINT 0 500ms 50 GEINT 1 500ms 50 GEINT 2 500ms k 2 2 Internal processing flow of EINT EINT Low Level Interrupt Service Routine LIS R Get the EINT status lt NO Mask the EINT SS Activate an HISR Mask EINT Acknowledge EINT MediaTek Confidential Revision 1 6 September 28 2006 Page 12 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Processing flow of EINT LISR EINT HISR Get the active channel Process th callback function YES Unmask the EINT source NO Processing flow of EINT HISR On the very firsthappening of an EINT LISR system won t take action but start a timer according to the pre defined software de bouncing time instead Meanwhile EINT source is disabled or masked until the timeout routine is serviced The next occurrence of the same EINT LISR will then activate the EINT HISR and EINT callback function registered through EINT Registration takes effect finally However if the external interrupt signal no longer holds the EINT interrupt status will be reset internally and kept unmasked for the next issuing At the HISR high level interrupt service routine EINT unmasking will be done according to the user s specification Syst
78. n s2 gt 0 if s1 is greater than s2 Description This function lexicographically compares two wide character strings not more than n wide characters kal_wstrcat Prototype WCHAR kal_wstrcat WCHAR s1 const WCHAR s2 Header file kal_release h Input s1 and s2 are two wide character strings to be concatenated Output Wide character string being concatenated Description This function concatenates a copy of s2 to s1 and terminates s1 witha 0x0000 The null terminator 0x0000 originally ending s7 is overwritten by the first character of s2 kal_wstrncat Prototype WCHAR kal_wstrncat WGHAR ei const WCHAR e int n Header file kal_release h Input s1 and s2 are two wide character strings to be concatenated this action will be taken on n wide characiers Output Wide character string being concatenated Description This function concatenates not more than n wide characters of the wide character string pointed to by s2 to the wide character string pointed to by s1 and terminates s1 with 0x0000 The null terminator 0x0000 originally ending s7 is overwritten by the first character of s2 MediaTek Confidential Revision 1 6 September 28 2006 Page 76 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_wstrchr Prototype WCHAR kal_wstrchr const WCHAR s int c Header file kal_releas
79. ng or time out state If it s in running state the new time out value would be applied if this function is called On the other hand if it s in time out state the original time out message will still be processed and a new timer will be scheduled stack_stop_timer Prototype stack_timer_status_type stack_stop_timer stack_timer_struct stack timer Header file stack_timer h Input stack_timeris the destination stack timer to be stopped Output Current status of the stack timer Description On the termination of a stack timer the processing procedure is highly dependent on it current status If the stack timer stays at STACK_TIMER_INITIALIZED or STACK_TIMER_NOT_RUNNING system does nothing except refilling its status to STACK TIMER_NOT_RUNNING If it is in STACK_TIMER_RUNNING at the mean time system will cancel it directly Having completely cancelled the stack timer its status will be re examined again if it is ever switched to STACK_TIMER_EXPIRED during the period the tracking element invalid_time_out_count will be incremented besides further changing the status to STACK_TIMER_STOPPED however the return will be STACK_TIMER_TIMED_OUT Otherwise the stack timer status and the return value will be STACK_TIMER_STOPPED consistently MediaTek Confidential Revision 1 6 September 28 2006 Page 54 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Servic
80. node eventid An event node on event scheduler it will be known an event ID subsequently 9 3 APls 9 3 1 KAL timer kal_cancel_timer Prototype void kal_cancel_timer kal_timerid est Omer Header file kal_release h Input ext_timeris destination KAL timer to be cancelled Description This service is used to cancel a timer in DEBUG_TIMER mode it is switches to KAL_TIMER_CANCELED if it is successfully cancelled kal_create_timer Prototype kal_timerid kal_create_timer kal_char mer name ptr Header file kal_release h Input timer_name_ptr is name of the timer to be created Output A KAL timer ID will be returned it is successfully created Description This service is used for creating KAL timer in DEBUG_TIMER soon after creation the timer stays at KAL_TIMER CREATED state It is strongly suggested to call this function only at system initialization stage and the related data allocated for the timer could not be freed once it s created MediaTek Confidential Revision 1 6 September 28 2006 Page 52 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_get_time Prototype void kal_get_time kal_uint32 ticks_ptr Header file kal_release h Input ticks_ptris used for returning currenttime ticks Description Users could use this function to query current time ticks
81. noninaconnnnnco rana nnnnaco rana rana rra rc Y A o 56 evshed timer Handler coccion er A e KE 56 ARO AAA A A el gt AM 56 9 4 Cl ee Vs AA AA A A RA 57 10 Memory Management common 59 10 1 Descriptions a O A 0 ocio 59 10 1 1 Control buffe FAR BU P O ccoo cnn 59 IIS AAA WK ARM AA 62 10 13 System memory and debug memorm ee 62 10 2 WalajStlictures apdaData IES WEEN 65 10 2 1 Control AA cc 65 10 22 nh O bots 67 ECH ki Je urclud 1 WEEN 69 Cahier a E T dae 69 oE e DU a Eeer 69 AAPP A 8 E 69 kal_query_ctrlbuf_Max_CONSUMPRION 2 ccceeeeeeseeeeeeeeeeeseeeeeneneeensneeeeeneeeesseeeesneeeaseedisdiececeneneeessegeesseeeeeseeenseees 69 UR GC EEGENEN MS W a EO it 69 Kal_adM_CrOAtO nonniccncnnncninncnnncnrr An nan A E D atean annaa aana a S oaaae 69 CCl ee cc ee A 2 69 Kal_adim_alloc ccs cececseeesesese E GE Kaf AA s O cocoa raras 70 kal adm Tree YM AAA MM AR SSA 70 kal adm gel d cb loc Mr coc IR ccoo nana 70 kal_adm geratotal Yeft_size A A 229 cc rr 70 kal_adm_Check_ ici RMB E 70 10 3 3 System and debug Memory cccecceccecceeeeeceeeeeeeeeeeeaaeeceeaeeseaeeesesaeeeceaaeeeecaeeeseaaeeeeseaeeeseeeeseeeeessiaeees 71 MediaTek Confidential Revision 1 6 September 28 2006 Page 7 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Inte
82. nt_peer_buff kal_uint16 pdu_len kal_uint16 header_len kal_uint16 tail_len kal_char le name opt kal_uint32 line if DEBUG_KAL is defined otherwise it is defined as void construct_int_peer_buff kal_uint16 pdu_len kal_uinti6 header_len kal_uint16 tail_len Similar with construct_int_local para system is responsible to allocate buffer for peer buffer in construct int peer buff total buffer size is summation of sizeof peer buff ptr header_len pdu len and tail_len if it is called by TST task system allocates buffer from TST buffer otherwise from control buffer The return buffer pointer will then be casted as pointer of local_para_struct the first byte of the buffer or ref_count will be initialized to 1 and the second 2 bytes of the buffer or msg_len would be filled as ocal_para_size Tree Um Prototype void free Um ilm_struct ilm_ptr Header file stack_lticom h Input ilm_ptr is pointer of ilm_struct which is going to be freed Description This is macro of void free_int_ilm ilm_struct ilm_ptr kal_char file_name kal_uint32 line if DEBUG_KAL is defined otherwise it is defined as void free_int_ilm ilm_struct ilm_ptr If iim_ptr gt peer_buff_ptr is not NULL then decrement the associated reference count i m_ptr gt peer_buff_ptr gt ref_count if it becomes zero system will free the buffer directly and resets the peer buffer pointer to NULL The same algorithm will be applied on local parameter as well
83. o Ar 26 MediaTek Confidential Revision 1 6 September 28 2006 Page 4 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide LORICH ONT O E 26 kal_create_hisr AAA A LAA A 26 CCl MCL ee e O cagon ee 26 kal_get_mytask_priority ccscssecessugeese A BW O O cercare 27 kal_get_task_self_id hM AAA ZS TA o O occ concern cerros 27 kal_if_ his 08 D O occ g WIEN 27 LEE NS AA A A A TE 27 stack_chaii e priority OMIC coccion ran corno 27 6 4 CU E ffe a 28 7 Task Synchronization Management ccs eccesseeeeeeseeeeeseeeeneeeeeeneaeeeesseeeessneeeeseaeeenseeeeessneesessneeeaeeeeeensneeees 31 7 1 O AE 31 7 1 1 Eventos a a A e 31 7 2 Data structures and Data Types ooooconncccnccconoconnnanannnonononennonnnnno nono na rra nnnn cnn lil cnn 32 7 3 Task Synchronization APIs 7 3 1 MUTEX kal_create_mutex kal_take_muteX ene le AA gn ee cercos 33 ARA O AA A L A AA SARA 33 7 3 2 Semaphgre ed ak o OF Weg 33 kal create SOMA WK a cc 99 II ccoo racer 33 Kal TASA o A rr EE EE E E E E E E E 33 GCUI OA MB a rr 34 7 3 3 CC aid da 34 al O a 34 k l set eg events a td iii 34 A A y VE 34 7 4 a ue iia a O A Te 36 8 Task Communication Management nnmnncniccninnnconcanc temna iDnnnnaaninnnnnnnanennnennnnnnnnnennnnnnnnn nanenane 37 8 1 Data Structures and
84. of buffer status typedef enum KAL_BUFF DEALLOCATED KAL_BUFF_ALLOCATED KAL_BUFF_CORRUPTED kal_buff_state Array of buff_pool_info_struct number of the entries is determined by RPS_CREATED_CTRL_BUFF_POOLS defined in mculadaptation include ctrl_buff_pool h It is an unified entrance of control buffer 10 2 2 ADM Description Defines the header structure of an ADM DataType Element Description Pointer to the previous memory block MB Pointer to the next memory block MB Description Defines the footer of a memory piece allocated from some ADM Data Type Element Description kal_uint32 stamp Fixed pattern 0x04F4F4F4 for the detection of memory corruption Description Defines the data structure of ADM memory logging Data Type Element Description kal_uint32 Fixed pattern 0x03F3F3F3 for the detection of memory corruption kal_char filename File name eume pae LN CSCS Description Defines the control block of an ADM Data Type Element Description MediaTek Confidential Revision 1 6 September 28 2006 Page 67 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_uint32 Identity of ADM kal_uint16 Number of block lists kal_uint16 Owner of the ADM existed if DEBUG_ADM is defined otherwise it is a reserved field kal_uint
85. ol auto_unmask kal_bool sensitivity Header file isrentry h Input hisr_callback is the callback function of nFIQ HISR If enable is KAL_TRUE system will enable nFIQ at nFIQ_Init auto_unmask leads the automatically unmask of nFIQ at HISR otherwise user is responsible to unmask it sensitivity is used to specify the sensitivity KAL_FALSE tells LEVEL_SENSITIVE and KAL_TRUE is EDGE_SENSITIVE MediaTek Confidential Revision 1 6 September 28 2006 Page 16 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Output Apply this function on base band chip without nFIQ results in the return value KAL FALSE otherwise KAL_TRUE Description This service aims at configuring GPIO mode please refer to Table 2 2 for the GPIO mapping Besides LISR registration and HISR creation of nFIQ are also done in the function Remark 1 It must be called after Drv_Init which is called from Application_Initialize Initialize otherwise the value will be overwritten 2 Users must be very careful in using nFIQ because it is the highest priority interrupt by default MediaTek Confidential Revision 1 6 September 28 2006 Page 17 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide
86. ore detailed 9 1 3 Event scheduler The scheduled event or event scheduler another alternative timer special for frequently happen events which needs non accurate timeout period It is especially suitable for upper layer applications which just need the timeout notification with less accuracy for instances a down counting counter used on tracking the backlight on off termination of an audio playing etc led_dll event_scheduler acre head dil tail t_ref_ticks cmpfunc t_susp_ticks alloc_fn_t t_set_time S r 3 free fnt timer_ id i is_ext_mem C oe A start timer Al A ode top timer ore umer j I data fuzz un P Fame al pre te __ lt lt malloc_fp_t next ty hs Je 0 free fp t is_ext_mem EE event bt event_hf_param abs_time Internal data structure of an event scheduler Figure above depicts the data structure of an event scheduler please refer to section 6 2 3 for more detailed Usually stack_start_timer stack stop timer stack is time out _valid and stack process time out act as the based timer for an event schedulersUsers who are using an event scheduler must know the exact event ID very well An event ID is actually a pointer from where system will allocate and release pointer while setting an event Memory de allocation will be done in evshed_ cancel event and evshed_t
87. otype void kal_get_my_task_index kal_uint32 index Header file kal_release h Input Pointer of type unsigned 32 bits which is used for return value Description Finding out correspondence task index of currently running execution unit if it is not a task index would be total number of tasks 1 MediaTek Confidential Revision 1 6 September 28 2006 Page 26 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_get_mytask_priority Prototype kal_uint32 kal_get_mytask_priority void Header file kal_release h Output Pointer of type unsigned 32 bits which is used for return value Description Retrieving priority of current execution unit either a task or an HISR for the former return value ranges from 0 to 255 while the later is either 0 1 or 2 kal get task_self_id Prototype kal_taskid kal_get_task_self_id void Header file kal_release h Output Current task ID Description Return the current executing task ID if the current execution unit is not a task KAL_NILTASK_ID will be returned kal_if_hisr Prototype kal_bool kal_if_hisr void Header file kal_release h Output KAL_FALSE if the current execution unit is a task and KAL TRUE if the current execution unit is a HISR Description Identify if the current execution unit is a HISR kal_sleep_task Prototype
88. ould not be handled stack_process_time_out Prototype void stack_process_time_out stack_timer_struct stack_timer Header file stack_timer h Input stack_timer is the destination stack timer to be processed Description Together with stack_is time out_valid they are the paired functions used for identify validity of an expiry message If an invalid expired message is received for instance the timer has been stopped stack process time out should be called to correctly maintain the control element invalid_time_out_count lt is in charge of decrementing invalid time out count by 1 besides switch the stack timer status to STACK_TIMER_NOT_RUNNING if it is in STACK_TIMER_EXPIRED stack_start_timer Prototype void stack_start_timer stack_timer_struct stack_timer kal_uint16 timer_indx kal_uint32 init_time Header file stack_timer h Input stack timer_struct is the stack timer to be set timer_indx is the index of the timer and init_time tells the timeout period similar to KAL timer the maximum value is also OXFFFFFFFF Description This facility is used to start a stack timer if the timeout period init_time is zero while setting the expiry ILM will be sent to the destination module immediately and system changes the stack timer status to STACK_TIMER_EXPIRED also Otherwise a stack timer is started and the new status is STACK_TIMER_RUNNING or STACK_TIMER_NOT_TIMED_OUT It is allowed to be called when the stack timer is in runni
89. ptr gt pdu len peer_buff_ptr gt pdu len tail_len Remark Fatal error append_to_peer buff insufficient tail memory fatal error code 1 0x10 error code 2 0x01 happens if either conditions holds 1 peer_buff_ptris NULL 2 tail len is zero 3 peer_buff_ptr gt free_tail_space is less than tail_len cancel_ilm Prototype kal bool cancel_ilm module_type module_id Header file stack_lticom h Input rmodule_id is source module ID which is going to cancel its previous delivery Output KAL_TRUE if source module has really allocated an ILM and system has decremented reference count of both local parameter and peer buffer if existed also if reference count becomes zero system will automatically release them KAL_FALSE if source module not yet allocates an ILM Description This function is used to halt the delivery of an ILM system will free the previously allocated ILM If either local parameter pointer or peer buffer pointer is not NIL these buffers will be released as well construct_local_para Prototype void construct_local_para localspara_size direction Header file app Iticom h Input local_para_sizeis size of local parameter in terms of bytes direction TD_RESET is used to enforce zero initialization of the local parameter Output Void pointer Description This is macro of MediaTek Confidential Revision 1 6 September 28 2006 Page 40 of 79 2004 2006 MediaTek Inc The information contained in
90. rms of Bytes which is consistent with the configured number Total number of the presently allocated entries Tracking the maximal number of the allocated entries that system ever experienced Tracking the maximal allocated buffer size Element num_buffs buff_size max_size_requested Description The physical data structure for buffer history available if and only if compile option DEBUG_BUF is defined Description Buffer status either KAL_BUFF_ALLOCATED or KAL_BUFF_DEALLOCATED kal_char file_name File name kal_uint32 line Line number kal_uint16 size Size to be allocated Element buffer_state Data Type kal_buff_state Description Used for tracking the historical operations on a dedicated buffer entry Again it is valid if and only if compile option DEBUG_BUF is defined Data Type Element Description kal_internal_taskid owner task kal_uint8 kal_history_node_t buffer_state MediaTek Confidential Revision 1 6 September 28 2006 Owner of the buffer expressed with task identity Buffer status either KAL_BUFF_ALLOCATED or KAL_BUFF_DEALLOCATED buff_history KAL_MAX_BUFF_HISTORY Array used for recording the operations ever processed and is associated on each buffer entry Page 65 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Gui
91. rrupt Handler and KAL Programming Guide kal_sys_mem_query_freesize coocoococcnccccnnanaconcnnanorannane rancio canna nora co rana emanan O em coca nc nana 71 kal_debug_mem_query_freesize oooncooococononccnccanacorannanonanacc crac IO cc cs 71 10 4 E ul EEN a AD A ooo A EE 72 Ce es eel Ue eee 73 11 1 Memory operation ig PAM BA MP occ 73 kal_mem_cmp AAA cc cc 9 E eneeeeensnceenneceesnnceessnnserenaneesennsanenanses 73 kal_mem_coy a AE O TTT D Il E 73 PCCD vo D occ cc A Dy anna 73 11 2 Bo0t Mode que A EEN 73 Stack UCD EN D 73 11 3 MUI DyieSISTINg processing EEN 73 Kal ACASO TEE TT E 73 kal dchar etrcpy commoccocnnnnncnccc annann naia aa O AS annaannanna 74 ARA AAA WT dl a A AMM 74 CCB ES cnn OA A cc 74 CCl 04 ee A O o eee 74 Kal_Achar_strcat ccccsescceseseesess AA A OA ccoo 74 kal_dchar_strncat 4 QEU Bo 0 cc ccoo rana rn oran rn 74 Kal_dchar_streii A cc Wf IO cc rn 75 kal dchzhk r rcht occ O cc nr 75 kal_dchar2char O a o occ 75 AR AA A CR oo E A 75 Kall ET e 75 CHUTE Te EE 75 Kal WSU CP ER Y a A 76 Kal_WStCMPDecnncnonnicnninncnnr e 76 AREA AE AAA AAA 76 AR AAA A A AY YA MM MM 76 kal 0 en ae A AS ef O A 76 ARAS AO AM A SSA 77 kal wetrrchr af o ic uge cnn rana nera manana 77 EWEG Ju Jh a Coo ua cocinera 77 Kal ATOM o dt 77 Kal LL iia n o a 77 11 5 sl EE 77 MediaTek Confidential Revision 1 6 September 28 2006 Page 8 of 79 O 2004 200
92. scription Ied_dll_node head Header of double linked list which points to the first led_dll_node Icd_dil_node Tail of double liked list which points to the last led_dll_node Icd_cmpfunc cmpfunc Compare function used for inserting a node malloc_fp_t alloc_fn_p Allocation function used for allocating a Icd_dll_node free_fp_t free_fn_p De allocation function used for de allocating a led_dll_node Description Internal data structure for the management of event scheduler MediaTek Confidential Revision 1 6 September 28 2006 Page 51 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide Icd_dll_node expired_dllhead Event s expired dl lier split in evshed timer handler kal_uint32 t_susp_ticks Scheduler s reference suspend time base for suspend operation kal_bool is_ Suspend Scheduler s suspension flag void void void stop_timer void Stop timer handler malloc fp_t alloc_fn_p Event s storage for allocation handler malloc_fp_t free_fn_p Event s storage for de allocation handler typedef void malloc_fp_t unsigned int Function type used as memory allocation typedef void free_fp_t void Function type used as memory de allocation typedef int Icd_cmpfunc const void const void Comparison function embedded on double linked list typedef Icd_dll_
93. size of and footer size size of ADM_MB_FOOT kal_adm_get_total_left_size Prototype kal_uint32 kal_adm_get_total_left_size KAL_ADM_ID adm_id Header file kal_release h Input adm_id is destination ADM to be queried Output Total free space of the dedicated ADM Description Users could rely on this service for retrieving total free space of dedicated ADM it is very useful in identifying fragmentation kal_adm_check_integrity Prototype void kal_adm_check_integrity KAL ADM ID adm_id Header file kal_release h Input adm_id is destination ADM to be queried Output Address of corrupted memory block If there is no memory corruption NULL is returned Description This function is only available from 05C W06 17 This function ensures the integrity of all allocated memory blocks If the header or footer of any allocated memory block is corrupted it returns the address of the corrupted memory block This is useful for debugging memory corruption MediaTek Confidential Revision 1 6 September 28 2006 Page 70 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL SRO Guide 10 3 3 System and debug memory Re kal_sys_mem_query_freesize ES kal_uint32 kal_sys_mem_ D p I le kal release bh gt An integer v ait ory sp o al ned cs ry free space kal_uint32 yt query_freesize void value of a
94. system guarantees the 4B alignment starting address for each allocation By using the sub pool concept system attempts to avoid fragmentation issue as much as possible Under the architecture all of the freed memory segments are categorized according to the pre defined sub pool size lt is user s responsibility to provide an appropriate sub pool list Internally sub poolis an array of type kal_unt32 and must be ended with Oxffffffff and 0x00 If it is set to NULL default sub pool setting will be applied kal_uint32 ADM_subpool_size 8 16 32 64 128 Oxffffffff 0x00 10 1 3 System memory and debug memory Typically system memory is a static memory pool declared at mcu custom system board version custom_contfig c it aims to provide the semi static memory space for run time usage The term semi static means that the memory size is application dependent but it would never be returned once allocated For examples control block of a task task s stack control block of a control buffer buffer pool etc Although system memory is restricted for system usage only customers are responsible to provide its actual size since it is application dependent define GLOBAL_MEM_SIZE 300 1024 define GLOBAL_DEBUG_MEM_SIZE 64 1024 Use static array to check memory usage at compile time with corresponding scatter file static kal_uint32 System_Mem_Pool GLOBAL_MEM_SIZE sizeof kal_uint32 static kal_uint32 Debug_Mem_Pool GLOBAL_DEBUG
95. t SOA nc 48 9 1 Description A EE 48 9 1 1 AE E xr AAA eyac naceassaceestbiadectie 48 9 1 2 BACK AAA a A dan iaraupeeeadaednysedvasestacavccasiecssgieestingaetee 48 9 1 3 e CHOU rico iii 49 9 2 Data Structures and WA E CR e 50 9 2 1 AAA EE eege Eder eebe a EE EC 50 9 2 2 Sc vi A ARA 50 9 2 3 Se EEN A A ci 51 9 3 APS a NA O AE 52 9 3 1 A Y AN AA MAA 52 OUR IT TEEN O O cacao ae 52 kal create Umer oonccccccnnaconanananracnnaranano oracion O A cc O canaria 52 CCl ee oO DA P een 53 kal get me remaining BRAAS cc coc E cacon rn ronca nana 53 LO EI 7 fl cc cc E 53 Kal SO 1 ENT A cs E OE E E E E 53 9 3 2 EE IA ASAS 53 Stack Il d A 53 MediaTek Confidential Bodson 1 6 September 9 200 Page Gof79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide stack CR CRT AAT ET e e necetenccaseecerednnereesen 54 stack_process_tiMe_OUt oconnconccconinnncnnnaconnnnaccnnaraco crac rana NAO Nos 54 DI E CA TN O occ IN cc 54 stack_stop_timer ooononconocacanonranaconnnnra e O ang O o W Eessen 54 stack mer status AAA ZS EC EM MME cocoa racer rc 55 9 3 3 IA Nk A MEM A AAA 55 A L ta A e A cc VE 55 evshed_Gelete all events Sa A O cc cn 55 eVShed_get_rem_ o a cc 55 Aee l e ii E E EE E A E E E 55 SA a AAA A O TE PERAE 55 evshed_suspend_all_eventS ooooonocccncco
96. tasks stack at internal SRAM Description Keep the run time task related information Data Type Element Description kal_char task_name ptr Pointer of task s name reference from element comp_name_ptr of comptask_info_struct kal char task_qname_ptr Name of external queue reference from element Comp Opname Dir of comptask_info_struct kal_uint32 task_priority Task priority copied from comp_priority of comptask_info_struct Kal_uint16 task_stack_size Stack size in terms of bytes also duplicated from comp_stack_size of comptask_info_struct MediaTek Confidential Revision 1 6 September 28 2006 Page 23 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide kal_taskid task_id Task ID which is assigned by OS at run time kal_msgqid task_ext_qid Task s external queue ID which is assigned by OS after creation int_q_type task_int_qid_ptr Task s internal queue ID which is assigned by OS after creation kal_task_func_ptr task_entry_func Task s entry function duplicated from comp_create_func of comptask_info_struct task_cfg_func_ ptr task_cfg_func Task s configuration function duplicated from comp_create_func of comptask_info_struct task_init_func_ptr task_init_ func Task s initialization function duplicated from comp_create_func of comptask_info_struct task_reset_fun
97. tom1_handler_info custom1_main task entry function NULL task initialization function NULL task configuration function NULL task reset handler NULL task termination handler handle comptask_handler_struct amp custom1_handler_info return KAL_TRUE y Step 5 Define the message ID Define the message ID in mcu custom system board version custom_sap h which must be started with MSG_ID_ Add customization message id here MSG_ID_CUSTOM1_CUSTOM2 CUSTOM_MSG_CODE BEGIN MSG_ID CUSTOM2_CUSTOM1 MediaTek Confidential Revision 1 6 September 28 2006 Page 29 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Nj i g Guide al message IDs Currently the maximal allowable customer message ID is 1000 fatal error Cu PCY tered if fatal error code 1 0x1503 error code 2 total number of customer define e exceeding A oig al P be en Gi MediaTek idential Revision 1 6 September 28 2006 Page 30 of 79 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 7 Task Synchronization Management The simplest form of synchronization involves the starting of a task at the appropriate time By providing
98. toring is officially turned off To turn on buffer monitoring at run time we need to know the ID of each control buffer size they are denoted in Table 11 1 Table 11 1 Identity number of control buffer MediaTek Confidential Revision 1 6 September 28 2006 Page 61 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide For example to monitor 8 and 128Bytes control buffer pressing the string in dialing screen 035670766 001 17 Be very careful that system performance will definitely be scarified under the circumstance Such enabling is not permanently available itis reset in next time power on 10 1 2 ADM In addition to control buffer upper layer applications may need more flexible dynamic memory mechanism such as allocating buffer larger than 2KB going through its own error handling if allocation failure MAUI provides an alternative dynamic memory management scheme namely Application Dynamic Memory ADM to fulfill such requirement Users are responsible to provide a memory pool and transfer the management to system garbage collection is excluded from ADM Specially note that control block and others overhead for management will be created from the memory pool provided by users therefore the memory pool size should take them into account The minimal allocatable size is 8Bytes and
99. tructure typedef struct ASSERT_DUMP_PARAM kal_uint32 addr ASSERT_DUMP_PARAM_MAX kal_uint32 len ASSERT_DUMP_PARAM_MAX in bytes ASSERT_DUMP_PARAM_T Specify 10 memory fragments in the structure as below ASSERT_DUMP_PARAM_T dump_param dump param addr 0 0x08000000 dump_param len 0 8 dump_param addr 1 0x08000000 100 dump_param len 1 8 dump_param addr 2 0x08000000 200 dump param len 2 8 dump_param addr 3 0x08000000 300 dump_param len 3 8 dump_param addr 4 0x08000000 400 dump_param len 4 8 dump_param addr 5 0x08000000 500 dump_param len 5 8 dump_param addr 6 0x08000000 600 dump_param len 6 8 dump_param addr 7 0x08000000 700 dump_param len 7 8 dump_param addr 8 0x08000000 800 dump param len 8 8 dump_param addr 9 0x08000000 900 dump_param len 9 0x100000 EXT_ASSERT_DUMP 0 1 2 3 amp dump_param MediaTek Confidential Revision 1 6 September 28 2006 Page 78 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL gt i g Guide t When the exception handler processes the exception later your data wi This may be useful for developers to debug Please As t foll exception log our last of the specified address For example if you only want to dum addr field must be NULL
100. use this API to avoid such error The usage is just the same as hold_peer_buff msg_get_ext_queue_info Prototype kal_bool msg_get_ext_queue_info kal_msgqid task_ext_qid kal_uint32 messages Header file stack_lticom h Input task_ext_gid is pointer of queue identity the returned information would be returned via messages Output KAL_TRUE if information retrieval successfully done otherwise KAL_FALSE Description This is an exported function for querying number of pending messages msg_get_ext_queue_length Prototype kal_bool msg get_ext_queue_length kal_msgqid task_ext_qid kal_uint32 length Header file stack Iticom h Input task_ext_gid is pointer of queue identity the returned information would be returned via length Output KAL_TRUE if information retrieval successfully done otherwise KAL_FALSE Description This is an exported function for querying total number of queue entries msg_send_ext_queue Prototype kal_bool msg_send_ext_queue ilm_struct ilm_ptr Header file stack_Itlcom h Input ilm_ptr is pointer of ILM which is going to be delivered Output KAL_TRUE if message is delivered successfully otherwise return KAL_FALSE Description This is an exported function for message delivery destination is always external queue of task specified in ilm_ptr gt dest_mod_id Destination task s external queue is targeted through the statement below task_info_g mod task q ilm_ptr gt dest_mod_id task_ext_qi
101. vailable memory space s function call is designed for querying the debug memory free space note that it always returns zero if DEBUG_KAL is not defined Revision 1 6 September 28 2006 O 2004 2006 MediaTek Inc The information contained in this document can be modified without notice Page 71 of 79 M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 10 4 Examples Below are two examples of ADM A Without using sub pool include kal_release h static kal_uint8 my_heap 3 1024 KAL ADM ID mv dm id kal_uint32 ptr create ADM my_dm_id kal_adm_create my_heap 3 1024 NULL KAL_FALSE if mv dm jd NULL my_error_handler fail to create a dm pool allocate memory ptr kal_uint32 kal_adm_alloc my_dm_id 1024 if ptr NULL if kal_adm_get_total_left_size my_dm_id gt 1024 my_error_handler fragmentation else my_error_handler out of memory free memory kal_adm_free my_dm_id ptr delete ADM if kal_adm_delete my_dm_id KAL_ADM_SUCCEED my_error_handler include kal_release h static kal_uint32 my_subpool_size 8 16 24 32 40 48 56 64 72 80 88 96 104 112 120 128 Oxffffffff O static kal_uint8 my_heap 3 1024 KAL ADM ID my_dm_id kal_uint32 ptr create ADM my_dm_id kal_adm_create my_heap 3 1024 my subpool size KAL_FALSE if my_dm_ id NULL
102. y this service is resumed kal_retrieve_eg_events Prototype kal status kal_retrieve_eg_events kal_eventgrpid eg_id kal_uint32 requested_events kal_uint8 operation kal_uint32 retrieved events kal_uint32 suspend Header file kalrelease h Input eg_id is pointer to the user supplied event flag group control block requested_events is a set bit indicates the corresponding event flag is requested operation specifies the operation options retrieved events contains event flags actually retrieved and suspend specifies whether to suspend the calling task if the requested event flag combination is not met MediaTek Confidential Revision 1 6 September 28 2006 Page 34 of 79 2004 2006 MediaTek Inc The information contained in this document can be modified without notice M Maui System Service User Manual Interrupt Handler and KAL Programming Guide 7 4 Example Below is an example of the usage of event group define SET_BITO 0x00000001 define SET_BIT1 0x00000002 define SET_BIT2 0x00000004 kal_hisrid SAMPLE_Hisr kal_eventgrpid SAMPLE_Events void SAMPLE_HISR_Entry void 04900004 An HISR sets an event kal_set_eg_events SAMPLE_Events SET_BITO SET_BIT1 SET_BIT2 KAL_OR 4404006 void SAMPLE_LISR void 6400008 kal_activate_hisr SAMPLE_Hisr OOOO OO8 kal status SAMPLE_consumer1 void kal_uint32 flags 0 OOOO O08 Consumer will be resumed if and only if event flags SET_BITO and SET_BI

Maui System Service User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents