VirtualBox

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

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

IPRT/dvm: s/offEnd/offLast - see coding guidelines on 'end' vs 'last'.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 12.0 KB
Line 
1/* $Id: dvm.h 77970 2019-04-01 01:35:07Z 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 * Queries the range of the given volume on the underyling medium.
219 *
220 * @returns IPRT status code.
221 * @param hVolFmt The format specific volume handle.
222 * @param poffStart Where to store the start byte offset on the
223 * underlying medium.
224 * @param poffLast Where to store the last byte offset on the
225 * underlying medium (inclusive).
226 */
227 DECLCALLBACKMEMBER(int, pfnVolumeQueryRange)(RTDVMVOLUMEFMT hVolFmt, uint64_t *poffStart, uint64_t *poffLast);
228
229 /**
230 * Returns whether the supplied range is at least partially intersecting
231 * with the given volume.
232 *
233 * @returns whether the range intersects with the volume.
234 * @param hVolFmt The format specific volume handle.
235 * @param offStart Start offset of the range.
236 * @param cbRange Size of the range to check in bytes.
237 * @param poffVol Where to store the offset of the range from the
238 * start of the volume if true is returned.
239 * @param pcbIntersect Where to store the number of bytes intersecting
240 * with the range if true is returned.
241 */
242 DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting)(RTDVMVOLUMEFMT hVolFmt,
243 uint64_t offStart, size_t cbRange,
244 uint64_t *poffVol,
245 uint64_t *pcbIntersect);
246
247 /**
248 * Read data from the given volume.
249 *
250 * @returns IPRT status code.
251 * @param hVolFmt The format specific volume handle.
252 * @param off Where to start reading from.
253 * @param pvBuf Where to store the read data.
254 * @param cbRead How many bytes to read.
255 */
256 DECLCALLBACKMEMBER(int, pfnVolumeRead)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead);
257
258 /**
259 * Write data to the given volume.
260 *
261 * @returns IPRT status code.
262 * @param hVolFmt The format specific volume handle.
263 * @param off Where to start writing to.
264 * @param pvBuf The data to write.
265 * @param cbWrite How many bytes to write.
266 */
267 DECLCALLBACKMEMBER(int, pfnVolumeWrite)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite);
268
269} RTDVMFMTOPS;
270/** Pointer to a DVM ops table. */
271typedef RTDVMFMTOPS *PRTDVMFMTOPS;
272/** Pointer to a const DVM ops table. */
273typedef const RTDVMFMTOPS *PCRTDVMFMTOPS;
274
275/** Checks whether a range is intersecting. */
276#define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) )
277
278/** Converts a LBA number to the byte offset. */
279#define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector)
280/** Converts a Byte offset to the LBA number. */
281#define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector)
282
283/**
284 * Returns the number of sectors in the disk.
285 *
286 * @returns Number of sectors.
287 * @param pDisk The disk descriptor.
288 */
289DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk)
290{
291 return pDisk->cbDisk / pDisk->cbSector;
292}
293
294/**
295 * Read from the disk at the given offset.
296 *
297 * @returns IPRT status code.
298 * @param pDisk The disk descriptor to read from.
299 * @param off Start offset.
300 * @param pvBuf Destination buffer.
301 * @param cbRead How much to read.
302 */
303DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead)
304{
305 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
306 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
307 AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER);
308 AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
309
310 return RTVfsFileReadAt(pDisk->hVfsFile, off, pvBuf, cbRead, NULL /*pcbRead*/);
311}
312
313/**
314 * Write to the disk at the given offset.
315 *
316 * @returns IPRT status code.
317 * @param pDisk The disk descriptor to write to.
318 * @param off Start offset.
319 * @param pvBuf Source buffer.
320 * @param cbWrite How much to write.
321 */
322DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite)
323{
324 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
325 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
326 AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER);
327 AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
328
329 return RTVfsFileWriteAt(pDisk->hVfsFile, off, pvBuf, cbWrite, NULL /*pcbWritten*/);
330}
331
332RT_C_DECLS_END
333
334#endif /* !IPRT_INCLUDED_INTERNAL_dvm_h */
335
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