[Feature]Upload Modem source code
Change-Id: Id4294f30faced84d3e6fd6d5e61e1111bf287a37
diff --git a/mcu/interface/service/kal/kal_public_api.h b/mcu/interface/service/kal/kal_public_api.h
new file mode 100644
index 0000000..f41102e
--- /dev/null
+++ b/mcu/interface/service/kal/kal_public_api.h
@@ -0,0 +1,5008 @@
+/*****************************************************************************
+* Copyright Statement:
+* --------------------
+* This software is protected by Copyright and the information contained
+* herein is confidential. The software may not be copied and the information
+* contained herein may not be used or disclosed except with the written
+* permission of MediaTek Inc. (C) 2005
+*
+* BY OPENING 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
+* MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
+*
+* THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
+* WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
+* LAWS PRINCIPLES. ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
+* RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
+* THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
+*
+*****************************************************************************/
+
+/*****************************************************************************
+ *
+ * Filename:
+ * ---------
+ * kal_public_api.h
+ *
+ * Project:
+ * --------
+ * Maui_Software
+ *
+ * Description:
+ * ------------
+ * This file provides KAL public API prototypes
+ *
+ * Author:
+ * -------
+ * -------
+ *
+ *============================================================================
+ * HISTORY
+ * Below this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
+ *------------------------------------------------------------------------------
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ ****************************************************************************/
+
+#ifndef _KAL_PUBLIC_API_H
+#define _KAL_PUBLIC_API_H
+
+/*******************************************************************************
+ * Common Header File Include
+ *******************************************************************************/
+#ifndef GEN_FOR_PC
+#include <stdio.h>
+#include <string.h>
+#endif
+
+#include "kal_general_types.h"
+#include "kal_public_defs.h"
+#include "kal_atomic_api.h"
+#include "mips_ia_utils_public.h"
+#include "kal_inline_api.h"
+
+#if defined(__DHL_MODULE__)
+#include "dhl_trace.h"
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+#if defined(KAL_ON_OSCAR)
+#define kal_snprintf _snprintf
+#else
+#define kal_snprintf snprintf
+#endif
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * sprintf
+ * DESCRIPTION
+ * sprintf accepts a series of arguments, applies to each a format specifier from *format,
+ * and writes the formatted data to buffer str, and a terminating NUL is output.
+ * PARAMETERS
+ * str: [IN] destination buffer
+ * format: [IN] specify the arguments output format
+ * ...: [IN] variable-parameter, a series of arguments
+ * NOTE
+ * number of variable-parameters must be less than or equal to 20, if more paramters are checked, will assert.
+ * this limitation is also apply to all sprintf/sscanf family functions, that is sprintf/snprintf/vsprintf/vsnprintf/sscanf/vsscanf
+ * RETURN VALUES
+ * the number of bytes in the output string, except the concluding NUL is not counted.
+ ******************************************************************************/
+#define kal_sprintf sprintf
+
+extern kal_char *kal_strtok_r(kal_char *string, const kal_char *seperators,
+ kal_char **ppLast);
+
+#define kal_toWCHAR(asciiString) L##asciiString
+
+/*************************************************************************
+* FUNCTION
+* kal_itoa
+*
+* DESCRIPTION
+* converts integers to string in various radixes
+*
+* PARAMETERS
+* value - integer need to convert
+* str - buffer to save convert result
+* radix - the base of the integer, like 2,10,16
+* RETURNS
+* return the str buffer address
+*
+*************************************************************************/
+extern char *kal_itoa(int value, char *str, int radix);
+
+/*
+ * 16bits string operations
+ */
+extern int kal_wstrlen(const WCHAR *wstr);
+extern WCHAR *kal_wstrcpy(WCHAR *to, const WCHAR *from);
+extern WCHAR *kal_wstrncpy(WCHAR *to, const WCHAR *from, int n);
+extern int kal_wstrcmp(const WCHAR *s1, const WCHAR *s2);
+extern int kal_wstrncmp(const WCHAR *s1, const WCHAR *s2, int n);
+extern WCHAR *kal_wstrcat(WCHAR *s1, const WCHAR *s2);
+extern WCHAR *kal_wstrncat(WCHAR *s1, const WCHAR *s2, int n);
+extern WCHAR *kal_wstrchr(const WCHAR *s, int c);
+extern WCHAR *kal_wstrrchr(const WCHAR *str, int ch);
+
+/*
+ * dual 8bits string operations
+ */
+extern int kal_dchar_strlen(const char *wstr);
+extern char *kal_dchar_strcpy(char *to, const char *from);
+extern char *kal_dchar_strncpy(char *to, const char *from, int n);
+extern int kal_dchar_strcmp(const char *s1, const char *s2);
+extern int kal_dchar_strncmp(const char *s1, const char *s2, int n);
+extern char *kal_dchar_strcat(char *s1, const char *s2);
+extern char *kal_dchar_strncat(char *s1, const char *s2, int n);
+extern char *kal_dchar_strchr(const char *s, int c);
+extern char *kal_dchar_strrchr(const char *str, int ch);
+extern void kal_dchar2char(WCHAR *outstr, char *tostr);
+extern void kal_wsprintf(WCHAR *outstr, char *fmt, ...);
+
+
+#if !defined(GEN_FOR_PC)
+
+/*************************************************************************
+* FUNCTION
+* time
+*
+* DESCRIPTION
+* time() return current calendar time as a value of type time_t .It stores the same value at
+* parameter t unless the argument is NULL. The value represents the number of seconds
+* since 00:00 hours, Jan 1, 1970 UTC (i.e., the current unix timestamp).
+*
+* PARAMETERS
+* t - pointer to an object of type time_t to store the current time.
+* You can just input NULL, the function still return a value of type time_t with the result.
+*
+* RETURNS
+* The current calendar time as a value of type time_t .
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+*************************************************************************/
+extern time_t time(time_t *t);
+
+/*************************************************************************
+* FUNCTION
+* time_ms_us
+*
+* DESCRIPTION
+* time_ms_us() return current calendar time as a value of type wall_clock .It stores the same value at
+* parameter t unless the argument is NULL. The value represents the number of milli-seconds and micro-seconds
+* since 00:00 hours, Jan 1, 1970 UTC (i.e., the current unix timestamp).
+*
+* PARAMETERS
+* t - pointer to an object of type wall_clock to store the current time.
+* You can just input NULL, the function still return a value of type wall_clock with the result.
+*
+* RETURNS
+* The current calendar time as a value of type wall_clock .
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+*************************************************************************/
+extern wall_clock time_ms_us(wall_clock *t);
+
+/*************************************************************************
+* FUNCTION
+* gmtime_r
+*
+* DESCRIPTION
+* Uses the value pointed by tim_p to fill the tm structure pointed by res with the values
+* that represent the corresponding time, expressed as UTC time (i.e., the time at the
+* GMT timezone). If tim_p or res is NULL, NULL will be returned and the content of res
+* will not be changed.
+*
+* PARAMETERS
+* tim_p - pointer to an object of type time_t that contains a time value.
+* res - pointer to an object of type tm to store the result converted by gmtime_r
+*
+* RETURNS
+* A pointer to inputted tm structure res with its members filled with the values that
+* correspond to the UTC time representation of tim_p.
+* Return NULL if tim_p or res is NULL.
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+* SEE ALSO
+* time, localtime_r
+*
+*************************************************************************/
+extern struct tm *gmtime_r(const time_t *tim_p, struct tm *res);
+
+
+/*************************************************************************
+* FUNCTION
+* localtime_r
+*
+* DESCRIPTION
+* Uses the value pointed by tim_p to fill the tm structure pointed by res with the values that
+* represent the corresponding time, expressed for the local timezone.
+* Note that localtime() may not available due to timezone is not updated within bootup 10
+* seconds. If it is happened, the result of localtime_r() is equal to gmtime_r(). (i.e. the returned
+* tm structure represents the corresponding UTC time.
+*
+* PARAMETERS
+* tim_p - pointer to an object of type time_t that contains a time value.
+* res - pointer to an object of type tm to store the result converted by localtime_r()
+*
+* RETURNS
+* A pointer to inputted tm structure res with its members filled with the values that
+* correspond to the local time representation of tim_p if localtime_r() is available. If localtime_r()
+* is not available, the tm structure represents the corresponding UTC time.
+* Return NULL if tim_p or res is NULL.
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+* SEE ALSO
+* time, gmtime_r
+*
+*************************************************************************/
+struct tm *localtime_r(const time_t *tim_p, struct tm *res);
+
+
+/*************************************************************************
+* FUNCTION
+* asctime_r
+*
+* DESCRIPTION
+* Interprets the contents of the tm structure pointed by tim_p as a calendar time and
+* converts it to a C-string containing a human-readable version of the corresponding
+* date and time. The returned string has the following format:
+* Www Mmm dd hh:mm:ss yyyy
+* Where Www is the weekday, Mmm the month (in letters), dd the day of the month,
+* hh:mm:ss the time, and yyyy the year. The string is followed by a new-line character
+* ('\n') and terminated with a null-character.
+* If tim_p or res is NULL, NULL will be returned and the content of res will not be changed.
+*
+* PARAMETERS
+* tim_p - pointer to a tm structure that contains a calendar time broken down into its
+* components (see struct tm).
+* res - a pointer to the string for containing result converted by asctime_r.
+* The length of the string should larger than 26.
+*
+* RETURNS
+* A pointer to inputted string res containing the date and time information in a
+* human-readable format.
+* Return NULL if tim_p or res is NULL.
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+* SEE ALSO
+* time, gmtime_r, localtime_r, ctime_r
+*
+*************************************************************************/
+char *asctime_r(const struct tm *tim_p, char *res);
+
+
+/*************************************************************************
+* FUNCTION
+* ctime_r
+*
+* DESCRIPTION
+* Interprets the contents of the tm structure pointed by tim_p as a calendar time and
+* converts it to a C-string containing a human-readable version of the corresponding
+* date and time, in terms of local time. The returned string has the following format:
+* Www Mmm dd hh:mm:ss yyyy
+* Where Www is the weekday, Mmm the month (in letters), dd the day of the month,
+* hh:mm:ss the time, and yyyy the year. The string is followed by a new-line character
+* ('\n') and terminated with a null-character.
+* Note that ctime_r() may not available due to timezone is not updated within bootup 10
+* seconds. If it is happened, the result of ctime_r(), asctime_r(localtime_r()), is equal to
+* asctime_r(gmtime_r()).
+*
+* PARAMETERS
+* tim_p - pointer to a tm structure that contains a calendar time broken down into its
+* components (see struct tm).
+* res - a pointer to the string for containing result converted by ctime_r.
+* The length of the string should larger than 26.
+*
+* RETURNS
+* A pointer to inputted string res containing the date and time information in a
+* human-readable format.
+* Return NULL if tim_p or res is NULL.
+*
+* NOTE
+* Only be supported in limited projects. If it is not supported, build fail is happened.
+*
+* SEE ALSO
+* time, gmtime_r, localtime_r, asctime_r
+*
+*************************************************************************/
+char *ctime_r(const time_t *tim_p, char *res);
+
+#endif /* !defined(GEN_FOR_PC) */
+#if defined(__MTK_TARGET__)
+/*KAL_CC_SPINLOCK*/
+extern void *kal_cc_md1_dsp_spinlock;
+
+kal_status MD1_DSP_kal_cc_take_spinlock(void * cc_spinlock_p,
+ kal_wait_mode wait_mode);
+void MD1_DSP_kal_cc_give_spinlock(void *cc_spinlock_p);
+#endif
+/*******************************************************************************
+ * Category 2 : Query Functions for Initialize and States
+ *******************************************************************************/
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_query_systemInit
+ * DESCRIPTION
+ * query whether the system is in initialization phase.
+ * PARAMETERS
+ * N/A
+ * RETURN VALUES
+ * KAL_TRUE: system is in initialization phase.
+ * KAL_FALSE: system is not in initialization phase.
+ ******************************************************************************/
+extern kal_bool kal_query_systemInit(void);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_curent_domain
+ * DESCRIPTION
+ * return current domain
+ * RETURNS
+ * enum kal_domain: KAL_DOMAIN_NORMAL/KAL_DOMAIN_HRT/KAL_DOMAIN_CHRT
+ ******************************************************************************/
+#if defined(__MTK_TARGET__)
+#if !defined(__kal_get_current_domain__)
+#define __kal_get_current_domain__
+#if defined(__MIPS_I7200__)
+#define kal_get_current_domain() (miu_mfc0(MIU_C0_KSCRATCH4) & 0x3)
+#endif /* defined(__MIPS_I7200__) */
+#endif /* __kal_get_current_domain__ */
+#else /* __MTK_TARGET__ */
+#define kal_get_current_domain() 0
+#endif /* __MTK_TARGET__ */
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_if_hrt_domain
+ * DESCRIPTION
+ * Identify if current VPE is HRT domain
+ * PARAMETERS
+ * VPE ID
+ * RETURNS
+ * KAL_TRUE if current VPE is HRT domain
+ ******************************************************************************/
+#if !defined(__MTK_TARGET__)
+#define kal_get_domain(vpe_id) 0
+#define kal_if_hrt_domain(vpe_id) 0
+#endif /* __MTK_TARGET__ */
+
+/*************************************************************************
+* FUNCTION
+* kal_runtime_affinity_set
+* DESCRIPTION
+* set current task's or current hisr's affinity attribute
+* PARAMETERS
+* affinity[IN]: VPE0_Group, VPE2_Group, SMP_NORMAL_Group
+* RETURNS
+* KAL_TRUE or KAL_FALSE
+*************************************************************************/
+kal_bool kal_runtime_affinity_set(kal_affinity_group affinity);
+
+/*************************************************************************
+* FUNCTION
+* kal_runtime_affinity_resume
+* DESCRIPTION
+* resume current task's or current hisr's affinity attribute to original config value
+* PARAMETERS
+* NONE
+* RETURNS
+* KAL_TRUE or KAL_FALSE
+*************************************************************************/
+kal_bool kal_runtime_affinity_resume(void);
+
+/*************************************************************************
+* FUNCTION
+* kal_runtime_affinity_to_current_vpe
+* DESCRIPTION
+* Affines the calling task to current VPE.
+* PARAMETERS
+* NONE
+* RETURNS
+* KAL_TRUE
+*************************************************************************/
+kal_bool kal_runtime_affinity_to_current_vpe(void);
+
+/*************************************************************************
+* FUNCTION
+* kal_runtime_group_affinity_set
+* DESCRIPTION
+* Sets the affinity of all tasks in given group. All tasks must be in some
+* of KAL_SUSPEND states or the whole operation will fail.
+* PARAMETERS
+* group_id[IN]: Group ID
+* affinity[IN]: affinity mask
+* RETURNS
+* KAL_TRUE if affinity set was successful
+* KAL_FALSE if affinity set failed (e.g. because one or more tasks were �n
+* non-suspended state
+*************************************************************************/
+
+kal_bool kal_runtime_group_affinity_set(kal_task_group_id group_id,
+ kal_affinity_group affinity);
+
+/* DOM-NOT_FOR_SDK-END */
+
+/*******************************************************************************
+ * Category 3 : LISR, HISR and TASK functions
+ *******************************************************************************/
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_thread_ID
+ * DESCRIPTION
+ * get current thread identity, which is a unique pointer for each thread.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current thread identity.
+ * NOTE
+ * thread is defined as task or HISR.
+ ******************************************************************************/
+void *kal_get_current_thread_ID(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_lisr_ID
+ * DESCRIPTION
+ * get current lisr identity.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current lisr identity.
+ ******************************************************************************/
+kal_uint32 kal_get_current_lisr_ID(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_sleep_task
+ * DESCRIPTION
+ * put the task into sleep for a specified duration which is expressed in terms
+ * of system tick.
+ * PARAMETERS
+ * time_in_ticks: [IN] how many system ticks to sleep.
+ * RETURNS
+ * N/A
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+void kal_sleep_task(kal_uint32 time_in_ticks);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_task
+ * DESCRIPTION
+ * get current task identity.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current task identity.
+ * SEE ALSO
+ * kal_get_current_task_index
+ ******************************************************************************/
+kal_taskid kal_get_current_task(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_hisr
+ * DESCRIPTION
+ * get current hisr identity.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current hisr identity.
+ * SEE ALSO
+ * kal_get_current_hisr_index
+ ******************************************************************************/
+kal_hisrid kal_get_current_hisr(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_task_priority
+ * DESCRIPTION
+ * get current task priority.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current task priority.
+ ******************************************************************************/
+kal_uint32 kal_get_current_task_priority(void);
+
+/*************************************************************************
+ * FUNCTION
+ * kal_get_task_status
+ *
+ * DESCRIPTION
+ * This routine is to get the task's status.
+ *
+ * PARAMETERS
+ * taskid : task id(pointer points to task control block
+ *
+ * RETURNS
+ * task's current status
+ *
+ * GLOBALS AFFECTED
+ *
+ *************************************************************************/
+kal_task_status kal_get_task_status(kal_taskid taskid);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_set_active_module_id
+ * DESCRIPTION
+ * set active module in current task.
+ * PARAMETERS
+ * module_id: [IN] active module in current task.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)This API must be called before kal_get_active_module_id(). So, the recommended place to call it
+ * is in task main function, immediately after get a ILM message.
+ * SEE ALSO
+ * kal_get_active_module_id
+ ******************************************************************************/
+extern void kal_set_active_module_id(module_type module_id);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_active_module_id
+ * DESCRIPTION
+ * get active module in current task.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * active module in current task.
+ * NOTE
+ * (1)This API return the last value set by kal_set_active_module_id().
+ * SEE ALSO
+ * kal_set_active_module_id
+ ******************************************************************************/
+extern module_type kal_get_active_module_id(void);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_lisr_module_id
+ * DESCRIPTION
+ * This routine is to get the irq's module id.
+ * PARAMETERS
+ * irq_id: [IN] IRQ Code ID.
+ * RETURNS
+ * irq's module id.
+ * SEE ALSO
+ *
+ ******************************************************************************/
+extern module_type kal_get_lisr_module_id(kal_uint32 irq_id);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_task_by_moduleID
+ * DESCRIPTION
+ * get taskid from task index.
+ * PARAMETERS
+ * index: [IN] target task index.
+ * RETURNS
+ * Return corresponding taskid. If the target task doesn't exist, return NULL.
+ * SEE ALSO
+ * kal_get_task_index
+ ******************************************************************************/
+extern kal_taskid kal_get_task_by_moduleID(module_type modele_id);
+
+/*************************************************************************
+* <GROUP Functions>
+*
+* FUNCTION
+* kal_task_mod_remap (Only for NL1 Build Load)
+* DESCRIPTION
+* This function will remap module to new task.
+* PARAMETERS
+* module_type: [IN] destination module Id
+* module_type: [IN] source module Id
+* RETURNS
+* None
+* GLOBALS AFFECTED
+* mod_task_g
+* NOTE
+* This Function is Only for NL1 Build Load.
+* SEE ALSO
+* kal_update_task_mod
+*************************************************************************/
+extern void kal_task_mod_remap(module_type dst_mod_id, module_type src_mod_id);
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_task_total_number
+ * DESCRIPTION
+ * query total task index number.
+ * PARAMETERS
+ * NA.
+ * RETURNS
+ * Return total task index number.
+ ******************************************************************************/
+extern kal_uint32 kal_get_task_total_number(void);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_send_msg_module_id_total_number
+ * DESCRIPTION
+ * query total module id number that can send message.
+ * PARAMETERS
+ * NA.
+ * RETURNS
+ * Return total module id number that can send message.
+ ******************************************************************************/
+extern kal_uint32 kal_get_send_msg_module_id_total_number(void);
+/* DOM-NOT_FOR_SDK-END */
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_current_hisr_index
+ * DESCRIPTION
+ * get current HISR index.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * current HISR index.
+ * NOTE
+ * (1)This API must be called from HISR.
+ ******************************************************************************/
+extern kal_uint32 kal_get_current_hisr_index(void);
+
+/*************************************************************************
+* <GROUP Functions>
+*
+* FUNCTION
+* kal_check_stack
+*
+* DESCRIPTION
+* This routine is to check whether the start of current thread stack is corrupted.
+* If so, the system enter fatal error handling.
+*
+* PARAMETERS
+* N/A
+* RETURNS
+*
+* GLOBALS AFFECTED
+*
+*************************************************************************/
+extern void kal_check_stack(void);
+
+ /*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_activate_hisr_index
+ * DESCRIPTION
+ * activate specified HISR.
+ * PARAMETERS
+ * ext_hisr: [IN] HISR index.
+ * RETURNS
+ * N/A
+ ******************************************************************************/
+extern void kal_activate_hisr_index(kal_hisr ext_hisr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_if_hisr
+ * DESCRIPTION
+ * Identify if the current execution unit is a HISR.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * KAL_FALSE if the current execution unit is a task, and KAL_TRUE if the current execution unit is a HISR.
+ * SEE ALSO
+ * kal_if_lisr
+ ******************************************************************************/
+extern kal_bool kal_if_hisr(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_if_lisr
+ * DESCRIPTION
+ * Identify if the current execution unit is a LISR.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * KAL_FALSE if the current execution unit is a task or HISR, and KAL_TRUE if the current execution unit is a LISR.
+ * SEE ALSO
+ * kal_if_hisr
+ ******************************************************************************/
+#if defined(__MTK_TARGET__)
+#if !defined(__kal_if_lisr__)
+#define __kal_if_lisr__
+#define kal_if_lisr() (miu_mfc0(MIU_C0_USERLOCAL) > 0)
+#endif
+#else
+extern kal_bool kal_if_lisr(void);
+#endif
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_task_affinity_by_moduleID
+ * DESCRIPTION
+ * Query the hard affinity attribute of a certain task by its MOD ID.
+ * PARAMETERS
+ * mod: [IN] the module id of the task wanting to query its affinity
+ * returnAffinity: [IN] the pointer to store the affinity query result
+ * the content will be kal_affinity_group enum
+ * RETURNS
+ * KAL_ERROR if the MOD ID is invalid or the task is not created. KAL_SUCCESS if the query is succeed.
+ * SEE ALSO
+ *
+ ******************************************************************************/
+kal_status kal_get_task_affinity_by_moduleID(module_type mod,
+ kal_affinity_group *returnAffinity);
+
+
+/*************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+* kal_get_current_context
+* DESCRIPTION
+* This function return current context we are running.
+* PARAMETERS
+* N/A
+* RETURNS
+* kal_sw_context_type
+*
+*************************************************************************/
+kal_sw_context_type kal_get_current_context(void);
+
+/* DOM_NOT_FOR_SDK-END */
+
+/*******************************************************************************
+ * Category 4 : Message Passing and Queue
+ *******************************************************************************/
+/* DOM-NOT_FOR_SDK-BEGIN */
+
+extern void *construct_int_local_para(kal_uint16 local_para_size,
+ kal_uint32 auto_reset,
+ const kal_char *file_ptr, kal_uint32 line);
+extern kal_bool free_int_local_para(local_para_struct *local_para_ptr,
+ const kal_char *file, kal_uint32 line);
+#define free_int_local_para_r free_int_local_para
+extern void *construct_int_peer_buff(kal_uint16 pdu_len, kal_uint16 header_len,
+ kal_uint16 tail_len,
+ const kal_char *file_name_ptr, kal_uint32 line);
+extern kal_bool free_int_peer_buff(peer_buff_struct *pdu_ptr, const kal_char *file,
+ kal_uint32 line);
+#define free_int_peer_buff_r free_int_peer_buff
+extern void destroy_int_ilm(ilm_struct *ilm_ptr, const kal_char *file_name,
+ kal_uint32 line);
+
+#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
+#define __construct_local_para(local_para_size, direction) \
+ construct_int_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ __FILE__, __LINE__)
+#define __free_local_para(local_para) \
+ free_int_local_para(local_para, __FILE__, __LINE__)
+#define __construct_peer_buff(pdu_len, header_len, tail_len, direction) \
+ construct_int_peer_buff(pdu_len, header_len, tail_len, __FILE__, __LINE__)
+#define __free_peer_buff(peer_buff) free_int_peer_buff(peer_buff, __FILE__, __LINE__)
+#else /* !DEBUG_KAL || !DEBUG_BUF2 */
+#define __construct_local_para(local_para_size, direction) \
+ construct_int_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ NULL, 0)
+#define __free_local_para(local_para) free_int_local_para(local_para, NULL, 0)
+#define __construct_peer_buff(pdu_len, header_len, tail_len, direction) \
+ construct_int_peer_buff(pdu_len, header_len, tail_len, NULL, 0)
+#define __free_peer_buff(peer_buff) free_int_peer_buff(peer_buff, NULL, 0)
+#endif
+/* DOM-NOT_FOR_SDK-END */
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * construct_local_para
+ * DESCRIPTION
+ * allocate a local_para structure which has local_para_size bytes including LOCAL_PARA_HDR.
+ * PARAMETERS
+ * local_para_size: [IN] local_para structure size, this size includes LOCAL_PARA_HDR header,
+ * so the minimum size is sizeof(LOCAL_PARA_HDR) which imply the pdu part is 0 byte.
+ * direction: [IN] a bitmask, each bit is defined as following values:
+ * 0 - nothing.
+ * TD_RESET - to zero-initialize the pdu in this local_para structure.
+ * RETURNS
+ * a local_para structure pointer. System enter fatal error handling if no enough memory.
+ * NOTE
+ * (1) the prototype of this API is:
+ * void* construct_local_para(kal_uint16 local_para_size, transfer_direction direction);
+ * (2) local_para structure is a user-defined structure has a predefined header LOCAL_PARA_HDR
+ * embedded in front of it:
+ * struct bt_connected_info {
+ * LOCAL_PARA_HDR; // this field must be the first elements in structure
+ * // user-defined fields follows, pdu of this local_para structure
+ * };
+ * LOCAL_PARA_HDR is defined as:
+ * #define LOCAL_PARA_HDR kal_uint8 ref_count; kal_uint8 lp_reserved; kal_uint16 msg_len;
+ * where msg_len is used to record the length of total structure including LOCAL_PARA_HDR,
+ * ref_count is used to record how many pointers reference to this structure, you must
+ * hold it on saving a private copy and free it after clear the private copy.
+ * (3) The initial reference count in local_para structure is 1. It is a common error to
+ * memset the whole structure to 0, if you want to zero-initialize pdu, pass TD_RESET
+ * in direction to do that.
+ * SEE ALSO
+ * free_local_para, hold_local_para, destroy_ilm, get_local_para_ptr
+ ******************************************************************************/
+#define construct_local_para(local_para_size, direction) \
+ __construct_local_para(local_para_size, direction)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * free_local_para
+ * DESCRIPTION
+ * decrease the local_para structure reference count, free the local_para if it reach 0.
+ * PARAMETERS
+ * local_para : [IN] local_para structure pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1)The prototype of this API is:
+ * void free_local_para(local_para_struct *local_para_ptr);
+ * (2)To pass user-defined local_para structure pointer to it, you need an explicit type-cast:
+ * free_local_para((local_para_struct *)ptr_to_bt_connected_info);
+ * SEE ALSO
+ * construct_local_para, hold_local_para, destroy_ilm
+ ******************************************************************************/
+#define free_local_para(local_para) __free_local_para(local_para)
+#define free_local_para_set_null(local_para) \
+ do { \
+ if (__free_local_para((local_para_struct *)local_para) == KAL_TRUE) \
+ local_para = NULL; \
+ } while (0)
+#define free_local_para_r free_local_para
+#define free_local_para_r_set_null free_local_para_set_null
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * construct_peer_buff
+ * DESCRIPTION
+ * allocate a peer_buff structure which has specified size in each part.
+ * PARAMETERS
+ * pdu_len: [IN] pdu size.
+ * header_len: [IN] reserve size in header.
+ * tail_len: [IN] reserve size in tail.
+ * direction: [IN] ignored, use 0.
+ * RETURNS
+ * a peer_buff structure pointer. System enter fatal error handling if no enough memory.
+ * NOTE
+ * (1) the prototype of this API is:
+ * void* construct_peer_buff(kal_uint16 pdu_len, kal_uint16 header_len, kal_uint16 tail_len,
+ * transfer_direction direction);
+ * (2) peer_buff is a opaque type which has reference count. Please use related API to manipulate it.
+ * (3) The initial reference count in peer_buff structure is 1.
+ * (4) It will use the size (pdu_len + header_len + tail_len + 8) to allocate buffer from control buffer pool.
+ * SEE ALSO
+ * free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu, append_to_peer_buff,
+ * prepend_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+#define construct_peer_buff(pdu_len, header_len, tail_len, direction) \
+ __construct_peer_buff(pdu_len, header_len, tail_len, direction)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * free_peer_buff
+ * DESCRIPTION
+ * decrease the peer_buff structure reference count, free the peer_buff if it reach 0.
+ * PARAMETERS
+ * peer_buff : [IN] peer_buff structure pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1)The prototype of this API is:
+ * void free_peer_buff(peer_buff_struct *peer_buff_ptr);
+ * SEE ALSO
+ * construct_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu, append_to_peer_buff,
+ * prepend_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+#define free_peer_buff(peer_buff) __free_peer_buff(peer_buff)
+#define free_peer_buff_set_null(peer_buff) \
+ do { \
+ if (__free_peer_buff(peer_buff) == KAL_TRUE) \
+ peer_buff = NULL; \
+ } while (0)
+#define free_peer_buff_r free_peer_buff
+#define free_peer_buff_r_set_null free_peer_buff_set_null
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * hold_local_para
+ * DESCRIPTION
+ * If local_para_ptr is not NULL, increment its reference counter by 1.
+ * PARAMETERS
+ * local_para_ptr : [IN] local_para structure pointer.
+ * RETURN VALUES
+ * KAL_TRUE if local_para_ptr is not NULL pointer, otherwise, KAL_FALSE.
+ * NOTE
+ * (1) To pass user-defined local_para structure pointer to it, you need an explicit type-cast:
+ * hold_local_para((local_para_struct *)ptr_to_bt_connected_info);
+ * SEE ALSO
+ * construct_local_para, free_local_para, destroy_ilm
+ ******************************************************************************/
+extern kal_bool hold_local_para(local_para_struct *local_para_ptr);
+#define hold_local_para_r hold_local_para
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * get_local_para_ptr
+ * DESCRIPTION
+ * retrieving start address & length of user-defined local_para structure.
+ * PARAMETERS
+ * local_para_ptr : [IN] local_para structure pointer.
+ * local_para_len_ptr : [OUT] to store length. If it is NULL, the length is not stored.
+ * RETURN VALUES
+ * start address of user-defined local_para structure, It's equal to local_para_ptr.
+ * NOTE
+ * (1)To pass user-defined local_para structure pointer to it, you need an explicit type-cast:
+ * get_local_para_ptr((local_para_struct *)ptr_to_bt_connected_info, &len);
+ * SEE ALSO
+ * construct_local_para
+ ******************************************************************************/
+void *get_local_para_ptr(local_para_struct *local_para_ptr,
+ kal_uint16 * local_para_len_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * hold_peer_buff
+ * DESCRIPTION
+ * If peer_buff_ptr is not NULL, increment its reference counter by 1.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * RETURN VALUES
+ * KAL_TRUE if peer_buff_ptr is not NULL pointer, otherwise, KAL_FALSE.
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, destroy_ilm
+ ******************************************************************************/
+extern kal_bool hold_peer_buff(peer_buff_struct *peer_buff_ptr);
+#define hold_peer_buff_r hold_peer_buff
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * get_peer_buff_pdu
+ * DESCRIPTION
+ * retrieving start address & length of pdu in peer buffer.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * length_ptr : [OUT] to store pdu's length. If it is NULL, the length is not stored.
+ * RETURN VALUES
+ * start address of pdu in peer buffer.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, append_to_peer_buff,
+ * prepend_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+void *get_peer_buff_pdu(peer_buff_struct *peer_buff_ptr, kal_uint16 *length_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * prepend_to_peer_buff
+ * DESCRIPTION
+ * prepend data to head of peer_buff. On success, pdu length increases header_len bytes,
+ * and free space at head decreases header_len bytes.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * header_data_ptr : [IN] data appended.
+ * header_len : [IN] length of data appended.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * If the free head room is smaller than header_len, system enter fatal error handling.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu,
+ * append_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+extern void prepend_to_peer_buff(peer_buff_struct *peer_buff_ptr,
+ void *header_data_ptr, kal_uint16 header_len);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * append_to_peer_buff
+ * DESCRIPTION
+ * append data to tail of peer_buff, On success, pdu length increases tail_len bytes,
+ * and free space at tail decreases tail_len bytes.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * tail_data_ptr : [IN] data appended.
+ * tail_len : [IN] length of data appended.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * If the free tail room is smaller than tail_len, system enter fatal error handling.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu,
+ * prepend_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+extern void append_to_peer_buff(peer_buff_struct *peer_buff_ptr, void *tail_data_ptr,
+ kal_uint16 tail_len);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * remove_head_of_peer_buff
+ * DESCRIPTION
+ * remove data at head of peer_buff. On success, pdu length decreases head_len bytes,
+ * and free space at head increases head_len bytes.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * head_len : [IN] length of data to remove.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1)If the pdu size is smaller than head_len, system enter fatal error handling.
+ * (2)This API replaces remove_hdr_of_peer_buff(). And remove_hdr_of_peer_buff() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu,
+ * prepend_to_peer_buff, append_to_peer_buff, remove_tail_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+extern void remove_head_of_peer_buff(peer_buff_struct *peer_buff_ptr,
+ kal_uint16 head_len);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * remove_tail_of_peer_buff
+ * DESCRIPTION
+ * remove data at tail of peer_buff. On success, pdu length decreases tail_len bytes,
+ * and free space at tail increases tail_len bytes.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * tail_len : [IN] length of data to remove.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * If the pdu size is smaller than tail_len, system enter fatal error handling.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu,
+ * prepend_to_peer_buff, append_to_peer_buff, remove_head_of_peer_buff, update_peer_buff_header
+ ******************************************************************************/
+extern void remove_tail_of_peer_buff(peer_buff_struct *peer_buff_ptr,
+ kal_uint16 tail_len);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * update_peer_buff_header
+ * DESCRIPTION
+ * Reinitialize peer buffer, reset size of free header space, pdu, free tail space to new values.
+ * PARAMETERS
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * new_head_len : [IN] new head size after update.
+ * new_pdu_len : [IN] new pdu size after update.
+ * new_tail_len : [IN] new tail size after update.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1)If total size is bigger than original size, system enter fatal error handling.
+ * SEE ALSO
+ * construct_peer_buff, free_peer_buff, hold_peer_buff, destroy_ilm, get_peer_buff_pdu,
+ * prepend_to_peer_buff, append_to_peer_buff, remove_head_of_peer_buff, remove_tail_of_peer_buff
+ ******************************************************************************/
+extern void update_peer_buff_header(peer_buff_struct *peer_buff_ptr,
+ kal_uint16 new_head_len, kal_uint16 new_pdu_len,
+ kal_uint16 new_tail_len);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_ext_queue
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's ext queue.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) The ILM messages is appended to tail of the queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * (3) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (4) Recommend use msg_send() , msg_send6() series, use this function as
+ * last choice for special condition
+ * SEE ALSO
+ * msg_send_to_head, msg_send6, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send_ext_queue(ilm_struct *ilm_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send_to_head, msg_send6, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send(ilm_struct *ilm_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_custom
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * Selectable custom DHL logging option.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * log_option : [IN] the custom logging to be used.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (5) Only use this if custom DHL logging is needed for the ILM. Normally use msg_send
+ * SEE ALSO
+ * msg_send_to_head, msg_send6, msg_send_to_head6
+ ******************************************************************************/
+#if defined(__DHL_MODULE__)
+kal_bool msg_send_custom(ilm_struct *ilm_ptr, e_custom_ilm_trace_option log_option);
+#else
+#define msg_send_custom(ip, lo) msg_send((ip))
+#endif
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_adt
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's queue.
+ * sender provide translator callback to translate user defined structure
+ * in ILM local/peer parameter to ADT for logging.
+ * sender provide free callback to free user defined structure in ILM
+ * local/peer parameter when the ILM is trapped during UT.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * translator_cb : [IN] translator callback to translate user defined structure to ADT
+ * free_cb : [IN] free callback to free user defined structure
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) This API replaces msg_send_ext_queue/msg_send_int_queue().
+ * They will be removed from next release.
+ * (5) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * They will be removed from next release.
+ * (6) If using the msg_send_adt has error, replace msg_send_adt with msg_send
+ * and test again. If the msg_send is OK but msg_send_adt is not, please
+ * contact the adt provider(TST/DHL module owner)
+ * SEE ALSO
+ * msg_send_to_head, msg_send6, msg_send_to_head6
+ ******************************************************************************/
+#ifdef __TST_MODULE__
+kal_bool msg_send_adt(ilm_struct * ilm_ptr,
+ translator_adt_enc_callback_t translator_cb,
+ ilm_free_callback_t free_cb);
+#else /* else of __TST_MODULE__ */
+#define msg_send_adt(ilm_ptr, translator_cb, free_cb) msg_send(ilm_ptr)
+#endif /* end of "else of __TST_MODULE__" */
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_int_head
+ * DESCRIPTION
+ * send a ILM message to head of destination task's internal queue.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to external queue, system enter fatal error handling.
+ * It uses similar logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to different tasks,
+ * then enter error handling.
+ * b. Otherwise, the message is sent to head of internal queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * SEE ALSO
+ * msg_send_to_int_head6
+ ******************************************************************************/
+kal_bool msg_send_to_int_head(ilm_struct *ilm_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_head
+ * DESCRIPTION
+ * send a ILM message to head of destination task's external queue.
+ * PARAMETERS
+ * ilm_ptr : [IN] the ILM message to be sent.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to internal queue, system enter fatal error handling.
+ * It uses similar logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, then enter error handling.
+ * b. Otherwise, the message is sent to head of external queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send_to_head(ilm_struct *ilm_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_int_head6
+ * DESCRIPTION
+ * send a ILM message to head of destination task's internal queue.
+ * this function is the same as msg_send_to_int_head except assigning content of ilm directly.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * local_para_ptr : [IN] local_para structure pointer.
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * SEE ALSO
+ * msg_send_to_int_head
+ ******************************************************************************/
+kal_bool msg_send_to_int_head6(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct *_local_para_ptr,
+ peer_buff_struct * _peer_buff_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send6
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * local_para_ptr : [IN] local_para structure pointer.
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) This API replaces msg_send_ext_queue/msg_send_int_queue().
+ * (5) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send4, msg_send5, msg_send_to_head, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send6(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct *_local_para_ptr,
+ peer_buff_struct * _peer_buff_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send6_custom
+ * DESCRIPTION
+ * send a ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * Selectable custom DHL logging option.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * local_para_ptr : [IN] local_para structure pointer.
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * log_option : [IN] the custom logging to be used.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) This API replaces msg_send_ext_queue/msg_send_int_queue().
+ * (5) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (6) Only use this if custom DHL logging is needed for the ILM. Normally use msg_send
+ * SEE ALSO
+ * msg_send, msg_send4, msg_send5, msg_send_to_head, msg_send_to_head6
+ ******************************************************************************/
+#if defined(__DHL_MODULE__)
+kal_bool msg_send6_custom(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct * _local_para_ptr,
+ peer_buff_struct * _peer_buff_ptr,
+ e_custom_ilm_trace_option log_option);
+#else
+#define msg_send6_custom(sm, dm, si, mi, lp, pb, lo) \
+ msg_send6((sm), (dm), (si), (mi), (lp), (pb))
+#endif
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send5
+ * DESCRIPTION
+ * same with msg_send6 with _peer_buff_ptr = NULL.
+ * NOTE
+ * SEE ALSO
+ * msg_send, msg_send4, msg_send6
+ ******************************************************************************/
+kal_bool msg_send5(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct *_local_para_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send4
+ * DESCRIPTION
+ * same with msg_send6 with _local_para_ptr = NULL & _peer_buff_ptr = NULL.
+ * SEE ALSO
+ * msg_send, msg_send5, msg_send6
+ ******************************************************************************/
+kal_bool msg_send4(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_head6
+ * DESCRIPTION
+ * send a ILM message to head of destination task's queue.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * local_para_ptr : [IN] local_para structure pointer.
+ * peer_buff_ptr : [IN] peer_buff structure pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to internal queue, system enter fatal error handling.
+ * It uses same logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * (3) This API replaces msg_send_ext_queue_to_head().
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head
+ ******************************************************************************/
+kal_bool msg_send_to_head6(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct *_local_para_ptr,
+ peer_buff_struct * _peer_buff_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_head5
+ * DESCRIPTION
+ * same with msg_send_to_head6 with _peer_buff_ptr = NULL.
+ * NOTE
+ * SEE ALSO
+ * msg_send_to_head, msg_send_to_head4, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send_to_head5(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id,
+ local_para_struct *_local_para_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_to_head4
+ * DESCRIPTION
+ * same with msg_send_to_head6 with _local_para_ptr = NULL & _peer_buff_ptr = NULL.
+ * NOTE
+ * SEE ALSO
+ * msg_send_to_head, msg_send_to_head5, msg_send_to_head6
+ ******************************************************************************/
+kal_bool msg_send_to_head4(module_type _src_mod_id, module_type _dest_mod_id,
+ sap_type _sap_id, msg_type _msg_id);
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_inline6
+ * DESCRIPTION
+ * send a inline-ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * data : [IN] data to be copy in inline-ILM.
+ * datalen : [IN] data length, it's maximum value is MSG_INLINE_ILM_MAX_PAYLOAD.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The inline data length specified by datalen is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * (5) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_bool msg_send_inline6(module_type src_mod, module_type dest_mod, sap_type sap_id,
+ msg_type msg_id, void *data, kal_uint32 datalen);
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_inline_to_head6
+ * DESCRIPTION
+ * send a ILM message to head of destination task's queue.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * data : [IN] data to be copy in inline-ILM.
+ * datalen : [IN] data length, it's maximum value is MSG_INLINE_ILM_MAX_PAYLOAD.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to internal queue, system enter fatal error handling.
+ * It uses same logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * (3) The inline data length specified by datalen is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6,msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_bool msg_send_inline_to_head6(module_type src_mod, module_type dest_mod,
+ sap_type sap_id, msg_type msg_id, void *data,
+ kal_uint32 datalen);
+
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_inline5
+ * DESCRIPTION
+ * send a inline-ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * msg_id : [IN] message id.
+ * data : [IN] data to be copy in inline-ILM.
+ * datalen : [IN] data length, it's maximum value is MSG_INLINE_ILM_MAX_PAYLOAD.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The inline data length specified by datalen is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * (5) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+#define msg_send_inline5(src_mod, dest_mod, msg_id, data, datalen) \
+ msg_send_inline6(src_mod, dest_mod, INLINE_ILM_SAP, msg_id, data, datalen)
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_inline_to_head5
+ * DESCRIPTION
+ * send a ILM message to head of destination task's queue.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * msg_id : [IN] message id.
+ * data : [IN] data to be copy in inline-ILM.
+ * datalen : [IN] data length, it's maximum value is MSG_INLINE_ILM_MAX_PAYLOAD.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to internal queue, system enter fatal error handling.
+ * It uses same logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * (3) The inline data length specified by datalen is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+#define msg_send_inline_to_head5(src_mod, dest_mod, sap_id, msg_id, data, datalen) \
+ msg_send_inline_to_head6(src_mod, dest_mod, INLINE_ILM_SAP, msg_id, data, \
+ datalen)
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_8bytes_inline6
+ * DESCRIPTION
+ * send a inline-ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * data1 : [IN] first 4-byte data to be copy in inline-ILM.
+ * data2 : [IN] second 4-byte data to be copy in inline-ILM.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (5) The inline data length is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5,msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_bool msg_send_8bytes_inline6(module_type src_mod, module_type dest_mod,
+ sap_type sap_id, msg_type msg_id, kal_uint32 data1,
+ kal_uint32 data2);
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_8bytes_inline6_custom
+ * DESCRIPTION
+ * send a inline-ILM message to tail of destination task's queue.
+ * Refer to NOTE about which queue (extq or intq) the message sent to.
+ * Uses custom logging based on the logging option.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * data1 : [IN] first 4-byte data to be copy in inline-ILM.
+ * data2 : [IN] second 4-byte data to be copy in inline-ILM.
+ * log_option : [IN] custom logging option
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) This API select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task, and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) The ILM messages is appended to tail of the queue.
+ * (3) If the destination queue is full, system enter fatal error handling.
+ * (4) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (5) The inline data length is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5,msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+#if defined(__DHL_MODULE__)
+kal_bool msg_send_8bytes_inline6_custom(module_type src_mod, module_type dest_mod,
+ sap_type sap_id, msg_type msg_id,
+ kal_uint32 data1, kal_uint32 data2,
+ e_custom_ilm_trace_option log_option);
+#else
+#define msg_send_8bytes_inline6_custom(sm, dm, si, mi, d1, d2, lo) \
+ msg_send_8bytes_inline6((sm), (dm), (si), (mi), (d1), (d2))
+#endif
+
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_send_8bytes_inline_to_head6
+ * DESCRIPTION
+ * send a ILM message to head of destination task's queue.
+ * PARAMETERS
+ * src_mod_id : [IN] source module id.
+ * dest_mod_id : [IN] destination module id.
+ * sap_id : [IN] service access point id.
+ * msg_id : [IN] message id.
+ * data1 : [IN] first 4-byte data to be copy in inline-ILM.
+ * data2 : [IN] second 4-byte data to be copy in inline-ILM.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) If the ILM is sent to internal queue, system enter fatal error handling.
+ * It uses same logic as msg_send to select queue based on following criteria:
+ * a. If src_mod_id and dest_mod_id in ilm_ptr mapped to same task,and the
+ * internal queue of the task is not NULL, the message is sent to internal queue.
+ * b. Otherwise, the message is sent to external queue.
+ * (2) If the destination queue is full, system enter fatal error handling.
+ * (3) The use of allocate_ilm()/cancel_ilm() is deprecated,
+ * (4) The inline data length is not recorded in destination ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_bool msg_send_8bytes_inline_to_head6(module_type src_mod, module_type dest_mod,
+ sap_type sap_id, msg_type msg_id,
+ kal_uint32 data1, kal_uint32 data2);
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_inline_4bytes_data1
+ * DESCRIPTION
+ * Get the inline first 4-byte data value in ILM message.
+ * PARAMETERS
+ * ilm_ptr : [IN] ILM message pointer.
+ * RETURN VALUES
+ * First 4-byte data value. If it's not an inline-ILM, system enter fatal error handling.
+ * NOTE
+ * (1) Users must pass a inline-ILM to this function.
+ * (2) The inline data length is not recorded in ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ *
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6,msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_uint32 msg_get_inline_4bytes_data1(ilm_struct *ilm_ptr);
+
+/******************************************************************************
+*
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_inline_4bytes_data2
+ * DESCRIPTION
+ * Get the inline second 4-byte data value in ILM message.
+ * PARAMETERS
+ * ilm_ptr : [IN] ILM message pointer.
+ * RETURN VALUES
+ * Second 4-byte data value. If it's not an inline-ILM, system enter fatal error handling.
+ * NOTE
+ * (1) Users must pass a inline-ILM to this function.
+ * (2) The inline data length is not recorded in ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ *
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+kal_uint32 msg_get_inline_4bytes_data2(ilm_struct *ilm_ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_is_inline
+ * DESCRIPTION
+ * judge whether is a inline-ILM or not.
+ * PARAMETERS
+ * ilm_ptr : [IN] ILM message pointer.
+ * RETURN VALUES
+ * KAL_TRUE : this is a inline-ILM.
+ * KAL_FALSE : this isn't a inline-ILM.
+ * NOTE
+ * (1) The prototype of this API is:
+ * kal_bool msg_is_inline(ilm_struct *ilm_ptr);
+ * (2) inline-ILM is identified by sap_id, always use this API to do this, never use
+ * sap_id comparison directly since this will change in future.
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+
+******************************************************************************/
+#define msg_is_inline(ilm_ptr) \
+ (((ilm_ptr)->sap_id & (INLINE_ILM_FLAG_SAP | INLINE_CUSTOM_ILM_FLAG_SAP)) \
+ ? KAL_TRUE \
+ : KAL_FALSE)
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_inline_data
+ * DESCRIPTION
+ * Get the inline data pointer in ILM message.
+ * PARAMETERS
+ * ilm_ptr : [IN] ILM message pointer.
+ * RETURN VALUES
+ * inline data pointer. If it's not an inline-ILM, system enter fatal error handling.
+ * NOTE
+ * (1) Users must pass a inline-ILM to this function.
+ * (2) The inline data length is not recorded in ILM messages.
+ * Its user's responsibility to know what the inline data is.
+ *
+ * SEE ALSO
+ * msg_send, msg_send6, msg_send_to_head6, msg_send_inline5, msg_send_inline_tp_head5,
+ * msg_is_inline, msg_get_inline_data
+ * msg_send_inline6, msg_send_inline_to_head6, msg_send_8bytes_inline6, msg_send_8bytes_inline_to_head6
+ * msg_get_inline_4bytes_data1, msg_get_inline_4bytes_data2
+ ******************************************************************************/
+void *msg_get_inline_data(ilm_struct *ilm_ptr);
+
+
+#if defined(DEBUG_KAL) && defined(DEBUG_ITC)
+#define __destroy_ilm(ilm_ptr) \
+ destroy_int_ilm((ilm_ptr), (kal_char *)__FILE__, __LINE__);
+#else
+#define __destroy_ilm(ilm_ptr) destroy_int_ilm((ilm_ptr), NULL, 0);
+#endif
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * destroy_ilm
+ * DESCRIPTION
+ * destroy an ILM. ref_count would minus 1 if buffer pointer is not NULL, buffer
+ * instance peer_buff_ptr or local_para_ptr will truly be released only if
+ * ref_count is zero.
+ * PARAMETERS
+ * ilm_ptr : [IN] ILM message pointer.
+ * RETURN VALUES
+ * N/A
+ * NOTE
+ * (1) The content pointed by ilm_ptr is not free.
+ * (2) It will return immediately without destroy the ILM if
+ * (2-A) the ILM is sent from timer (i.e. ilm_ptr->src_mod_id == MOD_TIMER)
+ * (2-B) the ILM is an inline ILM (i.e. (ilm_ptr->sap_id & INLINE_ILM_FLAG_SAP) != 0)
+ * If you want to replace this API by free_local_para[_r] or free_peer_buff[_r],
+ * please remember to skip timer ILM or inline ILM
+ * SEE ALSO
+ * msg_send, msg_receive_extq, msg_receive_intq, free_local_para, free_local_para_r
+ * free_peer_buff, free_peer_buff_r
+ ******************************************************************************/
+#define destroy_ilm(ilm_ptr) __destroy_ilm(ilm_ptr)
+
+#define destroy_shared_ilm_r destroy_ilm
+#define free_shared_peer_buff_r free_peer_buff
+#define free_shared_local_para_r free_local_para
+
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_receive_extq
+ * DESCRIPTION
+ * receive a ILM message from current task's external queue.
+ * PARAMETERS
+ * ilm_ptr : [OUT] ILM message pointer.
+ * RETURN VALUES
+ * KAL_TRUE: to indicate this operation finish successfully.
+ * NOTE
+ * (1) If the external queue is not empty, this API return immediately.
+ * Otherwise, it will suspend to wait for the arrival of ILM message.
+ * (2) This API replaces receive_msg_ext_q(). And receive_msg_ext_q() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * msg_send, msg_receive_intq, destroy_ilm
+ ******************************************************************************/
+kal_bool msg_receive_extq(ilm_struct *ilm_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_receive_extq_for_stack
+ * DESCRIPTION
+ * receive a ILM message from current task's external queue used for stack sharing.
+ * PARAMETERS
+ * ilm_ptr : [OUT] ILM message pointer.
+ * RETURN VALUES
+ * KAL_TRUE: to indicate this operation finish successfully.
+ * NOTE
+ * (1) If the external queue is not empty, this API return immediately.
+ * Otherwise, it will suspend to wait for the arrival of ILM message.
+ * (2) This API replaces receive_msg_ext_q(). And receive_msg_ext_q() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * msg_send, msg_receive_intq, destroy_ilm
+ ******************************************************************************/
+kal_bool msg_receive_extq_for_stack(ilm_struct *ilm_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_receive_intq
+ * DESCRIPTION
+ * receive a ILM message from current task's internal queue.
+ * PARAMETERS
+ * ilm_ptr : [OUT] ILM message pointer.
+ * RETURN VALUES
+ * KAL_TRUE: ILM fetched.
+ * KAL_FALSE: internal queue is empty and no ILM is fetched.
+ * NOTE
+ * This API replaces receive_msg_int_q(). And receive_msg_int_q() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * msg_send, msg_receive_extq, destroy_ilm
+ ******************************************************************************/
+kal_bool msg_receive_intq(ilm_struct *ilm_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_receive_isrq
+ * DESCRIPTION
+ * receive a ILM message from current ISR's queue.
+ * PARAMETERS
+ * ilm_ptr : [OUT] ILM message pointer.
+ * RETURN VALUES
+ * KAL_TRUE: ILM fetched.
+ * KAL_FALSE: internal queue is empty and no ILM is fetched.
+ * NOTE
+ *
+ * SEE ALSO
+ * msg_send, msg_receive_intq, destroy_ilm
+ ******************************************************************************/
+kal_bool msg_receive_isrq(ilm_struct *ilm_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_task_extq_messages
+ * DESCRIPTION
+ * get messages count in external queue of specified task by task index.
+ * PARAMETERS
+ * tindex : [IN] task index.
+ * RETURN VALUES
+ * messages count, -1 if error happens.
+ * NOTE
+ * (1)This API replaces msg_get_ext_queue_info(). And msg_get_ext_queue_info() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * msg_get_extq_messages, msg_get_task_extq_capacity, msg_get_extq_capacity
+ ******************************************************************************/
+kal_int32 msg_get_task_extq_messages(module_type module_id);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_extq_messages
+ * DESCRIPTION
+ * get messages count in external queue of current task.
+ * PARAMETERS
+ * N/A
+ * RETURN VALUES
+ * messages count, -1 if error happens.
+ * SEE ALSO
+ * msg_get_task_extq_messages, msg_get_task_extq_capacity, msg_get_extq_capacity
+ ******************************************************************************/
+kal_int32 msg_get_extq_messages(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_task_extq_capacity
+ * DESCRIPTION
+ * get capacity of external queue of specified task by task index.
+ * PARAMETERS
+ * tindex : [IN] task index.
+ * RETURN VALUES
+ * capacity of target external queue, -1 if error happens.
+ * NOTE
+ * (1)This API replaces msg_get_ext_queue_length(). And msg_get_ext_queue_length() is deprecated,
+ * it will be removed from next release.
+ * SEE ALSO
+ * msg_get_task_extq_messages, msg_get_extq_messages, msg_get_extq_capacity
+ ******************************************************************************/
+kal_int32 msg_get_task_extq_capacity(module_type tmod);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * msg_get_extq_capacity
+ * DESCRIPTION
+ * get capacity of external queue of current task.
+ * PARAMETERS
+ * N/A
+ * RETURN VALUES
+ * capacity of current task external queue, -1 if error happens.
+ * SEE ALSO
+ * msg_get_task_extq_messages, msg_get_extq_messages, msg_get_task_extq_capacity
+ ******************************************************************************/
+kal_int32 msg_get_extq_capacity(void);
+#if 0
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+/* under construction !*/
+#endif
+
+/*******************************************************************************
+ * Category 4.5 : Cross Core Message Passing and Queue
+ *******************************************************************************/
+#define construct_int_cc_cached_peer_buff construct_int_peer_buff
+#define construct_int_cc_non_cached_peer_buff construct_int_peer_buff
+#define construct_int_cc_cached_local_para construct_int_local_para
+#define construct_int_cc_non_cached_local_para construct_int_local_para
+
+#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
+#define __construct_int_cc_cached_local_para(local_para_size, direction) \
+ construct_int_cc_cached_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ __FILE__, __LINE__)
+#define __construct_int_cc_non_cached_local_para(local_para_size, direction) \
+ construct_int_cc_non_cached_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ __FILE__, __LINE__)
+
+#define __construct_int_cc_cached_peer_buff(pdu_len, header_len, tail_len, \
+ direction) \
+ construct_int_cc_cached_peer_buff(pdu_len, header_len, tail_len, __FILE__, \
+ __LINE__)
+#define __construct_int_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, \
+ direction) \
+ construct_int_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, __FILE__, \
+ __LINE__)
+
+#else /* !DEBUG_KAL || !DEBUG_BUF2 */
+#define __construct_int_cc_cached_local_para(local_para_size, direction) \
+ construct_int_cc_cached_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ NULL, 0)
+#define __construct_int_cc_non_cached_local_para(local_para_size, direction) \
+ construct_int_cc_non_cached_local_para( \
+ local_para_size, ((kal_uint32)(direction) & (kal_uint32)TD_RESET) ? 1 : 0, \
+ NULL, 0)
+
+#define __construct_int_cc_cached_peer_buff(pdu_len, header_len, tail_len, \
+ direction) \
+ construct_int_cc_cached_peer_buff(pdu_len, header_len, tail_len, NULL, 0)
+#define __construct_int_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, \
+ direction) \
+ construct_int_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, NULL, 0)
+
+#endif
+
+
+#define construct_cc_cached_local_para(local_para_size, direction) \
+ __construct_int_cc_cached_local_para(local_para_size, direction)
+#define construct_cc_non_cached_local_para(local_para_size, direction) \
+ __construct_int_cc_non_cached_local_para(local_para_size, direction)
+
+#define construct_cc_cached_peer_buff(pdu_len, header_len, tail_len, direction) \
+ __construct_int_cc_cached_peer_buff(pdu_len, header_len, tail_len, direction)
+#define construct_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, direction) \
+ __construct_int_cc_non_cached_peer_buff(pdu_len, header_len, tail_len, direction)
+
+#define msg_send_cc msg_send
+#define msg_send6_cc msg_send6
+#define msg_send5_cc msg_send5
+#define msg_send4_cc msg_send4
+#define msg_send_to_head_cc msg_send_to_head
+#define msg_send_to_head6_cc msg_send_to_head6
+#define msg_send_to_head5_cc msg_send_to_head5
+#define msg_send_to_head4_cc msg_send_to_head4
+
+
+#define msg_send_inline6_cc msg_send_inline6
+#define msg_send_inline_to_head6_cc msg_send_inline_to_head6
+
+#define msg_send_inline5_cc(src_mod, dest_mod, msg_id, data, datalen) \
+ msg_send_inline6_cc(src_mod, dest_mod, INLINE_ILM_SAP, msg_id, data, datalen)
+
+
+#define msg_send_inline_to_head5_cc(src_mod, dest_mod, sap_id, msg_id, data, \
+ datalen) \
+ msg_send_inline_to_head6_cc(src_mod, dest_mod, INLINE_ILM_SAP, msg_id, data, \
+ datalen)
+
+#define msg_send_8bytes_inline6_cc msg_send_8bytes_inline6
+
+#define msg_send_8bytes_inline_to_head6_cc msg_send_8bytes_inline_to_head6
+
+/* DOM-NOT_FOR_SDK-END */
+
+/*******************************************************************************
+ * Category 5 : Synchronous Mechanism : Mutex , Enhance Mutex , Semaphore,
+ * Event Group, Spinlock, HW ITC and atomic increment/decrement
+ *******************************************************************************/
+
+
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_create_mutex
+ * DESCRIPTION
+ * create a mutex.
+ * PARAMETERS
+ * mutex_name : [IN] mutex name. it's used for debug only, and only the
+ * first 8 characters retain.
+ * RETURNS
+ * Success: mutex pointer.
+ * Error: system enter fatal error handling.
+ * NOTE
+ * It is strongly suggested to call this function only in system initialization
+ * time, and the related data allocated for the mutex could not be freed
+ * once it is created.
+ * SEE ALSO
+ * kal_take_mutex kal_give_mutex
+ ******************************************************************************/
+kal_mutexid kal_create_mutex(kal_char *mutex_name);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_take_mutex
+ * DESCRIPTION
+ * Obtains an instance of the specified mutex. If the mutex is taken already
+ * before this call, the function cannot be immediately satisfied, and caller
+ * task will be suspended until other task give the ownership to caller task.
+ * After the function returns, caller task is the only task held this mutex.
+ * PARAMETERS
+ * mutex_ptr : [IN] mutex pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)Mutex is not a recursive lock. If caller task already held this mutex,
+ * then caller task will suspend forever because any task won^t and can^t
+ * give up mutex^s ownership.
+ * (2)Mutex is a FIFO queue. If multiple tasks are waiting on a mutex, the
+ * first waiting task is selected to be the next owner.
+ * SEE ALSO
+ * kal_create_mutex kal_give_mutex
+ ******************************************************************************/
+void kal_take_mutex(kal_mutexid mutex_ptr);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_give_mutex
+ * DESCRIPTION
+ * Give up mutex ownership. If any task is waiting on this mutex, the first
+ * waiting task is selected to be the next owner.
+ * PARAMETERS
+ * mutex_ptr : [IN] mutex pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * Mutex ownership is private to task. That means, give can be done at the same
+ * task of take, otherwise fatal error handling takes place.
+ * SEE ALSO
+ * kal_create_mutex kal_take_mutex
+ ******************************************************************************/
+void kal_give_mutex(kal_mutexid mutex_ptr);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_mutex_waiting_count
+ * DESCRIPTION
+ * This routine returns the numbers of task waiting on the mutex.
+ * PARAMETERS
+ * mutex_ptr : [IN] mutex pointer.
+ * waiting_count : [OUT] waiting count.
+ * RETURNS
+ * N/A
+ * NOTE
+ * This function is not in any critical section, e.g disable/enable interrupt, user should guarantee the atomic.
+ * SEE ALSO
+ * kal_create_mutex kal_take_mutex
+ ******************************************************************************/
+void kal_mutex_waiting_count(kal_mutexid mutex_ptr, kal_uint32 *waiting_count);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_create_enh_mutex
+ * DESCRIPTION
+ * create an enhmutex which implements Priority Inheritance Protocol(PIP) to
+ * avoid priority inversion.
+ * PARAMETERS
+ * mutex_name : [IN] enhmutex name. it's used for debug only, and only the
+ * first 8 characters retain.
+ * RETURNS
+ * Success: enhmutex pointer.
+ * Error: system enter fatal error handling.
+ * NOTE
+ * It is strongly suggested to call this function only in system initialization
+ * time, and the related data allocated for the enhmutex could not be freed
+ * once it is created.
+ * SEE ALSO
+ * kal_take_enh_mutex kal_give_enh_mutex
+ ******************************************************************************/
+kal_enhmutexid kal_create_enh_mutex(kal_char *mutex_name);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_take_enh_mutex
+ * DESCRIPTION
+ * Obtain an instance of the specified enhmutex. If the enhmutex is taken
+ * already before this call, the function cannot be immediately satisfied,
+ * caller task propogates its priority to the owner task if caller task has
+ * higher priority than owner task, and caller task will be suspended until
+ * other task give the ownership to caller task. After the function returns,
+ * caller task is the only task held this enhmutex.
+ * PARAMETERS
+ * mutex_ptr : [IN] enhmutex pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)Enhmutex is not a recursive lock. If caller task already held this
+ * enhmutex, then caller task will suspend forever because any task will not
+ * give up ehnmutex's ownership.
+ * (2)No promise of enhmutex's queue type. If multiple tasks is waiting on a
+ * mutex, no promise made which task will selected to run first.
+ * SEE ALSO
+ * kal_create_enh_mutex kal_give_enh_mutex
+ ******************************************************************************/
+void kal_take_enh_mutex(kal_enhmutexid mutex_ptr);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_give_enh_mutex
+ * DESCRIPTION
+ * Give up enhmutex ownership. If any task is waiting on this mutex, give the
+ * ownership to any task based on its judge.
+ * PARAMETERS
+ * mutex_ptr : [IN] mutex pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * Enhmutex ownership is private to task. That means, give can be done at the
+ * same task of take, otherwise fatal error handling takes place.
+ * SEE ALSO
+ * kal_create_enh_mutex kal_take_enh_mutex
+ ******************************************************************************/
+void kal_give_enh_mutex(kal_enhmutexid mutex_ptr);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_create_sem
+ * DESCRIPTION
+ * create a couting semaphore.
+ * PARAMETERS
+ * sem_name : [IN] semaphore name. it's used for debug only, and only the
+ * first 8 characters retain.
+ * initial_count : [IN] semaphore initial count.
+ * RETURNS
+ * Success: semaphore pointer.
+ * Error: system enter fatal error handling.
+ * NOTE
+ * (1)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 is created.
+ * (2)Semaphore values can range from 0 through 4,294,967,294 (2^32 - 2).
+ * SEE ALSO
+ * kal_take_sem kal_give_sem
+ ******************************************************************************/
+kal_semid kal_create_sem(kal_char *sem_name, kal_uint32 initial_count);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_take_sem
+ * DESCRIPTION
+ * Obtains an instance of the specified semaphore.
+ * PARAMETERS
+ * sem_ptr : [IN] semaphore pointer.
+ * wait_mode : [IN] wait mode, specify the behavior when the semaphore is
+ * not ready immediately, it can be one the the following values:
+ * KAL_NO_WAIT - don't wait for other task gives ownership to it
+ * KAL_INFINITE_WAIT - wait until ownership can be satisfied
+ * RETURN VALUES
+ * KAL_SUCCESS : the operation is done successfully
+ * KAL_SEM_NOT_AVAILABLE : the semaphore is unavailable immediately
+ * NOTE
+ * (1)Semaphore is a FIFO queue. If multiple tasks is waiting on a semaphore,
+ * the first waiting task is selected to be the next owner.
+ * SEE ALSO
+ * kal_create_sem kal_give_sem
+ ******************************************************************************/
+kal_status kal_take_sem(kal_semid sem_ptr, kal_wait_mode wait_mode);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_give_sem
+ * DESCRIPTION
+ * Give up 1 semaphore ownership. If any task is waiting on this semaphore,
+ * give the ownership to first waiting task.
+ * PARAMETERS
+ * sem_ptr : [IN] semaphore pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * kal_create_sem kal_take_sem
+ ******************************************************************************/
+void kal_give_sem(kal_semid sem_ptr);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_create_spinlock
+ * DESCRIPTION
+ * creates a spinlock.
+ * PARAMETERS
+ * spinlock_name : [IN] spinlock name. it's used for debug only, and only the
+ * first 7 characters retain.
+ * RETURNS
+ * Success: spinlock pointer.
+ * Error: system enter fatal error handling.
+ * SEE ALSO
+ * kal_delete_spinlock
+ ******************************************************************************/
+kal_spinlockid kal_create_spinlock(kal_char *spinlock_name);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_take_spinlock
+ * DESCRIPTION
+ * Obtains an instance of the specified spinlock.
+ * PARAMETERS
+ * ext_spinlock_id_ptr : [IN] spinlock pointer.
+ * wait_mode : [IN] wait mode, specify the behavior when the semaphore is
+ * not ready immediately, it can be one the the following values:
+ * KAL_NO_WAIT - don't wait for other task gives ownership to it
+ * KAL_INFINITE_WAIT - wait until ownership can be satisfied
+ * RETURN VALUES
+ * KAL_SUCCESS : the operation is done successfully
+ * KAL_SPINLOCK_NOT_AVAILABLE : the spinlock is unavailable immediately
+ * SEE ALSO
+ * kal_give_spinlock
+ ******************************************************************************/
+kal_status kal_take_spinlock(kal_spinlockid ext_spinlock_id_ptr,
+ kal_wait_mode wait_mode);
+/*******************************************************************************
+ * <GROUP Synchronous>
+ *
+ * FUNCTION
+ * kal_give_spinlock
+ * DESCRIPTION
+ * Give up 1 spinlock ownership.
+ * PARAMETERS
+ * ext_spinlock_id_ptr : [IN] spinlock pointer.
+ * RETURNS
+ * -
+ * SEE ALSO
+ * kal_take_spinlock
+ ******************************************************************************/
+void kal_give_spinlock(kal_spinlockid ext_spinlock_id_ptr);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kal_create_event_group
+ * DESCRIPTION
+ * create an event group.
+ * PARAMETERS
+ * eventgrp_name : [IN] event group name. it's used for debug only, and only
+ * the first 8 characters retain.
+ * RETURNS
+ * Success: event group pointer.
+ * Error: system enter fatal error handling.
+ * NOTE
+ * (1)It is strongly suggested to call this function only in system initialization
+ * time, and the related data allocated for the event group could not be freed
+ * once it is created.
+ * (2)Each event group contains 32 event flags, all event flags are initially
+ * set to 0.
+ * SEE ALSO
+ * kal_set_eg_events kal_retrieve_eg_events kal_retrieve_eg_events_timeout
+ ******************************************************************************/
+kal_eventgrpid kal_create_event_group(kal_char *eventgrp_name);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kal_set_eg_events
+ * DESCRIPTION
+ * sets the specified event flags in the specified event group. Any task waiting
+ * on the event group whose event flag request is satisfied by this service is resumed.
+ * PARAMETERS
+ * eg_ptr : [IN] event group pointer.
+ * events : [IN] event flags to be set.
+ * operation : [IN] specify the operation, which can be one of following values:
+ * KAL_AND - events in event group is AND with events argument,
+ * that is, mask out bits not set in events argument
+ * KAL_OR - events in event group is OR with events argument
+ * RETURNS
+ * Success: return KAL_SUCCESS
+ * Error: system enter fatal error handling.
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * kal_create_event_group kal_retrieve_eg_events kal_retrieve_eg_events_timeout
+ ******************************************************************************/
+kal_status kal_set_eg_events(kal_eventgrpid eg_ptr, kal_uint32 events,
+ kal_uint8 operation);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kal_retrieve_eg_events
+ * DESCRIPTION
+ * retrieves the specified event-flag combination from the specified event-flag group.
+ * PARAMETERS
+ * eg_ptr : [IN] event group pointer.
+ * requested_events : [IN] requested event flags
+ * operation : [IN] specify the operation, which can be one of following values:
+ * KAL_AND - all of the requested event flags are required
+ * KAL_AND_CONSUME - all of requested event flags are required, and
+ * automatically clears the event flags present on a successful request
+ * KAL_OR - one or more of the requested event flags is sufficient
+ * KAL_OR_CONSUME - one or more of the requested event flags is sufficient, and
+ * automatically clears the event flags present on a successful request
+ * retrieved_events: [OUT] actual events present in event group.
+ * suspend: [IN] whether to wait for the event flags set when they can be satisfied immediately,
+ * it can be one of following values:
+ * 0: don't wait and return KAL_NOT_PRESENT
+ * KAL_SUSPEND: wait until they can be satisfied
+ * RETURN VALUES
+ * KAL_SUCCESS: the operation is done successfully
+ * KAL_NOT_PRESENT: the request event flags are not present immediately
+ * Error: system enter fatal error handling.
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * kal_create_event_group kal_set_eg_events kal_retrieve_eg_events_timeout
+ ******************************************************************************/
+kal_status kal_retrieve_eg_events(kal_eventgrpid eg_ptr, kal_uint32 requested_events,
+ kal_uint8 operation, kal_uint32 *retrieved_events,
+ kal_uint32 suspend);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kal_retrieve_eg_events_timeout
+ * DESCRIPTION
+ * retrieves the specified event-flag combination from the specified event-flag group.
+ * PARAMETERS
+ * eg_ptr : [IN] event group pointer.
+ * requested_events : [IN] requested event flags
+ * operation : [IN] specify the operation, which can be one of following values:
+ * KAL_AND - all of the requested event flags are required
+ * KAL_AND_CONSUME - all of requested event flags are required, and
+ * automatically clears the event flags present on a successful request
+ * KAL_OR - one or more of the requested event flags is sufficient
+ * KAL_OR_CONSUME - one or more of the requested event flags is sufficient, and
+ * automatically clears the event flags present on a successful request
+ * retrieved_events: [OUT] actual events present in event group.
+ * timeout: [IN] how long to wait for the event flags set when they can be satisfied immediately,
+ * it can be one of following values:
+ * 0 - don't wait and return KAL_NOT_PRESENT
+ * KAL_SUSPEND - wait until they can be satisfied
+ * other values - wait at most timeout ticks, return KAL_NOT_PRESENT if timeout happens
+ * RETURN VALUES
+ * KAL_SUCCESS: the operation is done successfully
+ * KAL_NOT_PRESENT: the request event flags are not present immediately
+ * Error: system enter fatal error handling.
+ * NOTE
+ * This API's availability is dependent on a macro HAS_KAL_RETRIEVE_EG_EVENTS_TIMEOUT.
+ * If it's not defined, then this API is not available.
+ * SEE ALSO
+ * kal_create_event_group kal_set_eg_events kal_retrieve_eg_events
+ ******************************************************************************/
+kal_status kal_retrieve_eg_events_timeout(kal_eventgrpid eg_ptr,
+ kal_uint32 requested_events,
+ kal_uint8 operation,
+ kal_uint32 * retrieved_events,
+ kal_uint32 timeout);
+#define HAS_KAL_RETRIEVE_EG_EVENTS_TIMEOUT 1
+
+/*******************************************************************************
+ * Category 5.5 : Cross Core Event Group and RCU
+ *******************************************************************************/
+
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kalcc_create_event_group
+ * DESCRIPTION
+ * create a cross core event group.
+ * PARAMETERS
+ * eg_id : [IN] event group pointer, the memory should be allocated from
+ * shared memory
+ * eventgrp_name : [IN] event group name. it's used for debug only, and only
+ * the first 7 characters retain.
+ * RETURNS
+ * KAL_SUCCESS: create successfully
+ * KAL_INIT_BEFORE: the event group has been init before
+ * NOTE
+ * (1)It is strongly suggested to call this function only in system initialization
+ * time, and the related data allocated for the event group could not be freed
+ * once it's created.
+ * (2)Each event group contains 32 event flags, all event flags are initially
+ * set to 0.
+ * SEE ALSO
+ * kalcc_set_eg_events kalcc_retrieve_eg_events
+ ******************************************************************************/
+kal_status kalcc_create_event_group(cc_eventgrpid *eg_id, kal_char *eventgrp_name);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kalcc_set_eg_events
+ * DESCRIPTION
+ * sets the specified event flags in the specified event group. Any task waiting
+ * on the event group whose event flag request is satisfied by this service is resumed.
+ * PARAMETERS
+ * cc_eventgrpid : [IN] event group pointer.
+ * events : [IN] event flags to be set.
+ * operation : [IN] specify the operation, which can be one of following values:
+ * KAL_AND - events in event group is AND with events argument,
+ * that is, mask out bits not set in events argument
+ * KAL_OR - events in event group is OR with events argument
+ * RETURNS
+ * KAL_SUCCESS: the operation is done successfully
+ * Error: system enter fatal error handling.
+ * NOTE
+ * This function can not be called from hisr or system initialization; otherwise, assertion
+ * SEE ALSO
+ * kalcc_create_event_group kalcc_retrieve_eg_events
+ ******************************************************************************/
+kal_status kalcc_set_eg_events(cc_eventgrpid *eg_id, kal_uint32 events,
+ kal_uint8 operation);
+/*******************************************************************************
+ * <GROUP Communication>
+ *
+ * FUNCTION
+ * kalcc_retrieve_eg_events
+ * DESCRIPTION
+ * retrieves the specified event-flag combination from the specified event-flag group.
+ * PARAMETERS
+ * eg_id : [IN] event group pointer.
+ * requested_events : [IN] requested event flags
+ * operation : [IN] specify the operation, which can be one of following values:
+ * KAL_AND - all of the requested event flags are required
+ * KAL_AND_CONSUME - all of requested event flags are required, and
+ * automatically clears the event flags present on a successful request
+ * KAL_OR - one or more of the requested event flags is sufficient
+ * KAL_OR_CONSUME - one or more of the requested event flags is sufficient, and
+ * automatically clears the event flags present on a successful request
+ * retrieved_events: [OUT] actual events present in event group.
+ * suspend: [IN] whether to wait for the event flags set when they can be satisfied immediately,
+ * it can be one of following values:
+ * 0: don't wait and return CC_NOT_PRESENT
+ * KAL_SUSPEND: wait until they can be satisfied
+ * otherwise: system enter fatal error handling.
+ * RETURN VALUES
+ * KAL_SUCCESS: the operation is done successfully
+ * KAL_NOT_PRESENT: the request event flags are not present immediately
+ * Error: system enter fatal error handling.
+ * NOTE
+ * N/A
+ * SEE ALSO
+ * kalcc_create_event_group cc_set_eg_events
+ ******************************************************************************/
+kal_status kalcc_retrieve_eg_events(cc_eventgrpid *eg_id,
+ kal_uint32 requested_events, kal_uint8 operation,
+ kal_uint32 *retrieved_events,
+ kal_uint32 suspend);
+
+
+/* 1. creator*/
+kalcc_rcuid rcu_create(void *buff_addr, kal_uint32 allocated_buff_size,
+ kal_uint32 buff_size, kal_uint32 reserved);
+/* 2. writer */
+void *rcu_get_free_buff(kalcc_rcuid id);
+kal_status rcu_commit_data(void *data);
+/* 3. reader */
+void *rcu_get_read_lock(kalcc_rcuid id);
+kal_status rcu_free_read_lock(void *data);
+
+
+/*******************************************************************************
+ * Category 6 : Application Memory Management ADM , AFM
+ *******************************************************************************/
+
+extern KAL_ADM_ID(kal_adm_create)(void *mem_addr, kal_uint32 size,
+ kal_uint32 *subpool_size, kal_bool islogging);
+extern KAL_ADM_ID(kal_adm_create_and_profile)(void *mem_addr, kal_uint32 size,
+ kal_uint32 *subpool_size,
+ kal_bool islogging);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_create2
+ * DESCRIPTION
+ * Create a ADM pool.
+ * PARAMETERS
+ * mem_addr: [IN] starting address of the memory pool. It should be 4-byte alignment, or it will be aligned to next 4-aligned address.
+ * size: [IN] total size in byte of the memory pool.
+ * subpool_size: [IN] is an array, which describe size of each sub-pool.
+ * flags: [IN] new ADM pool extra flags, which is a combination of following values
+ * KAL_ADM_GUARDIAN_FLAG - RECOMMENDED! put a guard word before and after each user buffer to detect memory corruption
+ * it also enable some other error detections on this ADM pool.
+ * KAL_ADM_EXTHEADER_FLAG - has an extensible header immediate before each user buffer,
+ * whose size is specified by extheader_size_in_word
+ * KAL_ADM_CLEANDELETE_FLAG - on kal_adm_delete(), if any user buffer is not free yet,
+ * system enter fatal error handling
+ * KAL_ADM_REALLOCFAIL_FATAL_FLAG - if kal_adm_realloc() failed, system enter fatal error handling
+ * KAL_ADM_REALLOCFAIL_FREE_FLAG - if kal_adm_realloc() failed, free old user buffer before return NULL
+ * extheader_size_in_word: [IN] specified the extensible header size, only takes effect when KAL_ADM_EXTHEADER_FLAG is specified.
+ * this argument specified in unit of word, you can use KAL_ADM_EXTHEADER_WORDS(sizeof(struct A)) if you want
+ * to put a struct A in extensible header.
+ * RETURNS
+ * ADM id. If memory is too small to create a ADM, return NULL.
+ * NOTE
+ * (1)This API replaces kal_adm_create(). And kal_adm_create() is deprecated,
+ * it will be removed from next release.
+ * (2)subpool_size must be monotonic increasing and ends with {0xffffffff, 0}.
+ * If it's NULL, the default subpool size setting is used: { 16, 32, 64, 128, 256, 512, 0xffffffff, 0 }.
+ * Default subpool size has 7 subpools.
+ * (3)The ADM overhead for control block is divided into 2 parts:
+ * Static - that is (16*3+16*subpool_count}. subpool_count is element count in subpool_size except last element 0.
+ * Dynamic - Each user block has an extra: (8+extheader_size_in_word*4)
+ * SEE ALSO
+ * kal_adm_delete KAL_ADM_EXTHEADER_WORDS
+ ******************************************************************************/
+extern KAL_ADM_ID kal_adm_create2(void *mem_addr, kal_uint32 size,
+ kal_uint32 *subpool_size, kal_uint32 flags,
+ kal_int8 extheader_size_in_word);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_delete
+ * DESCRIPTION
+ * delete a ADM pool.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * RETURN VALUES
+ * KAL_SUCCESS: the operation succeeded.
+ * KAL_MEMORY_NOT_RELEASE: some user buffer is not free yet.
+ * NOTE
+ * if KAL_ADM_CLEANDELETE_FLAG is specified on creation and any user buffer is not free yet,
+ * system enter fatal error handling
+ * SEE ALSO
+ * kal_adm_create2
+ ******************************************************************************/
+extern kal_status kal_adm_delete(KAL_ADM_ID adm_id);
+
+extern void *__kal_adm_alloc(KAL_ADM_ID adm_id, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 opt, char *filename,
+ kal_uint32 line);
+extern void *__kal_adm_alloc_nc(KAL_ADM_ID adm_id, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 option,
+ char *filename, kal_uint32 line);
+extern void *__kal_adm_alloc_c(KAL_ADM_ID adm_id, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 option,
+ char *filename, kal_uint32 line);
+
+extern void *__kal_adm_realloc(KAL_ADM_ID adm_id, void *ptr, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 opt,
+ char *filename, kal_uint32 line);
+extern void *__kal_adm_realloc_nc(KAL_ADM_ID adm_id, void *ptr, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 opt,
+ char *filename, kal_uint32 line);
+extern void *__kal_adm_realloc_c(KAL_ADM_ID adm_id, void *ptr, kal_uint32 size,
+ kal_uint32 *actual_size, kal_uint32 opt,
+ char *filename, kal_uint32 line);
+
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc
+ * DESCRIPTION
+ * allocate a memory buffer from ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * the prototype of this API is:
+ * void *kal_adm_alloc(KAL_ADM_ID adm_id, kal_uint32 size);
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc_with_info kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc(adm_id, size) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#define kal_adm_alloc_dbg(adm_id, size, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, (f), (l))
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_with_info
+ * DESCRIPTION
+ * allocate a memory buffer from ADM, return the actually size (including any ADM overhead) of this memory block also.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * actual_size: [OUT] return the actually size in it.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * the prototype of this API is:
+ * void *kal_adm_alloc_with_info(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 *actual_size);
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_with_info(adm_id, size, actual_size) \
+ __kal_adm_alloc((adm_id), (size), (actual_size), 0x0, __FILE__, __LINE__)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_align
+ * DESCRIPTION
+ * allocate a memory buffer which satisfy the alignment requirement from ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * align: [IN] alignment requirement, which must be a multiple of 4.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * the prototype of this API is:
+ * void *kal_adm_alloc_align(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 alignment);
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_align(adm_id, size, alignment) \
+ __kal_adm_alloc((adm_id), (size), NULL, (alignment) & ~ADM_OPT_MASK, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_align_dbg(adm_id, size, alignment, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, (alignment) & ~ADM_OPT_MASK, (f), (l))
+
+
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define __kal_adm_alloc_cacheable(adm_id, size, option) \
+ __kal_adm_alloc_c((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#define __kal_adm_alloc_cacheable_with_info(adm_id, size, option, actual_size) \
+ __kal_adm_alloc_c((adm_id), (size), (actual_size), 0x0, __FILE__, __LINE__)
+#define __kal_adm_alloc_cacheable_dbg(adm_id, size, option, f, l) \
+ __kal_adm_alloc_c((adm_id), (size), NULL, 0, (f), (l))
+#else
+#define __kal_adm_alloc_cacheable(adm_id, size, option) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#define __kal_adm_alloc_cacheable_with_info(adm_id, size, option, actual_size) \
+ __kal_adm_alloc((adm_id), (size), (actual_size), 0x0, __FILE__, __LINE__)
+#define __kal_adm_alloc_cacheable_dbg(adm_id, size, option, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, (f), (l))
+#endif
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_cacheable
+ * DESCRIPTION
+ * allocate a memory buffer which is cacheable from ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_adm_alloc_cacheable(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused);
+ * (2)The pointer is cacheable only on platform that has ARM MMU (such as ARM9/ARM11 platform).
+ * If not, the pointer is still noncacheable.
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc_cacheable_with_info kal_adm_alloc_noncacheable kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_cacheable(adm_id, size, option_notused) \
+ __kal_adm_alloc_cacheable(adm_id, size, option_notused)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_cacheable_with_info
+ * DESCRIPTION
+ * allocate a memory buffer which is cacheable from ADM, return the actually size (including any ADM overhead) of this memory block also.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * actual_size: [OUT] return the actually size in it.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_adm_alloc_cacheable_with_info(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused, kal_uint32 *actual_size);
+ * (2)The pointer is cacheable only on platform that has ARM MMU (such as ARM9/ARM11 platform).
+ * If not, the pointer is still noncacheable.
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc_cacheable kal_adm_alloc_noncacheable kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_cacheable_with_info(adm_id, size, option_notused, \
+ actual_size) \
+ __kal_adm_alloc_cacheable_with_info(adm_id, size, option_notused, actual_size)
+#define kal_adm_alloc_cacheable_dbg(adm_id, size, option_notused, f, l) \
+ __kal_adm_alloc_cacheable_dbg(adm_id, size, option_notused, f, l)
+
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define __kal_adm_alloc_noncacheable(adm_id, size, option) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#define __kal_adm_alloc_noncacheable_with_info(adm_id, size, option, actual_size) \
+ __kal_adm_alloc_nc((adm_id), (size), (actual_size), 0x0, __FILE__, __LINE__)
+#define __kal_adm_alloc_noncacheable_dbg(adm_id, size, option, f, l) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, 0, (f), (l))
+#else
+#define __kal_adm_alloc_noncacheable(adm_id, size, option) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#define __kal_adm_alloc_noncacheable_with_info(adm_id, size, option, actual_size) \
+ __kal_adm_alloc((adm_id), (size), (actual_size), 0x0, __FILE__, __LINE__)
+#define __kal_adm_alloc_noncacheable_dbg(adm_id, size, option, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, (f), (l))
+#endif
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_noncacheable
+ * DESCRIPTION
+ * allocate a memory buffer which is noncacheable from ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_adm_alloc_noncacheable(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused);
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc_noncacheable_with_info kal_adm_alloc_cacheable kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_noncacheable(adm_id, size, option_notused) \
+ __kal_adm_alloc_noncacheable(adm_id, size, option_notused)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_alloc_noncacheable_with_info
+ * DESCRIPTION
+ * allocate a memory buffer which is noncacheable from ADM, return the actually size (including any ADM overhead) of this memory block also.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * actual_size: [OUT] return the actually size in it.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_adm_alloc_noncacheable_with_info(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused, kal_uint32 *actual_size);
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc_noncacheable kal_adm_alloc_cacheable kal_adm_free
+ ******************************************************************************/
+#define kal_adm_alloc_noncacheable_with_info(adm_id, size, option_notused, \
+ actual_size) \
+ __kal_adm_alloc_noncacheable_with_info(adm_id, size, option_notused, actual_size)
+#define kal_adm_alloc_noncacheable_dbg(adm_id, size, option_notused, f, l) \
+ __kal_adm_alloc_noncacheable_dbg(adm_id, size, option_notused, f, l)
+
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_realloc
+ * DESCRIPTION
+ * re-allocate a memory buffer from ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * ptr: [IN] old memory buffer pointer.
+ * size: [IN] request memory size.
+ * RETURNS
+ * re-allocated memory buffer pointer. return NULL if no memory available.
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_free kal_adm_alloc KAL_ADM_REALLOCFAIL_FATAL_FLAG KAL_ADM_REALLOCFAIL_FREE_FLAG
+ ******************************************************************************/
+#define kal_adm_realloc(adm_id, ptr, size) \
+ __kal_adm_realloc((adm_id), (ptr), (size), NULL, 0, __FILE__, __LINE__)
+#define kal_adm_realloc_dbg(adm_id, ptr, size, f, l) \
+ __kal_adm_realloc((adm_id), (ptr), (size), NULL, 0, (f), (l))
+#if defined(__MTK_TARGET__) && defined(__DYNAMIC_SWITCH_CACHEABILITY__)
+#define __kal_adm_realloc_noncacheable(adm_id, ptr, size) \
+ __kal_adm_realloc_nc((adm_id), (ptr), (size), NULL, 0, __FILE__, __LINE__)
+#define __kal_adm_realloc_cacheable(adm_id, ptr, size) \
+ __kal_adm_realloc_c((adm_id), (ptr), (size), NULL, 0, __FILE__, __LINE__)
+#else
+#define __kal_adm_realloc_noncacheable(adm_id, ptr, size) \
+ kal_adm_realloc(adm_id, ptr, size)
+#define __kal_adm_realloc_cacheable(adm_id, ptr, size) \
+ kal_adm_realloc(adm_id, ptr, size)
+#endif
+
+#define kal_adm_realloc_cacheable(adm_id, ptr, size) \
+ __kal_adm_realloc_cacheable(adm_id, ptr, size)
+#define kal_adm_realloc_noncacheable(adm_id, ptr, size) \
+ __kal_adm_realloc_noncacheable(adm_id, ptr, size)
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_free
+ * DESCRIPTION
+ * free a memory buffer to dedicated ADM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * ptr: [IN] memory buffer pointer to be free. This pointer must be allocated from adm_id.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * kal_adm_create2 kal_adm_alloc kal_adm_realloc
+ ******************************************************************************/
+extern void kal_adm_free(KAL_ADM_ID adm_id, void *ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_get_extheader
+ * DESCRIPTION
+ * get the extensible header associated with ptr, which is immediate before ptr.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * ptr: [IN] memory buffer pointer to query. This pointer must be returned from kal_adm_alloc*() functions.
+ * RETURNS
+ * associated extensible header pointer.
+ * NOTE
+ * (1)This ADM pool must has KAL_ADM_EXTHEADER_FLAG on creation.
+ * (2)The size of this extensible header is (extheader_size_in_word*4)
+ * SEE ALSO
+ * kal_adm_create2 KAL_ADM_EXTHEADER_FLAG
+ ******************************************************************************/
+extern void *kal_adm_get_extheader(KAL_ADM_ID adm_id, void *ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_get_alloc_size
+ * DESCRIPTION
+ * get the allocated memory size.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * ptr: [IN] memory buffer pointer to query. This pointer must be returned from kal_adm_alloc*() functions.
+ * RETURNS
+ * get the allocated memory size.
+ * NOTE
+ * N/A
+ * SEE ALSO
+ *
+ ******************************************************************************/
+extern kal_uint32 kal_adm_get_alloc_size(KAL_ADM_ID adm_id, void *ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_get_max_alloc_size
+ * DESCRIPTION
+ * get maximal available memory size to be allocated in a single kal_adm_alloc*().
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * RETURNS
+ * maximal available memory size to be allocated.
+ * NOTE
+ * (1)This size is guaranteed to allocated without considering any other requirement.
+ * For example, kal_adm_alloc(adm_id, kal_adm_get_max_alloc_size(adm_id)) can succeed.
+ * But kal_adm_alloc_align() is not guaranteed to succeed.
+ * SEE ALSO
+ * kal_adm_get_total_left_size
+ ******************************************************************************/
+extern kal_uint32 kal_adm_get_max_alloc_size(KAL_ADM_ID adm_id);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_get_total_left_size
+ * DESCRIPTION
+ * get total un-allocated memory size.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * RETURNS
+ * get total un-allocated memory size.
+ * NOTE
+ * (1)Total un-allocated memory size may be splitted in many blocks(fragmentation).
+ * SEE ALSO
+ * kal_adm_get_max_alloc_size
+ ******************************************************************************/
+extern kal_uint32 kal_adm_get_total_left_size(KAL_ADM_ID adm_id);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_adm_check_integrity
+ * DESCRIPTION
+ * Check the healthy of ADM pool.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * RETURNS
+ * return bad memory block first found. If the ADM pool is healthy, return NULL to indicate
+ * nothing wrong.
+ ******************************************************************************/
+extern void *kal_adm_check_integrity(KAL_ADM_ID adm_id);
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+extern void kal_adm_print_log(KAL_ADM_ID adm_id);
+extern kal_uint32 kal_adm_calc_worst_alloc_size(KAL_ADM_ID adm_id, kal_uint32 size,
+ kal_uint32 option);
+extern void *kal_adm_get_prev_block_ptr(KAL_ADM_ID adm_id, void *mem_addr);
+extern void *kal_adm_get_next_block_ptr(KAL_ADM_ID adm_id, void *mem_addr);
+extern void *kal_adm_get_trans_ptr(KAL_ADM_ID adm_id, void *mem_addr);
+
+
+/*
+ * Function prototype: void *kal_adm_alloc_mtkL1_cacheable(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option)
+ * Note: Allocate a MTKL1-cacheable memory block.
+ */
+#if defined(__MTK_TARGET__) && defined(__MTK_L1CACHEABLE__)
+#define kal_adm_alloc_mtkL1_cacheable(adm_id, size, option) \
+ __kal_adm_alloc_c((adm_id), (size), NULL, (option), __FILE__, __LINE__)
+#else /* __MTK_TARGET__ && __MTK_L1CACHEABLE__ */
+#define kal_adm_alloc_mtkL1_cacheable(adm_id, size, option) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+#endif /* __MTK_TARGET__ && __MTK_L1CACHEABLE__ */
+
+/*
+ * Function prototype: void *kal_adm_alloc_mtkL1_noncacheable(KAL_ADM_ID adm_id, kal_uint32 option)
+ * Note: Allocate a memory block. This is for RFU only.
+ */
+#define kal_adm_alloc_mtkL1_noncacheable(adm_id, size, option) \
+ __kal_adm_alloc((adm_id), (size), NULL, 0, __FILE__, __LINE__)
+
+/*
+ * Function prototype: void *kal_adm_alloc_nc_align(KAL_ADM_ID adm_id, kal_uint32 align_size)
+ * Note: Allocate a non-cacheable and aligned memory block.
+ */
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define kal_adm_alloc_nc_align(adm_id, size, a) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, (a) & ~ADM_OPT_MASK, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_nc_align_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, (a) & ~ADM_OPT_MASK, (f), (l))
+#else /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__) */
+#define kal_adm_alloc_nc_align(adm_id, size, a) \
+ __kal_adm_alloc((adm_id), (size), NULL, (a) & ~ADM_OPT_MASK, __FILE__, __LINE__)
+#define kal_adm_alloc_nc_align_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, (a) & ~ADM_OPT_MASK, (f), (l))
+#endif /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__) */
+
+/*
+ * Function prototype: void *kal_adm_alloc_topmost(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size)
+ * void *kal_adm_alloc_topmost_dbg(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size, kal_char *filename, kal_uint32 linenumber)
+ * Note: Allocate a memory block from the topmost address of the pool.
+ * The start address of the allocated memory will be aligned to the input parameter align_size.
+ * kal_adm_alloc_topmost_dbg() is the debug verion.
+ * The input parameters filename and line will be used for logging if logging is enabled.
+ */
+#define kal_adm_alloc_topmost(adm_id, size, a) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_topmost_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, (f), (l))
+
+/*
+ * Function prototype: void *kal_adm_alloc_c_topmost(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size)
+ * void *kal_adm_alloc_c_topmost_dbg(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size, kal_char *filename, kal_uint32 line)
+ * Note: Allocate a cacheable memory block from the topmost address of the pool.
+ * The start address of the allocated memory will be aligned to the input parameter align_size.
+ */
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define kal_adm_alloc_c_topmost(adm_id, size, a) \
+ __kal_adm_alloc_c((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_c_topmost_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc_c((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, (f), (l))
+#else /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__)*/
+#define kal_adm_alloc_c_topmost(adm_id, size, a) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_c_topmost_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, (f), (l))
+#endif /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__)*/
+
+/*
+ * Function prototype: void *kal_adm_alloc_nc_topmost(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size)
+ * void *kal_adm_alloc_nc_topmost_dbg(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 align_size, kal_char *filename, kal_uint32 line)
+ * Note: Allocate a non-cacheable memory block from the topmost address of the pool.
+ * The start address of the allocated memory will be aligned to the input parameter align_size.
+ * kal_adm_alloc_nc_topmost_dbg() is the debug version.
+ */
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define kal_adm_alloc_nc_topmost(adm_id, size, a) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_nc_topmost_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc_nc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, (f), (l))
+#else /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__)*/
+#define kal_adm_alloc_nc_topmost(adm_id, size, a) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, __FILE__, \
+ __LINE__)
+#define kal_adm_alloc_nc_topmost_dbg(adm_id, size, a, f, l) \
+ __kal_adm_alloc((adm_id), (size), NULL, \
+ ((a) & ~ADM_OPT_MASK) | ADM_OPT_TOPMOST_ALLOC, (f), (l))
+#endif /* __MTK_TARGET__ && (__ARM9_MMU__ || __DYNAMIC_SWITCH_CACHEABILITY__)*/
+/* DOM-NOT_FOR_SDK-END */
+
+
+/*
+ * AFM Section
+ */
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_create
+ * DESCRIPTION
+ * Create a AFM pool.
+ * PARAMETERS
+ * mem_addr: [IN] starting address of the memory pool. It should be 4-byte alignment, or it will be aligned to next 4-aligned address.
+ * size: [IN] total size in byte of the memory pool.
+ * subpool_size: [IN] is an array, which describe size of each sub-pool.
+ * subpool_nr: [IN] is an array, which describe element count of each sub-pool.
+ * flags: [IN] new AFM pool extra flags, which is a combination of following values
+ * AFM_OPT_ALIGN_ALLOC - user buffers in this AFM is aligned to CPU cache line (32 bytes)
+ * only available on platform which has a ARM MMU (ARM9+ chips).
+ * AFM_OPT_NOFALLBACK_ALLOC - when search avaiable user buffer, don't try to search subpools bigger than fittest subpool.
+ * left_mem: [OUT] get how many memory is not used by this AFM pool and can be used by app freely.
+ * RETURNS
+ * AFM id. If memory is too small to create a AFM, system enters fatal error handling.
+ * NOTE
+ * subpool_size must be monotonic increasing and ends with {0xffffffff, 0}.
+ * subpool_nr must has same elements as subpool_size.
+ * SEE ALSO
+ * kal_afm_delete
+ ******************************************************************************/
+extern KAL_AFM_ID kal_afm_create(void *mem_addr, kal_uint32 size,
+ kal_uint32 *subpool_size, kal_uint32 *subpool_nr,
+ kal_uint32 flags, kal_uint32 *left_mem);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_delete
+ * DESCRIPTION
+ * delete a AFM pool.
+ * PARAMETERS
+ * afm_id: [IN] AFM pool identity.
+ * RETURN VALUES
+ * KAL_SUCCESS: the operation succeeded.
+ * KAL_MEMORY_NOT_RELEASE: some user buffer is not freed yet.
+ * SEE ALSO
+ * kal_afm_create
+ ******************************************************************************/
+extern kal_status kal_afm_delete(KAL_AFM_ID afm_id);
+
+extern void *kal_afm_internal_alloc(KAL_AFM_ID afm_id, kal_uint32 size,
+ kal_uint32 * actual_size,
+ const kal_char *filename, kal_uint32 line);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_alloc
+ * DESCRIPTION
+ * allocate a memory buffer from AFM.
+ * PARAMETERS
+ * afm_id: [IN] AFM pool identity.
+ * size: [IN] request memory size.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * the prototype of this API is:
+ * void *kal_afm_alloc(KAL_AFM_ID afm_id, kal_uint32 size);
+ * SEE ALSO
+ * kal_afm_create kal_afm_free
+ ******************************************************************************/
+#define kal_afm_alloc(afm_id, size) \
+ kal_afm_internal_alloc(afm_id, size, NULL, __FILE__, __LINE__)
+#define kal_afm_alloc_dbg(afm_id, size, actual_size, filename, line) \
+ kal_afm_internal_alloc(afm_id, size, actual_size, filename, line)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_free
+ * DESCRIPTION
+ * free a memory buffer to dedicated AFM.
+ * PARAMETERS
+ * afm_id: [IN] AFM pool identity.
+ * ptr: [IN] memory buffer pointer to be freed. This pointer must be allocated from afm_id.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * kal_afm_create kal_afm_alloc
+ ******************************************************************************/
+extern void kal_afm_free(KAL_AFM_ID afm_id, void *ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_check_integrity
+ * DESCRIPTION
+ * Check the healthy of AFM pool.
+ * PARAMETERS
+ * afm_id: [IN] AFM pool identity.
+ * RETURNS
+ * return bad memory block first found. If the AFM pool is healthy, return NULL to indicate
+ * nothing wrong found.
+ ******************************************************************************/
+extern kal_int32 kal_afm_check_integrity(KAL_AFM_ID afm_id);
+
+extern void *kal_afm_internal_alloc_cacheable(KAL_AFM_ID adm_id, kal_uint32 size,
+ kal_uint32 * actual_size,
+ const kal_char *filename,
+ kal_uint32 line);
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define __kal_afm_alloc_cacheable(afm_id, size, option_notused) \
+ kal_afm_internal_alloc_cacheable(afm_id, size, NULL, __FILE__, __LINE__)
+#define __kal_afm_alloc_cacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ kal_afm_internal_alloc_cacheable(afm_id, size, actual_size, filename, line)
+#else
+#define __kal_afm_alloc_cacheable(afm_id, size, option_notused) \
+ kal_afm_internal_alloc(afm_id, size, NULL, __FILE__, __LINE__)
+#define __kal_afm_alloc_cacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ kal_afm_internal_alloc(afm_id, size, actual_size, filename, line)
+#endif
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_alloc_cacheable
+ * DESCRIPTION
+ * allocate a memory buffer which is cacheable from AFM.
+ * PARAMETERS
+ * afm_id: [IN] AFM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_afm_alloc_cacheable(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused);
+ * (2)This AFM must be created using AFM_OPT_ALIGN_ALLOC in kal_afm_create.
+ * (3)The pointer is cacheable only on platform that has ARM MMU (such as ARM9/ARM11 platform).
+ * If not, the pointer is still noncacheable.
+ * SEE ALSO
+ * kal_afm_create kal_afm_alloc_noncacheable kal_afm_free
+ ******************************************************************************/
+#define kal_afm_alloc_cacheable(afm_id, size, option_notused) \
+ __kal_afm_alloc_cacheable(afm_id, size, option_notused)
+#define kal_afm_alloc_cacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ __kal_afm_alloc_cacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line)
+
+extern void *kal_afm_internal_alloc_noncacheable(KAL_AFM_ID afm_id, kal_uint32 size,
+ kal_uint32 *actual_size,
+ char *filename, kal_uint32 line);
+#if defined(__MTK_TARGET__) && \
+ (defined(__ARM9_MMU__) || defined(__DYNAMIC_SWITCH_CACHEABILITY__))
+#define __kal_afm_alloc_noncacheable(afm_id, size, option_notused) \
+ kal_afm_internal_alloc_noncacheable(afm_id, size, NULL, __FILE__, __LINE__)
+#define __kal_afm_alloc_noncacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ kal_afm_internal_alloc_noncacheable(afm_id, size, actual_size, filename, line)
+#else
+#define __kal_afm_alloc_noncacheable(afm_id, size, option_notused) \
+ kal_afm_internal_alloc(afm_id, size, NULL, __FILE__, __LINE__)
+#define __kal_afm_alloc_noncacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ kal_afm_internal_alloc(afm_id, size, actual_size, filename, line)
+#endif
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_afm_alloc_noncacheable
+ * DESCRIPTION
+ * allocate a memory buffer which is noncacheable from AFM.
+ * PARAMETERS
+ * adm_id: [IN] ADM pool identity.
+ * size: [IN] request memory size.
+ * option_notused: [IN] useless, ignored.
+ * RETURNS
+ * allocated memory buffer pointer. return NULL if no memory available.
+ * NOTE
+ * (1)the prototype of this API is:
+ * void *kal_afm_alloc_noncacheable(KAL_ADM_ID adm_id, kal_uint32 size, kal_uint32 option_notused);
+ * (2)This AFM must be created using AFM_OPT_ALIGN_ALLOC in kal_afm_create.
+ * SEE ALSO
+ * kal_afm_create kal_afm_alloc_cacheable kal_afm_free
+ ******************************************************************************/
+#define kal_afm_alloc_noncacheable(afm_id, size, option_notused) \
+ __kal_afm_alloc_noncacheable(afm_id, size, option_notused)
+#define kal_afm_alloc_noncacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line) \
+ __kal_afm_alloc_noncacheable_dbg(afm_id, size, option_notused, actual_size, \
+ filename, line)
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+extern kal_int32 kal_afm_print_log(KAL_AFM_ID afm_id);
+extern kal_int32 kal_afm_get_subpool_num(KAL_AFM_ID afm_id);
+extern kal_int32 kal_afm_info_get(KAL_AFM_ID afm_id, kal_uint32 *option,
+ kal_uint32 *buff_size, kal_uint32 *buff_nr,
+ kal_uint32 *left_buf_nr,
+ kal_uint32 *total_left_mem_sz);
+extern kal_int32 kal_afm_custom_performance_info_get(
+ KAL_AFM_ID afm_id, kal_uint32 *option, kal_uint32 *buff_size,
+ kal_uint32 *buff_nr, kal_uint32 *alloc_cnt, kal_uint32 *min_left_buf_nr);
+extern kal_int32 kal_afm_set_cuslogging(KAL_AFM_ID afm_id, kal_uint32 cus_log_opt);
+extern kal_int32 kal_afm_get_cuslogging(KAL_AFM_ID afm_id, kal_uint32 *cus_log_opt);
+extern kal_int32 kal_afm_get_left_subpool_num(KAL_AFM_ID afm_id, kal_uint32 size);
+extern kal_uint32 kal_afm_get_buff_size(KAL_AFM_ID afm_id, void *user_addr);
+/* DOM-NOT_FOR_SDK-END */
+
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * Category 7 : System and Modem Memory Management
+ *******************************************************************************/
+extern void *get_ctrl_buffer_ext(kal_uint32 size, const kal_char *file_name,
+ kal_uint32 line);
+extern void free_ctrl_buffer_ext(void *buff_ptr, const kal_char *file_name,
+ kal_uint32 line);
+extern kal_uint32 query_ctrl_buffer_ext(kal_uint32 size);
+
+#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
+#define __get_ctrl_buffer(size) get_ctrl_buffer_ext(size, __FILE__, __LINE__)
+#define __free_ctrl_buffer(ptr) free_ctrl_buffer_ext(ptr, __FILE__, __LINE__)
+#else /* DEBUG_KAL && DEBUG_BUF2 */
+#define __get_ctrl_buffer(size) get_ctrl_buffer_ext(size, NULL, 0)
+#define __free_ctrl_buffer(ptr) free_ctrl_buffer_ext(ptr, NULL, 0)
+#endif /* DEBUG_KAL && DEBUG_BUF2 */
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * get_ctrl_buffer
+ * DESCRIPTION
+ * get a memory block at least size bytes from ctrl buffer.
+ * PARAMETERS
+ * size: [IN] request memory block.
+ * RETURNS
+ * memory block pointer. If all memory blocks used in corresponding ctrl buffer
+ * used up, system enter fatal error handling.
+ * NOTE
+ * (1)This API should be used in protocol stack only.
+ * SEE ALSO
+ * free_ctrl_buffer
+ ******************************************************************************/
+#define get_ctrl_buffer(size) __get_ctrl_buffer(size)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * free_ctrl_buffer
+ * DESCRIPTION
+ * free a memory block allocated from ctrl buffer.
+ * PARAMETERS
+ * ptr: [IN] memory block pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)This API should be used in protocol stack only.
+ * SEE ALSO
+ * get_ctrl_buffer
+ ******************************************************************************/
+#define free_ctrl_buffer(ptr) __free_ctrl_buffer(ptr)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * free_ctrl_buffer_set_null
+ * DESCRIPTION
+ * free a memory block allocated from ctrl buffer. then set pointer as null
+ * PARAMETERS
+ * ptr: [IN] memory block pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)This API should be used in protocol stack only.
+ * SEE ALSO
+ * get_ctrl_buffer
+ ******************************************************************************/
+#define free_ctrl_buffer_set_null(ptr) \
+ do { \
+ __free_ctrl_buffer(ptr); \
+ ptr = NULL; \
+ } while (0)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * query_ctrl_buffer
+ * DESCRIPTION
+ * query the avaiable memory blocks from ctrl buffer
+ * PARAMETERS
+ * size: [IN] request memory block.
+ * RETURNS
+ * the number of avaiable memory blocks
+ * SEE ALSO
+ * get_ctrl_buffer
+ ******************************************************************************/
+#define query_ctrl_buffer(size) query_ctrl_buffer_ext(size)
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_debug_cbs_leakage_check_start
+ * DESCRIPTION
+ * enable control buffer leakage check.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ *
+ ******************************************************************************/
+void kal_debug_cbs_leakage_check_start(void);
+void kal_debug_cbs_leakage_check_stop(void);
+
+extern kal_bool kal_set_sensitive_buff_ext(void *buff_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_set_sensitive_buff
+ * DESCRIPTION
+ * set the buffer as a sensitive data buffer.
+ * PARAMETERS
+ * buff_ptr: [IN] memory block pointer.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ *
+ ******************************************************************************/
+#define kal_set_sensitive_buff(ptr) kal_set_sensitive_buff_ext(ptr)
+
+/* DOM-NOT_FOR_SDK-END */
+/*******************************************************************************
+ * Category 8 : Timer Service
+ *******************************************************************************/
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_systicks
+ * DESCRIPTION
+ * return elapsed system ticks from boot up
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * elapsed system ticks from boot up
+ * NOTE
+ * (1)Each tick is KAL_MILLISECS_PER_TICK miliseconds.
+ * SEE ALSO
+ * KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+extern kal_uint32 kal_get_systicks(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_secs_to_ticks
+ * DESCRIPTION
+ * convert seconds to system ticks
+ * PARAMETERS
+ * secs : [IN] seconds
+ * RETURNS
+ * corresponding system ticks
+ * NOTE
+ * This functions is equvilent to (secs * 1000 / KAL_MILLISECS_PER_TICK).
+ * It uses table lookup to avoid floating division to speed up.
+ * SEE ALSO
+ * kal_milli_secs_to_ticks KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+extern kal_uint32 kal_secs_to_ticks(kal_uint32 secs);
+extern kal_uint32 kal_secs_to_ticks_real(kal_uint32 secs);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_milli_secs_to_ticks
+ * DESCRIPTION
+ * convert milliseconds to system ticks
+ * PARAMETERS
+ * milli_secs : [IN] milliseconds
+ * RETURNS
+ * corresponding system ticks
+ * NOTE
+ * This functions is equvilent to ( ( milli_secs + KAL_MILLISECS_PER_TICK / 2 ) / KAL_MILLISECS_PER_TICK).
+ * It uses table lookup to avoid floating division to speed up.
+ * SEE ALSO
+ * kal_milli_secs_to_ticks KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+extern kal_uint32 kal_milli_secs_to_ticks(kal_uint32 milli_secs);
+extern kal_uint32 kal_milli_secs_to_ticks_real(kal_uint32 milli_secs);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_ticks_to_secs
+ * DESCRIPTION
+ * convert system ticks to seconds
+ * PARAMETERS
+ * ticks : [IN] ticks count
+ * RETURNS
+ * corresponding seconds
+ * NOTE
+ * This functions is equvilent to (ticks * KAL_MILLISECS_PER_TICK / 1000).
+ * It uses table lookup to avoid floating multiplication to speed up.
+ * SEE ALSO
+ * kal_ticks_to_milli_secs KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+extern kal_uint32 kal_ticks_to_secs(kal_uint32 ticks);
+extern kal_uint32 kal_ticks_to_secs_real(kal_uint32 ticks);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_ticks_to_milli_secs
+ * DESCRIPTION
+ * convert system ticks to milliseconds
+ * PARAMETERS
+ * ticks : [IN] ticks count
+ * RETURNS
+ * corresponding milliseconds
+ * NOTE
+ * This functions is equvilent to (ticks * KAL_MILLISECS_PER_TICK).
+ * It uses table lookup to avoid floating multiplication to speed up.
+ * SEE ALSO
+ * kal_ticks_to_secs KAL_MILLISECS_PER_TICK
+ ******************************************************************************/
+extern kal_uint32 kal_ticks_to_milli_secs(kal_uint32 ticks);
+extern kal_uint32 kal_ticks_to_milli_secs_real(kal_uint32 ticks);
+
+/*******************************************************************************
+ * Category 8 : Timer Service
+ *******************************************************************************/
+/*************************************************************************
+ * Exported Function Prototypes for KAL timer
+ *************************************************************************/
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_create_timer
+ * DESCRIPTION
+ * create a kal timer.
+ * PARAMETERS
+ * timer_name : [IN] timer name. It's used for debug only, and only the
+ * first 8 characters retain.
+ * RETURNS
+ * Success: timer pointer.
+ * Error: system enter fatal error handling.
+ * NOTE
+ * (1)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 is created.
+ * (2)kal timer API is not thread safe and it's strongly suggested to use it
+ * in single task/HISR only.
+ * SEE ALSO
+ * kal_set_timer kal_cancel_timer kal_get_remaining_time kal_enable_delayed_timer kal_disable_delayed_timer
+ ******************************************************************************/
+kal_timerid kal_create_timer(kal_char *timer_name);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_set_timer
+ * DESCRIPTION
+ * start a kal timer.
+ * PARAMETERS
+ * timer_ptr : [IN] timer pointer.
+ * handler_func_ptr: [IN] pointer of timeout handler, it will be called after
+ * timeout happens
+ * handler_param_ptr: [IN] user supply argument for handler_func_ptr
+ * delay: [IN] timeout duration in terms of time ticks, the maximum value is 0xFFFFFFFF
+ * reschedule_time: [IN] reset delay to reschedule_time after timeout happens.
+ * If it's zero, no reschedule happens and the timer is one-shot.
+ * Otherwise, it's a periodic timer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * kal_set_timer will cancel previous set timeout event on this timer, and
+ * start a new one.
+ * SEE ALSO
+ * kal_create_timer kal_cancel_timer kal_get_remaining_time kal_enable_delayed_timer kal_disable_delayed_timer
+ ******************************************************************************/
+void kal_set_timer(kal_timerid timer_ptr, kal_timer_func_ptr handler_func_ptr,
+ void *handler_param_ptr, kal_uint32 delay,
+ kal_uint32 reschedule_time);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_cancel_timer
+ * DESCRIPTION
+ * cancel a kal timer.
+ * PARAMETERS
+ * timer_ptr : [IN] timer pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * Please note that canceling timer inside HISR may cancel a timer which is
+ * in expired stage but the callback function not yet been serviced.
+ * SEE ALSO
+ * kal_create_timer kal_set_timer kal_get_remaining_time kal_enable_delayed_timer kal_disable_delayed_timer
+ ******************************************************************************/
+void kal_cancel_timer(kal_timerid timer_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_get_remaining_time
+ * DESCRIPTION
+ * retrieve the remaining timeout period in units of time ticks
+ * PARAMETERS
+ * timer_ptr : [IN] timer pointer.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * kal_create_timer kal_set_timer kal_cancel_timer kal_enable_delayed_timer kal_disable_delayed_timer
+ ******************************************************************************/
+kal_uint32 kal_get_remaining_time(kal_timerid timer_ptr);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_enable_delayed_timer
+ *
+ * DESCRIPTION
+ * This routine implements to set the timer as an aligned timer, the max delay feature will be kept
+ * until kal_disable_delayed_timer() is invoked.
+ * Application Scenario is listed below:
+ * case 1: for target_API = [ kal_sleep_task(), kal_retrieve_eg_events_timeout() ]
+ *
+ * --> status = kal_enable_delayed_timer(NULL, max_delay);
+ *
+ * Attention:
+ * a. the API return value(status) must be checked: KAL_SUCCESS -> success, others -> fail
+ * b. max_delay is in ticks, not ms, if you want to set max delay time to (x ms), you
+ * should use this API like this:
+ * --> status = kal_enable_delayed_timer(NULL, kal_milli_secs_to_ticks(x));
+ *
+ * case 2: for target_API = [ kal_set_timer() ]
+ *
+ * --> status = kal_enable_delayed_timer(TIMER_ID, max_delay);
+ *
+ * Attention:
+ * a. the API return value(status) must be checked: KAL_SUCCESS -> success, others -> fail
+ * b. max_delay is in ticks, not ms, if you want to set max delay time to (x ms), you
+ * should use this API like this:
+ * --> status = kal_enable_delayed_timer(TIMER_ID, kal_milli_secs_to_ticks(x));
+ *
+ * PARAMETERS
+ * ext_timer: Id of the timer
+ * max_delay : max delay ticks
+ * RETURNS
+ * KAL_SUCCESS --> success
+ * KAL_TIMER_NON_TASK_CONTEXT --> invoked illegally in NON-Task context
+ * KAL_TIMER_INVALID_TIMER_ID --> KAL timer ID is invalid
+ * KAL_TIMER_MAX_DELAY_OUT_OF_RANGE --> max delay ticks is out of range
+ * SEE ALSO
+ * kal_create_timer kal_set_timer kal_cancel_timer kal_get_remaining_time kal_disable_delayed_timer
+ ******************************************************************************/
+kal_status kal_enable_delayed_timer(kal_timerid ext_timer, kal_uint32 max_delay);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_disable_delayed_timer
+ *
+ * DESCRIPTION
+ * This routine implements to set the timer as an unaligned timer. normally this API will be used with
+ * kal_enable_delayed_timer together.
+ * Application Scenario is listed below:
+ * case 1: for target_API = [ kal_sleep_task(), kal_retrieve_eg_events_timeout() ]
+ *
+ * status = kal_disable_delayed_timer(NULL);
+ *
+ * case 2: for target_API = [ kal_set_timer() ]
+ *
+ * status = kal_disable_delayed_timer(TIMER_ID);
+ *
+ * Attention:
+ * a. the API return value(status) must be checked: KAL_SUCCESS -> success, others -> fail
+ * b. max delay feature will be kept unchanged if kal_disable_delayed_timer() isn't invoked.
+ *
+ * PARAMETERS
+ * ext_timer: Id of the timer
+ * RETURNS
+ * KAL_SUCCESS --> success
+ * KAL_TIMER_NON_TASK_CONTEXT --> invoked illegally in NON-Task context
+ * SEE ALSO
+ * kal_create_timer kal_set_timer kal_cancel_timer kal_get_remaining_time kal_enable_delayed_timer
+ ******************************************************************************/
+kal_status kal_disable_delayed_timer(kal_timerid ext_timer);
+
+/* DOM-NOT_FOR_SDK-END */
+
+/*************************************************************************
+ * Exported Function Prototypes for event scheduler
+ *************************************************************************/
+
+/*******************************************************************************
+ * <GROUP CallBackFunctions>
+ *
+ * FUNCTION
+ * malloc_fp_t
+ * DESCRIPTION
+ * pointer to a function that can allocation memory like malloc.
+ * PARAMETERS
+ * size: [IN] request memory size in byte.
+ * RETURNS
+ * Successful: memory pointer.
+ * Fail: NULL.
+ ******************************************************************************/
+typedef void *(*malloc_fp_t)(unsigned int size);
+/*******************************************************************************
+ * <GROUP CallBackFunctions>
+ *
+ * FUNCTION
+ * realloc_fp_t
+ * DESCRIPTION
+ * pointer to a function that can re-allocation memory like realloc.
+ * PARAMETERS
+ * ptr: [IN] old pointer.
+ * new_size: [IN] new request memory size in byte.
+ * RETURNS
+ * Successful: memory pointer.
+ * Fail: NULL.
+ ******************************************************************************/
+typedef void *(*realloc_fp_t)(void *ptr, unsigned int new_size);
+/*******************************************************************************
+ * <GROUP CallBackFunctions>
+ *
+ * FUNCTION
+ * free_fp_t
+ * DESCRIPTION
+ * pointer to a function that can free memory like free.
+ * PARAMETERS
+ * ptr: [IN] memory pointer to be free.
+ * RETURNS
+ * N/A
+ ******************************************************************************/
+typedef void (*free_fp_t)(void *ptr);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_create
+ * DESCRIPTION
+ * create a new event scheduler.
+ * PARAMETERS
+ * timer_name: [IN] event scheduler name. it's used for debug only, and only the
+ * first 8 characters retain.
+ * dest_mod_id: [IN] the module this event scheduler belongs to. When event scheduler
+ * timeout happens, system sent timeout message to task of this module.
+ * fuzz: [IN]
+ * Timer inaccuracy in ticks that the event scheduler allow, regardless of sleep mode.
+ * If set, the event may delay or prematurely timeout for maximum fuzz ticks.
+ * If don't like it, just set it to 0.
+ *
+ * Advantage -
+ * Set this argument will save you a lot of CPU resource if the events are frequent and close to each other.
+ *
+ * max_delay_ticks: [IN]
+ * Behaviour -
+ * Time inaccuracy in ticks the event scheduler allow, due to target enters sleep mode.
+ * The event may delay for max max_delay_ticks tick if the target enters sleep mode,
+ * so that the target can sleep longer. The event will suffer no delay if the target doesn't enter sleep mode.
+ *
+ * Advantage -
+ * Set this argument will save the target a lot of power. You are encouraged to set this value for the sake of power.
+ *
+ * Note -
+ * max_delay_ticks = 0 ~ (MAX_DELAY_UNLIMITED - 1) ticks, exact delay ticks
+ * max_delay_ticks = MAX_DELAY_UNLIMITED ticks, won't wake up MCU from sleep (maximum save power).
+ *
+ * RETURNS
+ * Successful: created event scheduler pointer.
+ * Fail: system enter fatal error handling.
+ * NOTE
+ * (1)This API replaces new_evshed(). And new_evshed() is deprecated,
+ * it will be removed from next release.
+ * (2)It is strongly suggested to call this function only at system initialization stage.
+ * and There is no way to free the event schedule data structure once allocated.
+ * (3)Event scheduler is not thread safe, if you want to share it in multi-task/hisr,
+ * please use lock to protect it.
+ * (4)To reduce power consumption, it's strongly suggested to set max_delay_ticks.
+ * (5)The inaccuracy of event scheduler comes from
+ * schedule delay - Time lisr, Time HISR, the owner task may be preempted.
+ * Task handling message delay - There may be many ILMs to handle before the event expired ILM gets handled
+ * fuzz
+ * max_delay_ticks
+ * SEE ALSO
+ * evshed_set_event evshed_cancel_event evshed_timer_handler
+ ******************************************************************************/
+extern event_scheduler *evshed_create(kal_char *timer_name, module_type dest_mod_id,
+ kal_uint32 fuzz,
+ kal_uint32 max_delay_ticks);
+#define HAS_EVSHED_CREATE 1
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_set_index
+ * DESCRIPTION
+ * Set timer_index to distinguish many event schedulers.
+ * The default timer index is 0.
+ * PARAMETERS
+ * es_usr: [IN] event scheduler id returned by evshed_create
+ * timer_index: [IN] timer index given by user
+ * RETURNS
+ * None
+ ******************************************************************************/
+extern void evshed_set_index(event_scheduler *es, kal_uint16 timer_index);
+#define HAS_EVSHED_SET_INDEX 1
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_get_index
+ * DESCRIPTION
+ * Get the index set by evshed_set_index
+ * PARAMETERS
+ * expired_ilm: [IN] The ilm sent by expired event and got from task queue
+ * RETURNS
+ * Sucessful: The timer index of kal_uint32
+ * Fail: Fatal error if wrong ilm input
+ ******************************************************************************/
+extern kal_uint16 evshed_get_index(ilm_struct *expired_ilm);
+#define HAS_EVSHED_GET_INDEX 1
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_set_event
+ * DESCRIPTION
+ * set an event on event scheduler.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * event_hf: [IN] the callback function when event timeout.
+ * event_hf_param: [IN] the user supplied argument for event_hf.
+ * elapse_time: [IN] how many system ticks elapses before this event timeout.
+ * RETURNS
+ * Successful: return set eventid.
+ * Fail: return NULL.
+ * NOTE
+ * System will allocate memory for event id, it will be freed automatically when
+ * a. event is cancelled
+ * b. event expired
+ * It's not allowed to use the event id after above cases.
+ * If the event id is saved, please be careful to reset it.
+ * SEE ALSO
+ * evshed_create evshed_cancel_event evshed_timer_handler
+ ******************************************************************************/
+extern eventid evshed_set_event(event_scheduler *es, kal_timer_func_ptr event_hf,
+ void *event_hf_param, kal_uint32 elapse_time);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_set_event_userid
+ * DESCRIPTION
+ * set an event on event scheduler, and give this event an user id
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * event_hf: [IN] the callback function when event timeout.
+ * event_hf_param: [IN] the user supplied argument for event_hf.
+ * elapse_time: [IN] how many system ticks elapses before this event timeout.
+ * event_user_id: [IN] User can input an id to distinct the events.
+ * RETURNS
+ * Successful: return set eventid.
+ * Fail: return NULL.
+ * NOTE
+ * System will allocate memory for event id, it will be freed automatically when
+ * a. event is cancelled
+ * b. event expired
+ * It's not allowed to use the event id after above cases.
+ * If the event id is saved, please be careful to reset it.
+ * SEE ALSO
+ * evshed_create evshed_cancel_event evshed_timer_handler
+ ******************************************************************************/
+extern eventid evshed_set_event_userid(event_scheduler *es,
+ kal_timer_func_ptr event_hf,
+ void *event_hf_param, kal_uint32 elapse_time,
+ kal_uint32 event_user_id);
+#define HAS_EVSHED_SET_EVENT_USERID 1
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_get_event_userid
+ * DESCRIPTION
+ * Get the user id, inputted in evshed_set_event_userid
+ * PARAMETERS
+ * user_eventid: [IN] eventid returned by evshed_set_event_userid
+ * RETURNS
+ * Successful: returns kal_uint32
+ * Fail: If user_eventid is NULL, fatal error
+ * SEE ALSO
+ * evshed_create evshed_cancel_event evshed_timer_handler
+ ******************************************************************************/
+extern kal_uint32 evshed_get_event_userid(eventid user_eventid);
+#define HAS_EVSHED_GET_EVENT_USERID 1
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_cancel_event
+ * DESCRIPTION
+ * cancel a event on event scheduler.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * eid: [IN,OUT] pointer to event id.
+ * RETURNS
+ * Successful: remain ticks before this event expires.
+ * Fail: -1.
+ * NOTE
+ * (1)system would reset the event ID (eid) to NULL before returning; however,
+ * caller should pay attention to its privately saved event id
+ * SEE ALSO
+ * evshed_create evshed_set_event evshed_timer_handler evshed_delete_all_events
+ ******************************************************************************/
+extern kal_int32 evshed_cancel_event(event_scheduler *es, eventid *eid);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_get_remaining_time
+ * DESCRIPTION
+ * get remain ticks before this event expires.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * eid: [IN] event id.
+ * RETURNS
+ * Successful: remain ticks before this event expires.
+ ******************************************************************************/
+extern kal_uint32 evshed_get_remaining_time(event_scheduler *es, eventid eid);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_delete_all_events
+ * DESCRIPTION
+ * delete and cancel all events on event scheduler.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * evshed_create evshed_set_event evshed_timer_handler evshed_delete_all_events
+ *****************************************************************************/
+extern void evshed_delete_all_events(event_scheduler *es);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_timer_handler
+ * DESCRIPTION
+ * event scheduler main function. It will check all set events status, and call
+ * the callback function if they are expired.
+ *
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1)it's not thread-safe. Don't use in parallel.
+ * (2)If an event is expired, the eventid is freed automatically and don't use it any more.
+ * In evshed_timer_handler(), system would execute event registered timeout callback function.
+ * Caller should reset saved event id in registered timeout callback function,
+ * or cause potential bug to cancel wrong timer event.
+ * SEE ALSO
+ * evshed_create evshed_set_event evshed_cancel_event evshed_delete_all_events
+ *****************************************************************************/
+extern void evshed_timer_handler(event_scheduler *es);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_has_pending_events
+ * DESCRIPTION
+ * query there is any event pending (not yet expired).
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * return KAL_TRUE or KAL_FALSE.
+ * NOTE
+ *****************************************************************************/
+extern kal_bool evshed_has_pending_events(event_scheduler *es);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_suspend_all_events
+ * DESCRIPTION
+ * suspend all of the events set on an event scheduler.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * evshed_resume_all_events
+ *****************************************************************************/
+extern void evshed_suspend_all_events(event_scheduler *es);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_resume_all_events
+ * DESCRIPTION
+ * resume all of the events set on an event scheduler.
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * evshed_suspend_all_events
+ *****************************************************************************/
+extern void evshed_resume_all_events(event_scheduler *es);
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * evshed_enable_protect_property
+ * DESCRIPTION
+ * using mutex to protect the operation of event seheduler to avoid race condition whiler it is
+ * shared by multi-task
+ * PARAMETERS
+ * es: [IN] event scheduler pointer.
+ * RETURNS
+ * N/A
+ * NOTE
+ * (1) Event scheduler is not thread safe, if you want to share it in multi-task,
+ * You can use lock to protect it while using operation of event scheduler.
+ * This API is designed for it. Please call this function after calling evshed_create,
+ * then event scheduler is thread safe without using lock.
+ * (2) If this is called, the "expired" event could not be deleted by evshed_cancel_event()
+ * SEE ALSO
+ * evshed_create
+ *****************************************************************************/
+extern void evshed_enable_protect_property(event_scheduler *es);
+
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * Category 9 : Error Handling
+ *******************************************************************************/
+#include "kal_ex_api.h"
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+
+/*******************************************************************************
+ * Category 10 --- Profiling
+ *******************************************************************************/
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_profile_enable
+ * DESCRIPTION
+ * enable cpu usage profile.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * N/A
+ * SEE ALSO
+ * kal_profile_get_cpu_usage
+ ******************************************************************************/
+void kal_profile_enable(void);
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_profile_get_cpu_usage
+ * DESCRIPTION
+ * get cpu usage percentage, which is a float number at [0.0, 1.0].
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * cpu usage percentage.
+ * SEE ALSO
+ * kal_profile_enable
+ ******************************************************************************/
+float kal_profile_get_cpu_usage(void);
+
+/* DOM-NOT_FOR_SDK-END */
+
+/* DOM-NOT_FOR_SDK-BEGIN */
+/*******************************************************************************
+ * Category 11 : stack sharing
+ *******************************************************************************/
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_lock_current_stack
+ * DESCRIPTION
+ * to lock current stack to avoid sharing its memory with other tasks.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * KAL_SUCCESS.
+ * NOTE
+ * this API is used when KAL_STACK_SHARING is enable,
+ ******************************************************************************/
+extern kal_uint32 kal_lock_current_stack();
+
+/*******************************************************************************
+ * <GROUP Functions>
+ *
+ * FUNCTION
+ * kal_unlock_current_stack
+ * DESCRIPTION
+ * to unlock current task's stack to sharing its memory with other tasks.
+ * PARAMETERS
+ * N/A
+ * RETURNS
+ * KAL_SUCCESS.
+ * NOTE
+ * this API is used when KAL_STACK_SHARING is enable,
+ ******************************************************************************/
+extern kal_uint32 kal_unlock_current_stack();
+
+/*******************************************************************************
+ * Category Last ---
+ *******************************************************************************/
+
+/* DOM-NOT_FOR_SDK-END */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _KAL_PUBLIC_API_H */