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