1 /* 2 * Copyright 2001-2008 Texas Instruments - http://www.ti.com/ 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 18 /* 19 * ======== csl.h ======== 20 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 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 62 extern "C" { 63 #endif 64 65 #include <dspapi.h> 66 67 #ifdef UNICODE 68 /* 69 * ======== CSL_AnsiToWchar ======== 70 * Purpose: 71 * Convert an ansi string to a wide char string. 72 * Parameters: 73 * wpstrDest: wide char buffer pointer. 74 * pstrSource: ansi string buffer pointer. 75 * uSize: size of wpstrDest buffer. 76 * Returns: 77 * Number of characters copied into wpstrDest, excluding the NULL char. 78 * Requires: 79 * CSL initialized. 80 * Ensures: 81 * Details: 82 * uSize is the number of CHARACTERS in wpstrDest, NOT the number of BYTES 83 * in wpstrDest. with a WCHAR, the number of characters is bytes/2. 84 */ 85 extern ULONG CSL_AnsiToWchar(OUT WCHAR * pwszDest, 86 IN PSTR pstrSource, ULONG uSize); 87 #endif 88 89 /* 90 * ======== CSL_Atoi ======== 91 * Purpose: 92 * Convert a 1 or 2 digit string number into an integer 93 * Parameters: 94 * ptstrSrc: pointer to string. 95 * Returns: 96 * Integer 97 * Requires: 98 * CSL initialized. 99 * ptstrSrc is a valid string pointer. 100 * Ensures: 101 */ 102 extern INT CSL_Atoi(IN CONST CHAR * ptstrSrc); 103 104 /* 105 * ======== CSL_ByteSwap ======== 106 * Purpose: 107 * Convert an ansi string to a wide char string. 108 * Parameters: 109 * pstrSrc: Data to be copied and swapped. 110 * pstrDest: Output buffer for swapped data. 111 * ulBytes: Number of bytes to be swapped (should be even). 112 * Returns: 113 * Requires: 114 * CSL initialized. 115 * Ensures: 116 * Details: 117 */ 118 extern VOID CSL_ByteSwap(IN PSTR pstrSrc, 119 OUT PSTR pstrDest, IN ULONG ulBytes); 120 121 /* 122 * ======== CSL_Exit ======== 123 * Purpose: 124 * Discontinue usage of the CSL module. 125 * Parameters: 126 * Returns: 127 * Requires: 128 * CSL initialized. 129 * Ensures: 130 * Resources acquired in CSL_Init() are freed. 131 */ 132 extern VOID CSL_Exit(); 133 134 /* 135 * ======== CSL_Init ======== 136 * Purpose: 137 * Initialize the CSL module's private state. 138 * Parameters: 139 * Returns: 140 * TRUE if initialized; FALSE if error occured. 141 * Requires: 142 * Ensures: 143 * A requirement for each of the other public CSL functions. 144 */ 145 extern bool CSL_Init(); 146 147 /* 148 * ======== CSL_NumToAscii ======== 149 * Purpose: 150 * Convert a 1 or 2 digit number to a 2 digit string. 151 * Parameters: 152 * pstrNumber: Buffer to store converted string. 153 * dwNum: Number to convert. 154 * Returns: 155 * Requires: 156 * pstrNumber must be able to hold at least three characters. 157 * Ensures: 158 * pstrNumber will be null terminated. 159 */ 160 extern VOID CSL_NumToAscii(OUT PSTR pstrNumber, IN DWORD dwNum); 161 162 /* 163 * ======== CSL_Strcmp ======== 164 * Purpose: 165 * Compare 2 ASCII strings. Works the same way as stdio's strcmp. 166 * Parameters: 167 * pstrStr1: String 1. 168 * pstrStr2: String 2. 169 * Returns: 170 * A signed value that gives the results of the comparison: 171 * Zero: String1 equals String2. 172 * < Zero: String1 is less than String2. 173 * > Zero: String1 is greater than String2. 174 * Requires: 175 * CSL initialized. 176 * pstrStr1 is valid. 177 * pstrStr2 is valid. 178 * Ensures: 179 */ 180 extern LONG CSL_Strcmp(IN CONST PSTR pstrStr1, IN CONST PSTR pstrStr2); 181 182 /* 183 * ======== CSL_Strcpyn ======== 184 * Purpose: 185 * Safe strcpy function. 186 * Parameters: 187 * pstrDest: Ptr to destination buffer. 188 * pstrSrc: Ptr to source buffer. 189 * cMax: Size of destination buffer. 190 * Returns: 191 * Ptr to destination buffer; or NULL if error. 192 * Requires: 193 * CSL initialized. 194 * pstrDest is valid. 195 * pstrSrc is valid. 196 * Ensures: 197 * Will not copy more than cMax bytes from pstrSrc into pstrDest. 198 * pstrDest will be terminated by a NULL character. 199 */ 200 extern PSTR CSL_Strcpyn(OUT PSTR pstrDest, IN CONST PSTR pstrSrc, 201 IN DWORD cMax); 202 203 /* 204 * ======== CSL_Strstr ======== 205 * Purpose: 206 * Find substring in a stringn. 207 * Parameters: 208 * haystack: Ptr to string1. 209 * needle: Ptr to substring to catch. 210 * Returns: 211 * Ptr to first char matching the substring in the main string. 212 * Requires: 213 * CSL initialized. 214 * haystack is valid. 215 * needle is valid. 216 * Ensures: 217 */ 218 extern PSTR CSL_Strstr(IN CONST PSTR haystack, IN CONST PSTR needle); 219 220 /* 221 * ======== CSL_Strlen ======== 222 * Purpose: 223 * Determine the length of a null terminated ASCI string. 224 * Parameters: 225 * pstrSrc: pointer to string. 226 * Returns: 227 * String length in bytes. 228 * Requires: 229 * CSL initialized. 230 * pstrSrc is a valid string pointer. 231 * Ensures: 232 */ 233 extern DWORD CSL_Strlen(IN CONST PSTR pstrSrc); 234 235 /* 236 * ======== CSL_Strncat ======== 237 * Purpose: 238 * Concatenate two strings together. 239 * Parameters: 240 * pszDest: Destination string. 241 * pszSrc: Source string. 242 * dwSize: Number of characters to copy. 243 * Returns: 244 * Pointer to destination string. 245 * Requires: 246 * CSL initialized. 247 * pszDest and pszSrc are valid pointers. 248 * Ensures: 249 */ 250 extern PSTR CSL_Strncat(IN PSTR pszDest, 251 IN PSTR pszSrc, IN DWORD dwSize); 252 253 /* 254 * ======== CSL_Strncmp ======== 255 * Purpose: 256 * Compare at most n characters of two ASCII strings. Works the same 257 * way as stdio's strncmp. 258 * Parameters: 259 * pstrStr1: String 1. 260 * pstrStr2: String 2. 261 * n: Number of characters to compare. 262 * Returns: 263 * A signed value that gives the results of the comparison: 264 * Zero: String1 equals String2. 265 * < Zero: String1 is less than String2. 266 * > Zero: String1 is greater than String2. 267 * Requires: 268 * CSL initialized. 269 * pstrStr1 is valid. 270 * pstrStr2 is valid. 271 * Ensures: 272 */ 273 extern LONG CSL_Strncmp(IN CONST PSTR pstrStr1, 274 IN CONST PSTR pstrStr2, IN DWORD n); 275 276 /* 277 * ======== CSL_Strtok ======== 278 * Purpose: 279 * Tokenize a NULL terminated string 280 * Parameters: 281 * ptstrSrc: pointer to string. 282 * szSeparators: pointer to a string of seperators 283 * Returns: 284 * String 285 * Requires: 286 * CSL initialized. 287 * ptstrSrc is a valid string pointer. 288 * szSeparators is a valid string pointer. 289 * Ensures: 290 */ 291 extern CHAR *CSL_Strtok(IN CHAR * ptstrSrc, 292 IN CONST CHAR * szSeparators); 293 294 /* 295 * ======== CSL_Strtokr ======== 296 * Purpose: 297 * Re-entrant version of strtok. 298 * Parameters: 299 * pstrSrc: Pointer to string. May be NULL on subsequent calls. 300 * szSeparators: Pointer to a string of seperators 301 * ppstrCur: Location to store start of string for next call to 302 * to CSL_Strtokr. 303 * Returns: 304 * String (the token) 305 * Requires: 306 * CSL initialized. 307 * szSeparators != NULL 308 * ppstrCur != NULL 309 * Ensures: 310 */ 311 extern CHAR *CSL_Strtokr(IN CHAR * pstrSrc, 312 IN CONST CHAR * szSeparators, 313 OUT CHAR ** ppstrCur); 314 315 #ifdef UNICODE 316 /* 317 * ======== CSL_WcharToAnsi ======== 318 * Purpose: 319 * Convert a wide char string to an ansi string. 320 * Parameters: 321 * pstrDest: ansi string buffer pointer. 322 * pwszSource: wide char buffer pointer. 323 * uSize: number of chars to convert. 324 * Returns: 325 * Number of characters copied into pstrDest. 326 * Requires: 327 * CSL initialized. 328 * Ensures: 329 * Details: 330 * lNumOfChars is the number of CHARACTERS in wpstrDest, NOT the number of 331 * BYTES 332 */ 333 extern ULONG CSL_WcharToAnsi(OUT PSTR pstrDest, 334 IN WCHAR * pwszSource, IN ULONG uSize); 335 336 /* 337 * ======== CSL_Wstrlen ======== 338 * Purpose: 339 * Determine the length of a null terminated UNICODE string. 340 * Parameters: 341 * ptstrSrc: pointer to string. 342 * Returns: 343 * String length in bytes. 344 * Requires: 345 * CSL initialized. 346 * ptstrSrc is a valid string pointer. 347 * Ensures: 348 */ 349 extern DWORD CSL_Wstrlen(IN CONST TCHAR * ptstrSrc); 350 #endif 351 352 #ifdef __cplusplus 353 } 354 #endif 355 #endif /* CSL_ */ 356