//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// Use of this source code is subject to the terms of the Microsoft end-user
// license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
// If you did not accept the terms of the EULA, you are not authorized to use
// this source code. For a copy of the EULA, please see the LICENSE.RTF on your
// install media.
//

/*++

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.

Module Name:

    utldrv.h

Abstract:

   Private header file. Defines the data structure for utility driver

Functions:

Notes:

--*/
#ifndef _UTLDRV_H_
#define _UTLDRV_H_


#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

//  call back function definition
typedef VOID (*PFN_PowerOnCallback)(void);

//  
//  Driver to driver fast call context
//
/*

pContext is the UTLDRV driver context returned from CreateFile(L"UTL0:", ...) call.
 
 DWORD GetRegisterVA(PVOID pContext, DWORD dwAddr, DWORD dwSize, BOOL bPA, DWORD *pPVA);
   
    This function helps drivers to get the virtual address for the CPU registers they 
    specified. 

        dwAddr  :   is the address of the register you want to get virtual address. Depending
                    on the bPA flag, it could be the K-Mode virtuall address or physical
                    address. 
        dwSize  :   Size of the memory.
        bPA     :   TRUE if the dwAddr is physical address. FALSE if it is K-Mode virtual 
                    address. 
        pVA     :   is the pointer to the process virtual address you want to use in your driver.

        Return Value: ERROR_SUCCESS if it is succeeds.
        
DWORD GetMemVA(PVOID pContext, DWORD dwAddr, DWORD dwSize, BOOL bPA, DWORD dwFlags, DWORD *pVA);

    This function helps drivers to get the virtual address for the specified SDRAM.

        dwAddr  :   the address for the SDRAM you want to get virtual address. Depending on
                    the bPA flag, it could be the K-Mode virtual address or physical address.
        dwSize  :   size of the memory
        bPA     :   TRUE if the dwAddr is physical addresss. FALSE if it is K-Mode virtual
                    address.
        dwFlags :   Memory flags as you would pass to VirtualCopy. 
        pVA     :   pointer to the process virtual address you requested.

        Return Value: ERROR_SUCCESS if it is succeeds.
        
DWORD FreeMemVA(PVOID pContext, DWORD pVA);

    This function frees the allocated process virtual memory. 
    
        pVA     :   this is the process virtual memory returned by GetMemVA function call.
        
(*) For registers, UTLDRV won't free the virtual address until UTLDRV itself exits.  

typedef VOID (*PFN_PowerOnCallback)(void);

4. DWORD RegisterStorageDrv(PVOID pContext, PFN_PowerOnCallback pfnCallback);

    This function registers the block driver to the UTL driver for PowerOn notification.

        pfnCallback: the callback function for UTLDRV to call when we come back from PowerOff. 

        Return Value: 0xFFFFFFFF if the function failed. Use GetLastError() for error code.
                      Otherwise, it returns an ID which can be used to call UnRegisterStorageDrv
                      function.

5. VOID UnRegisterStorageDrv(PVOID pContext, PFN_PowerOnCallback pfnCallback);

    This function un-registers the blcok driver from the UTL driver. 


 */
typedef struct _UTL_FASTCALL {
    PVOID   pContext;
    DWORD   (*GetRegisterVA)(PVOID pContext, DWORD dwAddr, DWORD dwSize, BOOL bPA, DWORD *pPVA);
    DWORD   (*GetMemVA)(PVOID pContext, DWORD dwAddr, DWORD dwSize, BOOL bPA, DWORD dwFlags, DWORD *pPVA);
    DWORD   (*FreeMemVA)(PVOID pContext, DWORD pPVA);
    DWORD   (*RegisterBlockDrv)(PVOID pContext, PFN_PowerOnCallback);
    DWORD   (*UnRegisterBlockDrv)(PVOID pContext, PFN_PowerOnCallback);
} UTL_FASTCALL, *PUTL_FASTCALL;

//
//  Utility Ioctl
//
#define FILE_DEVICE_UTL FILE_DEVICE_CONTROLLER

//  OUT: UTL_FASTCALL
#define IOCTL_UTL_GET_FASTCALL  \
    CTL_CODE(FILE_DEVICE_UTL, 2, METHOD_BUFFERED, FILE_ANY_ACCESS)


#ifdef __cplusplus
}
#endif // __cplusplus


#endif // _UTLDRV_H_