dvm.h@ 85877

Last change on this file since 85877 was 85877, checked in by vboxsync, 4 years ago
Main: bugref:9224: DVM API changes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.2 KB

Line
1	/* $Id: dvm.h 85877 2020-08-24 17:03:23Z 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	* Closes a volume handle.
188	*
189	* @returns nothing.
190	* @param hVolFmt The format specific volume handle.
191	*/
192	DECLCALLBACKMEMBER(void, pfnVolumeClose,(RTDVMVOLUMEFMT hVolFmt));
193
194	/**
195	* Gets the size of the given volume.
196	*
197	* @returns Size of the volume in bytes or 0 on failure.
198	* @param hVolFmt The format specific volume handle.
199	*/
200	DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetSize,(RTDVMVOLUMEFMT hVolFmt));
201
202	/**
203	* Queries the name of the given volume.
204	*
205	* @returns IPRT status code.
206	* @param hVolFmt The format specific volume handle.
207	* @param ppszVolname Where to store the name of the volume on success.
208	*/
209	DECLCALLBACKMEMBER(int, pfnVolumeQueryName,(RTDVMVOLUMEFMT hVolFmt, char **ppszVolName));
210
211	/**
212	* Get the type of the given volume.
213	*
214	* @returns The volume type on success, DVMVOLTYPE_INVALID if hVol is invalid.
215	* @param hVolFmt The format specific volume handle.
216	*/
217	DECLCALLBACKMEMBER(RTDVMVOLTYPE, pfnVolumeGetType,(RTDVMVOLUMEFMT hVolFmt));
218
219	/**
220	* Get the flags of the given volume.
221	*
222	* @returns The volume flags or UINT64_MAX on failure.
223	* @param hVolFmt The format specific volume handle.
224	*/
225	DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetFlags,(RTDVMVOLUMEFMT hVolFmt));
226
227	/**
228	* Queries the range of the given volume on the underyling medium.
229	*
230	* @returns IPRT status code.
231	* @param hVolFmt The format specific volume handle.
232	* @param poffStart Where to store the start byte offset on the
233	* underlying medium.
234	* @param poffLast Where to store the last byte offset on the
235	* underlying medium (inclusive).
236	*/
237	DECLCALLBACKMEMBER(int, pfnVolumeQueryRange,(RTDVMVOLUMEFMT hVolFmt, uint64_t poffStart, uint64_t poffLast));
238
239	/**
240	* Returns whether the supplied range is at least partially intersecting
241	* with the given volume.
242	*
243	* @returns whether the range intersects with the volume.
244	* @param hVolFmt The format specific volume handle.
245	* @param offStart Start offset of the range.
246	* @param cbRange Size of the range to check in bytes.
247	* @param poffVol Where to store the offset of the range from the
248	* start of the volume if true is returned.
249	* @param pcbIntersect Where to store the number of bytes intersecting
250	* with the range if true is returned.
251	*/
252	DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting,(RTDVMVOLUMEFMT hVolFmt,
253	uint64_t offStart, size_t cbRange,
254	uint64_t *poffVol,
255	uint64_t *pcbIntersect));
256
257	/**
258	* Queries the range of the partition table the volume belongs to on the underlying medium.
259	*
260	* @returns IPRT status code.
261	* @param hVolFmt The format specific volume handle.
262	* @param poffTable Where to return the byte offset on the underlying
263	* media of the (partition/volume/whatever) table.
264	* @param pcbTable Where to return the table size in bytes. This
265	* typically includes alignment padding.
266	* @sa RTDvmVolumeQueryTableLocation
267	*/
268	DECLCALLBACKMEMBER(int, pfnVolumeQueryTableLocation,(RTDVMVOLUMEFMT hVolFmt, uint64_t poffStart, uint64_t poffLast));
269
270	/**
271	* Gets the tiven index for the specified volume.
272	*
273	* @returns The requested index. UINT32_MAX on failure.
274	* @param hVolFmt The format specific volume handle.
275	* @param enmIndex The index to get.
276	* @sa RTDvmVolumeGetIndex
277	*/
278	DECLCALLBACKMEMBER(uint32_t, pfnVolumeGetIndex,(RTDVMVOLUMEFMT hVolFmt, RTDVMVOLIDX enmIndex));
279
280	/**
281	* Query a generic volume property.
282	*
283	* This is an extensible interface for retriving mostly format specific
284	* information, or information that's not commonly used. (It's modelled after
285	* RTLdrQueryPropEx.)
286	*
287	* @returns IPRT status code.
288	* @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
289	* or that specific property). The caller must handle this result.
290	* @retval VERR_NOT_FOUND is currently not returned, but intended for cases
291	* where it wasn't present in the tables.
292	* @retval VERR_INVALID_FUNCTION if the @a enmProperty value is wrong.
293	* @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
294	* size in @a *pcbRet.
295	* @retval VERR_BUFFER_OVERFLOW if the property doesn't have a fixed size
296	* buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
297	* @retval VERR_INVALID_HANDLE if the handle is invalid.
298	*
299	* @param hVolFmt Handle to the volume.
300	* @param enmProperty The property to query.
301	* @param pvBuf Pointer to the input / output buffer. In most cases
302	* it's only used for returning data.
303	* @param cbBuf The size of the buffer. This is validated by the common
304	* code for all fixed typed & sized properties. The
305	* interger properties may have several supported sizes, in
306	* which case the user value is passed along as-is but it
307	* is okay to return a smaller amount of data. The common
308	* code will make upcast the data.
309	* @param pcbRet Where to return the amount of data returned. This must
310	* be set even for fixed type/sized data.
311	* @sa RTDvmVolumeQueryProp, RTDvmVolumeGetPropU64
312	*/
313	DECLCALLBACKMEMBER(int, pfnVolumeQueryProp,(RTDVMVOLUMEFMT hVolFmt, RTDVMVOLPROP enmProperty,
314	void pvBuf, size_t cbBuf, size_t pcbBuf));
315
316	/**
317	* Read data from the given volume.
318	*
319	* @returns IPRT status code.
320	* @param hVolFmt The format specific volume handle.
321	* @param off Where to start reading from.
322	* @param pvBuf Where to store the read data.
323	* @param cbRead How many bytes to read.
324	*/
325	DECLCALLBACKMEMBER(int, pfnVolumeRead,(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead));
326
327	/**
328	* Write data to the given volume.
329	*
330	* @returns IPRT status code.
331	* @param hVolFmt The format specific volume handle.
332	* @param off Where to start writing to.
333	* @param pvBuf The data to write.
334	* @param cbWrite How many bytes to write.
335	*/
336	DECLCALLBACKMEMBER(int, pfnVolumeWrite,(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite));
337
338	} RTDVMFMTOPS;
339	/** Pointer to a DVM ops table. */
340	typedef RTDVMFMTOPS *PRTDVMFMTOPS;
341	/** Pointer to a const DVM ops table. */
342	typedef const RTDVMFMTOPS *PCRTDVMFMTOPS;
343
344	/** Checks whether a range is intersecting. */
345	#define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) )
346
347	/** Converts a LBA number to the byte offset. */
348	#define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector)
349	/** Converts a Byte offset to the LBA number. */
350	#define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector)
351
352	/**
353	* Returns the number of sectors in the disk.
354	*
355	* @returns Number of sectors.
356	* @param pDisk The disk descriptor.
357	*/
358	DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk)
359	{
360	return pDisk->cbDisk / pDisk->cbSector;
361	}
362
363	/**
364	* Read from the disk at the given offset.
365	*
366	* @returns IPRT status code.
367	* @param pDisk The disk descriptor to read from.
368	* @param off Start offset.
369	* @param pvBuf Destination buffer.
370	* @param cbRead How much to read.
371	* @sa rtDvmDiskReadUnaligned
372	*/
373	DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead)
374	{
375	AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
376	AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
377	AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER);
378	AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
379
380	/* Use RTVfsFileReadAt if these triggers: */
381	Assert(!(cbRead % pDisk->cbSector));
382	Assert(!(off % pDisk->cbSector));
383
384	return RTVfsFileReadAt(pDisk->hVfsFile, off, pvBuf, cbRead, NULL /pcbRead/);
385	}
386
387	DECLHIDDEN(int) rtDvmDiskReadUnaligned(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead);
388
389	/**
390	* Write to the disk at the given offset.
391	*
392	* @returns IPRT status code.
393	* @param pDisk The disk descriptor to write to.
394	* @param off Start offset.
395	* @param pvBuf Source buffer.
396	* @param cbWrite How much to write.
397	*/
398	DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite)
399	{
400	AssertPtrReturn(pDisk, VERR_INVALID_POINTER);
401	AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
402	AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER);
403	AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER);
404
405	/* Write RTVfsFileReadAt if these triggers: */
406	Assert(!(cbWrite % pDisk->cbSector));
407	Assert(!(off % pDisk->cbSector));
408
409	return RTVfsFileWriteAt(pDisk->hVfsFile, off, pvBuf, cbWrite, NULL /pcbWritten/);
410	}
411
412	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtMbr;
413	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtGpt;
414	extern DECL_HIDDEN_DATA(const RTDVMFMTOPS) g_rtDvmFmtBsdLbl;
415
416	RT_C_DECLS_END
417
418	#endif /* !IPRT_INCLUDED_INTERNAL_dvm_h */
419

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

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

Download in other formats: