1/*
2 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
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 * @file picoos.h
18 *
19 * Copyright (C) 2008-2009 SVOX AG, Baslerstr. 30, 8048 Zuerich, Switzerland
20 * All rights reserved.
21 *
22 * History:
23 * - 2009-04-20 -- initial version
24 *
25 */
26/**
27 * @addtogroup picoos
28
29 * <b> Operating system generalization module </b>\n
30 *
31*/
32
33#ifndef PICOOS_H_
34#define PICOOS_H_
35
36#include "picodefs.h"
37#include "picopal.h"
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42#if 0
43}
44#endif
45
46
47/* some "switch"  used in picopal and in picocep ... */
48#define PICOOS_DIV_USE_INV PICOPAL_DIV_USE_INV
49
50/* *************************************************/
51/* types                                           */
52/* *************************************************/
53
54typedef picopal_uint8   picoos_uint8;
55typedef picopal_uint16  picoos_uint16;
56typedef picopal_uint32  picoos_uint32;
57
58typedef picopal_int8    picoos_int8;
59typedef picopal_int16   picoos_int16;
60typedef picopal_int32   picoos_int32;
61
62typedef picopal_double  picoos_double;
63typedef picopal_single  picoos_single;
64
65typedef picopal_char    picoos_char;
66typedef picopal_uchar   picoos_uchar;
67
68typedef picopal_uint8   picoos_bool;
69
70typedef picopal_objsize_t picoos_objsize_t;
71typedef picopal_ptrdiff_t picoos_ptrdiff_t;
72
73/* *************************************************/
74/* functions                                       */
75/* *************************************************/
76
77
78picoos_int32 picoos_atoi(const picoos_char *);
79picoos_int8 picoos_strcmp(const picoos_char *, const picoos_char *);
80picoos_int8 picoos_strncmp(const picoos_char *a, const picoos_char *b, picoos_objsize_t siz);
81picoos_uint32 picoos_strlen(const picoos_char *);
82picoos_char * picoos_strchr(const picoos_char *, picoos_char);
83picoos_char *picoos_strstr(const picoos_char *s, const picoos_char *substr);
84picoos_int16 picoos_slprintf(picoos_char * b, picoos_uint32 bsize, const picoos_char *f, ...);
85picoos_char * picoos_strcpy(picoos_char *, const picoos_char *);
86picoos_char * picoos_strcat(picoos_char *, const picoos_char *);
87
88/* copies 'length' bytes from 'src' to 'dest'. (regions may be overlapping) no error checks! */
89void * picoos_mem_copy(const void * src, void * dst,  picoos_objsize_t length);
90
91/* safe versions */
92picoos_objsize_t picoos_strlcpy(picoos_char *dst, const picoos_char *src, picoos_objsize_t siz);
93void * picoos_mem_set(void * dest, picoos_uint8 byte_val, picoos_objsize_t length);
94
95picoos_double picoos_cos(const picoos_double cos_arg);
96picoos_double picoos_sin(const picoos_double sin_arg);
97picoos_double picoos_fabs(const picoos_double fabs_arg);
98
99picoos_double picoos_quick_exp(const picoos_double y);
100
101
102void picoos_get_sep_part_str (picoos_char string[], picoos_int32 stringlen, picoos_int32 * ind, picoos_char sepCh, picoos_char part[], picoos_int32 maxsize, picoos_uint8 * done);
103pico_status_t picoos_string_to_uint32 (picoos_char str[], picoos_uint32 * res);
104pico_status_t picoos_string_to_int32 (picoos_char str[], picoos_int32 * res);
105
106/* *****************************************************************/
107/* "Common"                                                        */
108/* *****************************************************************/
109/* picoos_common is a collection of basic functionalities that must be globally accesible from every "big" function.
110 * It includes pointers to the MemoryManasger, ExceptionManager and a list of open files. */
111
112typedef struct memory_manager * picoos_MemoryManager;
113typedef struct picoos_exception_manager * picoos_ExceptionManager;
114typedef struct picoos_file * picoos_File;
115
116
117/**  object   : Common
118 *   shortcut : common
119 *
120 */
121typedef struct picoos_common * picoos_Common;
122
123/* the picoos_common structure itself is exported so no access functions are needed. Handle with care! (might be changed later) */
124typedef struct picoos_common {
125    picoos_ExceptionManager em;
126    picoos_MemoryManager mm;
127    picoos_File fileList;
128} picoos_common_t;
129
130picoos_Common picoos_newCommon(picoos_MemoryManager mm);
131
132void picoos_disposeCommon(picoos_MemoryManager mm, picoos_Common * this);
133
134
135/* *****************************************************************/
136/* Memory Management                                               */
137/* *****************************************************************/
138
139typedef picoos_char * byte_ptr_t;
140
141#define PICOOS_ALIGN_SIZE 8
142
143
144
145void * picoos_raw_malloc(byte_ptr_t raw_mem,
146        picoos_objsize_t raw_mem_size, picoos_objsize_t alloc_size,
147        byte_ptr_t * rest_mem, picoos_objsize_t * rest_mem_size);
148
149/**
150 * Creates a new memory manager object for the specified raw memory
151 * block. 'enableProtMem' enables or disables memory protection
152 * functionality; if disabled, picoos_protectMem() has no effect.
153 */
154picoos_MemoryManager picoos_newMemoryManager(
155        void *raw_memory,
156        picoos_objsize_t size,
157        picoos_bool enableMemProt);
158
159
160
161void picoos_disposeMemoryManager(picoos_MemoryManager * mm);
162
163
164void * picoos_allocate(picoos_MemoryManager this, picoos_objsize_t byteSize);
165void picoos_deallocate(picoos_MemoryManager this, void * * adr);
166
167/* the following memory manager routines are for testing and
168   debugging purposes */
169
170/**
171 * Same as picoos_allocate, but write access to the memory block may be
172 * prohibited by a subsequent call to picoos_protectMem().
173 */
174void *picoos_allocProtMem(picoos_MemoryManager mm, picoos_objsize_t byteSize);
175
176/**
177 * Releases a memory block previously allocated by picoos_allocProtMem().
178 */
179void picoos_deallocProtMem(picoos_MemoryManager mm, void **addr);
180
181/**
182 * Enables or disables write protection of a memory block previously
183 * allocated by picoos_allocProtMem(). If write protection is enabled,
184 * any subsequent write access will cause a segmentation fault.
185 */
186void picoos_protectMem(
187        picoos_MemoryManager mm,
188        void *addr,
189        picoos_objsize_t len,
190        picoos_bool enable);
191
192void picoos_getMemUsage(
193        picoos_MemoryManager this,
194        picoos_bool resetIncremental,
195        picoos_int32 *usedBytes,
196        picoos_int32 *incrUsedBytes,
197        picoos_int32 *maxUsedBytes);
198
199void picoos_showMemUsage(
200        picoos_MemoryManager this,
201        picoos_bool incremental,
202        picoos_bool resetIncremental);
203
204/* *****************************************************************/
205/* Exception Management                                                */
206/* *****************************************************************/
207/**  object   : ExceptionManager
208 *   shortcut : em
209 *
210 */
211
212
213#define PICOOS_MAX_EXC_MSG_LEN 512
214#define PICOOS_MAX_WARN_MSG_LEN 64
215#define PICOOS_MAX_NUM_WARNINGS 8
216
217void picoos_setErrorMsg(picoos_char * dst, picoos_objsize_t siz,
218        picoos_int16 code, picoos_char * base, const picoos_char *fmt, ...);
219
220
221picoos_ExceptionManager picoos_newExceptionManager(picoos_MemoryManager mm);
222
223void picoos_disposeExceptionManager(picoos_MemoryManager mm,
224        picoos_ExceptionManager * this);
225
226
227void picoos_emReset(picoos_ExceptionManager this);
228
229/* For convenience, this function returns the resulting exception code of 'this'
230 * (as would be returned by emGetExceptionCode).
231 * The return value therefore is NOT the status of raising
232 * the error! */
233pico_status_t picoos_emRaiseException(picoos_ExceptionManager this,
234        pico_status_t exceptionCode, picoos_char * baseMessage, picoos_char * fmt, ...);
235
236pico_status_t picoos_emGetExceptionCode(picoos_ExceptionManager this);
237
238void picoos_emGetExceptionMessage(picoos_ExceptionManager this, picoos_char * msg, picoos_uint16 maxsize);
239
240void picoos_emRaiseWarning(picoos_ExceptionManager this,
241        pico_status_t warningCode, picoos_char * baseMessage, picoos_char * fmt, ...);
242
243picoos_uint8 picoos_emGetNumOfWarnings(picoos_ExceptionManager this);
244
245pico_status_t picoos_emGetWarningCode(picoos_ExceptionManager this, picoos_uint8 warnNum);
246
247void picoos_emGetWarningMessage(picoos_ExceptionManager this, picoos_uint8 warnNum, picoos_char * msg, picoos_uint16 maxsize);
248
249
250
251
252/* *****************************************************************/
253/* File Access                                                     */
254/* *****************************************************************/
255
256#define picoos_MaxFileNameLen 512
257#define picoos_MaxKeyLen 512
258#define picoos_MaxPathLen 512
259#define picoos_MaxPathListLen 2048
260
261typedef picoos_char picoos_Key[picoos_MaxKeyLen];
262typedef picoos_char picoos_FileName[picoos_MaxFileNameLen];
263typedef picoos_char picoos_Path[picoos_MaxPathLen];
264typedef picoos_char picoos_PathList[picoos_MaxPathListLen];
265
266
267/* ***** Sequential binary file access ******/
268
269/* Remark: 'ReadByte', 'ReadBytes' and 'ReadVar' may be mixed;
270 'WriteByte', 'WriteBytes' and 'WriteVar' may be mixed. */
271
272/* Open existing binary file for read access. */
273picoos_uint8 picoos_OpenBinary(picoos_Common g, picoos_File * f, picoos_char name[]);
274
275
276/* Read next byte from file 'f'. */
277picoos_uint8  picoos_ReadByte(picoos_File f, picoos_uint8 * by);
278
279/* Read next 'len' bytes from 'f' into 'bytes'; 'len' returns the
280 number of bytes actually read (may be smaller than requested
281 length if 'bytes' is too small to hold all bytes or at end of file).
282 Remark: 'bytes' is compabtible with any variable of any size. */
283picoos_uint8  picoos_ReadBytes(picoos_File f, picoos_uint8 bytes[],
284        picoos_uint32 * len);
285
286
287/* Create new binary file.
288 If 'key' is not empty, the file is encrypted with 'key'. */
289picoos_uint8 picoos_CreateBinary(picoos_Common g, picoos_File * f, picoos_char name[]);
290
291picoos_uint8  picoos_WriteByte(picoos_File f, picoos_char by);
292
293/* Writes 'len' bytes from 'bytes' onto file 'f'; 'len' returns
294 the number of bytes actually written. */
295picoos_uint8  picoos_WriteBytes(picoos_File f, const picoos_char bytes[],
296        picoos_int32 * len);
297
298
299/* Close previously opened binary file. */
300picoos_uint8 picoos_CloseBinary(picoos_Common g, picoos_File * f);
301
302
303
304
305
306
307pico_status_t picoos_read_le_int16 (picoos_File file, picoos_int16 * val);
308pico_status_t picoos_read_le_uint16 (picoos_File file, picoos_uint16 * val);
309pico_status_t picoos_read_le_uint32 (picoos_File file, picoos_uint32 * val);
310
311
312pico_status_t picoos_read_pi_uint16 (picoos_File file, picoos_uint16 * val);
313pico_status_t picoos_read_pi_uint32 (picoos_File file, picoos_uint32 * val);
314
315pico_status_t picoos_write_le_uint16 (picoos_File file, picoos_uint16 val);
316pico_status_t picoos_write_le_uint32 (picoos_File file, picoos_uint32 val);
317
318/*
319pico_status_t picoos_write_pi_uint32 (picoos_File file, const picoos_uint32 val);
320
321pico_status_t picoos_write_pi_uint16 (picoos_File file, const picoos_uint16 val);
322*/
323
324
325/* **************************************************************************************/
326/* *** general file routines *****/
327
328/* Returns whether end of file was encountered in previous
329 read operation. */
330picoos_bool picoos_Eof(picoos_File f);
331
332/*  sets the file pointer to
333 'pos' bytes from beginning (first byte = byte 0). This
334 routine should only be used for binary files. */
335picoos_bool  picoos_SetPos(picoos_File f, picoos_int32 pos);
336
337/* Get position from file 'f'. */
338picoos_bool picoos_GetPos(picoos_File f, picoos_uint32 * pos);
339
340/* Returns the length of the file in bytes. */
341picoos_bool picoos_FileLength(picoos_File f, picoos_uint32 * len);
342
343/* Return full name of file 'f'. */
344picoos_bool picoos_Name(picoos_File f, picoos_char name[], picoos_uint32 maxsize);
345
346/* Returns whether file 'name' exists or not. */
347picoos_bool picoos_FileExists(picoos_Common g, picoos_char name[] /*, picoos_char ckey[] */);
348
349/* Delete a file. */
350picoos_bool  picoos_Delete(picoos_char name[]);
351
352/* Rename a file. */
353picoos_bool  picoos_Rename(picoos_char oldName[], picoos_char newName[]);
354
355
356/* *****************************************************************/
357/* Sampled Data Files                                                    */
358/* *****************************************************************/
359
360#define SAMPLE_FREQ_16KHZ (picoos_uint32) 16000
361
362typedef enum {
363    FILE_TYPE_WAV,
364    FILE_TYPE_AU,
365    FILE_TYPE_RAW,
366    FILE_TYPE_OTHER
367} wave_file_type_t;
368
369typedef enum {
370    FORMAT_TAG_LIN = 1, /**< linear 16-bit encoding */
371    FORMAT_TAG_ALAW = 6, /**< a-law encoding, 8 bit */
372    FORMAT_TAG_ULAW = 7 /**< u-law encoding, 8 bit */
373    /* there are many more */
374} wave_format_tag_t;
375
376
377typedef enum {
378    /* values corresponding RIFF wFormatTag */
379    PICOOS_ENC_LIN = FORMAT_TAG_LIN,  /**< linear 16-bit encoding; standard */
380    PICOOS_ENC_ALAW = FORMAT_TAG_ALAW, /**< a-law encoding, 8 bit */
381    PICOOS_ENC_ULAW = FORMAT_TAG_ULAW, /**< u-law encoding, 8 bit */
382    /* values outside RIFF wFormatTag values (above 4100) */
383    PICOOS_ENC_OTHER = 5000  /**< other; (treated as raw) */
384    }  picoos_encoding_t;
385
386typedef struct picoos_sd_file * picoos_SDFile;
387
388/* SDFile input functions */
389
390/* orig. comment from SDInOut.def
391             Opens sampled data file 'fileName' for input and returns
392             the encoding 'enc' of the file, sampling rate 'sf',
393             nr of samples 'nrSamples', and a handle to the opened file
394             in 'sdFile'.
395
396             If 'fileName' is empty, the input is taken from the direct
397             acoustic input using the sampling rate specified by
398             "SetRawDefaults". In this case, 'encoding' returns 'EncLin',
399             and 'nrSamples' returns 0.
400
401             The file format is taken from the file name extension:
402                ".wav"           --> wav file
403                ".au"            --> au file
404                other extensions --> headerless files
405
406             For wav and au files, the sampling rate and encoding are taken
407             from the file header and returned in 'sf' and 'enc'. For
408             headerless files, 'sf' and 'enc' are taken from the
409             most recently set default values (procedure SetRawDefaults).
410
411             'done' returns whether the sampled data file was successfully
412             opened. */
413extern picoos_bool picoos_sdfOpenIn (picoos_Common g, picoos_SDFile * sdFile, picoos_char fileName[], picoos_uint32 * sf, picoos_encoding_t * enc, picoos_uint32 * nrSamples);
414
415
416extern picoos_bool picoos_sdfGetSamples (picoos_SDFile sdFile, picoos_uint32 start, picoos_uint32 * nrSamples, picoos_int16 samples[]);
417
418
419extern picoos_bool picoos_sdfCloseIn (picoos_Common g, picoos_SDFile * sdFile);
420
421
422/* SDFile output functions*/
423
424extern picoos_bool picoos_sdfOpenOut (picoos_Common g, picoos_SDFile * sdFile, picoos_char fileName[], int sf, picoos_encoding_t enc);
425
426
427extern picoos_bool picoos_sdfPutSamples (picoos_SDFile sdFile, picoos_uint32 nrSamples, picoos_int16 samples[]);
428
429/*
430extern picoos_bool picoos_AbortOutput (picoos_SDFile sdFile);
431
432
433extern picoos_bool picoos_ResumeOutput (picoos_SDFile sdFile);
434
435
436extern picoos_bool picoos_FlushOutput (picoos_SDFile sdFile);
437*/
438
439extern picoos_bool picoos_sdfCloseOut (picoos_Common g, picoos_SDFile * sdFile);
440
441
442/* *****************************************************************/
443/* File Headers                                                    */
444/* *****************************************************************/
445
446#define PICOOS_MAX_FIELD_STRING_LEN 32 /* including terminating char */
447
448#define PICOOS_MAX_NUM_HEADER_FIELDS 10
449#define PICOOS_NUM_BASIC_HEADER_FIELDS 5
450
451#define PICOOS_HEADER_NAME 0
452#define PICOOS_HEADER_VERSION 1
453#define PICOOS_HEADER_DATE 2
454#define PICOOS_HEADER_TIME 3
455#define PICOOS_HEADER_CONTENT_TYPE 4
456
457#define PICOOS_MAX_HEADER_STRING_LEN (PICOOS_MAX_NUM_HEADER_FIELDS * (2 * PICOOS_MAX_FIELD_STRING_LEN))
458
459typedef picoos_char picoos_field_string_t[PICOOS_MAX_FIELD_STRING_LEN];
460
461typedef picoos_char picoos_header_string_t[PICOOS_MAX_HEADER_STRING_LEN];
462
463typedef enum {PICOOS_FIELD_IGNORE, PICOOS_FIELD_EQUAL, PICOOS_FIELD_COMPAT} picoos_compare_op_t;
464
465/* private */
466typedef struct picoos_file_header_field {
467    picoos_field_string_t key;
468    picoos_field_string_t value;
469    picoos_compare_op_t op;
470} picoos_file_header_field_t;
471
472/* public */
473typedef struct picoos_file_header * picoos_FileHeader;
474typedef struct picoos_file_header {
475    picoos_uint8 numFields;
476    picoos_file_header_field_t  field[PICOOS_MAX_NUM_HEADER_FIELDS];
477} picoos_file_header_t;
478
479
480pico_status_t picoos_clearHeader(picoos_FileHeader header);
481
482pico_status_t picoos_setHeaderField(picoos_FileHeader header, picoos_uint8 index, picoos_char * key, picoos_char * value, picoos_compare_op_t op);
483
484/* caller has to make sure allocated space at key and value are large enough to hold a picoos_field_string */
485pico_status_t picoos_getHeaderField(picoos_FileHeader header, picoos_uint8 index, picoos_field_string_t key, picoos_field_string_t value, picoos_compare_op_t * op);
486
487/* caller has to make sure allocated space at str is large enough to hold the header in question */
488/*
489pico_status_t picoos_hdrToString(picoos_FileHeader header, picoos_header_string_t str);
490*/
491
492pico_status_t picoos_hdrParseHeader(picoos_FileHeader header, picoos_header_string_t str);
493
494pico_status_t picoos_getSVOXHeaderString(picoos_char * str, picoos_uint8 * len, picoos_uint32 maxlen);
495
496pico_status_t picoos_readPicoHeader(picoos_File f, picoos_uint32 * headerlen);
497
498
499
500/* *****************************************************************/
501/* String search and compare operations                            */
502/* *****************************************************************/
503
504
505picoos_uint8 picoos_has_extension(const picoos_char *str, const picoos_char *suf);
506
507/* *****************************************************************/
508/* String/Number Manipulations  (might be moved to picopal)          */
509/* *****************************************************************/
510
511pico_status_t picoos_string_to_int32(picoos_char str[],
512        picoos_int32 * res);
513
514pico_status_t picoos_string_to_uint32(picoos_char str[],
515        picoos_uint32 * res);
516
517/* 'stringlen' is the part of input string to be considered, possibly not containing NULLC (e.g. result of strlen).
518 *  'maxsize' is the maximal size of 'part' including a byte for the terminating NULLC! */
519void picoos_get_sep_part_str(picoos_char string[],
520        picoos_int32 stringlen, picoos_int32 * ind, picoos_char sepCh,
521        picoos_char part[], picoos_int32 maxsize, picoos_uint8 * done);
522
523/* searches for the first contiguous string of printable characters (> ' ') inside fromStr, possibly skipping
524 * chars <= ' ') and returns it in toStr.
525 * fromStr is assumed to be NULLC terminated and toStr is forced to be NULLC terminated within maxsize.
526 * The search is started at *pos inside fromStr and at return, *pos is the position within fromStr after the
527 * found string, or the position after the end of fromStr, if no string was found.
528 * the function returns TRUE if a string was found and fitted toStr, or FALSE otherwise. */
529picoos_uint8 picoos_get_str (picoos_char * fromStr, picoos_uint32 * pos, picoos_char * toStr, picoos_objsize_t maxsize);
530
531
532pico_status_t picoos_read_mem_pi_uint16 (picoos_uint8 * data, picoos_uint32 * pos, picoos_uint16 * val);
533
534pico_status_t picoos_read_mem_pi_uint32 (picoos_uint8 * data, picoos_uint32 * pos, picoos_uint32 * val);
535
536pico_status_t picoos_write_mem_pi_uint16 (picoos_uint8 * data, picoos_uint32 * pos, picoos_uint16 val);
537
538
539/* *****************************************************************/
540/* timer function          */
541/* *****************************************************************/
542
543void picoos_get_timer(picopal_uint32 * sec, picopal_uint32 * usec);
544
545#ifdef __cplusplus
546}
547#endif
548
549
550#endif /*PICOOS_H_*/
551