dvm.h@ 86669

Last change on this file since 86669 was 85894, checked in by vboxsync, 4 years ago
IPRT/Dvm: Added RTDvmMapQueryTableLocations (for VMDK). Completely untested. bugref:9224
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 85894 2020-08-26 20:50:52Z vboxsync $ */
2	/** @file
3	* IPRT - Disk Volume Management Internals.
4	*/
5
6	/*
7	* Copyright (C) 2006-2020 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
39	RT_C_DECLS_BEGIN
40
41	/** Format specific volume manager handle. */
42	typedef struct RTDVMFMTINTERNAL *RTDVMFMT;
43	/** Pointer to a format specific volume manager handle. */
44	typedef RTDVMFMT *PRTDVMFMT;
45	/** NIL volume manager handle. */
46	#define NIL_RTDVMFMT ((RTDVMFMT)~0)
47
48	/** Format specific volume data handle. */
49	typedef struct RTDVMVOLUMEFMTINTERNAL *RTDVMVOLUMEFMT;
50	/** Pointer to a format specific volume data handle. */
51	typedef RTDVMVOLUMEFMT *PRTDVMVOLUMEFMT;
52	/** NIL volume handle. */
53	#define NIL_RTDVMVOLUMEFMT ((RTDVMVOLUMEFMT)~0)
54
55	/**
56	* Disk descriptor.
57	*/
58	typedef 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. */
68	typedef RTDVMDISK *PRTDVMDISK;
69	/** Pointer to a const descriptor. */
70	typedef 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	*/
83	typedef 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. */
363	typedef RTDVMFMTOPS *PRTDVMFMTOPS;
364	/** Pointer to a const DVM ops table. */
365	typedef 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	*/
381	DECLINLINE(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	*/
396	DECLINLINE(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
410	DECLHIDDEN(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	*/
421	DECLINLINE(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
435	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtMbr;
436	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtGpt;
437	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtBsdLbl;
438
439	RT_C_DECLS_END
440
441	#endif /* !IPRT_INCLUDED_INTERNAL_dvm_h */
442

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: