VirtualBox

source: vbox/trunk/src/VBox/Devices/Storage/IOBufMgmt.h@ 82254

Last change on this file since 82254 was 76565, checked in by vboxsync, 6 years ago

Devices: Use VBOX_INCLUDED_SRC_ as header guard prefix with scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 3.6 KB
Line 
1/* $Id: IOBufMgmt.h 76565 2019-01-01 04:23:20Z vboxsync $ */
2/** @file
3 * VBox storage devices: I/O buffer management API.
4 */
5
6/*
7 * Copyright (C) 2016-2019 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef VBOX_INCLUDED_SRC_Storage_IOBufMgmt_h
19#define VBOX_INCLUDED_SRC_Storage_IOBufMgmt_h
20#ifndef RT_WITHOUT_PRAGMA_ONCE
21# pragma once
22#endif
23
24#include <VBox/cdefs.h>
25#include <iprt/sg.h>
26
27RT_C_DECLS_BEGIN
28
29/**
30 * Opaque I/O buffer manager.
31 */
32typedef struct IOBUFMGRINT *IOBUFMGR;
33/** Pointer to a I/O buffer manager. */
34typedef IOBUFMGR *PIOBUFMGR;
35
36/* NIL I/O buffer manager handle. */
37#define NIL_IOBUFMGR ((IOBUFMGR)0)
38
39#define IOBUFMGR_F_DEFAULT (0)
40/** I/O buffer memory needs to be non pageable (for example because it contains sensitive data
41 * which shouldn't end up in swap unencrypted). */
42#define IOBUFMGR_F_REQUIRE_NOT_PAGABLE RT_BIT(0)
43
44/**
45 * I/O buffer descriptor.
46 */
47typedef struct IOBUFDESC
48{
49 /** S/G buffer. */
50 RTSGBUF SgBuf;
51 /** Internal data */
52 union
53 {
54#ifdef IOBUFDESCINT_DECLARED
55 IOBUFDESCINT Int;
56#endif
57 uint8_t abPadding[HC_ARCH_BITS == 32 ? 88 : 172];
58 };
59} IOBUFDESC;
60/** Pointer to a I/O buffer descriptor. */
61typedef IOBUFDESC *PIOBUFDESC;
62
63/**
64 * Creates I/O buffer manager.
65 *
66 * @returns VBox status code.
67 * @param phIoBufMgr Where to store the handle to the I/O buffer manager on success.
68 * @param cbMax The maximum amount of I/O memory to allow. Trying to allocate more than
69 * this will lead to out of memory errors. 0 for "unlimited" size (only restriction
70 * is the available memory on the host).
71 * @param fFlags Combination of IOBUFMGR_F_*
72 */
73DECLHIDDEN(int) IOBUFMgrCreate(PIOBUFMGR phIoBufMgr, size_t cbMax, uint32_t fFlags);
74
75/**
76 * Destroys the given I/O buffer manager.
77 *
78 * @returns VBox status code.
79 * @retval VERR_INVALID_STATE if there is still memory allocated by the given manager.
80 * @param hIoBufMgr The I/O buffer manager.
81 */
82DECLHIDDEN(int) IOBUFMgrDestroy(IOBUFMGR hIoBufMgr);
83
84/**
85 * Allocates a I/O buffer and fills the descriptor.
86 *
87 * @returns VBox status code.
88 * @retval VERR_NO_MEMORY if there is not enough free memory to satisfy the request
89 * and partial allocations are not allowed or allocating some internal tracking
90 * structures failed.
91 * @param hIoBufMgr The I/O buffer manager.
92 * @param pIoBufDesc The I/O buffer descriptor to initialize on success.
93 * @param cbIoBuf How much to allocate.
94 * @param pcbIoBufAllocated Where to store amount of memory the manager was able to allocate
95 * if there is not enough free memory to satisfy the complete request.
96 * NULL if partial allocations are not supported.
97 */
98DECLHIDDEN(int) IOBUFMgrAllocBuf(IOBUFMGR hIoBufMgr, PIOBUFDESC pIoBufDesc, size_t cbIoBuf,
99 size_t *pcbIoBufAllocated);
100
101/**
102 * Frees a given I/O buffer.
103 *
104 * @returns nothing.
105 * @param pIoBufDesc The I/O buffer descriptor to free.
106 */
107DECLHIDDEN(void) IOBUFMgrFreeBuf(PIOBUFDESC pIoBufDesc);
108
109RT_C_DECLS_END
110
111#endif /* !VBOX_INCLUDED_SRC_Storage_IOBufMgmt_h */
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette