File diff 85642093068c → 91e0d39c9812
BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_char_legacy.h
Show inline comments
 
new file 100644
 
/* **********************************************************
 
 * Copyright 2012 VMware, Inc.  All rights reserved.
 
 * **********************************************************/
 

	
 
/*
 
 * @VMKAPIMOD_LICENSE@
 
 */
 

	
 
/*
 
 ***********************************************************************
 
 * Character Devices                                              */ /**
 
 * \addtogroup CharDev 
 
 *
 
 * Interfaces that allow registration of generic vmkernel character
 
 * device nodes.
 
 *
 
 * @{
 
 ***********************************************************************
 
 */
 

	
 
#ifndef _VMKAPI_CHAR_LEGACY_H_
 
#define _VMKAPI_CHAR_LEGACY_H_
 

	
 
/** \cond never */
 
#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H
 
#error This vmkapi file should never be included directly but only via vmkapi.h
 
#endif
 
/** \endcond never */
 

	
 
/**
 
 * \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)
 

	
 
/**
 
 ***********************************************************************
 
 * 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.
 
 *
 
 * \nativedriversdisallowed
 
 *
 
 * \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.
 
 * 
 
 * \nativedriversdisallowed
 
 * \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);
 

	
 
#endif /* _VMKAPI_CHAR_LEGACY_H_ */
 
/** @} */