Added LogMessage@Test; added siCommonGetMessage function to sicommon interface
[spandex:spandex.git] / sct / common / include / sct_sicommon.h
1 /*
2  * Spandex benchmark and test framework.
3  *
4  * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
5  *
6  * Contact: Kari J. Kangas <kari.j.kangas@nokia.com>
7  *
8  *   This framework is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by the
10  * Free Software Foundation, version 2.1 of the License.
11  *
12  *   This framework is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
15  * for more details.
16  *
17  *   You should have received a copy of the GNU Lesser General Public License
18  * along with this framework; if not, see <http://www.gnu.org/licenses/>.
19  *
20  */
21
22 #if !defined( __SCT_SISYSTEM_H__ )
23 #define __SCT_SISYSTEM_H__
24
25 #include "sct_types.h"
26
27 #include <stddef.h>
28
29 /*!
30  * Character value that marks the end of system input stream.
31  *
32  */
33 #define SCT_END_OF_INPUT '\0'
34
35 /*!
36  * System string IDs to be used with siQuerySystemString.
37  *
38  */
39 typedef enum
40 {
41     /*! Internal marker, not mean to be used. */
42     SCT_SYSSTRING_INVALID,
43     /*! Name of the device. */
44     SCT_SYSSTRING_DEVICE_TYPE,
45     /*! CPU information (type and speed). */
46     SCT_SYSSTRING_CPU,
47     /*! Name of the operating system. */
48     SCT_SYSSTRING_OS,
49 } SCTSystemString;
50
51 /*!
52  * Memory attribute IDs to be used with siQueryMemoryAttribute. Note that
53  * querying the graphics memory attributes might have a dependency to underlying
54  * graphics system. For example, in a system supporting EGL, you might be able
55  * to query the correct attribute values only when EGL has been initialized for
56  * the calling thread.
57  *
58  */
59 typedef enum
60 {
61     /*! Internal marker, not mean to be used. */
62     SCT_MEMATTRIB_INVALID,
63     /*! Total amount of installed system RAM memory, in bytes. */
64     SCT_MEMATTRIB_TOTAL_SYSTEM_MEMORY,
65     /*! Amount of free system RAM memory, in bytes. */
66     SCT_MEMATTRIB_USED_SYSTEM_MEMORY,
67     /*! Total amount of installed graphics memory, in bytes. */
68     SCT_MEMATTRIB_TOTAL_GRAPHICS_MEMORY,
69     /*! Amount of free graphics memory, in bytes. */
70     SCT_MEMATTRIB_USED_GRAPHICS_MEMORY,
71     /*! Amount of used private graphics memory, in bytes. */
72     SCT_MEMATTRIB_USED_PRIVATE_GRAPHICS_MEMORY,
73     /*! Amount of used shared graphics memory, in bytes. */
74     SCT_MEMATTRIB_USED_SHARED_GRAPHICS_MEMORY,
75 } SCTMemoryAttribute;
76
77 /*!
78  * Thread priorities.
79  *
80  */
81 typedef enum
82 {
83     SCT_THREAD_PRIORITY_LOW,        
84     SCT_THREAD_PRIORITY_NORMAL,
85     SCT_THREAD_PRIORITY_HIGH,    
86 } SCTThreadPriority;
87
88 typedef void ( *SCTExtensionProc )( void );
89 typedef int ( *SCTBenchmarkWorkerThreadFunc )( SCTBenchmarkWorkerThreadContext* context );
90
91 #if defined( __cplusplus )
92 extern "C" {
93 #endif  /* defined( __cplusplus ) */
94
95     /*!
96      * Returns the context pointer for common system interface (which can
97      * be NULL on some platforms).
98      *
99      * This function can be used for example to cache the common system
100      * interface context pointer to a local variable. The cached pointer
101      * can then be used with common system interface calls to ensure the
102      * maximum execution speed on all platforms.
103      *
104      * \return Pointer to the internal common system interface context.
105      */
106     void* siCommonGetContext( void );
107
108     /*********************************************************************************
109      * Functions for querying system information.
110      ********************************************************************************/
111
112     /*!
113      * Returns a string describing the requested aspect of the underlying
114      * system.
115      *
116      * \param context   Pointer to common system interface context, or NULL.
117      * \param name      Id of the requested string.
118      *
119      * \return Pointer to a static NULL-terminated string.
120      */
121     const char* siCommonQuerySystemString( void* context, SCTSystemString name );
122
123     /*!
124      * Returns a size_t describing the requested aspect of the underlying
125      * memory system.
126      *
127      * \param context   Pointer to common system interface context, or NULL.
128      * \param name      Id of the requested memory attribute.
129      *
130      * \return Memory attribute value as size_t.
131      */
132     size_t siCommonQueryMemoryAttribute( void* context, SCTMemoryAttribute name );
133     
134     /*!
135      * Retreives the system's timer frequency.
136      *
137      * \param context Pointer to common system interface context, or NULL.
138      *
139      * \return The system's timer frequency.
140      */
141     unsigned long siCommonGetTimerFrequency( void* context );
142
143     /*!
144      * Retreives the current value of the system's timer.
145      *
146      * \param context Pointer to common system interface context, or NULL.
147      *
148      * \return The current value of the system's timer.
149      */
150     unsigned long siCommonGetTimerTick( void* context );
151
152     /********************************************************************************
153      * Information reporting functions.
154      *******************************************************************************/
155
156     /*!
157      * Debug print function. The arguments follow the conventions of a standard c
158      * library printf.
159      *
160      * \param context Pointer to common system interface context, or NULL
161      * \param fmt message format.
162      */
163     void siCommonDebugPrintf( void* context, const char* fmt, ... );
164     
165     /*!
166      * Error callback function.
167      *
168      * \param context Pointer to common system interface context, or NULL
169      * \param errorMessage Error string.
170      */
171     void siCommonErrorMessage( void* context, const char* errorMessage );
172     
173     /*!
174      * Warning callback function.
175      *
176      * \param context Pointer to common system interface context, or NULL.
177      * \param warningMessage Warning string.
178      */
179     void siCommonWarningMessage( void* context, const char* warningMessage );
180     
181     /*!
182      * Returns the value of global singleton pointer. The singleton pointer is
183      * used by the SCT core to store globally accessible data. The singleton is
184      * guaranteed to be NULL if it has not been set with siCommonSetSingleton.
185      *
186      * Note: it is possible that this function is relatively inefficient on some
187      * environments, so it is advisable to not call this function or the
188      * functions that use this function where the performance matters. E.g.,
189      * caching should be used in those cases.
190      *
191      * \param context Pointer to the common system interface context, or NULL.
192      */
193     void* siCommonGetSingleton( void* context );
194
195     /*!
196      * Sets the value of global singleton pointer. 
197      *
198      * \param context Pointer to the common system interface context, or NULL.
199      */
200     void siCommonSetSingleton( void* context, void* ptr );
201
202     /*!
203      * Displays a benchmark running progress message.
204      *
205      * This function is called every time when a new benchmark is
206      * started. The implementation can choose how to display the
207      * information or even completely ignore it.
208      *
209      * \param context Pointer to common system interface context, or NULL.
210      * \param totalBenchmarks Total number of benchmarks.
211      * \param currentBenchmark Current benchmark number.
212      * \param currentBenchmark Current benchmark repeat, 0 means benchmark initialization.
213      * \param benchmarkName Current benchmark name.
214      */
215     void siCommonProgressMessage( void* context, int totalBenchmark, int currentBenchmark, int currentRepeat, const char* benchmarkName );
216
217     /*!
218      * Function for displaying an assertion message.
219      *
220      * \param context Pointer to common system interface context, or NULL.
221      * \param exp Pointer to the assert exression (as a string).
222      * \param file Pointer to the name of the file where the assert failed .
223      * \param line Line number where the assert failed.
224      */
225     void siCommonAssert( void* context, void* exp, void* file, unsigned int line );
226
227     /********************************************************************************
228      * Memory management functions
229      *******************************************************************************/
230
231     /*!
232      * Allocates a memory block and clears it (contents are set to zero).
233      * 
234      * \param context Pointer to common system interface context, or NULL.
235      * \param size Amount of bytes to allocate.
236      * 
237      * \return Pointer to allocated memory block if successful, NULL if
238      * fails.
239      */
240 #if defined( SCT_CHECK_LEAKS )
241 # define siCommonMemoryAlloc( context, size ) siCommonMemoryAllocDbg( context, size, __FILE__, __LINE__)
242     void* siCommonMemoryAllocDbg( void* context, unsigned int size, const char* filename, int linenumber );
243 #else   /* defined( SCT_CHECK_LEAKS ) */
244     void* siCommonMemoryAlloc( void* context, unsigned int size );
245 #endif  /* defined( SCT_CHECK_LEAKS ) */
246
247     /*!
248      * Reallocate a memory block. 
249      *
250      * \param context Pointer to common system interface context, or NULL.
251      * \param data Pointer to memory block to be reallocated. Must be defined.
252      * \param size Amount of bytes to allocate.
253      *
254      * \return Pointer to reallocated memory block if successful, or
255      * NULL if failure.
256      */
257 #if defined(SCT_CHECK_LEAKS)
258 # define siCommonMemoryRealloc( context, data, size ) siCommonMemoryReallocDbg( context, data, size, __FILE__, __LINE__)
259     void* siCommonMemoryReallocDbg( void* context, void* data, unsigned int size, const char* filename, int linenumber );
260 #else
261     void* siCommonMemoryRealloc( void* context, void* data, unsigned int size );
262 #endif
263
264     /*!
265      * Frees a memory block.
266      * 
267      * \param context Pointer to common system interface context, or NULL.
268      * \param memblock Previously allocated memory block to be freed.
269      */
270     void siCommonMemoryFree( void* context, void* memblock );
271
272     /*********************************************************************************
273      * IO functions.
274      ********************************************************************************/
275
276     /*!
277      * Reads one characted from the system input stream.
278      *
279      * \param context Pointer to common system interface context, or NULL.
280      *
281      * \return Character value, which is SCT_END_OF_INPUT when there is not
282      * more data to read.
283      */
284     char siCommonReadChar( void* context );
285
286     /*!
287      * Write one character to the system output stream.
288      *
289      * \param context Pointer to common system interface context, or NULL.
290      * \param ch Character to write.
291      * 
292      * \return Non-zero if succesful, zero if fails.
293      */
294     int siCommonWriteChar( void* context, char ch );    
295
296     /*!
297      * Flush system output stream.
298      *
299      * \param context Pointer to common system interface context, or NULL.
300      *
301      * \return Non-zero if succesful, zero if fails.
302      */
303     int siCommonFlushOutput( void* context );  
304
305     /*********************************************************************************
306      * Thread functions
307      ********************************************************************************/
308     
309     /*!
310      * Create a benchmark thread and set it running. Implement to return a dummy
311      * object in platforms not supporting multithreading.
312      *
313      * \param context       Pointer to common system interface context, or NULL.
314      * \param func          Benchmark thread function.
315      * \param threadContext Benchmark thread context. The caller retains data ownership.
316      *
317      * \return Platform-specific thread object, or NULL if the function failed.
318      */
319     void* siCommonCreateThread( void* context, SCTBenchmarkWorkerThreadFunc func, SCTBenchmarkWorkerThreadContext* threadContext );
320
321     /*!
322      * Do system specific per-thread cleanup when the calling thread is being
323      * terminated; e.g. call CloseSTDLIB() in Symbian.
324      *
325      * \param context   Pointer to common system interface context, or NULL.
326      *
327      */
328     void siCommonThreadCleanup( void* context );
329     
330     /*!
331      * Wait for a benchmark thread to terminate and release the thread object. 
332      *
333      * \param context   Pointer to common system interface context, or NULL.
334      * \param thread    Pointer to a platform-specific thread object. Must be defined.
335      *
336      */
337     void siCommonJoinThread( void* context, void* thread );
338
339     /*!
340      * Set thread priority.
341      *
342      * \param context   Pointer to common system interface context, or NULL.
343      * \param priority  Thread priority.
344      *
345      * \return SCT_TRUE if success, SCT_FALSE if failure.
346      */
347     SCTBoolean siCommonSetThreadPriority( void* context, SCTThreadPriority priority );
348     
349     /*!
350      * Create mutex. Initially, mutex is unlocked. Implement to return a dummy
351      * object in platforms not supporting multithreading.
352      *
353      * \param context   Pointer to common system interface context, or NULL.
354      *
355      * \return Platform-specific mutex object, or NULL if the function failed.
356      */
357     void* siCommonCreateMutex( void* context );
358
359     /*!
360      * Lock mutex.
361      *
362      * \param context   Pointer to common system interface context, or NULL.
363      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
364      *
365      */
366     void siCommonLockMutex( void* context, void* mutex );
367
368     /*!
369      * Unlock mutex.
370      *
371      * \param context   Pointer to common system interface context, or NULL.
372      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
373      *
374      */
375     void siCommonUnlockMutex( void* context, void* mutex );
376         
377     /*!
378      * Destroy mutex.
379      *
380      * \param context   Pointer to common system interface context, or NULL.
381      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
382      *
383      */
384     void siCommonDestroyMutex( void* context, void* mutex );
385
386     /*!
387      * Create signal. Initially, signal is not triggered, i.e. wait for signal
388      * will block. Note that the thread module signals might be created and
389      * destroyed several times per benchmark to prevent signal state
390      * leaking. Implement to return a dummy object in platforms not supporting
391      * multithreading.
392      *
393      * \param context   Pointer to common system interface context, or NULL.
394      *
395      * \return Platform-specific signal object, or NULL if the function failed.
396      */
397     void* siCommonCreateSignal( void* context );
398
399     /*!
400      * Destroy signal.
401      *
402      * \param context   Pointer to common system interface context, or NULL.
403      * \param signal    Pointer to a platform-specific signal object. Must be defined.     
404      *
405      */
406     void siCommonDestroySignal( void* context, void* signal );    
407     
408     /*!
409      * Wait for signal.
410      *
411      * \param context        Pointer to common system interface context, or NULL.
412      * \param signal         Pointer to a platform-specific signal object. Must be defined.
413      * \param timeoutMillis  Timeout for wait, in milliseconds. Use infinite timeout if zero.
414      *
415      * \return Return 1 when signal received ok, 0 if timeout occurred, -1 if
416      * wait was aborted from external thread, or if the signal is disabled.
417      */
418     int siCommonWaitForSignal( void* context, void* signal, long timeoutMillis );
419
420     /*!
421      * Trigger signal. Set signal as triggered, releasing a single thread
422      * waiting for the signal. Ignored for disabled signals.
423      *
424      * \param context   Pointer to common system interface context, or NULL.
425      * \param signal    Pointer to a platform-specific signal object. Must be defined.
426      *
427      */
428     void siCommonTriggerSignal( void* context, void* signal );   
429     
430     /*!
431      * Cancel a signal. Wake up all threads waiting on the signal so that
432      * siCommonWaitForSignal returns -1. Signal is disabled after the call, all
433      * waits return immediately with -1.
434      *
435      * \param context   Pointer to common system interface context, or NULL.
436      * \param signal    Pointer to a platform-specific signal object. Must be defined.
437      *
438      */
439     void siCommonCancelSignal( void* context, void* signal );
440     
441     /*********************************************************************************
442      * Other functions
443      ********************************************************************************/
444
445     /*!
446      * Get a list of modules supported by the current system
447      * configuration. Caller must destroy the module list.
448      *
449      * \param context Pointer to common system interface context, or NULL.
450      *
451      * \return List of modules, or NULL if failure.
452      *
453      */
454     SCTModuleList* siCommonGetModules( void* context );
455
456     /*!
457      * Sleep specified amount of time.
458      *
459      * \param context Pointer to common system interface context, or NULL
460      * \param micros Microseconds to sleep
461      *
462      */
463     void siCommonSleep( void* context, unsigned long micros );
464
465     /*!
466      * Yield for other processes for example in long running loops.
467      *
468      * \param context Pointer to common system interface context, or NULL
469      */
470     void siCommonYield( void* context );
471
472     /*!
473      * Get time. Time string is returned in yyyy-mm-dd hh:mm:ss
474      * format.
475      *
476      * \param context Pointer to common system interface context, or NULL.
477      * \param buffer Time string buffer.
478      * \param length Length of the time string buffer.
479      */
480     void siCommonGetTime( void* context, char* buffer, int length );
481
482     /*!
483      * Get the address of a named function.
484      *
485      * \param context Pointer to common system interface context, or NULL.
486      * \param procname Function name. Must be defined.
487      *
488      * \return Address to function, or null if no such function exists.
489      */
490     SCTExtensionProc siCommonGetProcAddress( void* context, const char* procname );
491
492     /*!
493      * Get pending message.
494      *
495      * \param context       Pointer to common system interface context, or NULL.
496      * \param message       Pointer to a struct used to store the message. Must be defined.
497      * \param timeoutMillis Timeout for wait, in milliseconds. Use infinite timeout if zero.
498      *
499      * \return Return 1 when message received ok, 0 if timeout occurred, -1 if
500      * message receive failed. Message is not modified in case of timeout or failure.
501      */
502     int siCommonGetMessage( void* context, SCTMessage* message, long timeoutMillis );
503
504 #if defined( __cplusplus )
505 }
506 #endif /* defined( __cplusplus ) */
507
508 #endif /* !defined( __SCT_SISYSTEM_H__ ) */