auto import from //depot/cupcake/@135843
[android/platform/external/neven.git] / Embedded / common / src / b_BasicEm / Context.h
1 /*
2  * Copyright (C) 2008 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #ifndef bbs_CONTEXT_EM_H
18 #define bbs_CONTEXT_EM_H
19
20 /* ---- includes ----------------------------------------------------------- */
21
22 #include "b_BasicEm/Basic.h"
23 #include "b_BasicEm/MemTbl.h"
24 #include "b_BasicEm/DynMemManager.h"
25
26 /* ---- related objects  --------------------------------------------------- */
27
28 struct bbs_Context;
29
30 /* ---- typedefs ----------------------------------------------------------- */
31
32 /** error handler function pointer */
33 typedef void ( *bbs_errorFPtr )( struct bbs_Context* cpA );
34
35 /** callback handler function pointer */
36 typedef uint32 ( *bbs_callbackFPtr )( struct bbs_Context* cpA );
37
38 /* ---- constants ---------------------------------------------------------- */
39
40 #define bbs_CONTEXT_MAX_ERRORS                  8
41 #define bbs_CONTEXT_MAX_MEM_MANAGERS    8
42
43 #ifdef bbs_COMPACT_MESSAGE_HANDLING
44 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
45 #define bbs_ERROR_MAX_FILE_CHARS        24
46 /* characters allocated for text message (minimum 1) */
47 #define bbs_ERROR_MAX_TEXT_CHARS        1
48 #else
49 /* characters allocated for file name string (string is stored rightbound) (minimum 1)*/
50 #define bbs_ERROR_MAX_FILE_CHARS        52
51 /* characters allocated for text message (minimum 1) */
52 #define bbs_ERROR_MAX_TEXT_CHARS        256
53 #endif
54
55 /* defined error codes */
56 #define bbs_ERR_OK                                              0       /* no error condition */
57 #define bbs_ERR_ERROR                                   1       /* generic error */
58 #define bbs_ERR_OUT_OF_MEMORY                   2       /* malloc handler returns with NULL*/
59 #define bbs_ERR_MEMORY_OVERFLOW                 3       /* not enough memory in a segment or no segment */
60 #define bbs_ERR_WRONG_VERSION                   4       /* incompatible version in ..._memRead() */
61 #define bbs_ERR_CORRUPT_DATA                    5       /* corrupt data in ..._memRead()*/
62 #define bbs_ERR_CALLBACK_ERROR                  6       /* a defined error originiating from a callback function */
63
64 /* ---- object definition -------------------------------------------------- */
65
66 /** error object */
67 struct bbs_Error
68 {
69         /* error code */
70         uint32 errorE;
71
72         /* line number */
73         uint32 lineE;
74
75         /* file name */
76         char fileE[ bbs_ERROR_MAX_FILE_CHARS ];
77
78         /* error text */
79         char textE[ bbs_ERROR_MAX_TEXT_CHARS ];
80 };
81
82 /* ------------------------------------------------------------------------- */
83
84 /** context object */
85 struct bbs_Context 
86 {
87
88         /* ---- private data --------------------------------------------------- */
89
90         /** error stack */
91         struct bbs_Error errStackE[ bbs_CONTEXT_MAX_ERRORS ];
92
93         /** error stack index */
94         uint32 errIndexE;
95
96         /** memory table */
97         struct bbs_MemTbl memTblE;
98
99         /** multiple purpose dynamic memory managers */
100         struct bbs_DynMemManager dynMemManagerArrE[ bbs_CONTEXT_MAX_MEM_MANAGERS ];
101
102         /** number of used memory managers */
103         uint32 dynMemManagerArrSizeE;
104
105         /** error function handler */
106         bbs_errorFPtr errorHandlerE;
107
108         /** callback function handler */
109         bbs_callbackFPtr callbackHandlerE;
110
111         /** user-defined pointer */
112         void* userPtrE;
113
114         /* ---- public data ---------------------------------------------------- */
115
116 };
117
118 /* ---- associated objects ------------------------------------------------- */
119
120 /* ---- external functions ------------------------------------------------- */
121
122 /* ---- \ghd{ constructor/destructor } ------------------------------------- */
123
124 /** initializes bbs_Context  */
125 void bbs_Context_init( struct bbs_Context* cpA );
126
127 /** frees bbs_Context  */
128 void bbs_Context_exit( struct bbs_Context* cpA );
129
130 /* ---- \ghd{ operators } -------------------------------------------------- */
131
132 /** copy operator */
133 void bbs_Context_copy( struct bbs_Context* cpA, const struct bbs_Context* srcPtrA );
134
135 /* ---- \ghd{ query functions } -------------------------------------------- */
136
137 /* ---- \ghd{ modify functions } ------------------------------------------- */
138
139 /** composes an error object */
140 struct bbs_Error bbs_Error_create( uint32 errorA, uint32 lineA, const char* fileA, const char* textA, ... );
141
142 /* ---- \ghd{ memory I/O } ------------------------------------------------- */
143
144 /* ---- \ghd{ exec functions } --------------------------------------------- */
145
146 /****** ERROR HANDLING *********/
147
148 /** puts an error onto the error stack (returns false if stack was already full) */
149 flag bbs_Context_pushError( struct bbs_Context* cpA, struct bbs_Error errorA );
150
151 /** takes the last error from stack and returns it (when stack is empty: returns the error at stack position 0)*/
152 struct bbs_Error bbs_Context_popError( struct bbs_Context* cpA );
153
154 /** returns the last error of stack without removing it (when stack is empty: returns the error at stack position 0)*/
155 struct bbs_Error bbs_Context_peekError( struct bbs_Context* cpA );
156
157 /** returns true if the error stack is not empty */
158 flag bbs_Context_error( struct bbs_Context* cpA );
159
160 /** sets error handler; returns pointer to previous error handler 
161  *  Pointer to Error handler can be NULL (->no handler call)
162  *  The error handler is called by function pushError diectly after an error was posted
163  */
164 bbs_errorFPtr bbs_Context_setErrorHandler( struct bbs_Context* cpA,
165                                                                                bbs_errorFPtr errorHandlerA );
166
167 /*******************************/
168
169 /****** CALLBACK HANDLING ******/
170
171 /** call the callback handler, push error if return value is != bbs_ERR_OK */
172 void bbs_Context_doCallback( struct bbs_Context* cpA );
173
174 /** sets callback handler; returns pointer to previous callback handler 
175  *  Pointer to callback handler can be NULL (->no handler call)
176  *  The callback handler is called by function doCallback
177  */
178 bbs_callbackFPtr bbs_Context_setCallbackHandler( struct bbs_Context* cpA,
179                                                                                      bbs_callbackFPtr callbackHandlerA );
180
181 /*******************************/
182
183 /******* MEMORY HANDLING *******/
184
185 /** adds a static memory segment to memory table of context */
186 void bbs_Context_addStaticSeg(  struct bbs_Context* cpA,
187                                                             uint16* memPtrA, /* pointer to memory (32bit aligned)*/
188                                                                 uint32 sizeA,    /* size of memory segment in 16 bit units */
189                                                                 flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
190                                                                 uint32 idA );    /* ID of segment, id=0: unspecified */
191
192 /* adds a dynamic memory segment to memory table of context
193  * Upon destruction of the context object any residual will be freed automatically
194  */
195 void bbs_Context_addDynamicSeg( struct bbs_Context* cpA,
196                                                                 bbs_mallocFPtr mallocFPtrA,     /* function pointer to external mem alloc function (s. comment of type declaration)*/
197                                                                 bbs_freeFPtr freeFPtrA,     /* function pointer to external mem free function */
198                                                                 flag sharedA,    /* Indicates that this segment is to be shared among multiple objects */
199                                                                 uint32 idA );    /* ID of segment, id=0: unspecified */
200
201
202 /** Returns allocated memory in selected exclusive segment in units of 16bits */
203 uint32 bbs_Context_exclAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
204                                                                   
205 /** Returns allocated memory in selected exclusive segment in units of 16bits 
206  *  Note that in case of static memory the return value might not reflect 
207  *  the actually allocated memory amount.
208  */
209 uint32 bbs_Context_shrdAllocSize( struct bbs_Context* cpA, uint32 segIndexA );
210                                                                   
211 /*******************************/
212
213
214 /** quick compact setup for dynamic memory management environment 
215  *  creates an initialized segment with
216  *  - one dynamic exclusive segment
217  *  - one dynamic shared segment
218  *  - error handler (can be NULL)
219  *
220  * Don't forget to call bbs_Context_exit on returned context if it goes out of scope
221  */
222 void bbs_Context_quickInit( struct bbs_Context* cpA, 
223                                                     bbs_mallocFPtr mallocFPtrA, /* function pointer to external mem alloc function (s. comment of type declaration)*/
224                                                     bbs_freeFPtr freeFPtrA,
225                                                     bbs_errorFPtr errorHandlerA );
226
227                           
228 #endif /* bbs_CONTEXT_EM_H */
229