/* $Id: dvm.h 56290 2015-06-09 14:01:31Z vboxsync $ */ /** @file * IPRT - Disk Volume Management Internals. */ /* * Copyright (C) 2006-2015 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the * VirtualBox OSE distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. */ #ifndef ___internal_dvm_h #define ___internal_dvm_h #include #include #include #include "internal/magics.h" RT_C_DECLS_BEGIN /** Format specific volume manager handle. */ typedef struct RTDVMFMTINTERNAL *RTDVMFMT; /** Pointer to a format specific volume manager handle. */ typedef RTDVMFMT *PRTDVMFMT; /** NIL volume manager handle. */ #define NIL_RTDVMFMT ((RTDVMFMT)~0) /** Format specific volume data handle. */ typedef struct RTDVMVOLUMEFMTINTERNAL *RTDVMVOLUMEFMT; /** Pointer to a format specific volume data handle. */ typedef RTDVMVOLUMEFMT *PRTDVMVOLUMEFMT; /** NIL volume handle. */ #define NIL_RTDVMVOLUMEFMT ((RTDVMVOLUMEFMT)~0) /** * Disk descriptor. */ typedef struct RTDVMDISK { /** Size of the disk in bytes. */ uint64_t cbDisk; /** Sector size. */ uint64_t cbSector; /** Read callback */ PFNDVMREAD pfnRead; /** Write callback. */ PFNDVMWRITE pfnWrite; /** Opaque user data. */ void *pvUser; } RTDVMDISK; /** Pointer to a disk descriptor. */ typedef RTDVMDISK *PRTDVMDISK; /** Pointer to a const descriptor. */ typedef const RTDVMDISK *PCRTDVMDISK; /** Score to indicate that the backend can't handle the format at all */ #define RTDVM_MATCH_SCORE_UNSUPPORTED 0 /** Score to indicate that a backend supports the format * but there can be other backends. */ #define RTDVM_MATCH_SCORE_SUPPORTED (UINT32_MAX/2) /** Score to indicate a perfect match. */ #define RTDVM_MATCH_SCORE_PERFECT UINT32_MAX /** * Volume format operations. */ typedef struct RTDVMFMTOPS { /** Name of the format. */ const char *pcszFmt; /** * Probes the given disk for known structures. * * @returns IPRT status code. * @param pDisk Disk descriptor. * @param puScore Where to store the match score on success. */ DECLCALLBACKMEMBER(int, pfnProbe)(PCRTDVMDISK pDisk, uint32_t *puScore); /** * Opens the format to set up all structures. * * @returns IPRT status code. * @param pDisk The disk descriptor. * @param phVolMgrFmt Where to store the volume format data on success. */ DECLCALLBACKMEMBER(int, pfnOpen)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt); /** * Initializes a new volume map. * * @returns IPRT status code. * @param pDisk The disk descriptor. * @param phVolMgrFmt Where to store the volume format data on success. */ DECLCALLBACKMEMBER(int, pfnInitialize)(PCRTDVMDISK pDisk, PRTDVMFMT phVolMgrFmt); /** * Closes the volume format. * * @returns nothing. * @param hVolMgrFmt The format specific volume manager handle. */ DECLCALLBACKMEMBER(void, pfnClose)(RTDVMFMT hVolMgrFmt); /** * Returns whether the given range is in use by the volume manager. * * @returns IPRT status code. * @param hVolMgrFmt The format specific volume manager handle. * @param offStart Start offset of the range. * @param cbRange Size of the range to check in bytes. * @param pfUsed Where to store whether the range is in use by the * volume manager. */ DECLCALLBACKMEMBER(int, pfnQueryRangeUse)(RTDVMFMT hVolMgrFmt, uint64_t off, uint64_t cbRange, bool *pfUsed); /** * Gets the number of valid volumes in the map. * * @returns Number of valid volumes in the map or UINT32_MAX on failure. * @param hVolMgrFmt The format specific volume manager handle. */ DECLCALLBACKMEMBER(uint32_t, pfnGetValidVolumes)(RTDVMFMT hVolMgrFmt); /** * Gets the maximum number of volumes the map can have. * * @returns Maximum number of volumes in the map or 0 on failure. * @param hVolMgrFmt The format specific volume manager handle. */ DECLCALLBACKMEMBER(uint32_t, pfnGetMaxVolumes)(RTDVMFMT hVolMgrFmt); /** * Get the first valid volume from a map. * * @returns IPRT status code. * @param hVolMgrFmt The format specific volume manager handle. * @param phVolFmt Where to store the volume handle to the first volume * on success. */ DECLCALLBACKMEMBER(int, pfnQueryFirstVolume)(RTDVMFMT hVolMgrFmt, PRTDVMVOLUMEFMT phVolFmt); /** * Get the first valid volume from a map. * * @returns IPRT status code. * @param hVolMgrFmt The format specific volume manager handle. * @param hVolFmt The current volume. * @param phVolFmtNext Where to store the handle to the format specific * volume data of the next volume on success. */ DECLCALLBACKMEMBER(int, pfnQueryNextVolume)(RTDVMFMT hVolMgrFmt, RTDVMVOLUMEFMT hVolFmt, PRTDVMVOLUMEFMT phVolFmtNext); /** * Closes a volume handle. * * @returns nothing. * @param hVolFmt The format specific volume handle. */ DECLCALLBACKMEMBER(void, pfnVolumeClose)(RTDVMVOLUMEFMT hVolFmt); /** * Gets the size of the given volume. * * @returns Size of the volume in bytes or 0 on failure. * @param hVolFmt The format specific volume handle. */ DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetSize)(RTDVMVOLUMEFMT hVolFmt); /** * Queries the name of the given volume. * * @returns IPRT status code. * @param hVolFmt The format specific volume handle. * @param ppszVolname Where to store the name of the volume on success. */ DECLCALLBACKMEMBER(int, pfnVolumeQueryName)(RTDVMVOLUMEFMT hVolFmt, char **ppszVolName); /** * Get the type of the given volume. * * @returns The volume type on success, DVMVOLTYPE_INVALID if hVol is invalid. * @param hVolFmt The format specific volume handle. */ DECLCALLBACKMEMBER(RTDVMVOLTYPE, pfnVolumeGetType)(RTDVMVOLUMEFMT hVolFmt); /** * Get the flags of the given volume. * * @returns The volume flags or UINT64_MAX on failure. * @param hVolFmt The format specific volume handle. */ DECLCALLBACKMEMBER(uint64_t, pfnVolumeGetFlags)(RTDVMVOLUMEFMT hVolFmt); /** * Returns whether the supplied range is at least partially intersecting * with the given volume. * * @returns whether the range intersects with the volume. * @param hVolFmt The format specific volume handle. * @param offStart Start offset of the range. * @param cbRange Size of the range to check in bytes. * @param poffVol Where to store the offset of the range from the * start of the volume if true is returned. * @param pcbIntersect Where to store the number of bytes intersecting * with the range if true is returned. */ DECLCALLBACKMEMBER(bool, pfnVolumeIsRangeIntersecting)(RTDVMVOLUMEFMT hVolFmt, uint64_t offStart, size_t cbRange, uint64_t *poffVol, uint64_t *pcbIntersect); /** * Read data from the given volume. * * @returns IPRT status code. * @param hVolFmt The format specific volume handle. * @param off Where to start reading from. * @param pvBuf Where to store the read data. * @param cbRead How many bytes to read. */ DECLCALLBACKMEMBER(int, pfnVolumeRead)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, void *pvBuf, size_t cbRead); /** * Write data to the given volume. * * @returns IPRT status code. * @param hVolFmt The format specific volume handle. * @param off Where to start writing to. * @param pvBuf The data to write. * @param cbWrite How many bytes to write. */ DECLCALLBACKMEMBER(int, pfnVolumeWrite)(RTDVMVOLUMEFMT hVolFmt, uint64_t off, const void *pvBuf, size_t cbWrite); } RTDVMFMTOPS; /** Pointer to a DVM ops table. */ typedef RTDVMFMTOPS *PRTDVMFMTOPS; /** Pointer to a const DVM ops table. */ typedef const RTDVMFMTOPS *PCRTDVMFMTOPS; /** Checks whether a range is intersecting. */ #define RTDVM_RANGE_IS_INTERSECTING(start, size, off) ( (start) <= (off) && ((start) + (size)) > (off) ) /** Converts a LBA number to the byte offset. */ #define RTDVM_LBA2BYTE(lba, disk) ((lba) * (disk)->cbSector) /** Converts a Byte offset to the LBA number. */ #define RTDVM_BYTE2LBA(off, disk) ((off) / (disk)->cbSector) /** * Returns the number of sectors in the disk. * * @returns Number of sectors. * @param pDisk The disk descriptor. */ DECLINLINE(uint64_t) rtDvmDiskGetSectors(PCRTDVMDISK pDisk) { return pDisk->cbDisk / pDisk->cbSector; } /** * Read from the disk at the given offset. * * @returns IPRT status code. * @param pDisk The disk descriptor to read from. * @param off Start offset. * @param pvBuf Destination buffer. * @param cbRead How much to read. */ DECLINLINE(int) rtDvmDiskRead(PCRTDVMDISK pDisk, uint64_t off, void *pvBuf, size_t cbRead) { AssertPtrReturn(pDisk, VERR_INVALID_POINTER); AssertPtrReturn(pvBuf, VERR_INVALID_POINTER); AssertReturn(cbRead > 0, VERR_INVALID_PARAMETER); AssertReturn(off + cbRead <= pDisk->cbDisk, VERR_INVALID_PARAMETER); return pDisk->pfnRead(pDisk->pvUser, off, pvBuf, cbRead); } /** * Write to the disk at the given offset. * * @returns IPRT status code. * @param pDisk The disk descriptor to write to. * @param off Start offset. * @param pvBuf Source buffer. * @param cbWrite How much to write. */ DECLINLINE(int) rtDvmDiskWrite(PCRTDVMDISK pDisk, uint64_t off, const void *pvBuf, size_t cbWrite) { AssertPtrReturn(pDisk, VERR_INVALID_POINTER); AssertPtrReturn(pvBuf, VERR_INVALID_POINTER); AssertReturn(cbWrite > 0, VERR_INVALID_PARAMETER); AssertReturn(off + cbWrite <= pDisk->cbDisk, VERR_INVALID_PARAMETER); return pDisk->pfnWrite(pDisk->pvUser, off, pvBuf, cbWrite); } RT_C_DECLS_END #endif