#ifndef PHKERNELIFCE_COMMON_H    /* Multi-include protection.   <FILENAME>_H */
#define PHKERNELIFCE_COMMON_H


/*****************************************************************************/
/* Copyright (c) 2008 NXP B.V.                                               */
/*                                                                           */
/* This program 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, using version 2 of the License.             */
/*                                                                           */
/* This program 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 this program; if not, write to the Free Software               */
/* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307       */
/* USA.                                                                      */
/*                                                                           */
/*****************************************************************************/
/**
    @file   phKernelIfce.h
    @brief  Generic usermode to kernelspace API framework.

@b  Component:  phKernelIfce

    Do not include directly. Please include phKernelIfce.h instead.

*//*

Rev Date        Author      Comments
--------------------------------------------------------------------------------
  1 20061012    batelaan    Initial
  2 20061020    batelaan    Crosscheck fixes
  3 20071005    batelaan    Portability enhancements
  4 20080206    batelaan    Update file copyright/license text
  5 20080617    batelaan    Update file copyright/license text
--------------------------------------------------------------------------------
    For consistency and standardisation retain the Section Separators.
*/


/*******************
* INCLUDE FILES    *
********************/

#ifndef PHKERNELIFCE_H
  #error Please include phKernelIfce.h instead.
#endif

/**************************************************************************
* EXPORTED MACROS                          PH_KERNELIFCE_<_WORD>+             *
***************************************************************************/

/** Name of /dev/ device to access the the kernel module for phKernelIfce. */
#define PH_KERNELIFCE_DEVICE_NAME "kernelifce"

/** Path to /dev/ device to access the kernel module for phKernelIfce. */
#if TMFL_OS_IS_CE
#define PH_KERNELIFCE_DEVICE_PATH L"KIF0:"
#else
#define PH_KERNELIFCE_DEVICE_PATH "/dev/" PH_KERNELIFCE_DEVICE_NAME
#endif

/** Name of entry in /proc. */
#if TMFL_OS_IS_CE
#define PH_KERNELIFCE_IOCTL_CALL 'KIFC'
#else
#define PH_KERNELIFCE_PROC_ENTRY "kernelifce"
#define PH_KERNELIFCE_IOCTL_BASE 0xBE
#define PH_KERNELIFCE_IOCTL_CALL _IOW(PH_KERNELIFCE_IOCTL_BASE, 0, uint8_t*)
#endif

/** Maximum number of characters in a namespace or function name, excluding terminating NUL. */
#define PH_KERNELIFCE_MAX_NAME_LEN 63U

/** Indicates an uninitialised namespace or function ID.
 This is used as the initial value for the id field of ::phKernelIfce_Comp_t and ::phKernelIfce_Func_t. */
#define PH_KERNELIFCE_UNINITIALISED (-1)

/** System call was interupted. */
#define PH_ERR_KERNELIFCE_INTERRUPTED 1U

/** Insufficient memory. */
#define PH_ERR_KERNELIFCE_MEMORY 2U

/** Duplicate namespace name. Already registered. */
#define PH_ERR_KERNELIFCE_DUPL_NAMESPACE 3U

/** Duplicate function name. Already registered. */
#define PH_ERR_KERNELIFCE_DUPL_FUNC 4U

/** Unknown namespace name. Never registered or already deregistered. */
#define PH_ERR_KERNELIFCE_UNKNOWN_NAMESPACE 5U

/** Unknown function name. Never registered or already deregistered. */
#define PH_ERR_KERNELIFCE_UNKNOWN_FUNC 6U

/** #PH_KERNELIFCE_DEVICE_PATH inaccessible (kernel module not loaded?). */
#define PH_ERR_KERNELIFCE_DEVICE 7U

/** #PH_KERNELIFCE_DEVICE_PATH ioctl failed. */
#define PH_ERR_KERNELIFCE_IOCTL 8U

/** Unknown out of bounds namespace id. Internal error. */
#define PH_ERR_KERNELIFCE_BAD_NAMESPACE_ID 9U

/** Unknown out of bounds function id. Internal error. */
#define PH_ERR_KERNELIFCE_BAD_FUNC_ID 10U

/** Unknown error. */
#define PH_ERR_KERNELIFCE_UNKNOWN 11U

/** Memory access violation. */
#define PH_ERR_KERNELIFCE_FAULT 12U

/** Namespace or function name longer than #PH_KERNELIFCE_MAX_NAME_LEN. */
#define PH_ERR_KERNELIFCE_NAME_TOO_LONG 13U


/*********************************************************************
* EXPORTED TYPEDEFS                      [p]phKernelIfce_<Word>+_t       *
**********************************************************************/

/** Namespace. */
typedef struct phKernelIfce_NameSpace {
    char *name;
    /** ID of this namespace.
    When declaring a variable of this struct type set this
    to #PH_KERNELIFCE_UNINITIALISED. */
    int id;
} phKernelIfce_NameSpace_t;

/** Pointer to phKernelIfce_NameSpace_t. */
typedef phKernelIfce_NameSpace_t *pphKernelIfce_NameSpace_t;

/** Function within a namespace. */
typedef struct phKernelIfce_Func {
    pphKernelIfce_NameSpace_t pNameSpace;
    char *name;
    /** ID of this function.
    When declaring a variable of this struct type set this
    to #PH_KERNELIFCE_UNINITIALISED. */
    int id;
} phKernelIfce_Func_t;

/** Pointer to phKernelIfce_Func_t. */
typedef phKernelIfce_Func_t *pphKernelIfce_Func_t;

/** Common generic part of a structure used to pass information about
    a call from userspace (via phKernelIfce_Call()) to kernelspace, and viceversa.
*/
typedef struct phKernelIfce_CallData {
    /** Length in bytes of an actual runtime instance of calldata buffer. */
    size_t len;
    /** Points to the descriptor of the function. */
    pphKernelIfce_Func_t pFunc;
    /** On return from a phKernelIfce_Call() phKernelIfce will store
     * any phKernelIfce framework-related error code, for example
     * #PH_ERR_KERNELIFCE_BAD_FUNC_ID. */
    tmErrorCode_t err;
} phKernelIfce_CallData_t;

typedef phKernelIfce_CallData_t *pphKernelIfce_CallData_t;

/**************************************************************************
* EXPORTED DATA                     g[k|p|kp|pk|kpk]phKernelIfce_<Word>+      *
***************************************************************************/

/****************************************************************************
* EXPORTED FUNCTION PROTOTYPES                    phKernelIfce[_<Word>+]        *
*****************************************************************************/

/******************************************************************************/

#endif /* PHKERNELIFCE_COMMON_H      Do not add any thing below this line */
