source: trunk/kLdr/kLdrHlp.h@ 3384

/* $Id: kLdrHlp.h 2958 2007-02-09 05:12:22Z bird $ */
/** @file
 *
 * kLdr - The Dynamic Loader, Helper Functions.
 *
 * Copyright (c) 2006 knut st. osmundsen <bird@anduin.net>
 *
 *
 * This file is part of kLdr.
 *
 * kLdr is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * kLdr is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with kLdr; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */


#ifndef __kLdrHlp_h__
#define __kLdrHlp_h__

/** @defgroup grp_kLdrHlp  kLdrHlp - Helper Functions
 * @internal
 * @{ */

/** Get the minimum of two values. */
#define KLDR_MIN(a, b)              ((a) <= (b) ? (a) : (b))
/** Get the maximum of two values. */
#define KLDR_MAX(a, b)              ((a) >= (b) ? (a) : (b))
/** Calculate the offset of a structure member. */
#define KLDR_OFFSETOF(strct, memb)  ( (size_t)( &((strct *)0)->memb ) )
/** Align a size_t value. */
#define KLDR_ALIGN_Z(val, align)    ( ((val) + ((align) - 1)) & ~(size_t)((align) - 1) )
/** Align a void * value. */
#define KLDR_ALIGN_P(pv, align)     ( (void *)( ((uintptr_t)(pv) + ((align) - 1)) & ~(uintptr_t)((align) - 1) ) )
/** Align a size_t value. */
#define KLDR_ALIGN_ADDR(val, align) ( ((val) + ((align) - 1)) & ~(KLDRADDR)((align) - 1) )
/** Number of elements in an array. */
#define KLDR_ELEMENTS(a)            ( sizeof(a) / sizeof((a)[0]) )


/** @name Endian Conversion
 * @{ */

/** @def KLDRHLP_E2E_U16
 * Convert the endian of an unsigned 16-bit value. */
# define KLDRHLP_E2E_U16(u16)   ( (uint16_t) (((u16) >> 8) | ((u16) << 8)) )
/** @def KLDRHLP_E2E_U32
 * Convert the endian of an unsigned 32-bit value. */
# define KLDRHLP_E2E_U32(u32)   (   ( ((u32) & UINT32_C(0xff000000)) >> 24 ) \
                                  | ( ((u32) & UINT32_C(0x00ff0000)) >>  8 ) \
                                  | ( ((u32) & UINT32_C(0x0000ff00)) <<  8 ) \
                                  | ( ((u32) & UINT32_C(0x000000ff)) << 24 ) \
                                )
/** @def KLDRHLP_E2E_U64
 * Convert the endian of an unsigned 64-bit value. */
# define KLDRHLP_E2E_U64(u64)   (   ( ((u64) & UINT64_C(0xff00000000000000)) >> 56 ) \
                                  | ( ((u64) & UINT64_C(0x00ff000000000000)) >> 40 ) \
                                  | ( ((u64) & UINT64_C(0x0000ff0000000000)) >> 24 ) \
                                  | ( ((u64) & UINT64_C(0x000000ff00000000)) >>  8 ) \
                                  | ( ((u64) & UINT64_C(0x00000000ff000000)) <<  8 ) \
                                  | ( ((u64) & UINT64_C(0x0000000000ff0000)) << 24 ) \
                                  | ( ((u64) & UINT64_C(0x000000000000ff00)) << 40 ) \
                                  | ( ((u64) & UINT64_C(0x00000000000000ff)) << 56 ) \
                                )

/** @def KLDRHLP_LE2H_U16
 * Unsigned 16-bit little-endian to host endian. */
/** @def KLDRHLP_LE2H_U32
 * Unsigned 32-bit little-endian to host endian. */
/** @def KLDRHLP_LE2H_U64
 * Unsigned 64-bit little-endian to host endian. */
/** @def KLDRHLP_BE2H_U16
 * Unsigned 16-bit big-endian to host endian. */
