43
43
#endif // linux && !VMKERNEL
47
* We use the same value for the AF family and the socket option
48
* level. To set options, use the value of VMCISock_GetAFValue for
49
* 'level' and these constants for the optname.
47
* \brief Option name for STREAM socket buffer size.
49
* Use as the option name in \c setsockopt(3) or \c getsockopt(3) to set
50
* or get an \c unsigned \c long \c long that specifies the size of the
51
* buffer underlying a vSockets STREAM socket.
53
* \note Value is clamped to the MIN and MAX.
55
* \see VMCISock_GetAFValueFd()
56
* \see SO_VMCI_BUFFER_MIN_SIZE
57
* \see SO_VMCI_BUFFER_MAX_SIZE
59
* An example is given below.
63
* int af = VMCISock_GetAFValueFd(&vmciFd);
64
* unsigned long long val = 0x1000;
65
* int fd = socket(af, SOCK_STREAM, 0);
66
* setsockopt(fd, af, SO_VMCI_BUFFER_SIZE, &val, sizeof val);
69
* VMCISock_ReleaseAFValueFd(vmciFd);
52
73
#define SO_VMCI_BUFFER_SIZE 0
76
* \brief Option name for STREAM socket minimum buffer size.
78
* Use as the option name in \c setsockopt(3) or \c getsockopt(3) to set
79
* or get an \c unsigned \c long \c long that specifies the minimum size
80
* allowed for the buffer underlying a vSockets STREAM socket.
82
* \see VMCISock_GetAFValueFd()
83
* \see SO_VMCI_BUFFER_SIZE
84
* \see SO_VMCI_BUFFER_MAX_SIZE
86
* An example is given below.
90
* int af = VMCISock_GetAFValueFd(&vmciFd);
91
* unsigned long long val = 0x500;
92
* int fd = socket(af, SOCK_STREAM, 0);
93
* setsockopt(fd, af, SO_VMCI_BUFFER_MIN_SIZE, &val, sizeof val);
96
* VMCISock_ReleaseAFValueFd(vmciFd);
53
100
#define SO_VMCI_BUFFER_MIN_SIZE 1
103
* \brief Option name for STREAM socket maximum buffer size.
105
* Use as the option name in \c setsockopt(3) or \c getsockopt(3) to set or
106
* get an unsigned long long that specifies the maximum size allowed for the
107
* buffer underlying a vSockets STREAM socket.
109
* \see VMCISock_GetAFValueFd()
110
* \see SO_VMCI_BUFFER_SIZE
111
* \see SO_VMCI_BUFFER_MIN_SIZE
113
* An example is given below.
117
* int af = VMCISock_GetAFValueFd(&vmciFd);
118
* unsigned long long val = 0x4000;
119
* int fd = socket(af, SOCK_STREAM, 0);
120
* setsockopt(fd, af, SO_VMCI_BUFFER_MAX_SIZE, &val, sizeof val);
123
* VMCISock_ReleaseAFValueFd(vmciFd);
54
127
#define SO_VMCI_BUFFER_MAX_SIZE 2
130
* \brief Option name for socket peer's host-specific VM ID.
132
* Use as the option name in \c getsockopt(3) to get a host-specific identifier
133
* for the peer endpoint's VM. The identifier is a signed integer.
135
* \note Only available for ESX (VMKernel/userworld) endpoints.
137
* An example is given below.
141
* int af = VMCISock_GetAFValueFd(&vmciFd);
143
* socklen_t len = sizeof id;
144
* int fd = socket(af, SOCK_DGRAM, 0);
145
* getsockopt(fd, af, SO_VMCI_PEER_HOST_VM_ID, &id, &len);
148
* VMCISock_ReleaseAFValueFd(vmciFd);
55
152
#define SO_VMCI_PEER_HOST_VM_ID 3
155
* \brief Option name for socket's service label.
157
* Use as the option name in \c setsockopt(3) or \c getsockopt(3) to set or
158
* get the service label for a socket. The service label is a C-style
159
* NUL-terminated string.
161
* \note Only available for ESX (VMkernel/userworld) endpoints.
56
164
#define SO_VMCI_SERVICE_LABEL 4
167
* \brief Option name for determining if a socket is trusted.
169
* Use as the option name in \c getsockopt(3) to determine if a socket is
170
* trusted. The value is a signed integer.
172
* An example is given below.
176
* int af = VMCISock_GetAFValueFd(&vmciFd);
178
* socklen_t len = sizeof trusted;
179
* int fd = socket(af, SOCK_DGRAM, 0);
180
* getsockopt(fd, af, SO_VMCI_TRUSTED, &trusted, &len);
183
* VMCISock_ReleaseAFValueFd(vmciFd);
57
187
#define SO_VMCI_TRUSTED 5
190
* \brief Option name for STREAM socket connection timeout.
192
* Use as the option name in \c setsockopt(3) or \c getsockopt(3) to set or
193
* get the connection timeout for a STREAM socket. The value is platform
194
* dependent. On ESX, Linux and Mac OS, it is a \c struct \c timeval.
195
* On Windows, it is a \c DWORD.
197
* An example is given below.
201
* int af = VMCISock_GetAFValueFd(&vmciFd);
202
* struct timeval t = { 5, 100000 }; // 5.1 seconds
203
* int fd = socket(af, SOCK_STREAM, 0);
204
* setsockopt(fd, af, SO_VMCI_CONNECT_TIMEOUT, &t, sizeof t);
207
* VMCISock_ReleaseAFValueFd(vmciFd);
58
211
#define SO_VMCI_CONNECT_TIMEOUT 6
214
* \brief Option name for using non-blocking send/receive.
216
* Use as the option name for \c setsockopt(3) or \c getsockopt(3) to set or
217
* get the non-blocking transmit/receive flag for a STREAM socket. This flag
218
* determines whether \c send() and \c recv() can be called in non-blocking
219
* contexts for the given socket. The value is a signed integer.
221
* This option is only relevant to kernel endpoints, where descheduling
222
* the thread of execution is not allowed, for example, while holding a
223
* spinlock. It is not to be confused with conventional non-blocking socket
226
* \note Only available for VMKernel endpoints.
228
* An example is given below.
232
* int af = VMCISock_GetAFValueFd(&vmciFd);
234
* socklen_t len = sizeof nonblock;
235
* int fd = socket(af, SOCK_STREAM, 0);
236
* getsockopt(fd, af, SO_VMCI_NONBLOCK_TXRX, &nonblock, &len);
239
* VMCISock_ReleaseAFValueFd(vmciFd);
59
243
#define SO_VMCI_NONBLOCK_TXRX 7
62
* The VMCI sockets address equivalents of INADDR_ANY. The first works for
63
* the svm_cid (context id) field of the address structure below and indicates
64
* the current guest (or the host, if running outside a guest), while the
65
* second indicates any available port.
246
* \brief The vSocket equivalent of INADDR_ANY.
248
* This works for the \c svm_cid field of sockaddr_vm and indicates the
249
* context ID of the current endpoint.
253
* An example is given below.
257
* int af = VMCISock_GetAFValueFd(&vmciFd);
258
* struct sockaddr_vm addr;
259
* int fd = socket(af, SOCK_DGRAM, 0);
260
* addr.svm_family = af;
261
* addr.svm_cid = VMADDR_CID_ANY;
262
* addr.svm_port = 2000;
263
* bind(fd, &addr, sizeof addr);
266
* VMCISock_ReleaseAFValueFd(vmciFd);
68
270
#define VMADDR_CID_ANY ((unsigned int)-1)
273
* \brief Bind to any available port.
275
* Works for the \c svm_port field of sockaddr_vm.
279
* An example is given below.
283
* int af = VMCISock_GetAFValueFd(&vmciFd);
284
* struct sockaddr_vm addr;
285
* int fd = socket(af, SOCK_DGRAM, 0);
286
* addr.svm_family = af;
287
* addr.svm_cid = VMADDR_CID_ANY;
288
* addr.svm_port = VMADDR_PORT_ANY;
289
* bind(fd, &addr, sizeof addr);
292
* VMCISock_ReleaseAFValueFd(vmciFd);
69
296
#define VMADDR_PORT_ANY ((unsigned int)-1)
72
/* Invalid VMCI sockets version. */
299
* \brief Invalid vSockets version.
301
* \see VMCISock_Version()
74
304
#define VMCI_SOCKETS_INVALID_VERSION ((unsigned int)-1)
77
* Use these macros with the result of VMCISock_Version() to get the
78
* component parts of a valid version.
307
* \brief The epoch (first) component of the vSockets version.
309
* A single byte representing the epoch component of the vSockets version.
311
* \see VMCISock_Version()
313
* An example is given below.
316
* unsigned int ver = VMCISock_Version();
317
* unsigned char epoch = VMCI_SOCKETS_VERSION_EPOCH(ver);
81
321
#define VMCI_SOCKETS_VERSION_EPOCH(_v) (((_v) & 0xFF000000) >> 24)
324
* \brief The major (second) component of the vSockets version.
326
* A single byte representing the major component of the vSockets version.
327
* Typically changes for every major release of a product.
329
* \see VMCISock_Version()
331
* An example is given below.
334
* unsigned int ver = VMCISock_Version();
335
* unsigned char major = VMCI_SOCKETS_VERSION_MAJOR(ver);
82
339
#define VMCI_SOCKETS_VERSION_MAJOR(_v) (((_v) & 0x00FF0000) >> 16)
342
* \brief The minor (third) component of the vSockets version.
344
* Two bytes representing the minor component of the vSockets version.
346
* \see VMCISock_Version()
348
* An example is given below.
351
* unsigned int ver = VMCISock_Version();
352
* unsigned short minor = VMCI_SOCKETS_VERSION_MINOR(ver);
83
356
#define VMCI_SOCKETS_VERSION_MINOR(_v) (((_v) & 0x0000FFFF))
85
/* Missing types for some platforms. */
87
359
#if defined(_WIN32) || defined(VMKERNEL)
88
360
typedef unsigned short sa_family_t;
179
496
# elif defined(__APPLE__) && (KERNEL)
180
497
/* Nothing to define here. */
181
498
# else // __KERNEL__
182
# include <sys/types.h>
183
# include <sys/stat.h>
184
499
# include <fcntl.h>
185
502
# include <sys/ioctl.h>
503
# include <sys/stat.h>
504
# include <sys/types.h>
186
505
# include <unistd.h>
190
508
# define VMCI_SOCKETS_DEFAULT_DEVICE "/dev/vsock"
191
509
# define VMCI_SOCKETS_CLASSIC_ESX_DEVICE "/vmfs/devices/char/vsock/vsock"
194
# define VMCI_SOCKETS_VERSION 1972
195
# define VMCI_SOCKETS_GET_AF_VALUE 1976
196
# define VMCI_SOCKETS_GET_LOCAL_CID 1977
197
# elif defined(__APPLE__)
198
# include <sys/ioccom.h>
199
# define VMCI_SOCKETS_VERSION _IOR('V', 21, unsigned)
200
# define VMCI_SOCKETS_GET_AF_VALUE _IOR('V', 25 , int)
201
# define VMCI_SOCKETS_GET_LOCAL_CID _IOR('V', 26 , unsigned)
511
# define VMCI_SOCKETS_VERSION 1972
512
# define VMCI_SOCKETS_GET_AF_VALUE 1976
513
# define VMCI_SOCKETS_GET_LOCAL_CID 1977
514
# define VMCI_SOCKETS_UUID_2_CID 1991
515
# elif defined(__APPLE__)
516
# include <sys/ioccom.h>
517
# define VMCI_SOCKETS_VERSION _IOR( 'V', 21, unsigned)
518
# define VMCI_SOCKETS_GET_AF_VALUE _IOR( 'V', 25, int)
519
# define VMCI_SOCKETS_GET_LOCAL_CID _IOR( 'V', 26, unsigned)
520
# define VMCI_SOCKETS_UUID_2_CID _IOWR('V', 40, struct uuid_2_cid)
525
***********************************************************************
526
* VMCISock_Version */ /**
528
* \brief Retrieve the vSockets version.
530
* Returns the current version of vSockets. The version is a 32-bit
531
* unsigned integer that consist of three components: the epoch, the
532
* major version, and the minor version. Use the \c VMCI_SOCKETS_VERSION
533
* macros to extract the components.
535
* \see VMCI_SOCKETS_VERSION_EPOCH()
536
* \see VMCI_SOCKETS_VERSION_MAJOR()
537
* \see VMCI_SOCKETS_VERSION_MINOR()
539
* \retval VMCI_SOCKETS_INVALID_VERSION Not available.
540
* \retval other The current version.
542
* An example is given below.
545
* unsigned int ver = VMCISock_Version();
546
* if (ver != VMCI_SOCKETS_INVALID_VERSION) {
547
* printf("vSockets version=%d.%d.%d\n",
548
* VMCI_SOCKETS_VERSION_EPOCH(ver),
549
* VMCI_SOCKETS_VERSION_MAJOR(ver),
550
* VMCI_SOCKETS_VERSION_MINOR(ver));
554
***********************************************************************
204
557
static inline unsigned int VMCISock_Version(void)
226
*----------------------------------------------------------------------------
228
* VMCISock_GetAFValue and VMCISock_GetAFValueFd --
230
* Returns the value to be used for the VMCI Sockets address family.
231
* This value should be used as the domain argument to socket(2) (when
232
* you might otherwise use AF_INET). For VMCI Socket-specific options,
233
* this value should also be used for the level argument to
234
* setsockopt(2) (when you might otherwise use SOL_TCP).
236
* This function leaves its descriptor to the vsock device open so that
237
* the socket implementation knows that the socket family is still in
238
* use. We do this because we register our address family with the
239
* kernel on-demand and need a notification to unregister the address
242
* For many programs this behavior is sufficient as is, but some may
243
* wish to close this descriptor once they are done with VMCI Sockets.
244
* For these programs, we provide a VMCISock_GetAFValueFd() that takes
245
* an optional outFd argument. This value can be provided to
246
* VMCISock_ReleaseAFValueFd() only after the program no longer will
247
* use VMCI Sockets. Note that outFd is only valid in cases where
248
* VMCISock_GetAFValueFd() returns a non-negative value.
251
* The address family value to use on success, negative error code on
254
*----------------------------------------------------------------------------
579
***********************************************************************
580
* VMCISock_GetAFValueFd */ /**
582
* \brief Retrieve the address family value for vSockets.
584
* Returns the value to be used for the VMCI Sockets address family.
585
* This value should be used as the domain argument to \c socket(2) (when
586
* you might otherwise use \c AF_INET). For VMCI Socket-specific options,
587
* this value should also be used for the level argument to
588
* \c setsockopt(2) (when you might otherwise use \c SOL_TCP).
590
* \see VMCISock_ReleaseAFValueFd()
593
* \param[out] outFd File descriptor to the VMCI device. The
594
* address family value is valid until this
595
* descriptor is closed. This parameter is
596
* only valid if the return value is not -1.
597
* Call VMCISock_ReleaseAFValueFd() to close
600
* \retval -1 Not available.
601
* \retval other The address family value.
603
* An example is given below.
607
* int af = VMCISock_GetAFValueFd(&vmciFd);
609
* int fd = socket(af, SOCK_STREAM, 0);
616
***********************************************************************
257
619
static inline int VMCISock_GetAFValueFd(int *outFd)
647
***********************************************************************
648
* VMCISock_GetAFValue */ /**
650
* \brief Retrieve the address family value for vSockets.
652
* Returns the value to be used for the VMCI Sockets address family.
653
* This value should be used as the domain argument to \c socket(2) (when
654
* you might otherwise use \c AF_INET). For VMCI Socket-specific options,
655
* this value should also be used for the level argument to
656
* \c setsockopt(2) (when you might otherwise use \c SOL_TCP).
658
* \note This function leaves its descriptor to the vsock device open so
659
* that the socket implementation knows that the socket family is still in
660
* use. This is done because the address family is registered with the
661
* kernel on-demand and a notification is needed to unregister the address
662
* family. Use of this function is thus discouraged; please use
663
* VMCISock_GetAFValueFd() instead.
665
* \see VMCISock_GetAFValueFd()
668
* \retval -1 Not available.
669
* \retval other The address family value.
671
* An example is given below.
674
* int af = VMCISock_GetAFValue();
676
* int fd = socket(af, SOCK_STREAM, 0);
682
***********************************************************************
283
685
static inline int VMCISock_GetAFValue(void)
285
687
return VMCISock_GetAFValueFd(NULL);
689
/** \endcond PRIVATE */
692
***********************************************************************
693
* VMCISock_ReleaseAFValueFd */ /**
695
* \brief Release the file descriptor obtained when retrieving the
696
* address family value.
698
* Use this to release the file descriptor obtained by calling
699
* VMCISock_GetAFValueFd().
701
* \see VMCISock_GetAFValueFd()
703
* \param[in] fd File descriptor to the VMCI device.
705
***********************************************************************
289
708
static inline void VMCISock_ReleaseAFValueFd(int fd)