1/*
2 * dspbridge/mpu_api/inc/csl.h
3 *
4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5 *
6 * Copyright (C) 2007 Texas Instruments, Inc.
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published
10 * by the Free Software Foundation version 2.1 of the License.
11 *
12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind,
13 * whether express or implied; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 * Lesser General Public License for more details.
16 */
17
18
19/*
20 *  ======== csl.h ========
21 *  Purpose:
22 *      Platform independent C Standard library functions.
23 *
24 *  Public Functions:
25 *      CSL_AnsiToWchar
26 *      CSL_Atoi
27 *      CSL_ByteSwap
28 *      CSL_Exit
29 *      CSL_Init
30 *      CSL_NumToAscii
31 *      CSL_Strcmp
32 *      CSL_Strcpyn
33 *      CSL_Strlen
34 *      CSL_Strncat
35 *      CSL_Strncmp
36 *      CSL_Strtok
37 *      CSL_Strtokr
38 *      CSL_WcharToAnsi
39 *      CSL_Wstrlen
40 *
41 *! Revision History:
42 *! ================
43 *! 07-Aug-2002 jeh: Added CSL_Strtokr().
44 *! 21-Sep-2001 jeh: Added CSL_Strncmp.
45 *! 22-Nov-2000 map: Added CSL_Atoi and CSL_Strtok
46 *! 19-Nov-2000 kc:  Added CSL_ByteSwap().
47 *! 09-Nov-2000 kc:  Added CSL_Strncat.
48 *! 29-Oct-1999 kc:  Added CSL_Wstrlen().
49 *! 20-Sep-1999 ag:  Added CSL_Wchar2Ansi().
50 *! 19-Jan-1998 cr:  Code review cleanup (mostly documentation fixes).
51 *! 29-Dec-1997 cr:  Changed CSL_lowercase to CSL_Uppercase, added
52 *!                  CSL_AnsiToWchar.
53 *! 30-Sep-1997 cr:  Added explicit cdecl descriptors to fxn definitions.
54 *! 25-Jun-1997 cr:  Added CSL_strcmp.
55 *! 12-Jun-1996 gp:  Created.
56 */
57
58#ifndef CSL_
59#define CSL_
60
61#ifdef __cplusplus
62extern "C" {
63#endif
64
65#include <dspapi.h>
66#include <host_os.h>
67
68#ifdef UNICODE
69/*
70 *  ======== CSL_AnsiToWchar ========
71 *  Purpose:
72 *      Convert an ansi string to a wide char string.
73 *  Parameters:
74 *      wpstrDest:  wide char buffer pointer.
75 *      pstrSource: ansi string buffer pointer.
76 *      uSize:      size of wpstrDest buffer.
77 *  Returns:
78 *      Number of characters copied into wpstrDest, excluding the NULL char.
79 *  Requires:
80 *      CSL initialized.
81 *  Ensures:
82 *  Details:
83 *      uSize is the number of CHARACTERS in wpstrDest, NOT the number of BYTES
84 *      in wpstrDest.  with a WCHAR, the number of characters is bytes/2.
85 */
86	extern ULONG CSL_AnsiToWchar(OUT WCHAR * pwszDest,
87				     IN PSTR pstrSource, ULONG uSize);
88#endif
89
90/*
91 *  ======== CSL_Atoi ========
92 *  Purpose:
93 *      Convert a 1 or 2 digit string number into an integer
94 *  Parameters:
95 *      ptstrSrc:   pointer to string.
96 *  Returns:
97 *      Integer
98 *  Requires:
99 *      CSL initialized.
100 *      ptstrSrc is a valid string pointer.
101 *  Ensures:
102 */
103	extern INT CSL_Atoi(IN CONST CHAR * ptstrSrc);
104
105/*
106 *  ======== CSL_ByteSwap ========
107 *  Purpose:
108 *      Convert an ansi string to a wide char string.
109 *  Parameters:
110 *      pstrSrc:    Data to be copied and swapped.
111 *      pstrDest:   Output buffer for swapped data.
112 *      ulBytes:    Number of bytes to be swapped (should be even).
113 *  Returns:
114 *  Requires:
115 *      CSL initialized.
116 *  Ensures:
117 *  Details:
118 */
119	extern VOID CSL_ByteSwap(IN PSTR pstrSrc,
120				 OUT PSTR pstrDest, IN ULONG ulBytes);
121
122/*
123 *  ======== CSL_Exit ========
124 *  Purpose:
125 *      Discontinue usage of the CSL module.
126 *  Parameters:
127 *  Returns:
128 *  Requires:
129 *      CSL initialized.
130 *  Ensures:
131 *      Resources acquired in CSL_Init() are freed.
132 */
133	extern VOID CSL_Exit();
134
135/*
136 *  ======== CSL_Init ========
137 *  Purpose:
138 *      Initialize the CSL module's private state.
139 *  Parameters:
140 *  Returns:
141 *      TRUE if initialized; FALSE if error occured.
142 *  Requires:
143 *  Ensures:
144 *      A requirement for each of the other public CSL functions.
145 */
146	extern bool CSL_Init();
147
148/*
149 *  ======== CSL_NumToAscii ========
150 *  Purpose:
151 *      Convert a 1 or 2 digit number to a 2 digit string.
152 *  Parameters:
153 *      pstrNumber: Buffer to store converted string.
154 *      dwNum:      Number to convert.
155 *  Returns:
156 *  Requires:
157 *      pstrNumber must be able to hold at least three characters.
158 *  Ensures:
159 *      pstrNumber will be null terminated.
160 */
161	extern VOID CSL_NumToAscii(OUT PSTR pstrNumber, IN DWORD dwNum);
162
163/*
164 *  ======== CSL_Strcmp ========
165 *  Purpose:
166 *      Compare 2 ASCII strings.  Works the same way as stdio's strcmp.
167 *  Parameters:
168 *      pstrStr1:   String 1.
169 *      pstrStr2:   String 2.
170 *  Returns:
171 *      A signed value that gives the results of the comparison:
172 *      Zero:   String1 equals String2.
173 *      < Zero: String1 is less than String2.
174 *      > Zero: String1 is greater than String2.
175 *  Requires:
176 *      CSL initialized.
177 *      pstrStr1 is valid.
178 *      pstrStr2 is valid.
179 *  Ensures:
180 */
181	extern LONG CSL_Strcmp(IN CONST PSTR pstrStr1, IN CONST PSTR pstrStr2);
182
183/*
184 *  ======== CSL_Strcpyn ========
185 *  Purpose:
186 *      Safe strcpy function.
187 *  Parameters:
188 *      pstrDest:   Ptr to destination buffer.
189 *      pstrSrc:    Ptr to source buffer.
190 *      cMax:       Size of destination buffer.
191 *  Returns:
192 *      Ptr to destination buffer; or NULL if error.
193 *  Requires:
194 *      CSL initialized.
195 *      pstrDest is valid.
196 *      pstrSrc is valid.
197 *  Ensures:
198 *      Will not copy more than cMax bytes from pstrSrc into pstrDest.
199 *      pstrDest will be terminated by a NULL character.
200 */
201	extern PSTR CSL_Strcpyn(OUT PSTR pstrDest, IN CONST PSTR pstrSrc,
202				IN DWORD cMax);
203
204/*
205 *  ======== CSL_Strstr ========
206 *  Purpose:
207 *      Find substring in a stringn.
208 *  Parameters:
209 *      haystack:   Ptr to string1.
210 *      needle:    Ptr to substring to catch.
211 *  Returns:
212 *      Ptr to first char matching the substring in the main string.
213 *  Requires:
214 *      CSL initialized.
215 *      haystack is valid.
216 *      needle is valid.
217 *  Ensures:
218 */
219	extern PSTR CSL_Strstr(IN CONST PSTR haystack, IN CONST PSTR needle);
220
221/*
222 *  ======== CSL_Strlen ========
223 *  Purpose:
224 *      Determine the length of a null terminated ASCI string.
225 *  Parameters:
226 *      pstrSrc:    pointer to string.
227 *  Returns:
228 *      String length in bytes.
229 *  Requires:
230 *      CSL initialized.
231 *      pstrSrc is a valid string pointer.
232 *  Ensures:
233 */
234	extern DWORD CSL_Strlen(IN CONST PSTR pstrSrc);
235
236/*
237 *  ======== CSL_Strncat ========
238 *  Purpose:
239 *      Concatenate two strings together.
240 *  Parameters:
241 *      pszDest:    Destination string.
242 *      pszSrc:     Source string.
243 *      dwSize:     Number of characters to copy.
244 *  Returns:
245 *      Pointer to destination string.
246 *  Requires:
247 *      CSL initialized.
248 *      pszDest and pszSrc are valid pointers.
249 *  Ensures:
250 */
251	extern PSTR CSL_Strncat(IN PSTR pszDest,
252				IN PSTR pszSrc, IN DWORD dwSize);
253
254/*
255 *  ======== CSL_Strncmp ========
256 *  Purpose:
257 *      Compare at most n characters of two ASCII strings.  Works the same
258 *      way as stdio's strncmp.
259 *  Parameters:
260 *      pstrStr1:   String 1.
261 *      pstrStr2:   String 2.
262 *      n:          Number of characters to compare.
263 *  Returns:
264 *      A signed value that gives the results of the comparison:
265 *      Zero:   String1 equals String2.
266 *      < Zero: String1 is less than String2.
267 *      > Zero: String1 is greater than String2.
268 *  Requires:
269 *      CSL initialized.
270 *      pstrStr1 is valid.
271 *      pstrStr2 is valid.
272 *  Ensures:
273 */
274	extern LONG CSL_Strncmp(IN CONST PSTR pstrStr1,
275				IN CONST PSTR pstrStr2, IN DWORD n);
276
277/*
278 *  ======== CSL_Strtok ========
279 *  Purpose:
280 *      Tokenize a NULL terminated string
281 *  Parameters:
282 *      ptstrSrc:       pointer to string.
283 *      szSeparators:   pointer to a string of seperators
284 *  Returns:
285 *      String
286 *  Requires:
287 *      CSL initialized.
288 *      ptstrSrc is a valid string pointer.
289 *      szSeparators is a valid string pointer.
290 *  Ensures:
291 */
292	extern CHAR *CSL_Strtok(IN CHAR * ptstrSrc,
293				IN CONST CHAR * szSeparators);
294
295/*
296 *  ======== CSL_Strtokr ========
297 *  Purpose:
298 *      Re-entrant version of strtok.
299 *  Parameters:
300 *      pstrSrc:        Pointer to string. May be NULL on subsequent calls.
301 *      szSeparators:   Pointer to a string of seperators
302 *      ppstrCur:       Location to store start of string for next call to
303 *                      to CSL_Strtokr.
304 *  Returns:
305 *      String (the token)
306 *  Requires:
307 *      CSL initialized.
308 *      szSeparators != NULL
309 *      ppstrCur != NULL
310 *  Ensures:
311 */
312	extern CHAR *CSL_Strtokr(IN CHAR * pstrSrc,
313				 IN CONST CHAR * szSeparators,
314				 OUT CHAR ** ppstrCur);
315
316#ifdef UNICODE
317/*
318 *  ======== CSL_WcharToAnsi ========
319 *  Purpose:
320 *      Convert a wide char string to an ansi string.
321 *  Parameters:
322 *     pstrDest:    ansi string buffer pointer.
323 *     pwszSource:  wide char buffer pointer.
324 *     uSize:       number of chars to convert.
325 *  Returns:
326 *      Number of characters copied into pstrDest.
327 *  Requires:
328 *      CSL initialized.
329 *  Ensures:
330 *  Details:
331 *      lNumOfChars is the number of CHARACTERS in wpstrDest, NOT the number of
332 *      BYTES
333 */
334	extern ULONG CSL_WcharToAnsi(OUT PSTR pstrDest,
335				     IN WCHAR * pwszSource, IN ULONG uSize);
336
337/*
338 *  ======== CSL_Wstrlen ========
339 *  Purpose:
340 *      Determine the length of a null terminated UNICODE string.
341 *  Parameters:
342 *      ptstrSrc: pointer to string.
343 *  Returns:
344 *      String length in bytes.
345 *  Requires:
346 *      CSL initialized.
347 *      ptstrSrc is a valid string pointer.
348 *  Ensures:
349 */
350	extern DWORD CSL_Wstrlen(IN CONST TCHAR * ptstrSrc);
351#endif
352
353#ifdef __cplusplus
354}
355#endif
356#endif				/* CSL_ */
357