use std::borrow::Cow;
use std::io::{Cursor, Seek, Write};
use crate::fidelity::{AcceptedLoss, FidelityReport, LossPolicy, Synthesis};
use crate::image_source::ImageFile;
use crate::io::ByteSink;
use crate::sizing::Slack;
use crate::source::{FileContent, FileRange, Source};
use super::geometry::{ExfatLayout, GeometryError, PlanRequest, plan_layout};
use super::model::{
ClusterRun, ExfatModel, ModelConfig, ModelEntry, ModelError, Node, ROOT_DIR,
ROOT_LEADING_SLOTS, build_model, place_tree,
};
use super::ondisk::{
AllocationBitmapEntry, BOOT_CODE_LEN, BOOT_REGION_SECTORS, CHECKSUM_SECTOR, DIR_ENTRY_SIZE,
DirEntry, END_OF_CHAIN, EXTENDED_BOOT_FIRST_SECTOR, EXTENDED_BOOT_SECTORS, EntryType,
FAT_ENTRY_MEDIA, FAT_ENTRY_RESERVED, FILE_SYSTEM_NAME, FILE_SYSTEM_REVISION, FileEntry,
FileNameEntry, MAX_LABEL_UNITS, MainBootSector, NAME_UNITS_PER_ENTRY, ParseError,
RECOMMENDED_UPCASE_BYTES, RECOMMENDED_UPCASE_CHECKSUM, RECOMMENDED_UPCASE_TABLE,
SECONDARY_ALLOCATION_POSSIBLE, SECONDARY_NO_FAT_CHAIN, StreamExtensionEntry, UTC_OFFSET,
UpcaseTable, UpcaseTableEntry, VolumeLabelEntry, boot_checksum, entry_set_checksum,
pack_timestamp, percent_in_use, write_checksum_sector, write_extended_boot_sector,
write_upcase_table,
};
use crate::bytes::put_u32;
const DRIVE_SELECT: u8 = 0x80;
const NUMBER_OF_FATS: u8 = 1;
const TABLE_BATCH_ENTRIES: usize = 4096;
const BITMAP_BATCH_BYTES: usize = 16 << 10;
const TAIL_BYTES: u64 = 1 << 20;
const ZERO_BATCH_BYTES: usize = 64 << 10;
#[derive(Clone, Copy, PartialEq, Eq)]
pub struct VolumeLabel {
units: [u16; MAX_LABEL_UNITS],
len: u8,
}
impl VolumeLabel {
pub const MAX_UNITS: usize = MAX_LABEL_UNITS;
pub const UNNAMED: Self = Self {
units: [0; MAX_LABEL_UNITS],
len: 0,
};
pub fn new(name: &str) -> Result<Self, LabelError> {
let mut units = [0u16; MAX_LABEL_UNITS];
let mut len = 0usize;
if let Some(ch) = name
.chars()
.find(|ch| *ch != '\0' && crate::path::is_reserved_name_char(*ch))
{
return Err(LabelError::ForbiddenCharacter { ch });
}
for unit in name.encode_utf16() {
if unit == 0 {
return Err(LabelError::NulUnit { at: len });
}
if len == MAX_LABEL_UNITS {
return Err(LabelError::TooLong {
units: name.encode_utf16().count(),
limit: MAX_LABEL_UNITS,
});
}
units[len] = unit;
len += 1;
}
Ok(Self {
len: len as u8,
units,
})
}
#[must_use]
pub fn units(&self) -> &[u16] {
&self.units[..self.len as usize]
}
fn entry(&self) -> VolumeLabelEntry {
VolumeLabelEntry {
character_count: self.len,
label: self.units,
}
}
}
impl Default for VolumeLabel {
fn default() -> Self {
Self::UNNAMED
}
}
impl core::fmt::Debug for VolumeLabel {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
let text: String = char::decode_utf16(self.units().iter().copied())
.map(|c| c.unwrap_or(char::REPLACEMENT_CHARACTER))
.collect();
write!(f, "VolumeLabel({text:?})")
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum LabelError {
#[error("volume label of {units} UTF-16 units exceeds the {limit} the format holds")]
#[non_exhaustive]
TooLong {
units: usize,
limit: usize,
},
#[error("a volume label may not contain U+0000, and this one does at unit {at}")]
#[non_exhaustive]
NulUnit {
at: usize,
},
#[error("a volume label may not contain {ch:?}")]
#[non_exhaustive]
ForbiddenCharacter {
ch: char,
},
}
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub struct FormatOptions {
pub volume_serial: u32,
pub label: VolumeLabel,
pub boot_code: [u8; BOOT_CODE_LEN],
pub plan: PlanRequest,
pub accepted_loss: AcceptedLoss,
pub synthesis: Synthesis,
}
impl FormatOptions {
#[must_use]
pub const fn new(volume_serial: u32) -> Self {
Self {
volume_serial,
label: VolumeLabel::UNNAMED,
boot_code: [0; BOOT_CODE_LEN],
plan: PlanRequest::new(0),
accepted_loss: AcceptedLoss::NONE,
synthesis: Synthesis::new(),
}
}
#[must_use]
pub const fn label(mut self, label: VolumeLabel) -> Self {
self.label = label;
self
}
#[must_use]
pub const fn boot_code(mut self, boot_code: [u8; BOOT_CODE_LEN]) -> Self {
self.boot_code = boot_code;
self
}
#[must_use]
pub const fn plan(mut self, plan: PlanRequest) -> Self {
self.plan = plan;
self
}
#[must_use]
pub const fn accepted_loss(mut self, accepted: AcceptedLoss) -> Self {
self.accepted_loss = accepted;
self
}
#[must_use]
pub const fn synthesis(mut self, synthesis: Synthesis) -> Self {
self.synthesis = synthesis;
self
}
fn model_config<'a>(&self, upcase: &'a UpcaseTable) -> ModelConfig<'a> {
ModelConfig {
loss: LossPolicy {
accepted: self.accepted_loss,
synthesis: self.synthesis,
},
upcase,
}
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum FormatError {
#[error(transparent)]
Io(#[from] std::io::Error),
#[error(transparent)]
Geometry(#[from] GeometryError),
#[error(transparent)]
Parse(#[from] ParseError),
#[error(transparent)]
Model(#[from] ModelError),
#[error(
"directory {index} needs {bytes} bytes of entries and was given {capacity} bytes of \
clusters"
)]
#[non_exhaustive]
DirectoryOverflowsItsClusters {
index: usize,
bytes: u64,
capacity: u64,
},
#[error(
"a file declared by its length alone, under key {key}, holds no bytes for a write to \
place; the plan's stages say where they go"
)]
#[non_exhaustive]
ContentsNotHeld {
key: u64,
},
#[error("slack of {hundredths} hundredths of a percent is past the limit of {limit}")]
#[non_exhaustive]
SlackShareTooLarge {
hundredths: u16,
limit: u16,
},
#[error("no volume up to {ceiling} bytes holds the tree with the room asked for")]
#[non_exhaustive]
DoesNotFit {
ceiling: u64,
},
#[error("an image of {bytes} bytes cannot be held in memory on this machine")]
#[non_exhaustive]
ImageTooLargeInMemory {
bytes: u64,
},
#[error(
"{region} needs cluster {cluster}, which the layout's own fields say the volume does \
not have"
)]
#[non_exhaustive]
ClusterOutsideVolume {
region: &'static str,
cluster: u32,
},
}
pub struct Image {
bytes: Vec<u8>,
layout: ExfatLayout,
fidelity: FidelityReport,
}
impl Image {
#[must_use]
pub fn as_bytes(&self) -> &[u8] {
&self.bytes
}
#[must_use]
pub fn into_bytes(self) -> Vec<u8> {
self.bytes
}
#[must_use]
pub fn layout(&self) -> &ExfatLayout {
&self.layout
}
#[must_use]
pub fn fidelity(&self) -> &FidelityReport {
&self.fidelity
}
pub fn write_to(&self, mut w: impl Write) -> std::io::Result<()> {
w.write_all(&self.bytes)
}
}
pub struct FormatPlan {
layout: ExfatLayout,
volume_bytes: u64,
options: FormatOptions,
model: ExfatModel,
}
impl FormatPlan {
pub fn new(
source: impl Source,
volume_bytes: u64,
options: FormatOptions,
) -> Result<Self, FormatError> {
let layout = plan(volume_bytes, &options)?;
let upcase = UpcaseTable::recommended();
let model = build_model(
source.into_entries(),
&layout,
&options.model_config(&upcase),
)?;
Ok(Self {
layout,
volume_bytes,
options,
model,
})
}
pub fn fit(
source: impl Source,
options: FormatOptions,
slack: Slack,
) -> Result<Self, FormatError> {
let upcase = UpcaseTable::recommended();
let mut tree = place_tree(source.into_entries(), &options.model_config(&upcase))?;
let fitted = crate::exfat::fit::search(&mut tree, &options, slack)?;
let volume_bytes = fitted.layout.volume_length * u64::from(fitted.layout.bytes_per_sector);
Ok(Self {
layout: fitted.layout,
volume_bytes,
options,
model: tree.finish(fitted.used_clusters),
})
}
#[must_use]
pub const fn free_clusters(&self) -> u32 {
self.layout.cluster_count - self.model.used_clusters
}
#[must_use]
pub const fn layout(&self) -> &ExfatLayout {
&self.layout
}
#[must_use]
pub const fn volume_bytes(&self) -> u64 {
self.volume_bytes
}
#[must_use]
pub fn fidelity(&self) -> &FidelityReport {
&self.model.fidelity
}
#[must_use]
pub fn stages(&self) -> [Stage<'_>; 5] {
StageKind::ORDER.map(|kind| Stage { plan: self, kind })
}
pub fn write_to(&self, sink: impl Write + Seek) -> Result<ExfatLayout, FormatError> {
if let Some(key) = self.declared_key() {
return Err(FormatError::ContentsNotHeld { key });
}
let mut sink = ByteSink::new(sink);
sink.extend_to(self.volume_bytes)?;
let zeros = vec![0u8; ZERO_BATCH_BYTES];
for stage in self.stages() {
for piece in stage.pieces() {
match piece? {
Piece::Bytes { offset, bytes } => sink.write_at(offset, &bytes)?,
Piece::Zeros { offset, len } => {
let mut done = 0u64;
while done < len {
let n = (len - done).min(ZERO_BATCH_BYTES as u64);
sink.write_at(offset + done, &zeros[..n as usize])?;
done += n;
}
}
Piece::Range { offset, range } => {
range.for_each_window(|at, window| sink.write_at(offset + at, window))?;
}
Piece::Image { offset, file } => {
FileContent::Image(file.clone())
.for_each_window(|at, window| sink.write_at(offset + at, window))?;
}
Piece::Declared { key, .. } => {
return Err(FormatError::ContentsNotHeld { key });
}
}
}
sink.flush()?;
}
Ok(self.layout)
}
fn declared_key(&self) -> Option<u64> {
self.model
.contents
.iter()
.find_map(|content| match content {
FileContent::Declared { len, key } if *len > 0 => Some(*key),
_ => None,
})
}
}
pub fn format(
source: impl Source,
volume_bytes: u64,
options: FormatOptions,
) -> Result<Image, FormatError> {
let plan = FormatPlan::new(source, volume_bytes, options)?;
let buffer =
crate::io::image_buffer(volume_bytes).ok_or(FormatError::ImageTooLargeInMemory {
bytes: volume_bytes,
})?;
let mut image = Cursor::new(buffer);
let layout = plan.write_to(&mut image)?;
Ok(Image {
bytes: image.into_inner(),
layout,
fidelity: plan.model.fidelity,
})
}
pub fn format_to<W: Write + Seek>(
sink: W,
source: impl Source,
volume_bytes: u64,
options: FormatOptions,
) -> Result<FormatPlan, FormatError> {
let plan = FormatPlan::new(source, volume_bytes, options)?;
plan.write_to(sink)?;
Ok(plan)
}
fn plan(volume_bytes: u64, options: &FormatOptions) -> Result<ExfatLayout, FormatError> {
let mut request = options.plan;
request.volume_bytes = volume_bytes;
Ok(plan_layout(&request)?)
}
fn boot_region(
layout: &ExfatLayout,
options: &FormatOptions,
model: &ExfatModel,
) -> Result<Vec<u8>, FormatError> {
let sector = layout.bytes_per_sector as usize;
let mut region = vec![0u8; sector * BOOT_REGION_SECTORS as usize];
boot_sector(layout, options, model).write_to(&mut region[..sector])?;
for n in EXTENDED_BOOT_FIRST_SECTOR..EXTENDED_BOOT_FIRST_SECTOR + EXTENDED_BOOT_SECTORS {
let at = n as usize * sector;
write_extended_boot_sector(&mut region[at..at + sector]);
}
let checksum_at = CHECKSUM_SECTOR as usize * sector;
let checksum = boot_checksum(®ion[..checksum_at]);
write_checksum_sector(&mut region[checksum_at..checksum_at + sector], checksum);
Ok(region)
}
fn boot_sector(
layout: &ExfatLayout,
options: &FormatOptions,
model: &ExfatModel,
) -> MainBootSector {
MainBootSector {
jump_boot: MainBootSector::JUMP_BOOT,
file_system_name: FILE_SYSTEM_NAME,
partition_offset: 0,
volume_length: layout.volume_length,
fat_offset: layout.fat_offset,
fat_length: layout.fat_length,
cluster_heap_offset: layout.cluster_heap_offset,
cluster_count: layout.cluster_count,
first_cluster_of_root: layout.first_cluster_of_root,
volume_serial: options.volume_serial,
file_system_revision: FILE_SYSTEM_REVISION,
volume_flags: 0,
bytes_per_sector_shift: layout.bytes_per_sector_shift(),
sectors_per_cluster_shift: layout.sectors_per_cluster_shift(),
number_of_fats: NUMBER_OF_FATS,
drive_select: DRIVE_SELECT,
percent_in_use: percent_in_use(model.used_clusters, layout.cluster_count),
boot_code: options.boot_code,
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum StageKind {
Invalidate,
Body,
BackupBootRegion,
MainBootTail,
MainBootSector,
}
impl StageKind {
const ORDER: [Self; 5] = [
Self::Invalidate,
Self::Body,
Self::BackupBootRegion,
Self::MainBootTail,
Self::MainBootSector,
];
}
#[derive(Clone, Copy)]
pub struct Stage<'p> {
plan: &'p FormatPlan,
kind: StageKind,
}
impl<'p> Stage<'p> {
#[must_use]
pub const fn kind(&self) -> StageKind {
self.kind
}
#[must_use]
pub fn pieces(&self) -> Pieces<'p> {
match stage_runs(self.plan, self.kind) {
Ok(runs) => Pieces {
plan: self.plan,
runs: runs.into_iter(),
pending: None,
},
Err(e) => Pieces {
plan: self.plan,
runs: Vec::new().into_iter(),
pending: Some(e),
},
}
}
}
impl core::fmt::Debug for Stage<'_> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Stage")
.field("kind", &self.kind)
.finish_non_exhaustive()
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Piece<'p> {
#[non_exhaustive]
Bytes {
offset: u64,
bytes: Cow<'p, [u8]>,
},
#[non_exhaustive]
Zeros {
offset: u64,
len: u64,
},
#[non_exhaustive]
Range {
offset: u64,
range: &'p FileRange,
},
#[non_exhaustive]
Image {
offset: u64,
file: &'p ImageFile,
},
#[non_exhaustive]
Declared {
offset: u64,
len: u64,
key: u64,
},
}
impl Piece<'_> {
#[must_use]
pub const fn offset(&self) -> u64 {
match self {
Self::Bytes { offset, .. }
| Self::Zeros { offset, .. }
| Self::Range { offset, .. }
| Self::Image { offset, .. }
| Self::Declared { offset, .. } => *offset,
}
}
#[must_use]
pub fn len(&self) -> u64 {
match self {
Self::Bytes { bytes, .. } => bytes.len() as u64,
Self::Zeros { len, .. } | Self::Declared { len, .. } => *len,
Self::Range { range, .. } => range.len(),
Self::Image { file, .. } => file.len(),
}
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
pub struct Pieces<'p> {
plan: &'p FormatPlan,
runs: std::vec::IntoIter<Run<'p>>,
pending: Option<FormatError>,
}
impl<'p> Iterator for Pieces<'p> {
type Item = Result<Piece<'p>, FormatError>;
fn next(&mut self) -> Option<Self::Item> {
if let Some(e) = self.pending.take() {
return Some(Err(e));
}
let run = self.runs.next()?;
let piece = realize(self.plan, run);
if piece.is_err() {
self.runs = Vec::new().into_iter();
}
Some(piece)
}
}
impl core::fmt::Debug for Pieces<'_> {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("Pieces")
.field("remaining", &self.runs.len())
.finish_non_exhaustive()
}
}
enum Run<'p> {
Ready(Piece<'p>),
Table {
offset: u64,
first: u32,
count: u32,
last: u32,
},
Bitmap { offset: u64, from: u64, len: u64 },
Upcase { offset: u64, len: u64 },
Directory { index: usize, offset: u64 },
Boot { offset: u64, from: u64, to: u64 },
}
fn stage_runs(plan: &FormatPlan, kind: StageKind) -> Result<Vec<Run<'_>>, FormatError> {
let sector = u64::from(plan.layout.bytes_per_sector);
Ok(match kind {
StageKind::Invalidate => invalidate_runs(plan),
StageKind::Body => body_runs(plan)?,
StageKind::BackupBootRegion => vec![Run::Boot {
offset: BOOT_REGION_SECTORS * sector,
from: 0,
to: BOOT_REGION_SECTORS,
}],
StageKind::MainBootTail => vec![Run::Boot {
offset: sector,
from: 1,
to: BOOT_REGION_SECTORS,
}],
StageKind::MainBootSector => vec![Run::Boot {
offset: 0,
from: 0,
to: 1,
}],
})
}
fn invalidate_runs(plan: &FormatPlan) -> Vec<Run<'_>> {
let layout = &plan.layout;
let heap_at = u64::from(layout.cluster_heap_offset) * u64::from(layout.bytes_per_sector);
let heap_end = heap_at + layout.heap_bytes();
let free_from =
heap_at + u64::from(plan.model.used_clusters) * u64::from(layout.bytes_per_cluster);
let tail_from = free_from.max(heap_end.min(layout.total_bytes().saturating_sub(TAIL_BYTES)));
[(0, heap_at), (tail_from, plan.volume_bytes)]
.into_iter()
.filter(|(from, to)| to > from)
.map(|(offset, to)| {
Run::Ready(Piece::Zeros {
offset,
len: to - offset,
})
})
.collect()
}
fn body_runs(plan: &FormatPlan) -> Result<Vec<Run<'_>>, FormatError> {
let layout = &plan.layout;
let model = &plan.model;
let sector = u64::from(layout.bytes_per_sector);
let cluster = u64::from(layout.bytes_per_cluster);
let mut runs = Vec::new();
let last = layout.first_cluster_of_root + model.dirs[ROOT_DIR].run.count - 1;
let mut first = 0u32;
while first <= last {
let count = (last - first + 1).min(TABLE_BATCH_ENTRIES as u32);
let offset = layout
.fat_entry_byte(first)
.ok_or(FormatError::ClusterOutsideVolume {
region: "the allocation table's entry",
cluster: first,
})?;
runs.push(Run::Table {
offset,
first,
count,
last,
});
first += count;
}
let bitmap_at = cluster_start(layout, layout.bitmap_cluster, "the allocation bitmap")?;
let set = u64::from(model.used_clusters)
.div_ceil(8)
.next_multiple_of(sector);
let whole = layout.bitmap_bytes.next_multiple_of(sector);
let mut from = 0u64;
while from < set {
let len = (set - from).min(BITMAP_BATCH_BYTES as u64);
runs.push(Run::Bitmap {
offset: bitmap_at + from,
from,
len,
});
from += len;
}
if whole > set {
runs.push(Run::Ready(Piece::Zeros {
offset: bitmap_at + set,
len: whole - set,
}));
}
let upcase_at = cluster_start(layout, layout.upcase_cluster, "the up-case table")?;
let table = RECOMMENDED_UPCASE_BYTES.next_multiple_of(sector);
let clusters = layout.clusters_for(layout.upcase_bytes) * cluster;
runs.push(Run::Upcase {
offset: upcase_at,
len: table,
});
if clusters > table {
runs.push(Run::Ready(Piece::Zeros {
offset: upcase_at + table,
len: clusters - table,
}));
}
for (index, dir) in model.dirs.iter().enumerate() {
runs.push(Run::Directory {
index,
offset: cluster_start(layout, dir.run.first, "a directory")?,
});
for entry in &dir.entries {
let Node::File { content, size, run } = entry.node else {
continue;
};
if run.is_empty() {
continue;
}
let content = &model.contents[content];
assert_eq!(
content.len(),
size,
"a file's contents are not the length its entry records"
);
let offset = cluster_start(layout, run.first, "a file")?;
runs.push(Run::Ready(match content {
FileContent::Owned(bytes) => Piece::Bytes {
offset,
bytes: Cow::Borrowed(bytes),
},
FileContent::Range(range) => Piece::Range { offset, range },
FileContent::Image(file) => Piece::Image { offset, file },
FileContent::Declared { len, key } => Piece::Declared {
offset,
len: *len,
key: *key,
},
}));
}
}
Ok(runs)
}
fn cluster_start(layout: &ExfatLayout, n: u32, region: &'static str) -> Result<u64, FormatError> {
layout
.cluster_start_byte(n)
.ok_or(FormatError::ClusterOutsideVolume { region, cluster: n })
}
fn realize<'p>(plan: &'p FormatPlan, run: Run<'p>) -> Result<Piece<'p>, FormatError> {
let layout = &plan.layout;
let sector = u64::from(layout.bytes_per_sector);
let bytes = match run {
Run::Ready(piece) => return Ok(piece),
Run::Table {
offset,
first,
count,
last,
} => {
let mut batch = vec![0u8; (u64::from(count) * 4).next_multiple_of(sector) as usize];
for i in 0..count {
put_u32(
&mut batch,
i as usize * 4,
table_entry(layout, last, first + i),
);
}
(offset, batch)
}
Run::Bitmap { offset, from, len } => {
(offset, bitmap_bytes(plan.model.used_clusters, from, len))
}
Run::Upcase { offset, len } => {
let mut table = vec![0u8; len as usize];
write_upcase_table(
&RECOMMENDED_UPCASE_TABLE,
&mut table[..RECOMMENDED_UPCASE_BYTES as usize],
)?;
(offset, table)
}
Run::Directory { index, offset } => (offset, directory_clusters(plan, index)?),
Run::Boot { offset, from, to } => {
let region = boot_region(layout, &plan.options, &plan.model)?;
let s = sector as usize;
(offset, region[from as usize * s..to as usize * s].to_vec())
}
};
Ok(Piece::Bytes {
offset: bytes.0,
bytes: Cow::Owned(bytes.1),
})
}
fn bitmap_bytes(used: u32, from: u64, len: u64) -> Vec<u8> {
let whole = u64::from(used) / 8;
let remainder = used % 8;
(from..from + len)
.map(|n| match n.cmp(&whole) {
core::cmp::Ordering::Less => 0xFF,
core::cmp::Ordering::Equal if remainder != 0 => 0xFF >> (8 - remainder),
_ => 0,
})
.collect()
}
fn directory_clusters(plan: &FormatPlan, index: usize) -> Result<Vec<u8>, FormatError> {
let mut bytes = directory_bytes(&plan.model, &plan.layout, &plan.options, index)?;
let run = plan.model.dirs[index].run;
let capacity = u64::from(run.count) * u64::from(plan.layout.bytes_per_cluster);
if bytes.len() as u64 > capacity {
return Err(FormatError::DirectoryOverflowsItsClusters {
index,
bytes: bytes.len() as u64,
capacity,
});
}
bytes.resize(capacity as usize, 0);
Ok(bytes)
}
fn table_entry(layout: &ExfatLayout, last: u32, n: u32) -> u32 {
match n {
0 => FAT_ENTRY_MEDIA,
1 => FAT_ENTRY_RESERVED,
_ if n + 1 == layout.upcase_cluster => END_OF_CHAIN,
_ if n + 1 == layout.first_cluster_of_root => END_OF_CHAIN,
_ if n == last => END_OF_CHAIN,
_ => n + 1,
}
}
fn directory_bytes(
model: &ExfatModel,
layout: &ExfatLayout,
options: &FormatOptions,
index: usize,
) -> Result<Vec<u8>, FormatError> {
let mut out = Vec::new();
if index == ROOT_DIR {
out.resize(ROOT_LEADING_SLOTS as usize * DIR_ENTRY_SIZE, 0);
options.label.entry().write_to(&mut out[..DIR_ENTRY_SIZE])?;
DirEntry::reserved(EntryType::VOLUME_GUID).write_to(&mut out[DIR_ENTRY_SIZE..])?;
AllocationBitmapEntry {
bitmap_flags: 0,
first_cluster: layout.bitmap_cluster,
data_length: layout.bitmap_bytes,
}
.write_to(&mut out[2 * DIR_ENTRY_SIZE..])?;
UpcaseTableEntry {
table_checksum: RECOMMENDED_UPCASE_CHECKSUM,
first_cluster: layout.upcase_cluster,
data_length: layout.upcase_bytes,
}
.write_to(&mut out[3 * DIR_ENTRY_SIZE..])?;
}
for entry in &model.dirs[index].entries {
push_entry_set(&mut out, model, layout, entry)?;
}
Ok(out)
}
fn push_entry_set(
out: &mut Vec<u8>,
model: &ExfatModel,
layout: &ExfatLayout,
entry: &ModelEntry,
) -> Result<(), FormatError> {
let start = out.len();
let slots = entry.name.slots() as usize;
out.resize(start + slots * DIR_ENTRY_SIZE, 0);
let set = &mut out[start..];
FileEntry {
secondary_count: entry.name.secondary_count(),
set_checksum: 0,
attributes: entry.attributes,
create: pack_timestamp(entry.times.create),
modify: pack_timestamp(entry.times.modify),
access: pack_timestamp(entry.times.access),
create_tenth: entry.times.create.tenth,
modify_tenth: entry.times.modify.tenth,
create_utc_offset: UTC_OFFSET,
modify_utc_offset: UTC_OFFSET,
access_utc_offset: UTC_OFFSET,
}
.write_to(set)?;
let (run, data_length) = model.entry_target(entry.node, layout.bytes_per_cluster);
StreamExtensionEntry {
flags: stream_flags(run),
name_length: entry.name.units.len() as u8,
name_hash: entry.name.hash,
valid_data_length: data_length,
first_cluster: run.first,
data_length,
}
.write_to(&mut set[DIR_ENTRY_SIZE..])?;
for (n, chunk) in entry.name.units.chunks(NAME_UNITS_PER_ENTRY).enumerate() {
FileNameEntry::new(chunk).write_to(&mut set[(2 + n) * DIR_ENTRY_SIZE..])?;
}
let checksum = entry_set_checksum(&set[..slots * DIR_ENTRY_SIZE]);
crate::bytes::put_u16(set, 2, checksum);
Ok(())
}
const fn stream_flags(run: ClusterRun) -> u8 {
if run.is_empty() {
SECONDARY_ALLOCATION_POSSIBLE
} else {
SECONDARY_ALLOCATION_POSSIBLE | SECONDARY_NO_FAT_CHAIN
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::bytes::{get_u16, get_u32, get_u64};
use crate::exfat::ClusterSize;
use crate::exfat::geometry::FIRST_CLUSTER;
use crate::exfat::ondisk::{
BOOT_SIGNATURE, EXTENDED_BOOT_SIGNATURE, FileAttributes, MAX_NAME_UNITS,
MUST_BE_ZERO_RANGE, checksum_sector_value, extended_boot_signature, upcase_checksum,
};
use crate::fidelity::{Direction, Property};
use crate::source::{Metadata, TreeBuilder};
use crate::time::Timestamp;
const TIME: Timestamp = Timestamp {
secs: 1_426_325_212,
nanos: 0,
};
fn empty() -> TreeBuilder {
TreeBuilder::new()
}
fn image() -> Image {
format(empty(), 64 << 20, FormatOptions::new(0x1234_5678)).expect("format")
}
#[test]
fn the_image_is_the_size_it_was_asked_for() {
let image = format(empty(), 64 << 20, FormatOptions::new(1)).expect("format");
assert_eq!(image.as_bytes().len(), 64 << 20);
let ragged = format(empty(), (64 << 20) + 511, FormatOptions::new(1)).expect("format");
assert_eq!(ragged.as_bytes().len(), (64 << 20) + 511);
assert_eq!(ragged.layout().volume_length, image.layout().volume_length);
}
#[test]
fn two_formats_of_the_same_parameters_are_the_same_bytes() {
let options = FormatOptions::new(0xDEAD_BEEF).label(VolumeLabel::new("CARD").unwrap());
assert_eq!(
format(empty(), 32 << 20, options)
.expect("format")
.into_bytes(),
format(empty(), 32 << 20, options)
.expect("format")
.into_bytes()
);
assert_ne!(
format(empty(), 32 << 20, FormatOptions::new(1))
.expect("format")
.into_bytes(),
format(empty(), 32 << 20, FormatOptions::new(2))
.expect("format")
.into_bytes()
);
}
#[test]
fn both_boot_regions_are_written_and_each_carries_its_own_checksum() {
let image = image();
let layout = *image.layout();
let bytes = image.as_bytes();
let sector = layout.bytes_per_sector as usize;
let region = BOOT_REGION_SECTORS as usize * sector;
let main = &bytes[..region];
let backup = &bytes[region..2 * region];
assert_eq!(main, backup, "the backup region is a copy");
for (which, region) in [main, backup].into_iter().enumerate() {
let checksum_at = 11 * sector;
assert_eq!(
checksum_sector_value(®ion[checksum_at..]),
Some(boot_checksum(®ion[..checksum_at])),
"region {which}"
);
for n in 1..9 {
assert_eq!(
extended_boot_signature(®ion[n * sector..(n + 1) * sector]),
Some(EXTENDED_BOOT_SIGNATURE),
"region {which}, extended boot sector {n}"
);
}
assert!(
region[9 * sector..11 * sector].iter().all(|b| *b == 0),
"region {which}: the parameters and reserved sectors"
);
}
}
#[test]
fn the_boot_sector_records_the_geometry_that_was_planned() {
let image = image();
let layout = *image.layout();
let boot = MainBootSector::read_from(image.as_bytes()).expect("read");
assert_eq!(boot.volume_length, layout.volume_length);
assert_eq!(boot.fat_offset, layout.fat_offset);
assert_eq!(boot.fat_length, layout.fat_length);
assert_eq!(boot.cluster_heap_offset, layout.cluster_heap_offset);
assert_eq!(boot.cluster_count, layout.cluster_count);
assert_eq!(boot.first_cluster_of_root, layout.first_cluster_of_root);
assert_eq!(boot.volume_serial, 0x1234_5678);
assert_eq!(boot.file_system_revision, FILE_SYSTEM_REVISION);
assert_eq!(boot.number_of_fats, NUMBER_OF_FATS);
assert_eq!(boot.bytes_per_sector(), Some(layout.bytes_per_sector));
assert_eq!(boot.bytes_per_cluster(), Some(layout.bytes_per_cluster));
assert_eq!(boot.volume_flags, 0);
assert!(image.as_bytes()[MUST_BE_ZERO_RANGE].iter().all(|b| *b == 0));
assert_eq!(&image.as_bytes()[510..512], &BOOT_SIGNATURE.to_le_bytes());
}
#[test]
fn how_full_the_volume_is_is_computed_rather_than_left_at_zero() {
let coarse = format(
empty(),
4 << 20,
FormatOptions::new(1)
.plan(PlanRequest::new(0).cluster_size(ClusterSize::Bytes(32 << 10))),
)
.expect("format");
assert_eq!(coarse.layout().cluster_count, 64);
assert_eq!(
MainBootSector::read_from(coarse.as_bytes())
.unwrap()
.percent_in_use,
4
);
let ordinary = image();
assert_eq!(
MainBootSector::read_from(ordinary.as_bytes())
.unwrap()
.percent_in_use,
0,
"a volume with room rounds down to nothing, and says so"
);
}
#[test]
fn the_allocation_table_chains_each_resident_and_stops() {
for cluster in [ClusterSize::Bytes(512), ClusterSize::Bytes(4 << 10)] {
let image = format(
empty(),
64 << 20,
FormatOptions::new(1).plan(PlanRequest::new(0).cluster_size(cluster)),
)
.expect("format");
let layout = *image.layout();
let what = format!("{cluster:?}");
let entry = |n: u32| {
get_u32(
image.as_bytes(),
layout.fat_entry_byte(n).expect("in the table") as usize,
)
};
assert_eq!(entry(0), FAT_ENTRY_MEDIA, "{what}");
assert_eq!(entry(1), FAT_ENTRY_RESERVED, "{what}");
for (first, past) in [
(layout.bitmap_cluster, layout.upcase_cluster),
(layout.upcase_cluster, layout.first_cluster_of_root),
(
layout.first_cluster_of_root,
layout.first_cluster_of_root + 1,
),
] {
let mut at = first;
let mut steps = 0;
while entry(at) != END_OF_CHAIN {
assert_eq!(entry(at), at + 1, "{what}: cluster {at} chains forward");
at = entry(at);
steps += 1;
assert!(
steps < past - first + 1,
"{what}: chain from {first} runs on"
);
}
assert_eq!(
at,
past - 1,
"{what}: the chain from {first} ends where it should"
);
}
assert_eq!(entry(layout.first_cluster_of_root + 1), 0, "{what}");
}
}
#[test]
fn the_bitmap_sets_a_bit_for_each_resident_cluster_and_no_others() {
for cluster in [ClusterSize::Bytes(512), ClusterSize::Bytes(32 << 10)] {
let image = format(
empty(),
64 << 20,
FormatOptions::new(1).plan(PlanRequest::new(0).cluster_size(cluster)),
)
.expect("format");
let layout = *image.layout();
let what = format!("{cluster:?}");
let at = layout.cluster_start_byte(layout.bitmap_cluster).unwrap() as usize;
let bitmap = &image.as_bytes()[at..at + layout.bitmap_bytes as usize];
let used = (layout.first_cluster_of_root + 1 - FIRST_CLUSTER) as usize;
let set: usize = bitmap.iter().map(|b| b.count_ones() as usize).sum();
assert_eq!(set, used, "{what}: one bit per resident cluster");
for n in 0..used {
assert_eq!(bitmap[n / 8] >> (n % 8) & 1, 1, "{what}: bit {n} is set");
}
assert_eq!(bitmap[used / 8] >> (used % 8) & 1, 0, "{what}: bit {used}");
}
}
#[test]
fn the_up_case_table_lands_where_its_entry_says_and_checksums_to_what_it_advertises() {
let image = image();
let layout = *image.layout();
let at = layout.cluster_start_byte(layout.upcase_cluster).unwrap() as usize;
let table = &image.as_bytes()[at..at + layout.upcase_bytes as usize];
assert_eq!(upcase_checksum(table), RECOMMENDED_UPCASE_CHECKSUM);
let span = layout.clusters_for(layout.upcase_bytes) * u64::from(layout.bytes_per_cluster);
assert!(
image.as_bytes()[at + table.len()..at + span as usize]
.iter()
.all(|b| *b == 0)
);
}
#[test]
fn the_root_directory_holds_the_slots_a_format_writes_in_the_order_it_writes_them() {
let image = format(
empty(),
32 << 20,
FormatOptions::new(1).label(VolumeLabel::new("FERROSYS").unwrap()),
)
.expect("format");
let layout = *image.layout();
let at = layout
.cluster_start_byte(layout.first_cluster_of_root)
.unwrap() as usize;
let root = &image.as_bytes()[at..at + layout.bytes_per_cluster as usize];
let slot = |n: usize| &root[n * DIR_ENTRY_SIZE..(n + 1) * DIR_ENTRY_SIZE];
let label = VolumeLabelEntry::read_from(slot(0)).expect("a label entry");
assert_eq!(label.character_count, 8);
assert_eq!(
&label.label[..8],
&"FERROSYS".encode_utf16().collect::<Vec<_>>()[..]
);
assert_eq!(slot(1)[0], EntryType::VOLUME_GUID.cleared().0);
assert!(slot(1)[1..].iter().all(|b| *b == 0));
let bitmap = AllocationBitmapEntry::read_from(slot(2)).expect("a bitmap entry");
assert_eq!(bitmap.first_cluster, layout.bitmap_cluster);
assert_eq!(bitmap.data_length, layout.bitmap_bytes);
assert_eq!(bitmap.data_length, get_u64(slot(2), 24));
let upcase = UpcaseTableEntry::read_from(slot(3)).expect("an up-case entry");
assert_eq!(upcase.first_cluster, layout.upcase_cluster);
assert_eq!(upcase.data_length, RECOMMENDED_UPCASE_BYTES);
assert_eq!(upcase.table_checksum, RECOMMENDED_UPCASE_CHECKSUM);
assert!(root[4 * DIR_ENTRY_SIZE..].iter().all(|b| *b == 0));
}
#[test]
fn a_volume_with_no_name_carries_the_label_entry_all_the_same() {
let image = image();
let layout = *image.layout();
let at = layout
.cluster_start_byte(layout.first_cluster_of_root)
.unwrap() as usize;
let label = VolumeLabelEntry::read_from(&image.as_bytes()[at..]).expect("a label entry");
assert_eq!(label, VolumeLabelEntry::UNNAMED);
}
#[test]
fn streaming_a_volume_and_holding_one_produce_the_same_bytes() {
let options = FormatOptions::new(0x0BAD_F00D).label(VolumeLabel::new("SD").unwrap());
let held = format(empty(), 32 << 20, options).expect("format");
let mut streamed = Cursor::new(Vec::new());
let plan = format_to(&mut streamed, empty(), 32 << 20, options).expect("format");
assert_eq!(plan.layout(), held.layout());
assert_eq!(streamed.into_inner(), held.into_bytes());
}
#[test]
fn the_boot_code_a_caller_supplies_reaches_the_sector_and_the_checksum() {
let mut code = [0u8; BOOT_CODE_LEN];
code[..4].copy_from_slice(b"\xEB\x3C\x90\x00");
let plain = format(empty(), 32 << 20, FormatOptions::new(7)).expect("format");
let booting =
format(empty(), 32 << 20, FormatOptions::new(7).boot_code(code)).expect("format");
assert_eq!(&booting.as_bytes()[120..124], b"\xEB\x3C\x90\x00");
let sector = plain.layout().bytes_per_sector as usize;
assert_ne!(
&plain.as_bytes()[11 * sector..12 * sector],
&booting.as_bytes()[11 * sector..12 * sector]
);
}
fn slots_at(image: &Image, cluster: u32, count: usize) -> Vec<&[u8]> {
let at = image
.layout()
.cluster_start_byte(cluster)
.expect("a cluster") as usize;
(0..count)
.map(|n| &image.as_bytes()[at + n * DIR_ENTRY_SIZE..at + (n + 1) * DIR_ENTRY_SIZE])
.collect()
}
#[test]
fn a_file_becomes_a_set_whose_checksum_covers_every_entry_in_it() {
let image = format(
TreeBuilder::new().file(
b"/README.TXT".to_vec(),
b"hello\n",
Metadata::new(0o644, TIME),
),
32 << 20,
FormatOptions::new(1),
)
.expect("format");
let layout = *image.layout();
let slots = slots_at(&image, layout.first_cluster_of_root, 8);
let file = FileEntry::read_from(slots[4]).expect("a file entry");
assert_eq!(file.secondary_count, 2, "a stream extension and one name");
assert_eq!(file.attributes, FileAttributes::ARCHIVE);
assert_eq!(file.create, file.modify, "a creation time is derived");
assert_eq!(file.create_utc_offset, UTC_OFFSET);
assert_eq!(file.modify_utc_offset, UTC_OFFSET);
assert_eq!(file.access_utc_offset, UTC_OFFSET);
let stream = StreamExtensionEntry::read_from(slots[5]).expect("a stream extension");
assert_eq!(stream.name_length, 10);
assert_eq!(stream.data_length, 6);
assert_eq!(
stream.valid_data_length, 6,
"a format writes what it allocates"
);
assert!(stream.no_fat_chain());
let name = FileNameEntry::read_from(slots[6]).expect("a name entry");
assert_eq!(
&name.units[..10],
&"README.TXT".encode_utf16().collect::<Vec<_>>()[..]
);
assert!(
slots[7][0] == 0,
"the directory ends at the zero byte behind it"
);
let set: Vec<u8> = slots[4..7].concat();
assert_eq!(file.set_checksum, entry_set_checksum(&set));
assert_eq!(file.set_checksum, get_u16(slots[4], 2));
let folded = UpcaseTable::recommended().fold(&name.units[..10]);
assert_eq!(stream.name_hash, crate::exfat::ondisk::name_hash(&folded));
}
#[test]
fn a_files_bytes_land_where_its_stream_extension_says_they_do() {
let contents: Vec<u8> = (0..9_000u32).map(|n| n as u8).collect();
let image = format(
TreeBuilder::new()
.file(
b"/a.bin".to_vec(),
contents.clone(),
Metadata::new(0o644, TIME),
)
.file(b"/b.bin".to_vec(), b"second", Metadata::new(0o644, TIME)),
32 << 20,
FormatOptions::new(1),
)
.expect("format");
let layout = *image.layout();
for (slot, expected) in [(5usize, &contents[..]), (8, b"second")] {
let stream = StreamExtensionEntry::read_from(
slots_at(&image, layout.first_cluster_of_root, slot + 1)[slot],
)
.expect("a stream extension");
let at = layout
.cluster_start_byte(stream.first_cluster)
.expect("a cluster") as usize;
assert_eq!(
&image.as_bytes()[at..at + stream.data_length as usize],
expected
);
}
}
#[test]
fn a_subdirectory_holds_its_own_sets_and_no_dot_entries() {
let image = format(
TreeBuilder::new()
.directory(b"/dir".to_vec(), Metadata::new(0o755, TIME))
.file(b"/dir/inner.txt".to_vec(), b"x", Metadata::new(0o644, TIME)),
32 << 20,
FormatOptions::new(1),
)
.expect("format");
let layout = *image.layout();
let stream =
StreamExtensionEntry::read_from(slots_at(&image, layout.first_cluster_of_root, 6)[5])
.expect("a stream extension");
assert_eq!(stream.data_length, u64::from(layout.bytes_per_cluster));
assert_eq!(stream.valid_data_length, stream.data_length);
let inner = slots_at(&image, stream.first_cluster, 3);
let file = FileEntry::read_from(inner[0]).expect("a file entry");
assert_eq!(file.attributes, FileAttributes::ARCHIVE);
let name = FileNameEntry::read_from(inner[2]).expect("a name entry");
assert_eq!(
&name.units[..9],
&"inner.txt".encode_utf16().collect::<Vec<_>>()[..]
);
}
#[test]
fn a_name_too_long_for_one_entry_is_spread_across_as_many_as_it_needs() {
let name = "n".repeat(MAX_NAME_UNITS);
let image = format(
TreeBuilder::new().file(
format!("/{name}").into_bytes(),
b"x",
Metadata::new(0o644, TIME),
),
32 << 20,
FormatOptions::new(1),
)
.expect("format");
let layout = *image.layout();
let slots = slots_at(&image, layout.first_cluster_of_root, 4 + 19);
let file = FileEntry::read_from(slots[4]).expect("a file entry");
assert_eq!(
file.secondary_count, 18,
"a stream extension and seventeen names"
);
let stream = StreamExtensionEntry::read_from(slots[5]).expect("a stream extension");
assert_eq!(stream.name_length, MAX_NAME_UNITS as u8);
let mut units = Vec::new();
for slot in &slots[6..4 + 19] {
units.extend_from_slice(&FileNameEntry::read_from(slot).expect("a name").units);
}
assert_eq!(units.len(), 17 * NAME_UNITS_PER_ENTRY);
units.truncate(usize::from(stream.name_length));
assert_eq!(String::from_utf16(&units).expect("well-formed"), name);
}
#[test]
fn a_root_directory_that_outgrows_one_cluster_is_chained_where_a_subdirectory_is_not() {
let mut source = TreeBuilder::new();
for n in 0..60u32 {
source = source.file(
format!("/file-{n:04}.txt").into_bytes(),
b"x",
Metadata::new(0o644, TIME),
);
}
let image = format(source, 32 << 20, FormatOptions::new(1)).expect("format");
let layout = *image.layout();
let entry = |n: u32| {
get_u32(
image.as_bytes(),
layout.fat_entry_byte(n).expect("in the table") as usize,
)
};
let root_first = layout.first_cluster_of_root;
assert_eq!(entry(root_first), root_first + 1, "the root chains forward");
assert_eq!(entry(root_first + 1), END_OF_CHAIN);
assert_eq!(entry(root_first + 2), 0);
let stream =
StreamExtensionEntry::read_from(slots_at(&image, root_first, 6)[5]).expect("a stream");
assert!(stream.no_fat_chain());
assert_eq!(stream.first_cluster, root_first + 2);
}
#[test]
fn the_bitmap_marks_every_cluster_the_tree_holds_however_it_is_addressed() {
let image = format(
TreeBuilder::new()
.directory(b"/d".to_vec(), Metadata::new(0o755, TIME))
.file(
b"/d/big".to_vec(),
vec![0u8; 20_000],
Metadata::new(0o644, TIME),
),
32 << 20,
FormatOptions::new(1),
)
.expect("format");
let layout = *image.layout();
let at = layout.cluster_start_byte(layout.bitmap_cluster).unwrap() as usize;
let bitmap = &image.as_bytes()[at..at + layout.bitmap_bytes as usize];
let used = (layout.first_cluster_of_root - FIRST_CLUSTER) + 1 + 1 + 5;
assert_eq!(
bitmap.iter().map(|b| b.count_ones()).sum::<u32>(),
used,
"one bit per cluster in use"
);
for n in 0..used as usize {
assert_eq!(bitmap[n / 8] >> (n % 8) & 1, 1, "bit {n} is set");
}
assert_eq!(bitmap[used as usize / 8] >> (used % 8) & 1, 0);
}
#[test]
fn how_full_the_volume_is_counts_the_tree_and_not_only_the_format() {
let options =
FormatOptions::new(1).plan(PlanRequest::new(0).cluster_size(ClusterSize::Bytes(512)));
let bare = format(empty(), 4 << 20, options).expect("format");
let filled = format(
TreeBuilder::new().file(
b"/big".to_vec(),
vec![0u8; 1 << 20],
Metadata::new(0o644, TIME),
),
4 << 20,
options,
)
.expect("format");
let percent = |image: &Image| {
MainBootSector::read_from(image.as_bytes())
.expect("a boot sector")
.percent_in_use
};
assert_eq!(percent(&bare), 0);
assert_eq!(bare.layout().cluster_count, 4096);
assert_eq!(percent(&filled), 50);
}
#[test]
fn an_empty_source_writes_the_volume_the_family_wrote_before_it_had_a_tree() {
let options = FormatOptions::new(0x0BAD_F00D).label(VolumeLabel::new("SD").unwrap());
let bare = format(empty(), 32 << 20, options).expect("format");
let layout = *bare.layout();
let root = layout
.cluster_start_byte(layout.first_cluster_of_root)
.unwrap() as usize;
assert!(
bare.as_bytes()[root + ROOT_LEADING_SLOTS as usize * DIR_ENTRY_SIZE..][..layout
.bytes_per_cluster
as usize
- ROOT_LEADING_SLOTS as usize * DIR_ENTRY_SIZE]
.iter()
.all(|b| *b == 0),
"nothing follows the four entries a format writes"
);
assert_eq!(
bare.layout().first_cluster_of_root,
layout.first_cluster_of_root
);
assert!(bare.fidelity().is_faithful());
}
#[test]
fn two_formats_of_the_same_tree_are_the_same_bytes_and_stream_identically() {
let source = TreeBuilder::new()
.directory(b"/DCIM".to_vec(), Metadata::new(0o755, TIME))
.file(
b"/DCIM/IMG_0001.JPG".to_vec(),
b"\xFF\xD8\xFF",
Metadata::new(0o644, TIME),
)
.file(
b"/README.TXT".to_vec(),
b"hello\n",
Metadata::new(0o644, TIME),
);
let options = FormatOptions::new(0x1234_5678).label(VolumeLabel::new("CARD").unwrap());
let held = format(source.clone(), 32 << 20, options).expect("format");
assert_eq!(
held.as_bytes(),
format(source.clone(), 32 << 20, options)
.expect("format")
.as_bytes()
);
let mut streamed = Cursor::new(Vec::new());
let plan = format_to(&mut streamed, source, 32 << 20, options).expect("format");
assert_eq!(plan.layout(), held.layout());
assert_eq!(streamed.into_inner(), held.into_bytes());
}
#[test]
fn a_source_the_volume_cannot_hold_is_refused_before_the_destination_is_touched() {
let source = TreeBuilder::new().file(
b"/owned".to_vec(),
b"x",
Metadata {
uid: 1000,
gid: 1000,
..Metadata::new(0o644, TIME)
},
);
let mut sink = Cursor::new(Vec::new());
assert!(matches!(
format_to(&mut sink, source.clone(), 32 << 20, FormatOptions::new(1)),
Err(FormatError::Model(ModelError::LossNotAccepted {
property: Property::Ownership,
..
}))
));
assert!(sink.into_inner().is_empty());
let plan = FormatPlan::new(
source,
32 << 20,
FormatOptions::new(1).accepted_loss(AcceptedLoss::NONE.and(Property::Ownership)),
)
.expect("accepted");
assert_eq!(
plan.fidelity()
.count(Direction::Dropped, Property::Ownership),
1
);
assert!(plan.free_clusters() > 0);
}
#[test]
fn a_geometry_that_cannot_be_realized_fails_before_the_destination_is_touched() {
let mut sink = Cursor::new(Vec::new());
assert!(matches!(
format_to(&mut sink, empty(), 4096, FormatOptions::new(1)),
Err(FormatError::Geometry(GeometryError::VolumeTooSmall { .. }))
));
assert!(sink.into_inner().is_empty());
}
#[test]
fn a_label_is_bounded_by_the_field_and_not_by_its_characters() {
assert_eq!(VolumeLabel::new("ELEVENCHARS").unwrap().units().len(), 11);
assert!(matches!(
VolumeLabel::new("TWELVECHARSX"),
Err(LabelError::TooLong { limit: 11, .. })
));
assert_eq!(VolumeLabel::new("\u{1F600}").unwrap().units().len(), 2);
assert!(VolumeLabel::new("\u{1F600}\u{1F600}\u{1F600}\u{1F600}\u{1F600}").is_ok());
assert!(matches!(
VolumeLabel::new("\u{1F600}\u{1F600}\u{1F600}\u{1F600}\u{1F600}\u{1F600}"),
Err(LabelError::TooLong { .. })
));
assert!(matches!(
VolumeLabel::new("A\u{0}B"),
Err(LabelError::NulUnit { at: 1 })
));
}
#[test]
fn a_label_reserves_the_characters_a_name_does() {
for bad in [
"A/B", "A\\B", "A:B", "A*", "A?", "A\"B", "A<B", "A>B", "A|B", "A\u{1}",
] {
assert!(
matches!(
VolumeLabel::new(bad),
Err(LabelError::ForbiddenCharacter { .. })
),
"{bad:?}"
);
}
for good in ["A.B C", "Ferrosys ×", "x-y_z+1"] {
assert!(VolumeLabel::new(good).is_ok(), "{good:?}");
}
}
#[test]
fn a_label_keeps_the_case_and_the_characters_it_was_given() {
let label = VolumeLabel::new("Ferrosys ×").expect("a label");
assert_eq!(
label.units(),
&"Ferrosys ×".encode_utf16().collect::<Vec<_>>()[..]
);
assert_eq!(format!("{label:?}"), "VolumeLabel(\"Ferrosys ×\")");
}
fn populated() -> TreeBuilder {
let meta = Metadata::new(0o644, TIME);
TreeBuilder::new()
.directory(b"/DCIM".to_vec(), Metadata::new(0o755, TIME))
.file(b"/DCIM/EMPTY".to_vec(), Vec::new(), meta)
.file(
b"/DCIM/a name long enough to need three name entries.txt".to_vec(),
b"named\n",
meta,
)
.file(
b"/big.bin".to_vec(),
(0..20_000u32).map(|i| (i % 251) as u8).collect::<Vec<u8>>(),
meta,
)
.file(b"/eflasher.conf".to_vec(), b"autostart=yes\n", meta)
}
fn declared_bytes(key: u64, len: usize) -> Vec<u8> {
(0..len).map(|i| (i as u64 ^ key) as u8).collect()
}
fn every_piece(plan: &FormatPlan) -> Vec<(StageKind, Piece<'_>)> {
plan.stages()
.into_iter()
.flat_map(|stage| {
stage
.pieces()
.map(move |piece| (stage.kind(), piece.expect("every piece builds")))
})
.collect()
}
fn apply(plan: &FormatPlan, mut destination: Vec<u8>, reverse: bool) -> Vec<u8> {
for stage in plan.stages() {
let mut pieces: Vec<Piece<'_>> = stage
.pieces()
.collect::<Result<_, _>>()
.expect("every piece builds");
if reverse {
pieces.reverse();
}
for piece in pieces {
let at = piece.offset() as usize;
let slot = &mut destination[at..at + piece.len() as usize];
match piece {
Piece::Bytes { bytes, .. } => slot.copy_from_slice(&bytes),
Piece::Zeros { .. } => slot.fill(0),
Piece::Range { range, .. } => range.read_at(0, slot).expect("the range reads"),
Piece::Image { file, .. } => file.read_at(0, slot).expect("the file reads"),
Piece::Declared { key, .. } => {
let len = slot.len();
slot.copy_from_slice(&declared_bytes(key, len));
}
}
}
}
destination
}
fn destinations(size: usize) -> Vec<(&'static str, Vec<u8>)> {
let mut state = 0x9E37_79B9_7F4A_7C15u64;
let noise = (0..size)
.map(|_| {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
state as u8
})
.collect();
let meta = Metadata::new(0o644, TIME);
let mut earlier =
TreeBuilder::new().directory(b"/DCIM".to_vec(), Metadata::new(0o755, TIME));
for i in 0..60 {
let name = format!("/AN-EARLIER-FILE-WITH-A-LONG-NAME-{i:03}.TXT");
earlier = earlier.file(name.into_bytes(), format!("old {i}\n").into_bytes(), meta);
}
for i in 0..40 {
let name = format!("/DCIM/EARLIER-{i:03}.BIN");
earlier = earlier.file(name.into_bytes(), vec![0xA5; 3000 + i * 100], meta);
}
let earlier = format(earlier, size as u64, FormatOptions::new(0x1111_1111))
.expect("the earlier volume")
.into_bytes();
vec![
("zeros", vec![0; size]),
("every bit set", vec![0xFF; size]),
("noise", noise),
("an earlier volume", earlier),
]
}
fn read_back(what: &str, bytes: &[u8]) -> Vec<(Vec<u8>, Option<Vec<u8>>)> {
let mut reader = crate::exfat::Reader::open(Cursor::new(bytes))
.unwrap_or_else(|e| panic!("{what}: a strict open refused the volume: {e}"));
let report = reader.scan();
assert!(report.is_clean(), "{what}: the scan found {report:?}");
let walk = reader.walk().expect("the walk succeeds");
walk.into_iter()
.map(|entry| {
let contents = (!entry.node.is_dir())
.then(|| reader.read_data(&entry.node).expect("the file reads"));
(entry.path, contents)
})
.collect()
}
#[test]
fn a_format_is_five_stages_and_the_main_boot_sector_is_the_last_write() {
let plan = FormatPlan::new(populated(), 8 << 20, FormatOptions::new(1)).expect("plan");
let kinds: Vec<StageKind> = plan.stages().iter().map(Stage::kind).collect();
assert_eq!(
kinds,
[
StageKind::Invalidate,
StageKind::Body,
StageKind::BackupBootRegion,
StageKind::MainBootTail,
StageKind::MainBootSector,
]
);
let sector = u64::from(plan.layout().bytes_per_sector);
let place = |kind: StageKind| -> Vec<(u64, u64)> {
every_piece(&plan)
.into_iter()
.filter(|(k, _)| *k == kind)
.map(|(_, p)| (p.offset(), p.len()))
.collect()
};
let heap_at = u64::from(plan.layout().cluster_heap_offset) * sector;
assert_eq!(place(StageKind::Invalidate)[0], (0, heap_at));
assert_eq!(
place(StageKind::BackupBootRegion),
[(12 * sector, 12 * sector)]
);
assert_eq!(place(StageKind::MainBootTail), [(sector, 11 * sector)]);
assert_eq!(place(StageKind::MainBootSector), [(0, sector)]);
}
#[test]
fn every_piece_starts_on_a_sector_and_no_two_in_a_stage_share_one() {
let dir = tempfile::tempdir().expect("temp dir");
let host = dir.path().join("host");
std::fs::write(&host, vec![7u8; 9_000]).expect("write the host file");
let meta = Metadata::new(0o644, TIME);
let mut tree = populated()
.file(
b"/ranged".to_vec(),
FileContent::Range(FileRange::at_path(&host, 100, 8_000)),
meta,
)
.file(
b"/declared".to_vec(),
FileContent::Declared {
len: 12_345,
key: 3,
},
meta,
);
for i in 0..40 {
tree = tree.file(format!("/ROOT-{i:02}.TXT").into_bytes(), b"x", meta);
}
let requests = [
PlanRequest::new(0),
PlanRequest::new(0).cluster_size(ClusterSize::Bytes(512)),
PlanRequest::new(0).bytes_per_sector(4096),
PlanRequest::new(0)
.bytes_per_sector(4096)
.cluster_size(ClusterSize::Bytes(4096)),
];
for (size, request) in [8 << 20, (8 << 20) + 511, 16 << 20, 16 << 20]
.into_iter()
.zip(requests)
{
let options = FormatOptions::new(1).plan(request);
let plan = FormatPlan::new(tree.clone(), size, options).expect("plan");
let sector = u64::from(plan.layout().bytes_per_sector);
let pieces = every_piece(&plan);
for kind in StageKind::ORDER {
let mut ends: Vec<(u64, u64)> = Vec::new();
for (k, piece) in &pieces {
if *k != kind {
continue;
}
let (at, len) = (piece.offset(), piece.len());
assert!(len > 0, "{kind:?}: an empty piece at {at}");
assert_eq!(
at % sector,
0,
"{kind:?}: a piece at {at} is inside a sector"
);
let contents = matches!(
piece,
Piece::Range { .. } | Piece::Image { .. } | Piece::Declared { .. }
) || at + len == size;
let file_bytes = matches!(
piece,
Piece::Bytes {
bytes: Cow::Borrowed(_),
..
}
);
assert!(
contents || file_bytes || len % sector == 0,
"{kind:?}: a piece at {at} of {len} bytes ends inside a sector"
);
assert!(
at + len <= size,
"{kind:?}: a piece at {at} runs past the volume"
);
ends.push((at, (at + len).next_multiple_of(sector)));
}
ends.sort_unstable();
for pair in ends.windows(2) {
assert!(
pair[0].1 <= pair[1].0,
"{kind:?}: pieces at {} and {} share a sector",
pair[0].0,
pair[1].0
);
}
}
}
}
#[test]
fn what_the_destination_held_does_not_change_the_volume() {
let size = 8 << 20;
let options = FormatOptions::new(0x2222_2222);
let plan = FormatPlan::new(populated(), size, options).expect("plan");
let fresh = format(populated(), size, options)
.expect("format")
.into_bytes();
let expected = read_back("a fresh destination", &fresh);
let covered: Vec<std::ops::Range<usize>> = every_piece(&plan)
.iter()
.map(|(_, p)| p.offset() as usize..(p.offset() + p.len()) as usize)
.collect();
let layout = plan.layout();
let heap_at = layout.cluster_heap_offset as usize * layout.bytes_per_sector as usize;
for (what, destination) in destinations(size as usize) {
let mut sink = Cursor::new(destination);
plan.write_to(&mut sink).expect("write");
let written = sink.into_inner();
assert!(
written[..heap_at] == fresh[..heap_at],
"{what}: a byte before the heap is not the fresh destination's"
);
for range in &covered {
let at = written[range.clone()]
.iter()
.zip(&fresh[range.clone()])
.position(|(a, b)| a != b);
assert!(
at.is_none(),
"{what}: byte {:?} differs",
at.map(|a| a + range.start)
);
}
assert_eq!(read_back(what, &written), expected, "{what}");
}
}
#[test]
fn pieces_go_down_in_any_order_within_a_stage() {
let size = 8 << 20;
let plan = FormatPlan::new(populated(), size, FormatOptions::new(5)).expect("plan");
let mut sink = Cursor::new(vec![0xFF; size as usize]);
plan.write_to(&mut sink).expect("write");
assert!(
apply(&plan, vec![0xFF; size as usize], true) == sink.into_inner(),
"pieces applied in reverse made other bytes than the write"
);
}
#[test]
fn a_declared_file_comes_back_as_a_piece_and_a_write_to_a_sink_refuses_it_untouched() {
let size = 8 << 20;
let meta = Metadata::new(0o644, TIME);
let source = populated()
.file(
b"/os.img".to_vec(),
FileContent::Declared {
len: 10_000,
key: 7,
},
meta,
)
.file(
b"/none.img".to_vec(),
FileContent::Declared { len: 0, key: 8 },
meta,
);
let plan = FormatPlan::new(source, size, FormatOptions::new(1)).expect("plan");
let mut sink = Cursor::new(Vec::new());
assert!(matches!(
plan.write_to(&mut sink),
Err(FormatError::ContentsNotHeld { key: 7 })
));
assert!(
sink.into_inner().is_empty(),
"the refused write touched its sink"
);
let declared: Vec<(u64, u64, u64)> = every_piece(&plan)
.into_iter()
.filter_map(|(_, p)| match p {
Piece::Declared { offset, len, key } => Some((offset, len, key)),
_ => None,
})
.collect();
assert_eq!(declared.len(), 1);
let (offset, len, key) = declared[0];
assert_eq!((len, key), (10_000, 7));
assert_eq!(offset % u64::from(plan.layout().bytes_per_cluster), 0);
let bytes = apply(&plan, vec![0xFF; size as usize], false);
let files = read_back("the declared file filled in", &bytes);
let image = files
.iter()
.find(|(p, _)| p == b"/os.img")
.expect("the file is there");
assert!(image.1.as_deref() == Some(&declared_bytes(7, 10_000)[..]));
let none = files
.iter()
.find(|(p, _)| p == b"/none.img")
.expect("the file is there");
assert_eq!(none.1.as_deref(), Some(&[][..]));
let source = populated().file(
b"/none".to_vec(),
FileContent::Declared { len: 0, key: 9 },
meta,
);
let plan = FormatPlan::new(source, size, FormatOptions::new(1)).expect("plan");
plan.write_to(Cursor::new(Vec::new()))
.expect("nothing to supply");
}
#[test]
fn the_end_of_the_volume_is_zeroed_from_the_heaps_end_whatever_the_cluster_size() {
let plan = FormatPlan::new(populated(), 64 << 20, FormatOptions::new(1)).expect("plan");
let tail = every_piece(&plan)
.into_iter()
.filter(|(k, _)| *k == StageKind::Invalidate)
.map(|(_, p)| (p.offset(), p.len()))
.next_back()
.expect("the end of the volume is a piece");
assert_eq!(tail, ((64 << 20) - (1 << 20), 1 << 20));
let size = (300 << 20) + 12_345;
let request = PlanRequest::new(0).cluster_size(ClusterSize::Bytes(32 << 20));
let plan =
FormatPlan::new(populated(), size, FormatOptions::new(1).plan(request)).expect("plan");
let layout = plan.layout();
let heap_end = u64::from(layout.cluster_heap_offset) * u64::from(layout.bytes_per_sector)
+ layout.heap_bytes();
assert!(
size - heap_end > 1 << 20,
"the row must leave more than a mebibyte past the heap"
);
let (at, len) = every_piece(&plan)
.into_iter()
.filter(|(k, _)| *k == StageKind::Invalidate)
.map(|(_, p)| (p.offset(), p.len()))
.next_back()
.expect("the end of the volume is a piece");
assert!(
at <= heap_end,
"the end of the volume starts at {at}, past the heap's end at {heap_end}"
);
assert_eq!(at + len, size);
}
}