#include <Disk.h>

Inheritance diagram for Disk:

Collaboration diagram for Disk:

Classes
struct	ReadBuffer

struct	WriteBuffer

Public Types
enum	SubType { ATA = 0 , ATAPI }

Public Types inherited from Device
enum	Type { Generic , Root , Disk , Bus , Display , Network , Sound , Console , Mouse , Controller , UsbController , UsbGeneric , UsbContainer }

typedef Device (	Callback) (Device *)

Public Member Functions
	Disk (Device *p)

virtual Disk *	physicalDisk ()

bool	acquireUse (DiskUse &use)

uint32_t	endpointId ()

virtual bool	getPartitionUuid (String &uuid) const

virtual bool	getPartitionLabel (String &label) const

virtual PagingStatus	preparePagingTransport (PagingTransport *&transport)

void	retireEndpoint ()

bool	tryCloseEndpoint ()

void	reopenEndpoint ()

virtual Type	getType ()

virtual SubType	getSubType ()

virtual void	getName (String &str)

virtual void	dump (String &str)

virtual BufferView	read (uint64_t location)

virtual DiskReadView	readView (uint64_t location)

virtual DiskWriteView	writeView (uint64_t location)

virtual MUST_USE_RESULT bool	readInto (uint64_t location, void *buffer, size_t length)

virtual MUST_USE_RESULT bool	writeFrom (uint64_t location, const void *buffer, size_t length)

virtual MUST_USE_RESULT bool	writeFromBatch (WriteBuffer *buffers, size_t count)

virtual MUST_USE_RESULT bool	readIntoBatch (ReadBuffer *buffers, size_t count)

virtual MUST_USE_RESULT bool	syncData ()

MUST_USE_RESULT bool	readViews (uint64_t location, size_t length, BufferViewSequence &views)

void	unpinViews (uint64_t location, BufferViewSequence &views)

virtual void	write (uint64_t location)

virtual void	align (uint64_t location)
	Sets the page boundary alignment after a specific location on the disk.

virtual size_t	getSize () const
	Gets the size of the disk.

virtual size_t	getBlockSize () const
	Gets the preferred I/O extent of the disk.

virtual size_t	getNativeBlockSize () const

virtual MUST_USE_RESULT bool	pin (uint64_t location)=0
	Pins a cache page.

virtual void	unpin (uint64_t location)=0

virtual bool	cacheIsCritical ()
	Whether or not the cache is critical and cannot be flushed or deleted.

virtual void	flush (uint64_t location)
	Flush a cached page to disk.

virtual bool	sync (uint64_t location, bool async)

virtual MUST_USE_RESULT bool	syncPages (const uint64_t *locations, size_t count)

virtual MUST_USE_RESULT bool	syncAll ()

virtual MUST_USE_RESULT bool	retireCachePage (uint64_t location)

virtual MUST_USE_RESULT bool	zero (uint64_t location, size_t length)

Public Member Functions inherited from Device
	Device (Device *p)

Device *	getParent () const

void	setParent (Device *p)

virtual const String &	getSpecificType ()

virtual void	setSpecificType (String str)

void	setPciPosition (uint32_t bus, uint32_t device, uint32_t func)

void	setPciIdentifiers (uint8_t classCode, uint8_t subclassCode, uint16_t vendorId, uint16_t deviceId, uint8_t progIf)

void	setPciConfigHeader (const PciBus::ConfigSpace &space)

PciBus::ConfigSpace	getPciConfigHeader () const

uint8_t	getPciClassCode ()

uint8_t	getPciSubclassCode ()

uint16_t	getPciVendorId ()

uint16_t	getPciDeviceId ()

uint8_t	getPciProgInterface ()

uint32_t	getPciBusPosition ()

uint32_t	getPciDevicePosition ()

uint32_t	getPciFunctionNumber ()

Device *	getPhysicalFunction () const

size_t	getVirtualFunctionIndex () const

void	setVirtualFunction (Device *physicalFunction, size_t index)

virtual Vector< Address * > &	addresses ()

virtual uintptr_t	getInterruptNumber ()

virtual void	setInterruptNumber (uintptr_t n)

void	addChild (Device *pDevice)

Device *	getChild (size_t n)

size_t	getNumChildren ()

void	removeChild (size_t n)

void	removeChild (Device *d)

void	replaceChild (Device src, Device dest)

Static Public Attributes
static constexpr size_t	MaxReadBuffers = 32

static constexpr size_t	MaxWriteBuffers = 32

static constexpr size_t	MaxSyncPages = 64

Protected Member Functions
void	reserveEndpoint ()

void	publishEndpoint ()

virtual BufferView	acquireView (uint64_t location, bool writable, uint64_t &token)

virtual void	releaseView (uint64_t token, bool writable)

Protected Member Functions inherited from Device
	NOT_COPYABLE_OR_ASSIGNABLE (Device)

Private Attributes
DiskEndpoint *	m_Endpoint

Friends
class	DiskReadView

Additional Inherited Members
Static Public Member Functions inherited from Device
static bool	treeLockHeldByCurrentThread ()

static void	foreach (Callback callback, Device *root=0)

template<class F , class... Args>
static void	foreach (pedigree_std::Callable< F > &callback, Device *root, Args... args)

static void	addToRoot (Device *device)

static void	searchByVendorId (uint16_t vendorId, void(callback)(Device ), Device *root=0)

static void	searchByVendorIdAndDeviceId (uint16_t vendorId, uint16_t deviceId, void(callback)(Device ), Device *root=0)

static void	searchByClass (uint16_t classCode, void(callback)(Device ), Device *root=0)

static void	searchByClassAndSubclass (uint16_t classCode, uint16_t subclassCode, void(callback)(Device ), Device *root=0)

static void	searchByClassSubclassAndProgInterface (uint16_t classCode, uint16_t subclassCode, uint8_t progInterface, void(callback)(Device ), Device *root=0)

Static Protected Member Functions inherited from Device
static Device &	root ()

Protected Attributes inherited from Device
Vector< Address * >	m_Addresses

Vector< Device * >	m_Children

Device *	m_pParent

Device *	m_PhysicalFunction

size_t	m_VirtualFunctionIndex

uintptr_t	m_InterruptNumber

String	m_SpecificType

PciBus::ConfigSpace	m_ConfigHeader

uint8_t	m_ClassCode

uint8_t	m_SubclassCode

uint16_t	m_VendorId

uint16_t	m_DeviceId

uint8_t	m_ProgInterface

uint32_t	m_PciBusPos

uint32_t	m_PciDevicePos

uint32_t	m_PciFunctionNum

Static Protected Attributes inherited from Device
static Device	m_Root

static Mutex	m_TreeLock

Detailed Description

A disk is a random access fixed size block device.

Definition at line 35 of file Disk.h.

Member Enumeration Documentation

◆ SubType

enum Disk::SubType

Definition at line 37 of file Disk.h.

Constructor & Destructor Documentation

◆ Disk() [1/2]

Disk::Disk ( )

Definition at line 84 of file Disk.cc.

◆ Disk() [2/2]

Disk::Disk ( Device * p )

Definition at line 88 of file Disk.cc.

◆ ~Disk()

Disk::~Disk ( )

virtual

Definition at line 90 of file Disk.cc.

Member Function Documentation

◆ acquireUse()

bool Disk::acquireUse ( DiskUse & use )

Definition at line 98 of file Disk.cc.

◆ acquireView()

BufferView Disk::acquireView	(	uint64_t	location,
		bool	writable,
		uint64_t &	token
	)

protectedvirtual

Definition at line 188 of file Disk.cc.

◆ align()

void Disk::align ( uint64_t location )

virtual

Sets the page boundary alignment after a specific location on the disk.

For example, a partition beginning at byte 512 should align its first cache page with that boundary rather than with byte zero of the parent.

Use this function to keep the cache pages manipulated in read() and write() aligned with a child device whose start is not naturally page-aligned on the parent.

Reimplemented in ScsiDisk, DiskImage, and FileDisk.

Definition at line 342 of file Disk.cc.

◆ cacheIsCritical()

bool Disk::cacheIsCritical ( )

virtual

Whether or not the cache is critical and cannot be flushed or deleted.

Some implementations of this class may provide a Disk that does not actually back onto a writable media, or perhaps sit only in RAM and have no correlation to physical hardware. If cache pages are deleted for these implementations, data may be lost.

