req.h revision 590bfe12ce22cd3716448fbb9f4dc51664bfe5e2
5b281ba489ca18f0380d7efc7a5108b606cce449vboxsync * IPRT - Request packets
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * available from http://www.virtualbox.org. This file is free software;
c98fb3e16fcd571a790eab772c0c66173d225205vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * The contents of this file may alternatively be used under the terms
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * of the Common Development and Distribution License Version 1.0
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution, in which case the provisions of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * CDDL are applicable instead of those of the GPL.
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * You may elect to license modified versions of this file under the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * terms and conditions of either the GPL or the CDDL or both.
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * additional information or have any questions.
00314ca59bb0358d05053ee753174724d82adff4vboxsync/** @defgroup grp_rt_req RTReq - Request Packet Management
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @ingroup grp_rt
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Request type.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Invalid request. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** RT: Internal. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Maximum request type (exclusive). Used for validation. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Request state.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The state is invalid. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request have been allocated and is in the process of being filed. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request is queued by the requester. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request is begin processed. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request is completed, the requester is begin notified. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request packet is in the free chain. (The requester */
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Request flags.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request returns a iprt status code. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The request is a void request and have no status code. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Return type mask. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Caller does not wait on the packet, Queue process thread will free it. */
a74c1d37f653a258a981c18485e9df00b6e86e2evboxsync/** Pointer to a request queue. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync * RT Request packet.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * This is used to request an action in the queue handler thread.
00314ca59bb0358d05053ee753174724d82adff4vboxsynctypedef struct RTREQ
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Pointer to the next request in the chain. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Pointer to the queue this packet belongs to. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Request state. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** iprt status code for the completed request. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync volatile int iStatus;
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Requester event sem.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The request can use this event semaphore to wait/poll for completion
00314ca59bb0358d05053ee753174724d82adff4vboxsync * of the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Set if the event semaphore is clear. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync volatile bool fEventSemClear;
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Flags, RTREQ_FLAGS_*. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Request type. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Request specific data. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** RTREQTYPE_INTERNAL. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Pointer to the function to be called. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Number of arguments. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Array of arguments. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync/** Pointer to an RT request packet. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync/** @todo hide this */
00314ca59bb0358d05053ee753174724d82adff4vboxsynctypedef struct RTREQQUEUE
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Head of the request queue. Atomic. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** The last index used during alloc/free. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Number of free request packets. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Array of pointers to lists of free request packets. Atomic. */
00314ca59bb0358d05053ee753174724d82adff4vboxsync /** Requester event sem.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The request can use this event semaphore to wait/poll for new requests.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Create a request packet queueu
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param ppQueue Where to store the request queue pointer.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Destroy a request packet queueu
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Process one or more request packets
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being added.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for a pending request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Use RT_INDEFINITE_WAIT to only wait till one is added.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqProcess(PRTREQQUEUE pQueue, unsigned cMillies);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
00314ca59bb0358d05053ee753174724d82adff4vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The returned request packet must be freed using RTReqFree().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt statuscode.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * This will be NULL or a valid request pointer not matter what happends.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
2a226d423cb24072f0636a40d422cbc795033770vboxsync * The arguments must be of integer or pointer type and
2a226d423cb24072f0636a40d422cbc795033770vboxsync * not bigger in size than uintptr_t. Do not try pass
2a226d423cb24072f0636a40d422cbc795033770vboxsync * 64-bit integers directly in portable code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqCall(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request to a void function.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
00314ca59bb0358d05053ee753174724d82adff4vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The returned request packet must be freed using RTReqFree().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * This will be NULL or a valid request pointer not matter what happends.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
2a226d423cb24072f0636a40d422cbc795033770vboxsync * The arguments must be of integer or pointer type and
2a226d423cb24072f0636a40d422cbc795033770vboxsync * not bigger in size than uintptr_t. Do not try pass
2a226d423cb24072f0636a40d422cbc795033770vboxsync * 64-bit integers directly in portable code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqCallVoid(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request to a void function.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
00314ca59bb0358d05053ee753174724d82adff4vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The returned request packet must be freed using RTReqFree().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * This will be NULL or a valid request pointer not matter what happends, unless fFlags
00314ca59bb0358d05053ee753174724d82adff4vboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param fFlags A combination of the RTREQFLAGS values.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
2a226d423cb24072f0636a40d422cbc795033770vboxsync * The arguments must be of integer or pointer type and
2a226d423cb24072f0636a40d422cbc795033770vboxsync * not bigger in size than uintptr_t. Do not try pass
2a226d423cb24072f0636a40d422cbc795033770vboxsync * 64-bit integers directly in portable code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ... Function arguments.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqCallEx(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocate and queue a call request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's desired to poll on the completion of the request set cMillies
00314ca59bb0358d05053ee753174724d82adff4vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The returned request packet must be freed using RTReqFree().
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * This will be NULL or a valid request pointer not matter what happends, unless fFlags
00314ca59bb0358d05053ee753174724d82adff4vboxsync * contains RTREQFLAGS_NO_WAIT when it will be optional and always NULL.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param fFlags A combination of the RTREQFLAGS values.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pfnFunction Pointer to the function to call.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cArgs Number of arguments following in the ellipsis.
2a226d423cb24072f0636a40d422cbc795033770vboxsync * The arguments must be of integer or pointer type and
2a226d423cb24072f0636a40d422cbc795033770vboxsync * not bigger in size than uintptr_t. Do not try pass
2a226d423cb24072f0636a40d422cbc795033770vboxsync * 64-bit integers directly in portable code.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param Args Variable argument vector.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqCallV(PRTREQQUEUE pQueue, PRTREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Allocates a request packet.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The caller allocates a request packet, fills in the request data
00314ca59bb0358d05053ee753174724d82adff4vboxsync * union and queues the request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
cb13ee8e628d04a773894bf4f9e8047d74f2ee21vboxsync * @param pQueue The request queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param ppReq Where to store the pointer to the allocated packet.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param enmType Package type.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqAlloc(PRTREQQUEUE pQueue, PRTREQ *ppReq, RTREQTYPE enmType);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Free a request packet.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pReq Package to free.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @remark The request packet must be in allocated or completed state!
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Queue a request.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * The quest must be allocated using RTReqAlloc() and contain
00314ca59bb0358d05053ee753174724d82adff4vboxsync * all the required data.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * If it's disired to poll on the completion of the request set cMillies
00314ca59bb0358d05053ee753174724d82adff4vboxsync * to 0 and use RTReqWait() to check for completation. In the other case
00314ca59bb0358d05053ee753174724d82adff4vboxsync * use RT_INDEFINITE_WAIT.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pReq The request to queue.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait for the request to
00314ca59bb0358d05053ee753174724d82adff4vboxsync * be completed. Use RT_INDEFINITE_WAIT to only
00314ca59bb0358d05053ee753174724d82adff4vboxsync * wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqQueue(PRTREQ pReq, unsigned cMillies);
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Wait for a request to be completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns iprt status code.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Will not return VERR_INTERRUPTED.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param pReq The request to wait for.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * @param cMillies Number of milliseconds to wait.
00314ca59bb0358d05053ee753174724d82adff4vboxsync * Use RT_INDEFINITE_WAIT to only wait till it's completed.
00314ca59bb0358d05053ee753174724d82adff4vboxsyncRTDECL(int) RTReqWait(PRTREQ pReq, unsigned cMillies);
00314ca59bb0358d05053ee753174724d82adff4vboxsync#endif /* IN_RING3 */