VirtualBox

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

Last change on this file since 93115 was 93115, checked in by vboxsync, 2 years ago

scm --update-copyright-year
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.5 KB
Line 
1/* $Id: dvm.h 93115 2022-01-01 11:31:46Z vboxsync $ */
2/** @file
3 * IPRT - Disk Volume Management Internals.
4 */
5
6/*
7 * Copyright (C) 2006-2022 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 * Optional: Query the uuid of the current disk if applicable.
141 *
142 * @returns IPRT status code.
143 * @retval VERR_NOT_SUPPORTED if the partition scheme doesn't do UUIDs.
144 * @param hVolMgrFmt The format specific volume manager handle.
145 * @param pUuid Where to return the UUID.
146 */
147 DECLCALLBACKMEMBER(int, pfnQueryDiskUuid,(RTDVMFMT hVolMgrFmt, PRTUUID pUuid));
148
149 /**
150 * Gets the number of valid volumes in the map.
151 *
152 * @returns Number of valid volumes in the map or UINT32_MAX on failure.
153 * @param hVolMgrFmt The format specific volume manager handle.
154 */
155 DECLCALLBACKMEMBER(uint32_t, pfnGetValidVolumes,(RTDVMFMT hVolMgrFmt));
156
157 /**
158 * Gets the maximum number of volumes the map can have.
159 *
160 * @returns Maximum number of volumes in the map or 0 on failure.
161 * @param hVolMgrFmt The format specific volume manager handle.
162 */
163 DECLCALLBACKMEMBER(uint32_t, pfnGetMaxVolumes,(RTDVMFMT hVolMgrFmt));
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 phVolFmt Where to store the volume handle to the first volume
171 * on success.
172 */
173 DECLCALLBACKMEMBER(int, pfnQueryFirstVolume,(RTDVMFMT hVolMgrFmt, PRTDVMVOLUMEFMT phVolFmt));
174
175 /**
176 * Get the first valid volume from a map.
177 *
178 * @returns IPRT status code.
179 * @param hVolMgrFmt The format specific volume manager handle.
180 * @param hVolFmt The current volume.
181 * @param phVolFmtNext Where to store the handle to the format specific
182 * volume data of the next volume on success.
183 */
184 DECLCALLBACKMEMBER(int, pfnQueryNextVolume,(RTDVMFMT hVolMgrFmt, RTDVMVOLUMEFMT hVolFmt, PRTDVMVOLUMEFMT phVolFmtNext));
185
186 /**
187 * Query the partition table locations.
188 *
189 * @returns IPRT status code.
190 * @retval VERR_BUFFER_OVERFLOW if the table is too small, @a *pcActual will be
191 * set to the required size.
192 * @retval VERR_BUFFER_UNDERFLOW if the table is too big and @a pcActual is
193 * NULL.
194 * @param hVolMgrFmt The format specific volume manager handle.
195 * @param fFlags Flags, see RTDVMMAPQTABLOC_F_XXX.
196 * @param paLocations Where to return the info. Ignored if @a cLocations
197 * is zero, then only @a pcActual matters.
198 * @param cLocations The size of @a paLocations in items.
199 * @param pcActual Where to return the actual number of locations, or
200 * on VERR_BUFFER_OVERFLOW the necessary table size.
201 * Optional, when not specified the cLocations value
202 * must match exactly or it fails with
203 * VERR_BUFFER_UNDERFLOW.
204 * @sa RTDvmMapQueryTableLocations
205 */
206 DECLCALLBACKMEMBER(int, pfnQueryTableLocations,(RTDVMFMT hVolMgrFmt, uint32_t fFlags, PRTDVMTABLELOCATION paLocations,
207 size_t cLocations, size_t *pcActual));
208
209 /**
210 * Closes a volume handle.
211 *
212 * @returns nothing.
213 * @param hVolFmt The format specific volume handle.
214 */
215 DECLCALLBACKMEMBER(void, pfnVolumeClose,(RTDVMVOLUMEFMT hVolFmt));
216
217 /**
218 * Gets the size of the given volume.
219 *
220 * @returns Size of the volume in bytes or 0 on failure.
221 * @param hVolFmt The format specific volume handle.
222 */
223 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetSize,(RTDVMVOLUMEFMT hVolFmt));
224
225 /**
226 * Queries the name of the given volume.
227 *
228 * @returns IPRT status code.
229 * @param hVolFmt The format specific volume handle.
230 * @param ppszVolname Where to store the name of the volume on success.
231 */
232 DECLCALLBACKMEMBER(int, pfnVolumeQueryName,(RTDVMVOLUMEFMT hVolFmt, char **ppszVolName));
233
234 /**
235 * Get the type of the given volume.
236 *
237 * @returns The volume type on success, DVMVOLTYPE_INVALID if hVol is invalid.
238 * @param hVolFmt The format specific volume handle.
239 */
240 DECLCALLBACKMEMBER(RTDVMVOLTYPE, pfnVolumeGetType,(RTDVMVOLUMEFMT hVolFmt));
241
242 /**
243 * Get the flags of the given volume.
244 *
245 * @returns The volume flags or UINT64_MAX on failure.
246 * @param hVolFmt The format specific volume handle.
247 */
248 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetFlags,(RTDVMVOLUMEFMT hVolFmt));
249
250 /**
251 * Queries the range of the given volume on the underyling medium.
252 *
253 * @returns IPRT status code.
254 * @param hVolFmt The format specific volume handle.
255 * @param poffStart Where to store the start byte offset on the
256 * underlying medium.
257 * @param poffLast Where to store the last byte offset on the
258 * underlying medium (inclusive).
259 */
260 DECLCALLBACKMEMBER(int, pfnVolumeQueryRange,(RTDVMVOLUMEFMT hVolFmt, uint64_t *poffStart, uint64_t *poffLast));
261
262 /**
263 * Returns whether the supplied range is at least partially intersecting
264 * with the given volume.
265 *
266 * @returns whether the range intersects with the volume.
267 * @param hVolFmt The format specific volume handle.
268 * @param offStart Start offset of the range.
269 * @param cbRange Size of the range to check in bytes.
270 * @param poffVol Where to store the offset of the range from the
271 * start of the volume if true is returned.
272 * @param pcbIntersect Where to store the number of bytes intersecting
273 * with the range if true is returned.
274 */
275 DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting,(RTDVMVOLUMEFMT hVolFmt,
276 uint64_t offStart, size_t cbRange,
277 uint64_t *poffVol,
278 uint64_t *pcbIntersect));
279
280 /**
281 * Queries the range of the partition table the volume belongs to on the underlying medium.
282 *
283 * @returns IPRT status code.
284 * @param hVolFmt The format specific volume handle.
285 * @param poffTable Where to return the byte offset on the underlying
286 * media of the (partition/volume/whatever) table.
287 * @param pcbTable Where to return the table size in bytes. This
288 * typically includes alignment padding.
289 * @sa RTDvmVolumeQueryTableLocation
290 */
291 DECLCALLBACKMEMBER(int, pfnVolumeQueryTableLocation,(RTDVMVOLUMEFMT hVolFmt, uint64_t *poffStart, uint64_t *poffLast));
292
293 /**
294 * Gets the tiven index for the specified volume.
295 *
296 * @returns The requested index. UINT32_MAX on failure.
297 * @param hVolFmt The format specific volume handle.
298 * @param enmIndex The index to get. Never RTDVMVOLIDX_HOST.
299 * @sa RTDvmVolumeGetIndex
300 */
301 DECLCALLBACKMEMBER(uint32_t, pfnVolumeGetIndex,(RTDVMVOLUMEFMT hVolFmt, RTDVMVOLIDX enmIndex));
302
303 /**
304 * Query a generic volume property.
305 *
306 * This is an extensible interface for retriving mostly format specific
307 * information, or information that's not commonly used. (It's modelled after
308 * RTLdrQueryPropEx.)
309 *
310 * @returns IPRT status code.
311 * @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
312 * or that specific property). The caller must handle this result.
313 * @retval VERR_NOT_FOUND is currently not returned, but intended for cases
314 * where it wasn't present in the tables.
315 * @retval VERR_INVALID_FUNCTION if the @a enmProperty value is wrong.
316 * @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
317 * size in @a *pcbBuf.
318 * @retval VERR_BUFFER_OVERFLOW if the property doesn't have a fixed size
319 * buffer and the buffer isn't big enough. Correct size in @a *pcbBuf.
320 * @retval VERR_INVALID_HANDLE if the handle is invalid.
321 *
322 * @param hVolFmt Handle to the volume.
323 * @param enmProperty The property to query.
324 * @param pvBuf Pointer to the input / output buffer. In most cases
325 * it's only used for returning data.
326 * @param cbBuf The size of the buffer. This is validated by the common
327 * code for all fixed typed & sized properties. The
328 * interger properties may have several supported sizes, in
329 * which case the user value is passed along as-is but it
330 * is okay to return a smaller amount of data. The common
331 * code will make upcast the data.
332 * @param pcbBuf Where to return the amount of data returned. This must
333 * be set even for fixed type/sized data.
334 * @sa RTDvmVolumeQueryProp, RTDvmVolumeGetPropU64
335 */
336 DECLCALLBACKMEMBER(int, pfnVolumeQueryProp,(RTDVMVOLUMEFMT hVolFmt, RTDVMVOLPROP enmProperty,
337 void *pvBuf, size_t cbBuf, size_t *pcbBuf));
338
339 /**
340 * Read data from the given volume.
341 *
342 * @returns IPRT status code.
343 * @param hVolFmt The format specific volume handle.
344 * @param off Where to start reading from.
345 * @param pvBuf Where to store the read data.
346 * @param cbRead How many bytes to read.
347 */
348 DECLCALLBACKMEMBER(int, pfnVolumeRead,(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead));
349
350 /**
351 * Write data to the given volume.
352 *
353 * @returns IPRT status code.
354 * @param hVolFmt The format specific volume handle.
355 * @param off Where to start writing to.
356 * @param pvBuf The data to write.
357 * @param cbWrite How many bytes to write.
358 */
359 DECLCALLBACKMEMBER(int, pfnVolumeWrite,(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite));
360
361} RTDVMFMTOPS;
362/** Pointer to a DVM ops table. */
363typedef RTDVMFMTOPS *PRTDVMFMTOPS;
364/** Pointer to a const DVM ops table. */
365typedef const RTDVMFMTOPS *PCRTDVMFMTOPS;
366
367/** Checks whether a range is intersecting. */
368#define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) )
369
370/** Converts a LBA number to the byte offset. */
371#define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector)
372/** Converts a Byte offset to the LBA number. */
373#define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector)
374
375/**
376 * Returns the number of sectors in the disk.
377 *
378 * @returns Number of sectors.
379 * @param pDisk The disk descriptor.
380 */
381DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk)
382{
383 return pDisk->cbDisk / pDisk->cbSector;
384}
385
386/**
387 * Read from the disk at the given offset.
388 *
389 * @returns IPRT status code.
390 * @param pDisk The disk descriptor to read from.
391 * @param off Start offset.
392 * @param pvBuf Destination buffer.
393 * @param cbRead How much to read.
394 * @sa rtDvmDiskReadUnaligned
395 */
396DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead)
397{
398 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
399 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
400 AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER);
401 AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
402
403 /* Use RTVfsFileReadAt if these triggers: */
404 Assert(!(cbRead % pDisk->cbSector));
405 Assert(!(off % pDisk->cbSector));
406
407 return RTVfsFileReadAt(pDisk->hVfsFile, off, pvBuf, cbRead, NULL /*pcbRead*/);
408}
409
410DECLHIDDEN(int) rtDvmDiskReadUnaligned(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead);
411
412/**
413 * Write to the disk at the given offset.
414 *
415 * @returns IPRT status code.
416 * @param pDisk The disk descriptor to write to.
417 * @param off Start offset.
418 * @param pvBuf Source buffer.
419 * @param cbWrite How much to write.
420 */
421DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite)
422{
423 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
424 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
425 AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER);
426 AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
427
428 /* Write RTVfsFileReadAt if these triggers: */
429 Assert(!(cbWrite % pDisk->cbSector));
430 Assert(!(off % pDisk->cbSector));
431
432 return RTVfsFileWriteAt(pDisk->hVfsFile, off, pvBuf, cbWrite, NULL /*pcbWritten*/);
433}
434
435extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtMbr;
436extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtGpt;
437extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtBsdLbl;
438
439RT_C_DECLS_END
440
441#endif /* !IPRT_INCLUDED_INTERNAL_dvm_h */
442
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use