aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2026-05-06 20:36:28 +00:00
Code Issues 3 Packages Projects Releases Wiki Activity
Files
e0b8fc76c1922dd9845803e00283de66ab4331e1
libaaruformat/docs/html/dump_8h.html

196 lines
12 KiB
HTML
Raw Normal View History

Add doxygen documentation
2025-10-11 01:35:43 +01:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
Updated doxygen documentation.
2025-12-21 20:17:32 +00:00
<meta name="generator" content="Doxygen 1.15.0"/>
Add doxygen documentation
2025-10-11 01:35:43 +01:00
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libaaruformat: include/aaruformat/structs/dump.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
Updated doxygen documentation.
2025-12-21 20:17:32 +00:00
<!-- Generated by Doxygen 1.15.0 -->
Add doxygen documentation
2025-10-11 01:35:43 +01:00
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('dump_8h.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">dump.h File Reference</div></div>
</div><!--header-->
<div class="contents">
<p>Packed on-disk structures describing hardware and software used during image acquisition.
<a href="#details">More...</a></p>
<div class="textblock"><code>#include &lt;stdint.h&gt;</code><br />
</div>
<p><a href="dump_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-nested-classes" class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:DumpHardwareHeader" id="r_DumpHardwareHeader"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structDumpHardwareHeader.html">DumpHardwareHeader</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Header that precedes a sequence of dump hardware entries and their variable-length payload. <a href="structDumpHardwareHeader.html#details">More...</a><br /></td></tr>
<tr class="memitem:DumpHardwareEntry" id="r_DumpHardwareEntry"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structDumpHardwareEntry.html">DumpHardwareEntry</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Per-environment length table describing subsequent UTF-8 strings and optional extent array. <a href="structDumpHardwareEntry.html#details">More...</a><br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-typedef-members" class="groupheader"><a id="typedef-members" name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:aa981a0ca569affe1e54ca0e382adb1cd" id="r_aa981a0ca569affe1e54ca0e382adb1cd"><td class="memItemLeft" align="right" valign="top">typedef struct DumpHardwareHeader&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#aa981a0ca569affe1e54ca0e382adb1cd">DumpHardwareHeader</a></td></tr>
<tr class="memitem:afd61d0986223157fbb7355586be9dcf1" id="r_afd61d0986223157fbb7355586be9dcf1"><td class="memItemLeft" align="right" valign="top">typedef struct DumpHardwareEntry&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#afd61d0986223157fbb7355586be9dcf1">DumpHardwareEntry</a></td></tr>
</table>
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Packed on-disk structures describing hardware and software used during image acquisition. </p>
<p>A Dump Hardware block (identifier = BlockType::DumpHardwareBlock) records one or more dump "environments" – typically combinations of a physical device (drive, controller, adapter) and the software stack that performed the read operation. Each environment is represented by a <a class="el" href="structDumpHardwareEntry.html">DumpHardwareEntry</a> followed by a sequence of UTF‑8 strings and an optional array of extent ranges (<a class="el" href="structDumpExtent.html">DumpExtent</a>, defined in <a class="el" href="context_8h.html" title="Central runtime context structures for libaaruformat (image state, caches, checksum buffers).">context.h</a>) that delimit portions of the medium this environment contributed to.</p>
<p>Binary layout (little-endian, packed, all multi-byte integers LE):</p>
<p><a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> (sizeof = 16 bytes) identifier (4) -&gt; BlockType::DumpHardwareBlock entries (2) -&gt; number of following hardware entries length (4) -&gt; total bytes of payload that follow this header crc64 (8) -&gt; CRC64-ECMA of the payload bytes</p>
<p>Repeated for i in [0, entries): <a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> (36 bytes) manufacturerLength (4) modelLength (4) revisionLength (4) firmwareLength (4) serialLength (4) softwareNameLength (4) softwareVersionLength (4) softwareOperatingSystemLength (4) extents (4) -&gt; number of <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> structs after the strings</p>
<p>Variable-length UTF-8 strings (not NUL-terminated on disk) appear immediately after the entry, in the exact order of the length fields above; each string is present only if its length &gt; 0. The reader allocates an extra byte to append '\0' for in-memory convenience.</p>
<p>Array of 'extents' <a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> structures (each 16 bytes: start, end) follows the strings if extents &gt; 0. The semantic of each extent is an inclusive [start, end] logical sector (or unit) range contributed by this hardware/software combination.</p>
<p>CRC semantics:</p><ul>
<li>crc64 covers exactly 'length' bytes immediately following the header.</li>
<li>For legacy images with header.imageMajorVersion &lt;= AARUF_VERSION_V1 the original C# writer produced a byte-swapped CRC; the library compensates internally (see <a class="el" href="internal_8h.html#a0e2cfc858c0551bc9bef11d5bdb85aac" title="Processes a dump hardware block from the image stream.">process_dumphw_block()</a>).</li>
</ul>
<p>Invariants / validation recommendations:</p><ul>
<li>identifier == BlockType::DumpHardwareBlock</li>
<li>Accumulated size of all (entry + strings + extents arrays) == length</li>
<li>All length fields are trusted only after bounds checking against remaining payload bytes</li>
<li>Strings are raw UTF-8 data with no implicit terminator</li>
<li>extents * sizeof(DumpExtent) fits inside remaining payload</li>
</ul>
<p>Memory management notes (runtime library):</p><ul>
<li>Each string is malloc'ed with +1 byte for terminator during processing.</li>
<li>Extents array is malloc'ed per entry when extents &gt; 0.</li>
<li>See aaruformatContext::dumpHardwareEntriesWithData for owning pointers.</li>
</ul>
<dl class="section warning"><dt>Warning</dt><dd>Structures are packed; never rely on natural alignment when mapping from a byte buffer. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="structDumpHardwareHeader.html" title="Header that precedes a sequence of dump hardware entries and their variable-length payload.">DumpHardwareHeader</a> </dd>
<dd>
<a class="el" href="structDumpHardwareEntry.html" title="Per-environment length table describing subsequent UTF-8 strings and optional extent array.">DumpHardwareEntry</a> </dd>
<dd>
<a class="el" href="structDumpExtent.html" title="Inclusive [start,end] logical sector range contributed by a single hardware environment.">DumpExtent</a> (in <a class="el" href="context_8h.html" title="Central runtime context structures for libaaruformat (image state, caches, checksum buffers).">context.h</a>) </dd>
<dd>
<a class="el" href="enums_8h.html#a54420623f26ab6bb61042b41cccf37a3" title="List of known block types contained in an Aaru image.">BlockType</a> </dd></dl>
<p class="definition">Definition in file <a class="el" href="dump_8h_source.html">dump.h</a>.</p>
</div><a name="doc-typedef-members" id="doc-typedef-members"></a><h2 id="header-doc-typedef-members" class="groupheader">Typedef Documentation</h2>
<a id="afd61d0986223157fbb7355586be9dcf1" name="afd61d0986223157fbb7355586be9dcf1"></a>
<h2 class="memtitle"><span class="permalink"><a href="#afd61d0986223157fbb7355586be9dcf1">&#9670;&#160;</a></span>DumpHardwareEntry</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct DumpHardwareEntry DumpHardwareEntry</td>
</tr>
</table>
</div><div class="memdoc">
</div>
</div>
<a id="aa981a0ca569affe1e54ca0e382adb1cd" name="aa981a0ca569affe1e54ca0e382adb1cd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa981a0ca569affe1e54ca0e382adb1cd">&#9670;&#160;</a></span>DumpHardwareHeader</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct DumpHardwareHeader DumpHardwareHeader</td>
</tr>
</table>
</div><div class="memdoc">
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a href="dir_aeff2545c9dfcfc842fe9d84b123cb31.html">aaruformat</a></li><li class="navelem"><a href="dir_6387aeb6e475a334d8dc12d69f21999e.html">structs</a></li><li class="navelem"><a href="dump_8h.html">dump.h</a></li>
Updated doxygen documentation.
2025-12-21 20:17:32 +00:00
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 </li>
Add doxygen documentation
2025-10-11 01:35:43 +01:00
</ul>
</div>
</body>
</html>
Reference in New Issue Copy Permalink