/*
 * mckernel.h
 *
 * 32-bit Motion Control Device Driver
 *
 * Definition of interface between hardware-specific portions of
 * kernel driver and the helper library mckernel.lib
 *
 * The hardware-specific portion of a motion control driver will
 * have an NT-specific DriverEntry function that will call Init()
 * to initialise the helper library after performing hardware detect and
 * initialise. All NT interaction will then be done by the library mckernel.lib
 * calling back to the hardware-specific code only through the dispatch
 * table below.
 *
 * All h/w specific functions are given a pointer to a PDEVICE_INFO structure
 * which they can pass to Inp(), Outp(). GetHWInfo() will return a
 * pointer to the hardware-specific data structure requested from Init().
 *
 */

#ifndef _MCKERNEL_
  #define _MCKERNEL_

/* include necessary headers so that hardware-specific callers do not
 * explicitly reference NT-specific headers.
 */

  #if defined(_NT)
    #include <ntddk.h>
  #else
typedef long NTSTATUS;
  #endif

  #include <windef.h>
  #include <mcstruct.h>
  #include <mioctl.h>

#ifdef _OLD_DLL
  #define PT_PMAC1  1
  #define PT_PMAC2  2
  #define PT_PMACUL 3
  #define PT_PMAC   4
  #define PT_PMAC1T 5
  #define PT_PMAC2T 6
  #define PT_PMACUT 7
  #define PT_UMAC   8
#endif

/*****************************************************************************
 * hardware-independent device-extension data structure - opaque to
 * h/w specific functions.
*****************************************************************************/
typedef struct _DEVICE_INFO DEVICE_INFO, *PDEVICE_INFO;

/*****************************************************************************
 Callbacks to h/w specific code

 These are the hardware-specific functions called from the dispatcher
*****************************************************************************/
typedef struct __CALLBACK
{
  // called on device open/close - optional routines
  BOOLEAN (*DeviceOpenFunc)(PDEVICE_INFO);
  BOOLEAN (*DeviceCloseFunc)(PDEVICE_INFO);
  BOOLEAN (*InterruptInitFunc)(PDEVICE_INFO pDevInfo, ULONG interruptMask);
  BOOLEAN (*InterruptTermFunc)(PDEVICE_INFO);

  // returns TRUE if Interrupt needs Service
  ULONG   (*InterruptAcknowledge)(PDEVICE_INFO);

  // called on driver-unload
  BOOLEAN (*CleanupFunc)(PDEVICE_INFO);

} _CALLBACK, * P_CALLBACK;

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

 Support functions for NT
*****************************************************************************/
  #if defined(_NT)
/*
 * PmacCreateDevice
 *
 * Create the device object, and any necessary related setup, and
 * allocate device extension data. The device extension data is
 * a DEVICE_INFO struct plus however much data the caller wants for
 * hardware-specific data.
 *
 * parameters:
 *  pDriverObject - pointer to driver object (arg to DriverEntry)
 *  RegistryPathName - entry for this driver in registry (arg to DriverEntry)
 *  HWInfoSize - amount of data to allocate at end of DeviceExtension
 *  DeviceNumber - the nth Pmac to create a device object for
 *
 * returns pointer to device extension data as DEVICE_INFO struct.
 */
PDEVICE_OBJECT
  PmacCreateDevice(
      PDRIVER_OBJECT  pDriverObject,
      PUNICODE_STRING RegistryPathName,
      ULONG           HWInfoSize,
    UCHAR           DeviceNumber);

PDEVICE_INFO PmacDeleteDevice(PDRIVER_OBJECT  pDriverObject,PDEVICE_INFO pDevInfo);

/*
 * GetResources
 *
 * map port and frame buffer into system address space or i/o space, and
 * report resource usage of the ports, interrupt and physical memory
 * address used.
 *
 * Note: We do not connect the interrupt: this is not done until
 * a subsequent call to ConnectInterrupt(). We do, however, report
 * usage of the interrupt.
 *
 * we return TRUE if success, or FALSE if we couldn't get the resources.
 */