Note that cache should only be marked "critical" if it is possible to write via an implementation. There is no need to worry about cache pages being deleted on a read-only disk as they will be re-created on the next read (and no written data is lost).

This function allows callers that want to delete cache pages to verify that the cache is not critical to the performance of the implementation.

Returns: True if the cache is critical and must not be removed or flushed. False otherwise.

Reimplemented in FileDisk.

Definition at line 352 of file Disk.cc.

◆ dump()

void Disk::dump ( String & str )

virtual

Dumps a textual representation of the device into the given string.

Reimplemented from Device.

Reimplemented in DiskImage, and Partition.

Definition at line 159 of file Disk.cc.

◆ endpointId()

uint32_t Disk::endpointId ( )

Definition at line 111 of file Disk.cc.

◆ flush()

void Disk::flush ( uint64_t location )

virtual

Flush a cached page to disk.

Essentially a no-op if the given location is not actually in cache. Called either by filesystem drivers (on removable disks) or from a central cache manager which handles flushing caches back to the disk on a regular basis.

Will not remove the page from cache, that must be done by the caller.

Reimplemented in ScsiDisk, and Partition.

Definition at line 356 of file Disk.cc.

Referenced by Partition::flush().

Here is the caller graph for this function:

◆ getBlockSize()

size_t Disk::getBlockSize ( ) const

virtual

Gets the preferred I/O extent of the disk.

This may describe a native device block or a larger cache-fill/readahead extent, depending on the implementation. It is independent of the cache page boundary reported by BufferView::size().

Reimplemented in AtaDisk, ScsiDisk, DiskImage, AhciDisk, NvmeDisk, Partition, and VirtioBlkDisk.

Definition at line 348 of file Disk.cc.

Referenced by Partition::getBlockSize().

Here is the caller graph for this function:

◆ getName()

void Disk::getName ( String & str )

virtual

Stores the device's name in str.

Reimplemented from Device.

Reimplemented in AhciDisk, NvmeDisk, VirtioBlkDisk, AtaDisk, ScsiDisk, DiskImage, FileDisk, and Partition.

Definition at line 155 of file Disk.cc.

Referenced by Ext2Filesystem::initialise(), and FatFilesystem::initialise().

Here is the caller graph for this function:

◆ getNativeBlockSize()

size_t Disk::getNativeBlockSize ( ) const

virtual

Size of a logical sector used by on-disk LBA addressing.

Reimplemented in AtaDisk, ScsiDisk, AhciDisk, NvmeDisk, Partition, and VirtioBlkDisk.

Definition at line 383 of file Disk.cc.

Referenced by Partition::getNativeBlockSize(), and msdosProbeDisk().

Here is the caller graph for this function:

◆ getPartitionLabel()

bool Disk::getPartitionLabel ( String & label ) const

virtual

Definition at line 121 of file Disk.cc.

◆ getPartitionUuid()

bool Disk::getPartitionUuid ( String & uuid ) const

virtual

GPT-style partition identity, when this endpoint represents a partition.

Reimplemented in Partition.

Definition at line 116 of file Disk.cc.

◆ getSize()

size_t Disk::getSize ( ) const

virtual

Gets the size of the disk.

This is the size in bytes of the disk. Reads or writes beyond this size will fail.

Reimplemented in AtaDisk, ScsiDisk, DiskImage, FileDisk, AhciDisk, NvmeDisk, Partition, and VirtioBlkDisk.

Definition at line 344 of file Disk.cc.

Referenced by RawFsFile::RawFsFile(), readInto(), readViews(), syncPages(), Partition::syncPages(), Ext2File::syncPages(), and zero().

Here is the caller graph for this function:

◆ getSubType()

Disk::SubType Disk::getSubType ( )

virtual

Definition at line 151 of file Disk.cc.

◆ getType()

Device::Type Disk::getType ( )

virtual

Returns the (abstract) type of the device.

Reimplemented from Device.

Definition at line 147 of file Disk.cc.

References Device::Disk.

◆ physicalDisk()

Disk * Disk::physicalDisk ( )

virtual

Definition at line 94 of file Disk.cc.

◆ pin()

