intnet.h revision d7d9af8101b599f4118ff4326c046cc322f9763c
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * INETNET - Internal Networking.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Copyright (C) 2006 InnoTek Systemberatung GmbH
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * available from http://www.virtualbox.org. This file is free software;
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * you can redistribute it and/or modify it under the terms of the GNU
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * General Public License as published by the Free Software Foundation,
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * If you received this file as part of a commercial VirtualBox
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * distribution, then only the terms of your commercial VirtualBox
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * license agreement apply instead of the previous paragraph.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Generic two-sided ring buffer.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The deal is that there is exactly one writer and one reader.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * When offRead equals offWrite the buffer is empty. In the other
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * extreme the writer will not use the last free byte in the buffer.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The start of the buffer offset relative to the. (inclusive) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The offset to the end of the buffer. (exclusive) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The current read offset. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The current write offset. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to a ring buffer. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Get the amount of space available for writing.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns Number of available bytes.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pRingBuf The ring buffer.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncDECLINLINE(uint32_t) INTNETRingGetWritable(PINTNETRINGBUF pRingBuf)
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync ? pRingBuf->offEnd - pRingBuf->offWrite + pRingBuf->offRead - pRingBuf->offStart - 1
9dfcf62b7a5a289684d46ee55f6042d49509daecvboxsync * Get the amount of data ready for reading.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns Number of ready bytes.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pRingBuf The ring buffer.
49e54e2ffe0c10864d06e9d1ebe24a8eb1327a6bvboxsyncDECLINLINE(uint32_t) INTNETRingGetReadable(PINTNETRINGBUF pRingBuf)
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync : pRingBuf->offEnd - pRingBuf->offRead + pRingBuf->offWrite - pRingBuf->offStart;
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * A interface buffer.
e214bb78026c1d64078b34ca9504d3f5abbc52efvboxsynctypedef struct INTNETBUF
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the entire buffer. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the send area. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the receive area. */
91f8453d16b48876deddaba298c211071d0ca3a5vboxsync /** The receive buffer. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The send buffer. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of times yields help solve an overflow. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of times yields didn't help solve an overflow. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of lost packets due to overflows. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of packets received (not counting lost ones). */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of frame bytes received (not couting lost frames). */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Number of packets received. */
a59528c40bbfdcee2e315756333f8c66f35b5accvboxsync /** Number of frame bytes sent. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Internal networking interface handle. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to an internal networking interface handle. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Or mask to obscure the handle index. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Mask to extract the handle index. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** The maximum number of handles (exclusive) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Invalid handle. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The packet header.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The header is intentionally 8 bytes long. It will always
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * start at an 8 byte aligned address. Assuming that the buffer
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * size is a multiple of 8 bytes, that means that we can guarantee
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * that the entire header is contiguous in both virtual and physical
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsynctypedef struct INTNETHDR
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Header type. This is currently serving as a magic, it
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * can be extended later to encode special command packets and stuff.. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the frame. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The offset from the start of this header to where the actual frame starts.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * This is used to keep the frame it self continguous in virtual memory and
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * thereby both simplify reading and */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** INTNETHDR::u16Type value for normal frames. */
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * Calculates the pointer to the frame.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns Pointer to the start of the frame.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pHdr Pointer to the packet header
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pBuf The buffer the header is within. Only used in strict builds.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncDECLINLINE(void *) INTNETHdrGetFramePtr(PINTNETHDR pHdr, PINTNETBUF pBuf)
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync const uintptr_t off = (uintptr_t)pu8 - (uintptr_t)pBuf;
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Skips to the next (read) frame in the buffer.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pBuf The buffer.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pRingBuf The ring buffer in question.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncDECLINLINE(void) INTNETRingSkipFrame(PINTNETBUF pBuf, PINTNETRINGBUF pRingBuf)
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync PINTNETHDR pHdr = (PINTNETHDR)((uint8_t *)pBuf + offRead);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /* skip the frame */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync Assert(offRead <= pRingBuf->offEnd && offRead >= pRingBuf->offStart);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** The maximum length of a network name. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The packed down arguments of INTNETR0Open().
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @see INTNETR0Open()
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The network name. (input) */
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync /** The size of the send buffer. (input) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the receive buffer. (input) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Whether new participants should be subjected to access check or not. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The handle to the network interface. (output) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to an INTNETR0Open() argument package. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The packed down arguments of INTNETR0IfClose().
9dfcf62b7a5a289684d46ee55f6042d49509daecvboxsync * @see INTNETR0IfClose()
9dfcf62b7a5a289684d46ee55f6042d49509daecvboxsync /** The handle to the network interface. */
9dfcf62b7a5a289684d46ee55f6042d49509daecvboxsync/** Pointer to an INTNETR0Open() argument package. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Argument buffer for calling INTNETR0IfGetRing3Buffer().
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @see INTNETR0IfGetRing3Buffer()
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync /** Handle to the interface. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The pointer to the ring3 buffer. (output) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to an INTNETR0IfGetRing3Buffer() argument package. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsynctypedef INTNETIFGETRING3BUFFERARGS *PINTNETIFGETRING3BUFFERARGS;
49e54e2ffe0c10864d06e9d1ebe24a8eb1327a6bvboxsync * Argument buffer for calling INTNETR0IfSetPromiscuousMode().
49e54e2ffe0c10864d06e9d1ebe24a8eb1327a6bvboxsync * @see INTNETR0IfSetPromiscuousMode()
49e54e2ffe0c10864d06e9d1ebe24a8eb1327a6bvboxsync /** Handle to the interface. */
49e54e2ffe0c10864d06e9d1ebe24a8eb1327a6bvboxsync /** The new promiscuous mode. */
91f8453d16b48876deddaba298c211071d0ca3a5vboxsync/** Pointer to an INTNETR0IfSetPromiscuousMode() argument package. */
91f8453d16b48876deddaba298c211071d0ca3a5vboxsynctypedef INTNETIFSETPROMISCUOUSMODEARGS *PINTNETIFSETPROMISCUOUSMODEARGS;
91f8453d16b48876deddaba298c211071d0ca3a5vboxsync * Argument buffer for calling INTNETR0IfSend().
91f8453d16b48876deddaba298c211071d0ca3a5vboxsync * @see INTNETR0IfSend()
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Handle to the interface. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Pointer to the frame. (Optional) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync const void *pvFrame;
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The size of the frame. (Optional) */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to an INTNETR0IfSend() argument package. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Argument buffer for calling INTNETR0IfWait().
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @see INTNETR0IfWait()
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** Handle to the interface. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync /** The number of milliseconds to wait. */
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync/** Pointer to an INTNETR0IfWait() argument package. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync#if defined(IN_RING0) || defined(IN_INTNET_TESTCASE)
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync/** Pointer to an internal network ring-0 instance. */
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Create an instance of the Ring-0 internal networking service.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @returns VBox status code.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param ppIntNet Where to store the instance pointer.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0Create(PINTNET *ppIntNet);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Destroys an instance of the Ring-0 internal networking service.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pIntNet Pointer to the instance data.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(void) INTNETR0Destroy(PINTNET pIntNet);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Opens a network interface and attaches it to the specified network.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pIntNet The internal network instance.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pSession The session handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pszNetwork The network name.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param cbSend The send buffer size.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param cbRecv The receive buffer size.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param fRestrictAccess Whether new participants should be subjected to access check or not.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param phIf Where to store the handle to the network interface.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0Open(PINTNET pIntNet, PSUPDRVSESSION pSession, const char *pszNetwork, unsigned cbSend, unsigned cbRecv, bool fRestrictAccess, PINTNETIFHANDLE phIf);
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * Close an interface.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pIntNet The instance handle.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param hIf The interface handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0IfClose(PINTNET pIntNet, INTNETIFHANDLE hIf);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Gets the ring-0 address of the current buffer.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pIntNet The instance data.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param hIF The interface handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param ppRing0Buf Where to store the address of the ring-3 mapping.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsyncINTNETR0DECL(int) INTNETR0IfGetRing0Buffer(PINTNET pIntNet, INTNETIFHANDLE hIf, PINTNETBUF *ppRing0Buf);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Maps the default buffer into ring 3.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pIntNet The instance data.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param hIF The interface handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param ppRing3Buf Where to store the address of the ring-3 mapping.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsyncINTNETR0DECL(int) INTNETR0IfGetRing3Buffer(PINTNET pIntNet, INTNETIFHANDLE hIf, PINTNETBUF *ppRing3Buf);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Sets the promiscuous mode property of an interface.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pIntNet The instance handle.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param hIf The interface handle.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param fPromiscuous Set if the interface should be in promiscuous mode, clear if not.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0IfSetPromiscuousMode(PINTNET pIntNet, INTNETIFHANDLE hIf, bool fPromiscuous);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Sends one or more frames.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * The function will first the frame which is passed as the optional
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * arguments pvFrame and cbFrame. These are optional since it also
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * possible to chain together one or more frames in the send buffer
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * which the function will process after considering it's arguments.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @returns VBox status code.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pIntNet The instance data.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param hIF The interface handle.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param pvFrame Pointer to the frame.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @param cbFrame Size of the frame.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0IfSend(PINTNET pIntNet, INTNETIFHANDLE hIf, const void *pvFrame, unsigned cbFrame);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * Wait for the interface to get signaled.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * The interface will be signaled when is put into the receive buffer.
adf2bcd2e5d07d5a11553b88e147c1f4b2249bffvboxsync * @returns VBox status code.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param pIntNet The instance handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param hIf The interface handle.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * @param cMillies Number of milliseconds to wait. RT_INDEFINITE_WAIT should be
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync * used if indefinite wait is desired.
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsyncINTNETR0DECL(int) INTNETR0IfWait(PINTNET pIntNet, INTNETIFHANDLE hIf, unsigned cMillies);
71c8a528203c289a8585ce10ac6bafc4274058c6vboxsync#endif /* IN_RING0 */