Major commit for preparing 1.1.1 release
[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 /*! Character value that marks the end of system input stream. */
28 #define SCT_END_OF_INPUT '\0'
29
30 /*! System information IDs to be used with siQueryAttribute. */
31 typedef enum
32 {
33     /*! Internal marker, not mean to be used. */
34     SCT_SYSINFO_INVALID,
35     /*! Name of the device. */
36     SCT_SYSINFO_DEVICE_TYPE,
37     /*! CPU information (type and speed). */
38     SCT_SYSINFO_CPU,
39     /*! Name of the operating system. */
40     SCT_SYSINFO_OS,
41     /*! Total amount of installed RAM memory (in mega- or gigabytes). */
42     SCT_SYSINFO_RAM_TOTAL,
43     /*! Amount of free RAM memory at the start of benchmarking. */
44     SCT_SYSINFO_RAM_FREE,
45 } SCTSystemAttribute;
46
47 typedef void ( *SCTExtensionProc )( void );
48 typedef int ( *SCTBenchmarkWorkerThreadFunc )( SCTBenchmarkWorkerThreadContext* context );
49
50 #if defined( __cplusplus )
51 extern "C" {
52 #endif  /* defined( __cplusplus ) */
53
54     /*!
55      * Returns the context pointer for common system interface (which can
56      * be NULL on some platforms).
57      *
58      * This function can be used for example to cache the common system
59      * interface context pointer to a local variable. The cached pointer
60      * can then be used with common system interface calls to ensure the
61      * maximum execution speed on all platforms.
62      *
63      * \return Pointer to the internal common system interface context.
64      */
65     void* siCommonGetContext( void );
66
67 /*********************************************************************************
68  * Functions for querying system information.
69  ********************************************************************************/
70
71     /*!
72      * Returns a string describing the requested aspect of the underlying
73      * system.
74      *
75      * \param context Pointer to common system interface context, or NULL
76      * \param name Id of the requested system information
77      *
78      * \return Pointer to a static NULL-terminated string.
79      */
80     const char* siCommonQueryAttribute( void* context, SCTSystemAttribute name );
81     
82     /*!
83      * Retreives the system's timer frequency
84      *
85      * \param context Pointer to common system interface context, or NULL
86      *
87      * \return The system's timer frequency
88      */
89     unsigned long siCommonGetTimerFrequency( void* context );
90
91     /*!
92      * Retreives the current value of the system's timer
93      *
94      * \param context Pointer to common system interface context, or NULL
95      *
96      * \return The current value of the system's timer
97      */
98     unsigned long siCommonGetTimerTick( void* context );
99
100 /********************************************************************************
101  * Information reporting functions.
102  *******************************************************************************/
103
104    /*!
105     * Debug print function. The arguments follow the conventions of a standard c
106     * library printf.
107     *
108     * \param context Pointer to common system interface context, or NULL
109     * \param fmt message format.
110     */
111     void siCommonDebugPrintf( void* context, const char* fmt, ... );
112     
113    /*!
114     * Error callback function.
115     *
116     * \param context Pointer to common system interface context, or NULL
117     * \param errorMessage Error string
118     */
119     void siCommonErrorMessage( void* context, const char* errorMessage );
120
121    /*!
122     * Warning callback function.
123     *
124     * \param context Pointer to common system interface context, or NULL
125     * \param warningMessage Warning string
126     */
127     void siCommonWarningMessage( void* context, const char* warningMessage );
128     
129     /*!
130      * Returns the value of global singleton pointer. The singleton pointer is
131      * used by the SCT core to store globally accessible data. The singleton is
132      * guaranteed to be NULL if it has not been set with siCommonSetSingleton.
133      *
134      * Note: it is possible that this function is relatively inefficient on some
135      * environments, so it is advisable to not call this function or the
136      * functions that use this function where the performance matters. E.g.,
137      * caching should be used in those cases.
138      *
139      * \param context Pointer to the common system interface context, or NULL
140      */
141     void* siCommonGetSingleton( void* context );
142
143     /*!
144      * Sets the value of global singleton pointer. 
145      *
146      * \param context Pointer to the common system interface context, or NULL
147      */
148     void siCommonSetSingleton( void* context, void* ptr );
149
150     /*!
151      * Displays a benchmark running progress message.
152      *
153      * This function is called every time when a new benchmark is
154      * started. The implementation can choose how to display the
155      * information or even completely ignore it.
156      *
157      * \param context Pointer to common system interface context, or NULL
158      * \param totalBenchmarks Total number of benchmarks
159      * \param currentBenchmark Current benchmark number
160      * \param currentBenchmark Current benchmark repeat
161      * \param benchmarkName Current benchmark name
162      */
163     void siCommonProgressMessage( void* context, int totalBenchmark, int currentBenchmark, int currentRepeat, const char* benchmarkName );
164
165     /*!
166      * Function for displaying an assertion message.
167      *
168      * \param context Pointer to common system interface context, or NULL
169      * \param exp Pointer to the assert exression (as a string)
170      * \param file Pointer to the name of the file where the assert failed 
171      * \param line Line number where the assert failed
172      */
173     void siCommonAssert( void* context, void* exp, void* file, unsigned int line );
174
175 /********************************************************************************
176  * Memory management functions
177  *******************************************************************************/
178
179     /*!
180      * Allocates a memory block and clears it (contents are set to zero).
181      * 
182      * \param context Pointer to common system interface context, or NULL
183      * \param size Amount of bytes to allocate
184      * 
185      * \return Pointer to allocated memory block if successful, NULL if
186      * fails
187      */
188 #if defined( SCT_CHECK_LEAKS )
189 # define siCommonMemoryAlloc( context, size ) siCommonMemoryAllocDbg( context, size, __FILE__, __LINE__)
190     void* siCommonMemoryAllocDbg( void* context, unsigned int size, const char* filename, int linenumber );
191 #else   /* defined( SCT_CHECK_LEAKS ) */
192     void* siCommonMemoryAlloc( void* context, unsigned int size );
193 #endif  /* defined( SCT_CHECK_LEAKS ) */
194
195     /*!
196      * Reallocate a memory block. 
197      *
198      * \param context Pointer to common system interface context, or NULL
199      * \param data Pointer to memory block to be reallocated. Must be defined
200      * \param size Amount of bytes to allocate
201      *
202      * \return Pointer to reallocated memory block if successful, or
203      * NULL if failure
204      */
205 #if defined(SCT_CHECK_LEAKS)
206 # define siCommonMemoryRealloc( context, data, size ) siCommonMemoryReallocDbg( context, data, size, __FILE__, __LINE__)
207     void* siCommonMemoryReallocDbg( void* context, void* data, unsigned int size, const char* filename, int linenumber );
208 #else
209     void* siCommonMemoryRealloc( void* context, void* data, unsigned int size );
210 #endif
211
212     /*!
213      * Frees a memory block
214      * 
215      * \param context Pointer to common system interface context, or NULL
216      * \param memblock Previously allocated memory block to be freed
217      */
218     void siCommonMemoryFree( void* context, void* memblock );
219
220 /*********************************************************************************
221  * IO functions.
222  ********************************************************************************/
223
224     /*!
225      * Reads one characted from the system input stream.
226      *
227      * \param context Pointer to common system interface context, or NULL
228      *
229      * \return Character value, which is SCT_END_OF_INPUT when there is not
230      * more data to read.
231      */
232     char siCommonReadChar( void* context );
233
234     /*!
235      * Write one character to the system output stream.
236      *
237      * \param context Pointer to common system interface context, or NULL
238      * \param ch Character to write
239      * 
240      * \return Non-zero if succesful, zero if fails
241      */
242     int siCommonWriteChar( void* context, char ch );    
243
244     /*!
245      * Flush system output stream.
246      *
247      * \param context Pointer to common system interface context, or NULL
248      *
249      * \return Non-zero if succesful, zero if fails
250      */
251     int siCommonFlushOutput( void* context );  
252
253 /*********************************************************************************
254  * Thread functions
255  ********************************************************************************/
256     
257     /*!
258      * Create a benchmark thread and set it running. Implement to return a dummy
259      * object in platforms not supporting multithreading.
260      *
261      * \param context       Pointer to common system interface context, or NULL.
262      * \param func          Benchmark thread function.
263      * \param threadContext Benchmark thread context. The caller retains data ownership.
264      *
265      * \return Platform-specific thread object, or NULL if the function failed.
266      */
267     void* siCommonCreateThread( void* context, SCTBenchmarkWorkerThreadFunc func, SCTBenchmarkWorkerThreadContext* threadContext );
268
269     /*!
270      * Do system specific per-thread cleanup when the calling thread is being
271      * terminated; e.g. call CloseSTDLIB() in Symbian.
272      *
273      * \param context   Pointer to common system interface context, or NULL.
274      *
275      */
276     void siCommonThreadCleanup( void* context );
277     
278     /*!
279      * Wait for a benchmark thread to terminate and release the thread object. 
280      *
281      * \param context   Pointer to common system interface context, or NULL.
282      * \param thread    Pointer to a platform-specific thread object. Must be defined.
283      *
284      */
285     void siCommonJoinThread( void* context, void* thread );
286     
287     /*!
288      * Create mutex. Initially, mutex is unlocked. Implement to return a dummy
289      * object in platforms not supporting multithreading.
290      *
291      * \param context   Pointer to common system interface context, or NULL.
292      *
293      * \return Platform-specific mutex object, or NULL if the function failed.
294      */
295     void* siCommonCreateMutex( void* context );
296
297     /*!
298      * Lock mutex.
299      *
300      * \param context   Pointer to common system interface context, or NULL.
301      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
302      *
303      */
304     void siCommonLockMutex( void* context, void* mutex );
305
306     /*!
307      * Unlock mutex.
308      *
309      * \param context   Pointer to common system interface context, or NULL.
310      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
311      *
312      */
313     void siCommonUnlockMutex( void* context, void* mutex );
314         
315     /*!
316      * Destroy mutex.
317      *
318      * \param context   Pointer to common system interface context, or NULL.
319      * \param mutex     Pointer to a platform-specific mutex object. Must be defined.     
320      *
321      */
322     void siCommonDestroyMutex( void* context, void* mutex );
323
324     /*!
325      * Create signal. Initially, signal is not triggered, i.e. wait for signal
326      * will block. Implement to return a dummy object in platforms not
327      * supporting multithreading.
328      *
329      * \param context   Pointer to common system interface context, or NULL.
330      *
331      * \return Platform-specific signal object, or NULL if the function failed.
332      */
333     void* siCommonCreateSignal( void* context );
334
335     /*!
336      * Wait for signal.
337      *
338      * \param context        Pointer to common system interface context, or NULL.
339      * \param signal         Pointer to a platform-specific signal object. Must be defined.
340      * \param timeoutMillis  Timeout for wait, in milliseconds. Use infinite timeout if zero.
341      *
342      * \return Return 1 when signal received ok, 0 if timeout occurred, -1 if
343      * wait was aborted from external thread, or if the signal is disabled.
344      */
345     int siCommonWaitForSignal( void* context, void* signal, long timeoutMillis );
346
347     /*!
348      * Disable signal. Wake up all threads waiting on the signal so that
349      * siCommonWaitForSignal returns -1. Signal is disabled after the call, all
350      * waits return immediately with -1.
351      *
352      * \param context   Pointer to common system interface context, or NULL.
353      * \param signal    Pointer to a platform-specific signal object. Must be defined.
354      *
355      */
356     void siCommonDisableSignal( void* context, void* signal );
357
358     /*!
359      * Enable signal. Signal is be enabled after the call.
360      *
361      * \param context   Pointer to common system interface context, or NULL.
362      * \param signal    Pointer to a platform-specific signal object. Must be defined.
363      *
364      */
365     void siCommonEnableSignal( void* context, void* signal );
366     
367     /*!
368      * Trigger signal. Set signal as triggered, releasing a single thread
369      * waiting for the signal. Ignored for disabled signals.
370      *
371      * \param context   Pointer to common system interface context, or NULL.
372      * \param signal    Pointer to a platform-specific signal object. Must be defined.
373      *
374      */
375     void siCommonTriggerSignal( void* context, void* signal );
376     
377     /*!
378      * Destroy signal.
379      *
380      * \param context   Pointer to common system interface context, or NULL.
381      * \param signal    Pointer to a platform-specific signal object. Must be defined.     
382      *
383      */
384     void siCommonDestroySignal( void* context, void* signal );    
385     
386 /*********************************************************************************
387  * Other functions
388  ********************************************************************************/
389
390     /*!
391      * Get a list of modules supported by the current system
392      * configuration. Caller must destroy the module list.
393      *
394      * \param context Pointer to common system interface context, or NULL.
395      *
396      * \return List of modules, or NULL if failure.
397      *
398      */
399     SCTModuleList* siCommonGetModules( void* context );
400
401     /*!
402      * Sleep specified amount of time.
403      *
404      * \param context Pointer to common system interface context, or NULL
405      * \param micros Microseconds to sleep
406      *
407      */
408     void siCommonSleep( void* context, int micros );
409
410     /*!
411      * Yield for other processes for example in long running loops.
412      *
413      * \param context Pointer to common system interface context, or NULL
414      */
415     void siCommonYield( void* context );
416
417     /*!
418      * Get time. Time string is returned in yyyy-mm-dd hh:mm:ss
419      * format.
420      *
421      * \param context Pointer to common system interface context, or NULL.
422      * \param buffer Time string buffer.
423      * \param length Length of the time string buffer.
424      */
425     void siCommonGetTime( void* context, char* buffer, int length );
426
427     /*!
428      * Get the address of a named function.
429      *
430      * \param context Pointer to common system interface context, or NULL.
431      * \param procname Function name. Must be defined.
432      *
433      * \return Address to function, or null if no such function exists.
434      */
435     SCTExtensionProc siCommonGetProcAddress( void* context, const char* procname );
436
437 #if defined( __cplusplus )
438 }
439 #endif /* defined( __cplusplus ) */
440
441 #endif /* !defined( __SCT_SISYSTEM_H__ ) */