1 /****************************************************************************** 2 * 3 * Copyright (C) 2014 The Android Open Source Project 4 * Copyright 2002 - 2004 Open Interface North America, Inc. All rights reserved. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at: 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 ******************************************************************************/ 19 #ifndef _OI_OSINTERFACE_H 20 #define _OI_OSINTERFACE_H 21 /** 22 @file 23 * This file provides the platform-independent interface for functions for which 24 * implementation is platform-specific. 25 * 26 * The functions in this header file define the operating system or hardware 27 * services needed by the BLUEmagic 3.0 protocol stack. The 28 * actual implementation of these services is platform-dependent. 29 * 30 */ 31 32 /********************************************************************************** 33 $Revision: #1 $ 34 ***********************************************************************************/ 35 36 #include "oi_stddefs.h" 37 #include "oi_time.h" 38 #include "oi_status.h" 39 #include "oi_modules.h" 40 41 /** \addtogroup Misc Miscellaneous APIs */ 42 /**@{*/ 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 49 /** 50 * Terminates execution. 51 * 52 * @param reason Reason for termination 53 */ 54 void OI_FatalError(OI_STATUS reason); 55 56 /** 57 * This function logs an error. 58 * 59 * When built for release mode, BLUEmagic 3 errors are logged to 60 * this function. (in debug mode, errors are logged via 61 * OI_Print()). 62 * 63 * @param module Module in which the error was detected (see 64 * oi_modules.h) 65 * @param lineno Line number of the C file OI_SLOG_ERROR called 66 * @param status Status code associated with the error event 67 */ 68 void OI_LogError(OI_MODULE module, OI_INT lineno, OI_STATUS status); 69 70 /** 71 * This function initializes the debug code handling. 72 * 73 * When built for debug mode, this function performs platform 74 * dependent initialization to handle message codes passed in 75 * via OI_SetMsgCode(). 76 */ 77 void OI_InitDebugCodeHandler(void); 78 79 80 /** 81 * This function reads the time from the real time clock. 82 * 83 * All timing in BM3 is relative, typically a granularity 84 * of 5 or 10 msecs is adequate. 85 * 86 * @param[out] now Pointer to the buffer to which the current 87 * time will be returned 88 */ 89 void OI_Time_Now(OI_TIME *now); 90 91 /** 92 * This function causes the current thread to sleep for the 93 * specified amount of time. This function must be called 94 * without the stack access token. 95 * 96 * @note BM3 corestack and profiles never suspend and never call 97 * OI_Sleep. The use of OI_Sleep is limited to applications and 98 * platform-specific code. 99 * 100 * If your port and applications never use OI_Sleep, this function can be left unimplemented. 101 * 102 * @param milliseconds Number of milliseconds to sleep 103 */ 104 void OI_Sleep(OI_UINT32 milliseconds); 105 106 107 /** 108 * Defines for message type codes. 109 */ 110 #define OI_MSG_CODE_APPLICATION 0 /**< Application output */ 111 #define OI_MSG_CODE_ERROR 1 /**< Error message output */ 112 #define OI_MSG_CODE_WARNING 2 /**< Warning message output */ 113 #define OI_MSG_CODE_TRACE 3 /**< User API function trace output */ 114 #define OI_MSG_CODE_PRINT1 4 /**< Catagory 1 debug print output */ 115 #define OI_MSG_CODE_PRINT2 5 /**< Catagory 2 debug print output */ 116 #define OI_MSG_CODE_HEADER 6 /**< Error/Debug output header */ 117 118 /** 119 * This function is used to indicate the type of text being output with 120 * OI_Print(). For the Linux and Win32 platforms, it will set 121 * the color of the text. Other possible uses could be to insert 122 * HTML style tags, add some other message type indication, or 123 * be completely ignored altogether. 124 * 125 * @param code OI_MSG_CODE_* indicating setting the message type. 126 */ 127 void OI_SetMsgCode(OI_UINT8 code); 128 129 /** 130 * All output from OI_Printf() and all debug output is sent to OI_Print. 131 * Typically, if the platform has a console, OI_Print() is sent to stdout. 132 * Embedded platforms typically send OI_Print() output to a serial port. 133 * 134 * @param str String to print 135 */ 136 void OI_Print(OI_CHAR const *str); 137 138 /** 139 * In cases where OI_Print() is sending output to a logfile in addition to console, 140 * it is desirable to also put console input into the logfile. 141 * This function can be called by the console input process. 142 * 143 * @note This is an optional API which is strictly 144 * between the platform-specific stack_console and osinterface 145 * modules. This API need only be implemented on those 146 * platforms where is serves a useful purpose, e.g., win32. 147 * 148 * @param str Console input string 149 */ 150 151 void OI_Print_ConsoleInput(OI_CHAR const *str); 152 153 /** 154 * This function computes the CRC16 of the program image. 155 */ 156 OI_UINT16 OI_ProgramImageCRC16(void); 157 158 /** 159 * Writes an integer to stdout in hex. This macro is intended 160 * for selective use when debugging in small memory 161 * configurations or other times when it is not possible to use 162 * OI_DBGPRINT. 163 * 164 * @param n the integer to print 165 */ 166 167 #define OI_Print_Int(n) \ 168 { \ 169 static const OI_CHAR _digits[] = "0123456789ABCDEF"; \ 170 OI_CHAR _buf[9]; \ 171 OI_CHAR *_str = &_buf[8]; \ 172 OI_UINT32 _i = n; \ 173 *_str = 0; \ 174 do { *(--_str) = _digits[(_i & 0xF)]; _i >>= 4; } while (_i); \ 175 OI_Print(_str); \ 176 } 177 178 /** 179 * Application Dynamic Memory allocation. 180 * 181 * These APIs are provided for application use on those 182 * platforms which have no dynamic memory support. Memory is 183 * allocated from the pool-based heap managed by the stack's 184 * internal memory manager. 185 */ 186 void *OI_APP_Malloc(OI_INT32 size); 187 void OI_APP_Free(void *ptr); 188 189 /*****************************************************************************/ 190 #ifdef __cplusplus 191 } 192 #endif 193 194 /**@}*/ 195 196 #endif /* _OI_OSINTERFACE_H */ 197 198