448 lines
17 KiB
C
448 lines
17 KiB
C
/* **********************************************************
|
|
* Copyright 1998 - 2010 VMware, Inc. All rights reserved.
|
|
* **********************************************************/
|
|
|
|
/*
|
|
* @VMKAPIMOD_LICENSE@
|
|
*/
|
|
|
|
/*
|
|
***********************************************************************
|
|
* Character Devices */ /**
|
|
* \defgroup CharDev Character Devices
|
|
*
|
|
* Interfaces that allow management of vmkernel's UNIX-like character
|
|
* device nodes.
|
|
*
|
|
* @{
|
|
***********************************************************************
|
|
*/
|
|
|
|
#ifndef _VMKAPI_CHAR_H_
|
|
#define _VMKAPI_CHAR_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 */
|
|
|
|
/*
|
|
* UNIX-style open flags supported for character devices
|
|
*/
|
|
/** \brief Read-only. */
|
|
#define VMK_CHARDEV_OFLAG_RDONLY 0x00000000
|
|
|
|
/** \brief Write-only. */
|
|
#define VMK_CHARDEV_OFLAG_WRONLY 0x00000001
|
|
|
|
/** \brief Read-write. */
|
|
#define VMK_CHARDEV_OFLAG_RDWR 0x00000002
|
|
|
|
/** \brief Mask for read/write flags. */
|
|
#define VMK_CHARDEV_OFLAG_RDWR_MASK 0x00000003
|
|
|
|
/** \brief Exclusive access. */
|
|
#define VMK_CHARDEV_OFLAG_EXCLUSIVE 0x00000080
|
|
|
|
/** \brief Append to end of file. Always set for writes */
|
|
#define VMK_CHARDEV_OFLAG_APPEND 0x00000400
|
|
|
|
/** \brief Don't block for file operations. */
|
|
#define VMK_CHARDEV_OFLAG_NONBLOCK 0x00000800
|
|
|
|
/** \brief Synchronous file operations. */
|
|
#define VMK_CHARDEV_OFLAG_SYNC 0x00001000
|
|
|
|
/** \brief Use direct I/O. */
|
|
#define VMK_CHARDEV_OFLAG_DIRECT 0x00004000
|
|
|
|
/** \brief Flags for poll entry point */
|
|
typedef enum vmk_PollEvent {
|
|
/** \brief No events are available */
|
|
VMKAPI_POLL_NONE = 0x00,
|
|
/** \brief The device is ready for reading */
|
|
VMKAPI_POLL_READ = 0x01,
|
|
/** \brief The device is ready for writing */
|
|
VMKAPI_POLL_WRITE = 0x04,
|
|
/** \brief The file was closed during polling for read status */
|
|
VMKAPI_POLL_RDHUP = 0x08,
|
|
/** \brief The file was closed during polling for write status */
|
|
VMKAPI_POLL_WRHUP = 0x10,
|
|
/** \brief The file is no longer valid */
|
|
VMKAPI_POLL_INVALID = 0x20,
|
|
} vmk_PollEvent;
|
|
|
|
|
|
/**
|
|
* \brief Character device's file descriptor's attibutes.
|
|
*/
|
|
typedef struct vmk_CharDevFdAttr {
|
|
/**
|
|
* \brief UNIX-style file flags used when opening the device
|
|
* from the host.
|
|
*/
|
|
vmk_uint32 openFlags;
|
|
|
|
/**
|
|
* \brief Client data associated with the device.
|
|
*
|
|
* This is device-specific data provided by the driver during
|
|
* registration.
|
|
*/
|
|
vmk_AddrCookie clientDeviceData;
|
|
|
|
/**
|
|
* \brief Client data associated with the file descriptor.
|
|
*
|
|
* May be used by the character driver to store information
|
|
* persistent across syscalls
|
|
*
|
|
* The field can be updated by the driver at any time during
|
|
* a syscall.
|
|
*/
|
|
vmk_AddrCookie clientInstanceData;
|
|
/* For use by the character device driver */
|
|
/* across open/ioctl/close calls */
|
|
} vmk_CharDevFdAttr;
|
|
|
|
/**
|
|
* \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_CharDevOpenFn -- */ /**
|
|
*
|
|
* \brief A character device driver's open callback.
|
|
*
|
|
* If the open operation indicates success, the reference count for
|
|
* the driver's module will be incremented, which will prevent the
|
|
* module from being unloaded until the file is closed. It is
|
|
* guaranteed that the driver's corresponding close callback will
|
|
* be invoked for this attr object in the future if the open call
|
|
* was successful (either when the user-space application closes the
|
|
* file or when the application itself is closed).
|
|
* If the open operation fails, no further operations for this attr
|
|
* object will be issued.
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
*
|
|
* \retval VMK_OK The open function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevOpenFn)(vmk_CharDevFdAttr *attr);
|
|
|
|
/**
|
|
***********************************************************************
|
|
* vmk_CharDevCloseFn -- */ /**
|
|
*
|
|
* \brief A character device driver's close callback.
|
|
*
|
|
* If the driver's close operation fails, it will not be retried. After
|
|
* executing the close callback, the driver module's reference count is
|
|
* decremented, which may make the module eligible for unloading (if no
|
|
* other outstanding references exist).
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
*
|
|
* \retval VMK_OK The close function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevCloseFn)(vmk_CharDevFdAttr *attr);
|
|
|
|
/**
|
|
***********************************************************************
|
|
* vmk_CharDevIoctlFn -- */ /**
|
|
*
|
|
* \brief A character device driver's ioctl callback.
|
|
*
|
|
* An ioctl callback may, depending on the convention of the ioctl
|
|
* command, return two status codes. One is the return value of the
|
|
* callback, and the other is returned via the result parameter.
|
|
* For non-VMware (driver-specific) ioctl commands, the return
|
|
* value only indicates whether or not the callback executed. In
|
|
* this case, which is the usual case for third-party modules, the result
|
|
* parameter's value indicates the integer status code that
|
|
* should be passed back to the user process.
|
|
*
|
|
* Note that the userData may be a pointer from either a 32-bit or
|
|
* a 64-bit process. The callerSize parameter instructs how the
|
|
* ioctl callback should interpret the userData in the case it is a
|
|
* pointer.
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
* \param[in] cmd Command code corresponding to the requested
|
|
* operation.
|
|
* \param[in,out] userData Opaque data passed by the user to the
|
|
* ioctl command. May be a user-space pointer.
|
|
* \param[in] callerSize The size (VMK_IOCTL_CALLER_32 or
|
|
* VMK_IOCTL_CALLER_64) of the calling
|
|
* process.
|
|
* \param[out] result The result of the ioctl command, to be
|
|
* passed to the user process.
|
|
*
|
|
* \retval VMK_OK The ioctl function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevIoctlFn)(vmk_CharDevFdAttr *attr,
|
|
unsigned int cmd,
|
|
vmk_uintptr_t userData,
|
|
vmk_IoctlCallerSize callerSize,
|
|
vmk_int32 *result);
|
|
|
|
/**
|
|
***********************************************************************
|
|
* vmk_CharDevReadFn -- */ /**
|
|
*
|
|
* \brief A character device driver's read callback.
|
|
*
|
|
* The buffer for a read callback is a user-space buffer and therefore
|
|
* must be written to indirectly using vmk_CopyToUser.
|
|
* A read callback must always indicate how many bytes have been read,
|
|
* even if an error was encountered during the read. The nature of the
|
|
* error is then reflected in the return status.
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
* \param[out] buffer User buffer of bytes to write to.
|
|
* \param[in] nbytes Number of bytes to read.
|
|
* \param[in] ppos Offset associated with this read request.
|
|
* \param[out] nread Number of bytes read.
|
|
*
|
|
* \retval VMK_OK The read function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevReadFn)(vmk_CharDevFdAttr *attr,
|
|
char *buffer,
|
|
vmk_ByteCount nbytes,
|
|
vmk_loff_t *ppos,
|
|
vmk_ByteCountSigned *nread);
|
|
|
|
/**
|
|
***********************************************************************
|
|
* vmk_CharDevWriteFn -- */ /**
|
|
*
|
|
* \brief A character device driver's write callback.
|
|
*
|
|
* The buffer for a write callback is a user-space buffer and therefore
|
|
* must be read from indirectly using vmk_CopyFromUser.
|
|
* A write callback must always indicate how many bytes have been written,
|
|
* even if an error was encountered during the write. The nature of the
|
|
* error is then reflected in the return status.
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
* \param[in] buffer User buffer of bytes to read from.
|
|
* \param[in] nbytes Number of bytes to write.
|
|
* \param[in] ppos Offset associated with this write request.
|
|
* \param[out] nwritten Number of bytes written.
|
|
*
|
|
* \retval VMK_OK The write function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevWriteFn)(vmk_CharDevFdAttr *attr,
|
|
char *buffer,
|
|
vmk_ByteCount nbytes,
|
|
vmk_loff_t *ppos,
|
|
vmk_ByteCountSigned *nwritten);
|
|
|
|
/**
|
|
***********************************************************************
|
|
* vmk_CharDevPollFn -- */ /**
|
|
*
|
|
* \brief A character device driver's poll callback.
|
|
*
|
|
* \note This callback is permitted to block.
|
|
*
|
|
* \param[in] attr File-descriptor attributes for this operation.
|
|
* \param[in] pollCtx Poll context of the calling thread. This
|
|
* is an opaque handle supplied by the kernel.
|
|
* The driver must associate a globally unique
|
|
* token (such as a pointer) of its choosing
|
|
* with this poll context using
|
|
* vmk_CharDevSetPollContext. Poll wakeups
|
|
* are thus performed, later, using
|
|
* vmk_CharDevWakePollers by supplying that
|
|
* driver-chosen token.
|
|
* \param[out] pollMask Bitmask of vmk_PollEvent indicators
|
|
* reflecting the current status of the
|
|
* character device.
|
|
*
|
|
* \retval VMK_OK The poll function completed successfully.
|
|
* \retval Other The call failed and the error will be passed to
|
|
* the user.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
typedef VMK_ReturnStatus (*vmk_CharDevPollFn)(vmk_CharDevFdAttr *attr,
|
|
vmk_PollContext pollCtx,
|
|
unsigned *pollMask);
|
|
|
|
/**
|
|
* \brief Character device driver's entry points
|
|
*/
|
|
typedef struct vmk_CharDevOps {
|
|
vmk_CharDevOpenFn open;
|
|
vmk_CharDevCloseFn close;
|
|
vmk_CharDevIoctlFn ioctl;
|
|
vmk_CharDevPollFn poll;
|
|
vmk_CharDevReadFn read;
|
|
vmk_CharDevWriteFn write;
|
|
} vmk_CharDevOps;
|
|
|
|
/**
|
|
***********************************************************************
|
|
* 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);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_CharDevWakePollers -- */ /**
|
|
*
|
|
* \brief Wake up all users waiting on a poll call with the specified
|
|
* token.
|
|
*
|
|
* \param[in] token Context on which worlds are waiting.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
void vmk_CharDevWakePollers(vmk_PollToken token);
|
|
|
|
/*
|
|
***********************************************************************
|
|
* vmk_CharDevSetPollContext -- */ /**
|
|
*
|
|
* \brief Set the poll context of the calling world to the specified
|
|
* context.
|
|
*
|
|
* \param[in] pollCtx The poll context of the calling thread.
|
|
* \param[out] token The token to set in the poll context.
|
|
*
|
|
***********************************************************************
|
|
*/
|
|
void vmk_CharDevSetPollContext(vmk_PollContext pollCtx, vmk_PollToken *token);
|
|
|
|
#endif /* _VMKAPI_CHAR_H_ */
|
|
/** @} */
|