Files
@ d6b9b2ac5869
Branch filter:
Location: vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_char.h
d6b9b2ac5869
13.8 KiB
text/x-chdr
ESXi-5.5-U2
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 | /* **********************************************************
* Copyright 1998 - 2010,2012 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 File integerity for synchronous file I/O. */
#define VMK_CHARDEV_OFLAG_SYNC 0x00101000
/** \brief Data integrity for synchronous file I/O. */
#define VMK_CHARDEV_OFLAG_DSYNC 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 poll token handle.
*/
typedef void *vmk_PollToken;
/**
* \brief Opaque poll context handle.
*/
typedef void *vmk_PollContext;
/**
* \brief Identifier for logical graphics devices.
*/
#define VMK_CHARDEV_IDENTIFIER_GRAPHICS "com.vmware.graphics"
/**
* \brief Character device driver's entry points.
*/
struct vmk_CharDevOps;
/** \brief Character device registration data. */
typedef struct vmk_CharDevRegData {
/** \brief Module creating this device. */
vmk_ModuleID moduleID;
/** \brief Device operations. */
const struct vmk_CharDevOps *fileOps;
/** \brief Device private data. */
vmk_AddrCookie devicePrivate;
} vmk_CharDevRegData;
/**
***********************************************************************
* 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_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_ */
/** @} */
|