/** @def KLDRHLP_BE2H_U32
 * Unsigned 32-bit big-endian to host endian. */
/** @def KLDRHLP_BE2H_U64
 * Unsigned 64-bit big-endian to host endian. */
#ifdef KLDR_LITTLE_ENDIAN
# define KLDRHLP_LE2H_U16(u16)  ((uint16_t)(u16))
# define KLDRHLP_LE2H_U32(u32)  ((uint32_t)(u32))
# define KLDRHLP_LE2H_U64(u64)  ((uint32_t)(u32))
# define KLDRHLP_BE2H_U16(u16)  KLDRHLP_E2E_U16(u16)
# define KLDRHLP_BE2H_U32(u32)  KLDRHLP_E2E_U32(u32)
# define KLDRHLP_BE2H_U64(u64)  KLDRHLP_E2E_U64(u64)
#elif defined(KLDR_BIG_ENDIAN)
# define KLDRHLP_LE2H_U16(u16)  KLDRHLP_E2E_U16(u16)
# define KLDRHLP_LE2H_U32(u32)  KLDRHLP_E2E_U32(u32)
# define KLDRHLP_LE2H_U32(u64)  KLDRHLP_E2E_U64(u64)
# define KLDRHLP_BE2H_U16(u16)  ((uint16_t)(u16))
# define KLDRHLP_BE2H_U32(u32)  ((uint32_t)(u32))
# define KLDRHLP_BE2H_U64(u64)  ((uint32_t)(u32))
#else
# error "KLDR_BIG_ENDIAN or KLDR_LITTLE_ENDIAN is supposed to be defined."
#endif

/** @} */


/*
 * Compiler specific helpers / CRT.
 * (I.e. operations that tend to have compiler intrinsic implementations).
 */
#ifndef KLDR_USE_CRT

# ifdef __GNUC__
/** memchr */
#  define kLdrHlpMemChr(a,b,c)  __builtin_memchr(a,b,c)
/** memcmp */
#  define kLdrHlpMemComp(a,b,c) __builtin_memcmp(a,b,c)
/** memcpy */
#  define kLdrHlpMemCopy(a,b,c) __builtin_memcpy(a,b,c)
/** memmove */
/*# define kLdrHlpMemMove(a,b,c) __builtin_memmove(a,b,c)*/
#  define kLdrHlpMemMove_needed
/** memset */
#  define kLdrHlpMemSet(a,b,c)  __builtin_memset(a,b,c)
/** strchr */
#  define kLdrHlpStrChr(a, b)   __builtin_strchr(a, b)
/** strcmp */
#  define kLdrHlpStrComp(a, b)  __builtin_strcmp(a, b)
/** strncmp */
#  define kLdrHlpStrNComp(a,b,c) __builtin_strncmp(a, b, c)
/** strlen */
#  define kLdrHlpStrLen(a)      __builtin_strlen(a)
/** alloca */
#  define kLdrHlpAllocA(a)      __builtin_alloca(a)
/** int3 */
#  define kldrHlpBreakpoint() do { __asm__ __volatile__ ("int3\n\tnop"); } while (0)
/** NULL */
#  ifndef NULL
#   define NULL 0
#  endif
# endif

# ifdef _MSC_VER
#  include <string.h>
#  include <malloc.h>
#  pragma intrinsic(memcmp, memcpy, memset, strcmp, strlen, __debugbreak)
/** memchr */
#  define kLdrHlpMemChr_needed
/** memcmp */
#  define kLdrHlpMemComp(a,b,c) memcmp(a,b,c)
/** memcpy */
#  define kLdrHlpMemCopy(a,b,c) memcpy(a,b,c)
/** memmove */
#  define kLdrHlpMemMove_needed
/** memset */
#  define kLdrHlpMemSet(a,b,c)  memset(a,b,c)
/** strcmp */
#  define kLdrHlpStrComp(a, b)  strcmp(a, b)
/** strncmp */
#  define kLdrHlpStrNComp_needed
/** strlen */
#  define kLdrHlpStrLen(a)      strlen(a)
/** strchr */
#  define kLdrHlpStrChr_needed
/** alloca */
#  define kLdrHlpAllocA(a)      alloca(a)
/** int3 */
#  define kldrHlpBreakpoint() __debugbreak()
/** NULL */
#  ifndef NULL
#   define NULL 0
#  endif
# endif

# ifdef kLdrHlpStrChr_needed
char   *kLdrHlpStrChr(const char *psz, int ch);
# endif
# ifdef kLdrHlpStrChr_needed
int     kLdrHlpStrNComp(const char *psz1, const char *psz2, size_t cch);
# endif
# ifdef kLdrHlpMemChr_needed
void   *kLdrHlpMemChr(const void *pv, int ch, size_t cb);
# endif
# ifdef kLdrHlpMemMove_needed
void   *kLdrHlpMemMove(void *pv1, const void *pv2, size_t cb);
# endif


#else /* KLDR_USE_CRT */

#  include <string.h>
#  include <stdlib.h>
#  ifdef _MSC_VER
#   include <malloc.h>
#  endif

#  define kLdrHlpMemChr(a,b,c)  memchr(a,b,c)
/** memcmp */
#  define kLdrHlpMemComp(a,b,c) memcmp(a,b,c)
/** memcpy */
#  define kLdrHlpMemCopy(a,b,c) memcpy(a,b,c)
/** memmove */
#  define kLdrHlpMemMove(a,b,c) memmove(a,b,c)
/** memset */
#  define kLdrHlpMemSet(a,b,c)  memset(a,b,c)
/** strchr */
#  define kLdrHlpStrChr(a, b)   strchr(a, b)
/** strcmp */
#  define kLdrHlpStrComp(a, b)  strcmp(a, b)
/** strncmp */
#  define kLdrHlpStrNComp(a,b,c) strncmp(a, b, c)
/** strlen */
#  define kLdrHlpStrLen(a)      strlen(a)
/** alloca */
#  define kLdrHlpAllocA(a)      alloca(a)
/** int3 */
#  ifdef __GNUC__
#   define kldrHlpBreakpoint() do { __asm__ __volatile__ ("int3\n\tnop"); } while (0)
#  endif
#  ifdef _MSC_VER
#   define kldrHlpBreakpoint() __debugbreak()
#  endif

#endif

#if (!defined(kLdrHlpMemChr) && !defined(kLdrHlpStrChr_needed))\
 || !defined(kLdrHlpMemComp) \
 || !defined(kLdrHlpMemCopy) \
 || !defined(kLdrHlpMemSet) \
 || (!defined(kLdrHlpStrChr) && !defined(kLdrHlpStrChr_needed)) \
 || !defined(kLdrHlpStrComp) \
 || (!defined(kLdrHlpStrNComp) && !defined(kLdrHlpStrNComp_needed)) \
 || !defined(kLdrHlpStrLen) \
 || !defined(kLdrHlpAllocA) \
 || !defined(kldrHlpBreakpoint)
# error "Needs porting to your compiler."
#endif

#ifdef __cplusplus
extern "C" {
#endif

size_t  kLdrHlpStrNLen(const char *psz, size_t cchMax);
int     kLdrHlpMemIComp(const void *pv1, const void *pv2, size_t cb);
int     kLdrHlpStrIComp(const char *pv1, const char *pv2);

int     kldrHlpSemInit(void);
void    kldrHlpSemTerm(void);
int     kldrHlpSemRequest(void);
void    kldrHlpSemRelease(void);

int     kldrHlpPageAlloc(void **ppv, size_t cb, KLDRPROT enmProt, unsigned fFixed);
int     kldrHlpPageProtect(void *pv, size_t cb, KLDRPROT enmProt);
int     kldrHlpPageFree(void *pv, size_t cb);

int     kldrHlpHeapInit(void);
void    kldrHlpHeapTerm(void);
void    kldrHlpHeapDonate(void *pv, size_t cb);
void *  kldrHlpAlloc(size_t cb);
void *  kldrHlpAllocZ(size_t cb);
void    kldrHlpFree(void *pv);

int     kldrHlpGetEnv(const char *pszVar, char *pszVal, size_t cchVal);
int     kldrHlpGetEnvUZ(const char *pszVar, size_t *pcb);
char   *kldrHlpGetFilename(const char *pszFilename);
char   *kldrHlpGetSuff(const char *pszFilename);
char   *kldrHlpGetExt(const char *pszFilename);
int     kldrHlpIsFilenameOnly(const char *pszFilename);
void    kldrHlpExit(int rc);
void    kldrHlpSleep(unsigned cMillies);
char   *kldrHlpInt2Ascii(char *psz, size_t cch, long lVal, unsigned iBase);
void    kldrHlpAssertMsg(const char *pszExpr, const char *pszFile, unsigned iLine, const char *pszFunction);

#ifdef __cplusplus
}
#endif


/** Assertion macro.
 * Users should wrap it since this is ALWAYS compiled in. */
#define kldrHlpAssert(expr) \
    do { \
        if (!(expr)) \
        { \
            kldrHlpAssertMsg(#expr, __FILE__, __LINE__, __FUNCTION__); \
            kldrHlpBreakpoint(); \
        } \
    } while (0)


/** @name Parameter validation macros
 * @{ */

/** Crash validation of a string argument. */
#define KLDRHLP_VALIDATE_STRING(str) \
    do { kLdrHlpStrLen(str); } while (0)

/** Crash validation of an optional string argument. */
#define KLDRHLP_VALIDATE_OPTIONAL_STRING(str) \
    do { if (str) { KLDRHLP_VALIDATE_STRING(str); } } while (0)

/** Return/Crash validation of an output buffer. */
#define KLDRHLP_VALIDATE_BUFFER(buf, cb) \
    do { \
        if ((cb)) \
        { \
            uint8_t             __b; \
            uint8_t volatile *  __pb = (uint8_t volatile *)(buf); \
            size_t              __cbPage1 = 0x1000 - ((uintptr_t)(__pb) & 0xfff); /* ASSUMES page size! */ \
            __b = *__pb; *__pb = 0xff; *__pb = __b; \
            if ((cb) > __cbPage1) \
            { \
                size_t  __cb = (cb) - __cbPage1; \
                __pb -= __cbPage1; \
                for (;;) \
                { \
                    __b = *__pb; *__pb = 0xff; *__pb = __b; \
                    if (__cb < 0x1000) \
                        break; \
                    __pb += 0x1000; \
                    __cb -= 0x1000; \
                } \
            } \
        } \
        else \
            return KLDR_ERR_INVALID_PARAMETER; \
    } while (0)

/** Crash validation of an optional output buffer. */
#define KLDRHLP_VALIDATE_OPTIONAL_BUFFER(buf, cb) \
    do { \
        if ((buf) != NULL && (cb) != 0) \
        { \
            KLDRHLP_VALIDATE_BUFFER(buf, cb); \
        } \
    } while (0)

/** Return validation of an enum argument. */
#define KLDRHLP_VALIDATE_ENUM(arg, enumname) \
    do { \
        if ((arg) <= enumname##_INVALID || (arg) >= enumname##_END) \
        {  \
            return KLDR_ERR_INVALID_PARAMETER; \
        } \
    } while (0)

/** Return validation of a flags argument. */
#define KLDRHLP_VALIDATE_FLAGS(arg, AllowedMask) \
    do { \
        if ((arg) & ~(AllowedMask)) \
        {  \
            return KLDR_ERR_INVALID_PARAMETER; \
        } \
    } while (0)

/** @} */


/** @} */

#endif /* __kLdrHlp_h__ */