mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
196 lines
12 KiB
HTML
196 lines
12 KiB
HTML
<!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"/>
|
||
<meta name="generator" content="Doxygen 1.14.0"/>
|
||
<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"> 1.0</span>
|
||
</div>
|
||
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<!-- end header part -->
|
||
<!-- Generated by Doxygen 1.14.0 -->
|
||
<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 <stdint.h></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  </td><td class="memItemRight" valign="bottom"><a class="el" href="structDumpHardwareHeader.html">DumpHardwareHeader</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </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  </td><td class="memItemRight" valign="bottom"><a class="el" href="structDumpHardwareEntry.html">DumpHardwareEntry</a></td></tr>
|
||
<tr class="memdesc:"><td class="mdescLeft"> </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 </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 </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) -> BlockType::DumpHardwareBlock entries (2) -> number of following hardware entries length (4) -> total bytes of payload that follow this header crc64 (8) -> 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) -> 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 > 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 > 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 <= 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 > 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">◆ </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">◆ </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>
|
||
<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.14.0 </li>
|
||
</ul>
|
||
</div>
|
||
</body>
|
||
</html>
|