virtual MUST_USE_RESULT bool Disk::pin ( uint64_t location )

pure virtual

Pins a cache page.

This allows an upstream user of Disk pages to 'pin' cache pages, causing them to only be freed once all consumers have done an 'unpin'. The pin and unpin semantics allow for memory mappings to be made in a reasonably safe manner, as it can be assumed that the physical page for a particular cache block will not be freed.

Returns: True only when this call acquired a reference to the page currently published for location. Callers must not use an address obtained before a failed pin.

Implemented in ScsiDisk, DiskImage, FileDisk, and Partition.

Referenced by Partition::pin(), and Iso9660File::pinBlock().

Here is the caller graph for this function:

◆ preparePagingTransport()

PagingStatus Disk::preparePagingTransport ( PagingTransport *& transport )

virtual

Called while the endpoint excludes new ordinary users.

Reimplemented in AtaDisk.

Definition at line 142 of file Disk.cc.

◆ publishEndpoint()

void Disk::publishEndpoint ( )

protected

Definition at line 130 of file Disk.cc.

◆ read()

BufferView Disk::read ( uint64_t location )

virtual

Read from location on disk and return a view beginning at that byte. location must be 512-byte aligned. The returned view ends at the boundary of the independently owned cache page containing location; its size is unrelated to the device's block or readahead size.

Note: A successful read returns exactly one caller-owned reference to the cache page containing location. The view is non-owning: use unpin() exactly once after every copy and subview is no longer in use. Larger I/O extents do not extend this ownership.

Parameters

location The offset from the start of the device, in bytes, to start the read, must be multiple of 512. Prefer readView() for readers and writeView() for scoped mutation. This legacy interface treats every read()/pin() reference as potentially mutable until its matching unpin(). No derived pointers may survive that reference.

Returns: A writable view containing the data, or an empty view on failure. If the data is written, the page is marked as dirty and may be written back to disk at any time (or forced with write() or flush() ).

Reimplemented in ScsiDisk, DiskImage, FileDisk, and Partition.

Definition at line 163 of file Disk.cc.

Referenced by Ext2Filesystem::initialise(), FatFilesystem::initialise(), Partition::read(), Ext2Filesystem::readBlock(), RawFsFile::readBlock(), FatFilesystem::readSectorBlock(), readViews(), and zero().

Here is the caller graph for this function:

◆ readInto()

bool Disk::readInto	(	uint64_t	location,
		void *	buffer,
		size_t	length
	)

virtual

Transfers exactly length bytes using caller-owned, pinned storage. The buffer must remain valid until return and must not alias this disk's cache. No buffer reference is retained. Failure may have transferred a prefix. Existing block-cache data remains coherent; unsupported transports copy through their ordinary cache views.

Reimplemented in Partition, and ScsiDisk.

Definition at line 219 of file Disk.cc.

References getSize(), and readView().

Referenced by readIntoBatch(), and Iso9660File::readPage().

Here is the caller graph for this function:

◆ readIntoBatch()

bool Disk::readIntoBatch	(	ReadBuffer *	buffers,
		size_t	count
	)

virtual

Reads up to MaxReadBuffers independent ranges into caller-owned, pinned storage. Physical mappings must remain stable until return. Every issued transfer is drained before return, including on failure. complete is reset on entry and set only for fully initialised buffers; successful buffers remain usable when another range fails.

Reimplemented in Partition, and ScsiDisk.

Definition at line 199 of file Disk.cc.

References readInto().

Referenced by ScsiDisk::readIntoBatch(), and Ext2File::readPages().

Here is the caller graph for this function:

◆ readView()

DiskReadView Disk::readView ( uint64_t location )

virtual

Owning views release their pin automatically. Read views cannot modify cache data. Returning a write view records changes; use sync() or syncAll() for durability.

Reimplemented in Partition.

Definition at line 167 of file Disk.cc.

Referenced by readInto().

Here is the caller graph for this function:

◆ readViews()

bool Disk::readViews	(	uint64_t	location,
		size_t	length,
		BufferViewSequence &	views
	)

Reads exactly the requested length into a caller-supplied sequence of bounded cache views. The sequence must be empty on entry. Each appended view owns one cache reference until unpinViews() is called.

