VirtualBox

source: vbox/trunk/src/VBox/Runtime/include/internal/dvm.h@ 76559

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

IPRT/include: Use IPRT_INCLUDED_INTERNAL_ rather than _internal_ as header guard prefix, letting scm enforce this.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.4 KB
Line 
1/* $Id: dvm.h 76559 2019-01-01 02:55:59Z vboxsync $ */
2/** @file
3 * IPRT - Disk Volume Management Internals.
4 */
5
6/*
7 * Copyright (C) 2006-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 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef IPRT_INCLUDED_INTERNAL_dvm_h
28#define IPRT_INCLUDED_INTERNAL_dvm_h
29#ifndef RT_WITHOUT_PRAGMA_ONCE
30# pragma once
31#endif
32
33#include <iprt/types.h>
34#include <iprt/err.h>
35#include <iprt/assert.h>
36#include <iprt/vfs.h>
37#include "internal/magics.h"
38
39RT_C_DECLS_BEGIN
40
41/** Format specific volume manager handle. */
42typedef struct RTDVMFMTINTERNAL *RTDVMFMT;
43/** Pointer to a format specific volume manager handle. */
44typedef RTDVMFMT *PRTDVMFMT;
45/** NIL volume manager handle. */
46#define NIL_RTDVMFMT ((RTDVMFMT)~0)
47
48/** Format specific volume data handle. */
49typedef struct RTDVMVOLUMEFMTINTERNAL *RTDVMVOLUMEFMT;
50/** Pointer to a format specific volume data handle. */
51typedef RTDVMVOLUMEFMT *PRTDVMVOLUMEFMT;
52/** NIL volume handle. */
53#define NIL_RTDVMVOLUMEFMT ((RTDVMVOLUMEFMT)~0)
54
55/**
56 * Disk descriptor.
57 */
58typedef struct RTDVMDISK
59{
60 /** Size of the disk in bytes. */
61 uint64_t cbDisk;
62 /** Sector size. */
63 uint64_t cbSector;
64 /** The VFS file handle if backed by such. */
65 RTVFSFILE hVfsFile;
66} RTDVMDISK;
67/** Pointer to a disk descriptor. */
68typedef RTDVMDISK *PRTDVMDISK;
69/** Pointer to a const descriptor. */
70typedef const RTDVMDISK *PCRTDVMDISK;
71
72/** Score to indicate that the backend can't handle the format at all */
73#define RTDVM_MATCH_SCORE_UNSUPPORTED 0
74/** Score to indicate that a backend supports the format
75 * but there can be other backends. */
76#define RTDVM_MATCH_SCORE_SUPPORTED (UINT32_MAX/2)
77/** Score to indicate a perfect match. */
78#define RTDVM_MATCH_SCORE_PERFECT UINT32_MAX
79
80/**
81 * Volume format operations.
82 */
83typedef struct RTDVMFMTOPS
84{
85 /** Name of the format. */
86 const char *pszFmt;
87 /** The format type. */
88 RTDVMFORMATTYPE enmFormat;
89
90 /**
91 * Probes the given disk for known structures.
92 *
93 * @returns IPRT status code.
94 * @param pDisk Disk descriptor.
95 * @param puScore Where to store the match score on success.
96 */
97 DECLCALLBACKMEMBER(int, pfnProbe)(PCRTDVMDISK pDisk, uint32_t *puScore);
98
99 /**
100 * Opens the format to set up all structures.
101 *
102 * @returns IPRT status code.
103 * @param pDisk The disk descriptor.
104 * @param phVolMgrFmt Where to store the volume format data on success.
105 */
106 DECLCALLBACKMEMBER(int, pfnOpen)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt);
107
108 /**
109 * Initializes a new volume map.
110 *
111 * @returns IPRT status code.
112 * @param pDisk The disk descriptor.
113 * @param phVolMgrFmt Where to store the volume format data on success.
114 */
115 DECLCALLBACKMEMBER(int, pfnInitialize)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt);
116
117 /**
118 * Closes the volume format.
119 *
120 * @returns nothing.
121 * @param hVolMgrFmt The format specific volume manager handle.
122 */
123 DECLCALLBACKMEMBER(void, pfnClose)(RTDVMFMT hVolMgrFmt);
124
125 /**
126 * Returns whether the given range is in use by the volume manager.
127 *
128 * @returns IPRT status code.
129 * @param hVolMgrFmt The format specific volume manager handle.
130 * @param offStart Start offset of the range.
131 * @param cbRange Size of the range to check in bytes.
132 * @param pfUsed Where to store whether the range is in use by the
133 * volume manager.
134 */
135 DECLCALLBACKMEMBER(int, pfnQueryRangeUse)(RTDVMFMT hVolMgrFmt,
136 uint64_t off, uint64_t cbRange,
137 bool *pfUsed);
138
139 /**
140 * Gets the number of valid volumes in the map.
141 *
142 * @returns Number of valid volumes in the map or UINT32_MAX on failure.
143 * @param hVolMgrFmt The format specific volume manager handle.
144 */
145 DECLCALLBACKMEMBER(uint32_t, pfnGetValidVolumes)(RTDVMFMT hVolMgrFmt);
146
147 /**
148 * Gets the maximum number of volumes the map can have.
149 *
150 * @returns Maximum number of volumes in the map or 0 on failure.
151 * @param hVolMgrFmt The format specific volume manager handle.
152 */
153 DECLCALLBACKMEMBER(uint32_t, pfnGetMaxVolumes)(RTDVMFMT hVolMgrFmt);
154
155 /**
156 * Get the first valid volume from a map.
157 *
158 * @returns IPRT status code.
159 * @param hVolMgrFmt The format specific volume manager handle.
160 * @param phVolFmt Where to store the volume handle to the first volume
161 * on success.
162 */
163 DECLCALLBACKMEMBER(int, pfnQueryFirstVolume)(RTDVMFMT hVolMgrFmt, PRTDVMVOLUMEFMT phVolFmt);
164
165 /**
166 * Get the first valid volume from a map.
167 *
168 * @returns IPRT status code.
169 * @param hVolMgrFmt The format specific volume manager handle.
170 * @param hVolFmt The current volume.
171 * @param phVolFmtNext Where to store the handle to the format specific
172 * volume data of the next volume on success.
173 */
174 DECLCALLBACKMEMBER(int, pfnQueryNextVolume)(RTDVMFMT hVolMgrFmt, RTDVMVOLUMEFMT hVolFmt, PRTDVMVOLUMEFMT phVolFmtNext);
175
176 /**
177 * Closes a volume handle.
178 *
179 * @returns nothing.
180 * @param hVolFmt The format specific volume handle.
181 */
182 DECLCALLBACKMEMBER(void, pfnVolumeClose)(RTDVMVOLUMEFMT hVolFmt);
183
184 /**
185 * Gets the size of the given volume.
186 *
187 * @returns Size of the volume in bytes or 0 on failure.
188 * @param hVolFmt The format specific volume handle.
189 */
190 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetSize)(RTDVMVOLUMEFMT hVolFmt);
191
192 /**
193 * Queries the name of the given volume.
194 *
195 * @returns IPRT status code.
196 * @param hVolFmt The format specific volume handle.
197 * @param ppszVolname Where to store the name of the volume on success.
198 */
199 DECLCALLBACKMEMBER(int, pfnVolumeQueryName)(RTDVMVOLUMEFMT hVolFmt, char **ppszVolName);
200
201 /**
202 * Get the type of the given volume.
203 *
204 * @returns The volume type on success, DVMVOLTYPE_INVALID if hVol is invalid.
205 * @param hVolFmt The format specific volume handle.
206 */
207 DECLCALLBACKMEMBER(RTDVMVOLTYPE, pfnVolumeGetType)(RTDVMVOLUMEFMT hVolFmt);
208
209 /**
210 * Get the flags of the given volume.
211 *
212 * @returns The volume flags or UINT64_MAX on failure.
213 * @param hVolFmt The format specific volume handle.
214 */
215 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetFlags)(RTDVMVOLUMEFMT hVolFmt);
216
217 /**
218 * Returns whether the supplied range is at least partially intersecting
219 * with the given volume.
220 *
221 * @returns whether the range intersects with the volume.
222 * @param hVolFmt The format specific volume handle.
223 * @param offStart Start offset of the range.
224 * @param cbRange Size of the range to check in bytes.
225 * @param poffVol Where to store the offset of the range from the
226 * start of the volume if true is returned.
227 * @param pcbIntersect Where to store the number of bytes intersecting
228 * with the range if true is returned.
229 */
230 DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting)(RTDVMVOLUMEFMT hVolFmt,
231 uint64_t offStart, size_t cbRange,
232 uint64_t *poffVol,
233 uint64_t *pcbIntersect);
234
235 /**
236 * Read data from the given volume.
237 *
238 * @returns IPRT status code.
239 * @param hVolFmt The format specific volume handle.
240 * @param off Where to start reading from.
241 * @param pvBuf Where to store the read data.
242 * @param cbRead How many bytes to read.
243 */
244 DECLCALLBACKMEMBER(int, pfnVolumeRead)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead);
245
246 /**
247 * Write data to the given volume.
248 *
249 * @returns IPRT status code.
250 * @param hVolFmt The format specific volume handle.
251 * @param off Where to start writing to.
252 * @param pvBuf The data to write.
253 * @param cbWrite How many bytes to write.
254 */
255 DECLCALLBACKMEMBER(int, pfnVolumeWrite)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite);
256
257} RTDVMFMTOPS;
258/** Pointer to a DVM ops table. */
259typedef RTDVMFMTOPS *PRTDVMFMTOPS;
260/** Pointer to a const DVM ops table. */
261typedef const RTDVMFMTOPS *PCRTDVMFMTOPS;
262
263/** Checks whether a range is intersecting. */
264#define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) )
265
266/** Converts a LBA number to the byte offset. */
267#define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector)
268/** Converts a Byte offset to the LBA number. */
269#define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector)
270
271/**
272 * Returns the number of sectors in the disk.
273 *
274 * @returns Number of sectors.
275 * @param pDisk The disk descriptor.
276 */
277DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk)
278{
279 return pDisk->cbDisk / pDisk->cbSector;
280}
281
282/**
283 * Read from the disk at the given offset.
284 *
285 * @returns IPRT status code.
286 * @param pDisk The disk descriptor to read from.
287 * @param off Start offset.
288 * @param pvBuf Destination buffer.
289 * @param cbRead How much to read.
290 */
291DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead)
292{
293 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
294 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
295 AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER);
296 AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
297
298 return RTVfsFileReadAt(pDisk->hVfsFile, off, pvBuf, cbRead, NULL /*pcbRead*/);
299}
300
301/**
302 * Write to the disk at the given offset.
303 *
304 * @returns IPRT status code.
305 * @param pDisk The disk descriptor to write to.
306 * @param off Start offset.
307 * @param pvBuf Source buffer.
308 * @param cbWrite How much to write.
309 */
310DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite)
311{
312 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
313 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
314 AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER);
315 AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
316
317 return RTVfsFileWriteAt(pDisk->hVfsFile, off, pvBuf, cbWrite, NULL /*pcbWritten*/);
318}
319
320RT_C_DECLS_END
321
322#endif
323
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