BOOLEAN
  GetResources(
      PDEVICE_INFO pDevInfo,
      PDRIVER_OBJECT pDriverObject,
      DWORD  PortBase,
      ULONG   NrOfPorts,
      ULONG   Interrupt,
      BOOLEAN bLatched,
      DWORD   FrameBuffer);

// the dispatch routine to which all IRPs go
NTSTATUS Dispatch(
    IN PDEVICE_OBJECT pDeviceObject,
    IN PIRP pIrp
);


// cancel routine - set as cancel routine for pending irps (wait-error
// or add-buffer). Called to de-queue and complete them if cancelled.
VOID Cancel(
    IN PDEVICE_OBJECT pDeviceObject,
    IN PIRP pIrp
);

// call to unload or abort load of the driver
VOID Cleanup(PDRIVER_OBJECT pDriverObject);

/* interrupt service routine - returns TRUE if interrupt handled.
 * all interrupts come in here and are then dispatched to hw ack routine
 * the Context pointer is a pointer to DEVICE_INFO.
 */
BOOLEAN
  InterruptService(
      IN PKINTERRUPT pInterruptObject,
      IN PVOID Context
  );

/*
 * DPC routine scheduled in MC_InterruptService.
 */
VOID
  Deferred(
      PKDPC pDpc,
      PDEVICE_OBJECT pDeviceObject,
      PIRP pIrpNotUsed,
      PVOID Context
  );

/*
 * extract the next item from a cancellable queue of irps
 * if bCancelHeld is true, then we already hold the cancel spinlock so we
 * should not try to get it
 */
PIRP
  ExtractNextIrp(
      PLIST_ENTRY pQueueHead,
      BOOLEAN bCancelHeld
  );

/*
 * extract a specific IRP from the given queue, while possibly holding the
 * cancel spinlock already.
 */
PIRP
  ExtractThisIrp(
      PLIST_ENTRY pHead,
      PIRP pIrpToFind,
      BOOLEAN bCancelHeld
  );

/*
 * interlocked queue access functions
 */
/*
 * QueueRequest
 *
 * Add an irp to a cancellable queue.
 * Check the cancel flag and return FALSE if cancelled.
 * otherwise set the cancel routine and add to queue.
 *
 */
BOOLEAN
  QueueRequest(
      PIRP pIrp,
      PLIST_ENTRY pQueueHead,
      PDRIVER_CANCEL pCancelFunc
  );

/*
 * ReplaceRequest
 *
 * return a request to the head of a cancellable queue
 *
 */
BOOLEAN
  ReplaceRequest(
      PIRP pIrp,
      PLIST_ENTRY pQueueHead,
      PDRIVER_CANCEL pCancelFunc
  );


/*
 * increment the skipcount, and complete a wait-error irp if there
 * is one waiting.
 */
VOID
  ReportSkip(
      PDEVICE_INFO pDevInfo
  );

/*
 * queue a wait-error request to the queue of cancellable wait-error requests,
 * and return the irp's status (pending, cancelled, etc);
 *
 * When queuing, check the cancel flag and insert the correct cancel routine.
 *
 * If there is a skip-count to report, then:
 *   --- if there is another irp on the q already complete that and leave
 *       the current irp pending.
 *   -- otherwise return STATUS_SUCCESSFUL for this IRP, having written out
 *      the result data.
 *
 * Even if cancelled or complete, IoCompleteRequest will NOT have been called
 * for this request.
 */
NTSTATUS
QueueWaitError(
    PDEVICE_INFO pDevInfo,
    PIRP pIrp
);

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

*****************************************************************************/
  #endif // _NT

/*
 * ConnectInterrupt
 *
 * This assumes that GetResources() has already been called to report the
 * resource usage, and that the _CALLBACK table has been set up
 * to handle interrupts.
 *
 * returns TRUE if success.
 */
BOOLEAN ConnectInterrupt(
    PDEVICE_INFO pDevInfo,