Failure releases every reference acquired by this operation and leaves the sequence empty.

Definition at line 303 of file Disk.cc.

References getSize(), read(), unpin(), and unpinViews().

Referenced by Iso9660Filesystem::readSector().

Here is the caller graph for this function:

◆ releaseView()

void Disk::releaseView	(	uint64_t	token,
		bool	writable
	)

protectedvirtual

Definition at line 193 of file Disk.cc.

◆ reopenEndpoint()

void Disk::reopenEndpoint ( )

Definition at line 139 of file Disk.cc.

◆ reserveEndpoint()

void Disk::reserveEndpoint ( )

protected

Definition at line 126 of file Disk.cc.

◆ retireCachePage()

bool Disk::retireCachePage ( uint64_t location )

virtual

Synchronously writes and retires the target cache page containing location.

A successful call means the page is no longer published by this disk's cache. It does not imply that a volatile device write cache has been flushed. Callers must release their own reference to the page before entering this operation.

Returns: True when the page was retired or was already absent. False when this disk does not support retirement or the page must remain available for a later retry.

Reimplemented in ScsiDisk, and Partition.

Definition at line 379 of file Disk.cc.

Referenced by Partition::retireCachePage().

Here is the caller graph for this function:

◆ retireEndpoint()

void Disk::retireEndpoint ( )

Withdraws selectors and joins users before derived driver teardown.

Definition at line 133 of file Disk.cc.

◆ sync()

bool Disk::sync	(	uint64_t	location,
		bool	async
	)

virtual

Writes a cached page and reports failure. Synchronous success includes the device's write-cache flush; asynchronous success means admission only. Unsupported backends return false rather than claiming persistence.

Reimplemented in ScsiDisk, and Partition.

Definition at line 358 of file Disk.cc.

Referenced by Ext2Filesystem::shutdown(), Partition::sync(), and syncPages().

Here is the caller graph for this function:

◆ syncAll()

bool Disk::syncAll ( )

virtual

Drains existing cached writes and the device write cache synchronously.

Reimplemented in ScsiDisk, and Partition.

Definition at line 375 of file Disk.cc.

Referenced by Ext2Filesystem::shutdown(), Ext2Filesystem::sync(), and Partition::syncAll().

Here is the caller graph for this function:

◆ syncData()

bool Disk::syncData ( )

virtual

Makes preceding successful writeFrom() calls durable. Call after all writes in a batch, including a partially failed batch. writeFrom() alone promises transfer completion, not a device write-cache barrier. Legacy fallbacks persist each write individually, so their final barrier is already done.

Reimplemented in Partition, and ScsiDisk.

Definition at line 299 of file Disk.cc.

Referenced by Partition::syncData(), and FatFilesystem::writeSectorBlock().

Here is the caller graph for this function:

◆ syncPages()

bool Disk::syncPages	(	const uint64_t *	locations,
		size_t	count
	)

virtual

Synchronously persists every listed cached page, including the device cache.

Reimplemented in Partition, and ScsiDisk.

Definition at line 362 of file Disk.cc.

References getSize(), and sync().

Referenced by Partition::syncPages(), and Ext2File::syncPages().

Here is the caller graph for this function:

◆ tryCloseEndpoint()

bool Disk::tryCloseEndpoint ( )

Definition at line 136 of file Disk.cc.

◆ unpin()

virtual void Disk::unpin ( uint64_t location )

pure virtual

Unpins a cache page (see pin() for more information and rationale).

Implemented in ScsiDisk, DiskImage, FileDisk, and Partition.

Referenced by Ext2Filesystem::deviceRemoved(), Ext2Filesystem::initialise(), FatFilesystem::initialise(), Ext2Filesystem::readBlock(), RawFsFile::readBlock(), FatFilesystem::readSectorBlock(), readViews(), Partition::unpin(), Iso9660File::unpinBlock(), unpinViews(), and zero().

Here is the caller graph for this function:

◆ unpinViews()

void Disk::unpinViews	(	uint64_t	location,
		BufferViewSequence &	views
	)

Releases every cache reference represented by the supplied sequence.

Definition at line 330 of file Disk.cc.

References unpin().

Referenced by Iso9660Filesystem::readSector(), and readViews().

Here is the caller graph for this function:

◆ write()

void Disk::write ( uint64_t location )

virtual

This function schedules a cache writeback of the given location. The data to be written back is fetched from the cache (pointer returned by read() ).

Parameters

location The offset from the start of the device, in bytes, to start the write. Must be 512byte aligned.

Reimplemented in ScsiDisk, FileDisk, Partition, and VirtioBlkDisk.

Definition at line 340 of file Disk.cc.

Referenced by Ext2Filesystem::findFreeBlocksInGroup(), Ext2Filesystem::releaseBlockLocked(), Ext2Filesystem::retireInodeLocked(), Ext2Filesystem::shutdown(), Partition::write(), Ext2Filesystem::writeBlock(), and zero().

Here is the caller graph for this function:

◆ writeFrom()

bool Disk::writeFrom	(	uint64_t	location,
		const void *	buffer,
		size_t	length
	)

virtual

Definition at line 249 of file Disk.cc.

◆ writeFromBatch()

bool Disk::writeFromBatch	(	WriteBuffer *	buffers,
		size_t	count
	)

virtual

Writes caller-owned buffers, draining all issued I/O before return. complete reports each fully transferred range, including on partial failure. Storage must remain valid until return; syncData() supplies durability.

Reimplemented in Partition, ScsiDisk, and VirtioBlkDisk.

Definition at line 285 of file Disk.cc.

Referenced by ScsiDisk::writeFromBatch().

Here is the caller graph for this function:

◆ writeView()

DiskWriteView Disk::writeView ( uint64_t location )

virtual

Definition at line 178 of file Disk.cc.

◆ zero()

bool Disk::zero	(	uint64_t	location,
		size_t	length
	)

virtual

Zeroes a range in the cache; syncAll supplies durability. A failed call may have zeroed a prefix. Full cache pages need no old contents read.

Reimplemented in Partition, ScsiDisk, and VirtioBlkDisk.

Definition at line 387 of file Disk.cc.

References getSize(), read(), unpin(), and write().

Referenced by Ext2Node::ensureLargeEnough(), and ScsiDisk::zero().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ DiskReadView

friend class DiskReadView

friend

Definition at line 103 of file Disk.h.

Member Data Documentation

◆ m_Endpoint

DiskEndpoint* Disk::m_Endpoint

private

Definition at line 64 of file Disk.h.

◆ MaxReadBuffers

constexpr size_t Disk::MaxReadBuffers = 32

staticconstexpr

Definition at line 125 of file Disk.h.

◆ MaxSyncPages

constexpr size_t Disk::MaxSyncPages = 64

staticconstexpr

Definition at line 275 of file Disk.h.

◆ MaxWriteBuffers

constexpr size_t Disk::MaxWriteBuffers = 32

staticconstexpr

Definition at line 134 of file Disk.h.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ SubType

Constructor & Destructor Documentation

◆ Disk() [1/2]

◆ Disk() [2/2]

◆ ~Disk()

Member Function Documentation

◆ acquireUse()

◆ acquireView()

◆ align()

◆ cacheIsCritical()

◆ dump()

◆ endpointId()

◆ flush()

◆ getBlockSize()

◆ getName()

◆ getNativeBlockSize()

◆ getPartitionLabel()

◆ getPartitionUuid()

◆ getSize()

◆ getSubType()

◆ getType()

◆ physicalDisk()

◆ pin()

◆ preparePagingTransport()

◆ publishEndpoint()

◆ read()

◆ readInto()

◆ readIntoBatch()

◆ readView()

◆ readViews()

◆ releaseView()

◆ reopenEndpoint()

◆ reserveEndpoint()

◆ retireCachePage()

◆ retireEndpoint()

◆ sync()

◆ syncAll()

◆ syncData()

◆ syncPages()

◆ tryCloseEndpoint()

◆ unpin()

◆ unpinViews()

◆ write()

◆ writeFrom()

◆ writeFromBatch()

◆ writeView()

◆ zero()

Friends And Related Symbol Documentation

◆ DiskReadView

Member Data Documentation

◆ m_Endpoint

◆ MaxReadBuffers

◆ MaxSyncPages

◆ MaxWriteBuffers