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