VirtualBox

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

Last change on this file since 62477 was 62477, checked in by vboxsync, 8 years ago

(C) 2016
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.3 KB
Line 
1/* $Id: dvm.h 62477 2016-07-22 18:27:37Z vboxsync $ */
2/** @file
3 * IPRT - Disk Volume Management Internals.
4 */
5
6/*
7 * Copyright (C) 2006-2016 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 ___internal_dvm_h
28#define ___internal_dvm_h
29
30#include <iprt/types.h>
31#include <iprt/err.h>
32#include <iprt/assert.h>
33#include "internal/magics.h"
34
35RT_C_DECLS_BEGIN
36
37/** Format specific volume manager handle. */
38typedef struct RTDVMFMTINTERNAL *RTDVMFMT;
39/** Pointer to a format specific volume manager handle. */
40typedef RTDVMFMT *PRTDVMFMT;
41/** NIL volume manager handle. */
42#define NIL_RTDVMFMT ((RTDVMFMT)~0)
43
44/** Format specific volume data handle. */
45typedef struct RTDVMVOLUMEFMTINTERNAL *RTDVMVOLUMEFMT;
46/** Pointer to a format specific volume data handle. */
47typedef RTDVMVOLUMEFMT *PRTDVMVOLUMEFMT;
48/** NIL volume handle. */
49#define NIL_RTDVMVOLUMEFMT ((RTDVMVOLUMEFMT)~0)
50
51/**
52 * Disk descriptor.
53 */
54typedef struct RTDVMDISK
55{
56 /** Size of the disk in bytes. */
57 uint64_t cbDisk;
58 /** Sector size. */
59 uint64_t cbSector;
60 /** Read callback */
61 PFNDVMREAD pfnRead;
62 /** Write callback. */
63 PFNDVMWRITE pfnWrite;
64 /** Opaque user data. */
65 void *pvUser;
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 *pcszFmt;
87
88 /**
89 * Probes the given disk for known structures.
90 *
91 * @returns IPRT status code.
92 * @param pDisk Disk descriptor.
93 * @param puScore Where to store the match score on success.
94 */
95 DECLCALLBACKMEMBER(int, pfnProbe)(PCRTDVMDISK pDisk, uint32_t *puScore);
96
97 /**
98 * Opens the format to set up all structures.
99 *
100 * @returns IPRT status code.
101 * @param pDisk The disk descriptor.
102 * @param phVolMgrFmt Where to store the volume format data on success.
103 */
104 DECLCALLBACKMEMBER(int, pfnOpen)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt);
105
106 /**
107 * Initializes a new volume map.
108 *
109 * @returns IPRT status code.
110 * @param pDisk The disk descriptor.
111 * @param phVolMgrFmt Where to store the volume format data on success.
112 */
113 DECLCALLBACKMEMBER(int, pfnInitialize)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt);
114
115 /**
116 * Closes the volume format.
117 *
118 * @returns nothing.
119 * @param hVolMgrFmt The format specific volume manager handle.
120 */
121 DECLCALLBACKMEMBER(void, pfnClose)(RTDVMFMT hVolMgrFmt);
122
123 /**
124 * Returns whether the given range is in use by the volume manager.
125 *
126 * @returns IPRT status code.
127 * @param hVolMgrFmt The format specific volume manager handle.
128 * @param offStart Start offset of the range.
129 * @param cbRange Size of the range to check in bytes.
130 * @param pfUsed Where to store whether the range is in use by the
131 * volume manager.
132 */
133 DECLCALLBACKMEMBER(int, pfnQueryRangeUse)(RTDVMFMT hVolMgrFmt,
134 uint64_t off, uint64_t cbRange,
135 bool *pfUsed);
136
137 /**
138 * Gets the number of valid volumes in the map.
139 *
140 * @returns Number of valid volumes in the map or UINT32_MAX on failure.
141 * @param hVolMgrFmt The format specific volume manager handle.
142 */
143 DECLCALLBACKMEMBER(uint32_t, pfnGetValidVolumes)(RTDVMFMT hVolMgrFmt);
144
145 /**
146 * Gets the maximum number of volumes the map can have.
147 *
148 * @returns Maximum number of volumes in the map or 0 on failure.
149 * @param hVolMgrFmt The format specific volume manager handle.
150 */
151 DECLCALLBACKMEMBER(uint32_t, pfnGetMaxVolumes)(RTDVMFMT hVolMgrFmt);
152
153 /**
154 * Get the first valid volume from a map.
155 *
156 * @returns IPRT status code.
157 * @param hVolMgrFmt The format specific volume manager handle.
158 * @param phVolFmt Where to store the volume handle to the first volume
159 * on success.
160 */
161 DECLCALLBACKMEMBER(int, pfnQueryFirstVolume)(RTDVMFMT hVolMgrFmt, PRTDVMVOLUMEFMT phVolFmt);
162
163 /**
164 * Get the first valid volume from a map.
165 *
166 * @returns IPRT status code.
167 * @param hVolMgrFmt The format specific volume manager handle.
168 * @param hVolFmt The current volume.
169 * @param phVolFmtNext Where to store the handle to the format specific
170 * volume data of the next volume on success.
171 */
172 DECLCALLBACKMEMBER(int, pfnQueryNextVolume)(RTDVMFMT hVolMgrFmt, RTDVMVOLUMEFMT hVolFmt, PRTDVMVOLUMEFMT phVolFmtNext);
173
174 /**
175 * Closes a volume handle.
176 *
177 * @returns nothing.
178 * @param hVolFmt The format specific volume handle.
179 */
180 DECLCALLBACKMEMBER(void, pfnVolumeClose)(RTDVMVOLUMEFMT hVolFmt);
181
182 /**
183 * Gets the size of the given volume.
184 *
185 * @returns Size of the volume in bytes or 0 on failure.
186 * @param hVolFmt The format specific volume handle.
187 */
188 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetSize)(RTDVMVOLUMEFMT hVolFmt);
189
190 /**
191 * Queries the name of the given volume.
192 *
193 * @returns IPRT status code.
194 * @param hVolFmt The format specific volume handle.
195 * @param ppszVolname Where to store the name of the volume on success.
196 */
197 DECLCALLBACKMEMBER(int, pfnVolumeQueryName)(RTDVMVOLUMEFMT hVolFmt, char **ppszVolName);
198
199 /**
200 * Get the type of the given volume.
201 *
202 * @returns The volume type on success, DVMVOLTYPE_INVALID if hVol is invalid.
203 * @param hVolFmt The format specific volume handle.
204 */
205 DECLCALLBACKMEMBER(RTDVMVOLTYPE, pfnVolumeGetType)(RTDVMVOLUMEFMT hVolFmt);
206
207 /**
208 * Get the flags of the given volume.
209 *
210 * @returns The volume flags or UINT64_MAX on failure.
211 * @param hVolFmt The format specific volume handle.
212 */
213 DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetFlags)(RTDVMVOLUMEFMT hVolFmt);
214
215 /**
216 * Returns whether the supplied range is at least partially intersecting
217 * with the given volume.
218 *
219 * @returns whether the range intersects with the volume.
220 * @param hVolFmt The format specific volume handle.
221 * @param offStart Start offset of the range.
222 * @param cbRange Size of the range to check in bytes.
223 * @param poffVol Where to store the offset of the range from the
224 * start of the volume if true is returned.
225 * @param pcbIntersect Where to store the number of bytes intersecting
226 * with the range if true is returned.
227 */
228 DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting)(RTDVMVOLUMEFMT hVolFmt,
229 uint64_t offStart, size_t cbRange,
230 uint64_t *poffVol,
231 uint64_t *pcbIntersect);
232
233 /**
234 * Read data from the given volume.
235 *
236 * @returns IPRT status code.
237 * @param hVolFmt The format specific volume handle.
238 * @param off Where to start reading from.
239 * @param pvBuf Where to store the read data.
240 * @param cbRead How many bytes to read.
241 */
242 DECLCALLBACKMEMBER(int, pfnVolumeRead)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead);
243
244 /**
245 * Write data to the given volume.
246 *
247 * @returns IPRT status code.
248 * @param hVolFmt The format specific volume handle.
249 * @param off Where to start writing to.
250 * @param pvBuf The data to write.
251 * @param cbWrite How many bytes to write.
252 */
253 DECLCALLBACKMEMBER(int, pfnVolumeWrite)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite);
254
255} RTDVMFMTOPS;
256/** Pointer to a DVM ops table. */
257typedef RTDVMFMTOPS *PRTDVMFMTOPS;
258/** Pointer to a const DVM ops table. */
259typedef const RTDVMFMTOPS *PCRTDVMFMTOPS;
260
261/** Checks whether a range is intersecting. */
262#define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) )
263
264/** Converts a LBA number to the byte offset. */
265#define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector)
266/** Converts a Byte offset to the LBA number. */
267#define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector)
268
269/**
270 * Returns the number of sectors in the disk.
271 *
272 * @returns Number of sectors.
273 * @param pDisk The disk descriptor.
274 */
275DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk)
276{
277 return pDisk->cbDisk / pDisk->cbSector;
278}
279
280/**
281 * Read from the disk at the given offset.
282 *
283 * @returns IPRT status code.
284 * @param pDisk The disk descriptor to read from.
285 * @param off Start offset.
286 * @param pvBuf Destination buffer.
287 * @param cbRead How much to read.
288 */
289DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead)
290{
291 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
292 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
293 AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER);
294 AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
295
296 return pDisk->pfnRead(pDisk->pvUser, off, pvBuf, cbRead);
297}
298
299/**
300 * Write to the disk at the given offset.
301 *
302 * @returns IPRT status code.
303 * @param pDisk The disk descriptor to write to.
304 * @param off Start offset.
305 * @param pvBuf Source buffer.
306 * @param cbWrite How much to write.
307 */
308DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite)
309{
310 AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
311 AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
312 AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER);
313 AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
314
315 return pDisk->pfnWrite(pDisk->pvUser, off, pvBuf, cbWrite);
316}
317
318RT_C_DECLS_END
319
320#endif
321
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