* Copyright 1998 - 2010 VMware, Inc.  All rights reserved.

/** \brief Synchronous file operations. */

#define VMK_CHARDEV_OFLAG_SYNC         0x00001000

 * \brief Opaque handle to a character device.

typedef struct vmkCharDevInt* vmk_CharDev;

 * \brief A default initialization value for a vmk_CharDev.

#define VMK_INVALID_CHARDEV (NULL)

 * \brief Opaque poll token handle.

typedef void *vmk_PollToken;

 * \brief Opaque poll context handle.

typedef void *vmk_PollContext;

/**

 ***********************************************************************

 * vmk_CharDevCleanupFn --                                        */ /**

 *

 * \brief Prototype for a character device driver's cleanup callback.

 *

 * \param[in]  private  Optional private data to be used by the callback

 *

 * \retval VMK_OK The cleanup function executed correctly.

 *                This is not an indicator of the success or failure of

 *                the operations in the function, but merely that they

 *                ran.  Any other return value is not allowed.

 *

 ***********************************************************************

 */

typedef VMK_ReturnStatus (*vmk_CharDevCleanupFn)(vmk_AddrCookie private);

/*

 ***********************************************************************

 * vmk_CharDevRegister --                                         */ /**

 *

 * \brief Register the specified character device, to be invoked from

 *        user-space.

 *

 * \param[in]  module         Module that owns the character device.

 * \param[in]  name           The name of the device - this must be unique.

 * \param[in]  fileOps        Table of the driver file operations.

 *                            Neither open nor close can be supplied 

 *                            without the other.

 *                            If read or write operations are supplied, 

 *                            then open and close must also be supplied.

 * \param[in]  cleanup        Function automatically invoked to clean up

 *                            after all file ops have ceased and the 

 *                            device has been unregistered.  May be NULL.

 * \param[in]  devicePrivate  Data given to the driver for each file 

 *                            op and cleaned up after unregistration.

 * \param[out] assignedHandle Handle to the registered character device.

 *

 * \retval VMK_EXISTS         A device with that name is already registered

 * \retval VMK_FAILURE        Unable to allocate internal slot for the device

 * \retval VMK_NO_MEMORY      Unable to allocate memory for device metadata

 * \retval VMK_BAD_PARAM      Module ID was invalid, name was invalid,

 *                            or one or more specified driver ops are NULL

 *

 ***********************************************************************

 */

VMK_ReturnStatus vmk_CharDevRegister(

   vmk_ModuleID module,

   const char *name,

   const vmk_CharDevOps *fileOps,

   vmk_CharDevCleanupFn cleanup,

   vmk_AddrCookie devicePrivate,

   vmk_CharDev *assignedHandle);

/*

 ***********************************************************************

 * vmk_CharDevUnregister --                                       */ /**

 *

 * \brief Unregister a character device.

 *

 * The character device will be unregistered automatically by

 * the kernel only after all open files to the device have been

 * closed.  If no files are open when vmk_CharDevUnregister is

 * called, the device may be unregistered immediately and have the

 * cleanup function registered with it invoked.  If the device has 

 * files open, vmk_CharDevUnregister internally defers the device for 

 * later automatic removal and returns to the caller immediately.  When 

 * the last file is closed, the device will then be destroyed and the 

 * cleanup function invoked.

 * 

 * \note No new open files to the device can be created after calling

 *       vmk_CharDevUnregister.

 * \note The vmkernel will prevent a module from being unloaded while

 *       it has open files associated with a character device, even

 *       if that device has been requested to be unregistered.

 *

 * \param[in] deviceHandle Handle of device assigned during registration.

 *

 * \retval VMK_NOT_FOUND The device does not exist.

 * \retval VMK_OK The device was either unregistered or internally

 *                deferred for unregistration once all associated files

 *                close.

 *

 ***********************************************************************

 */

VMK_ReturnStatus vmk_CharDevUnregister(vmk_CharDev deviceHandle);