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
45extern "C" {
46#endif
47
48
49/**
50 * Terminates execution.
51 *
52 * @param reason  Reason for termination
53 */
54void 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 */
68void 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 */
77void 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 */
89void 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 */
104void 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 */
127void 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 */
136void 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
151void OI_Print_ConsoleInput(OI_CHAR const *str);
152
153/**
154 *  This function computes the CRC16 of the program image.
155 */
156OI_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 */
186void *OI_APP_Malloc(OI_INT32 size);
187void OI_APP_Free(void *ptr);
188
189/*****************************************************************************/
190#ifdef __cplusplus
191}
192#endif
193
194/**@}*/
195
196#endif /* _OI_OSINTERFACE_H */
197
198