drivers/gpu/drm/tyr/fw/parser.rs - linux - Git at Google

 // SPDX-License-Identifier: GPL-2.0 or MIT

 //! Firmware binary parser for Mali CSF (Command Stream Frontend) GPU.
 //!
 //! This module implements a parser for the Mali GPU firmware binary format. The firmware
 //! file contains a header followed by a sequence of entries, each describing how to load
 //! firmware sections into the MCU (Microcontroller Unit) memory. The parser extracts section
 //! metadata including:
 //! - Virtual address ranges where sections should be mapped
 //! - Data ranges (byte offsets) within the firmware binary
 //! - Section flags (permissions, cache modes)

 use core::{
     mem::size_of,
     ops::Range, //
 };

 use kernel::{
     bits::bit_u32,
     device::Device,
     prelude::*,
     sizes::SZ_4K, //
 };

 use crate::{
     fw::{
         CacheMode,
         SectionFlags,
         CSF_MCU_SHARED_REGION_START, //
     },
     vm::{
         VmFlag,
         VmMapFlags, //
     }, //
 };

 /// A parsed firmware section ready for loading into MCU memory.
 ///
 /// Represents a single firmware section extracted from the firmware binary, containing
 /// all information needed to map the section's data into the MCU's virtual address space.
 pub(super) struct ParsedSection {
     /// Byte offset range within the firmware binary where this section's data resides.
     pub(super) data_range: Range<u32>,
     /// MCU virtual address range where this section should be mapped.
     pub(super) va: Range<u32>,
     /// Memory protection and caching flags for the mapping.
     pub(super) vm_map_flags: VmMapFlags,
 }

 /// A bare-bones `std::io::Cursor<[u8]>` clone to keep track of the current position in the
 /// firmware binary.
 ///
 /// Provides methods to sequentially read primitive types and byte arrays from the firmware
 /// binary while maintaining the current read position.
 struct Cursor<'a> {
     dev: &'a Device,
     data: &'a [u8],
     pos: usize,
 }

 impl<'a> Cursor<'a> {
     fn new(dev: &'a Device, data: &'a [u8]) -> Self {
         Self { dev, data, pos: 0 }
     }

     fn len(&self) -> usize {
         self.data.len()
     }

     fn pos(&self) -> usize {
         self.pos
     }

     /// Returns a view into the cursor's data.
     ///
     /// This spawns a new cursor, leaving the current cursor unchanged.
     fn view(&self, range: Range<usize>) -> Result<Cursor<'_>> {
         if range.start < self.pos || range.end > self.data.len() {
             dev_err!(
                 self.dev,
                 "Invalid cursor range {:?} for data of length {}",
                 range,
                 self.data.len()
             );

             Err(EINVAL)
         } else {
             Ok(Self {
                 dev: self.dev,
                 data: &self.data[range],
                 pos: 0,
             })
         }
     }

     /// Reads a slice of bytes from the current position and advances the cursor.
     ///
     /// Returns an error if the read would exceed the data bounds.
     fn read(&mut self, nbytes: usize) -> Result<&[u8]> {
         let start = self.pos;
         let end = start + nbytes;

         if end > self.data.len() {
             dev_err!(
                 self.dev,
                 "Invalid firmware file: read of size {} at position {} is out of bounds",
                 nbytes,
                 start,
             );
             return Err(EINVAL);
         }

         self.pos += nbytes;
         Ok(&self.data[start..end])
     }

     /// Reads a little-endian `u8` from the current position and advances the cursor.
     fn read_u8(&mut self) -> Result<u8> {
         let bytes = self.read(size_of::<u8>())?;
         Ok(bytes[0])
     }

     /// Reads a little-endian `u16` from the current position and advances the cursor.
     fn read_u16(&mut self) -> Result<u16> {
         let bytes: [u8; 2] = self
             .read(size_of::<u16>())?
             .try_into()
             .map_err(|_| EINVAL)?;

         Ok(u16::from_le_bytes(bytes))
     }

     /// Reads a little-endian `u32` from the current position and advances the cursor.
     fn read_u32(&mut self) -> Result<u32> {
         let bytes: [u8; 4] = self
             .read(size_of::<u32>())?
             .try_into()
             .map_err(|_| EINVAL)?;

         Ok(u32::from_le_bytes(bytes))
     }

     /// Advances the cursor position by the specified number of bytes.
     ///
     /// Returns an error if the advance would exceed the data bounds.
     fn advance(&mut self, nbytes: usize) -> Result {
         if self.pos + nbytes > self.data.len() {
             dev_err!(
                 self.dev,
                 "Invalid firmware file: advance of size {} at position {} is out of bounds",
                 nbytes,
                 self.pos,
             );
             return Err(EINVAL);
         }
         self.pos += nbytes;
         Ok(())
     }
 }

 /// Parser for Mali CSF GPU firmware binaries.
 ///
 /// Parses the firmware binary format, extracting section metadata including virtual
 /// address ranges, data offsets, and memory protection flags needed to load firmware
 /// into the MCU's memory.
 pub(super) struct FwParser<'a> {
     cursor: Cursor<'a>,
 }

 impl<'a> FwParser<'a> {
     /// Creates a new firmware parser for the given firmware binary data.
     pub(super) fn new(dev: &'a Device, data: &'a [u8]) -> Self {
         Self {
             cursor: Cursor::new(dev, data),
         }
     }

     /// Parses the firmware binary and returns a collection of parsed sections.
     ///
     /// This method validates the firmware header and iterates through all entries
     /// in the binary, extracting section information needed for loading.
     pub(super) fn parse(&mut self) -> Result<KVec<ParsedSection>> {
         let fw_header = self.parse_fw_header()?;
         let header_end = fw_header.size as usize;

         let mut parsed_sections = KVec::new();
         while self.cursor.pos() < header_end {
             let entry_section = self.parse_entry(header_end)?;

             if let Some(inner) = entry_section.inner {
                 parsed_sections.push(inner, GFP_KERNEL)?;
             }
         }

         if parsed_sections.is_empty() {
             dev_err!(self.cursor.dev, "Firmware contains no loadable sections");
             return Err(EINVAL);
         }

         Ok(parsed_sections)
     }

     fn parse_fw_header(&mut self) -> Result<FirmwareHeader> {
         let fw_header: FirmwareHeader = match FirmwareHeader::new(&mut self.cursor) {
             Ok(fw_header) => fw_header,
             Err(e) => {
                 dev_err!(self.cursor.dev, "Invalid firmware file: {}", e.to_errno());
                 return Err(e);
             }
         };

         if fw_header.size as usize > self.cursor.len() {
             dev_err!(self.cursor.dev, "Firmware image is truncated");
             return Err(EINVAL);
         }
         Ok(fw_header)
     }

     fn parse_entry(&mut self, header_end: usize) -> Result<EntrySection> {
         let entry_start = self.cursor.pos();

         let entry_header_end = entry_start
             .checked_add(size_of::<EntryHeader>())
             .ok_or(EINVAL)?;

         if entry_header_end > header_end {
             dev_err!(
                 self.cursor.dev,
                 "Firmware entry header at {:#x} exceeds header region ending at {:#x}",
                 entry_start,
                 header_end
             );
             return Err(EINVAL);
         }

         let entry_section = EntrySection {
             entry_hdr: EntryHeader(self.cursor.read_u32()?),
             inner: None,
         };

         let firmware_size = self.cursor.len();
         let entry_size = entry_section.entry_hdr.size() as usize;

         if self.cursor.pos() % size_of::<u32>() != 0
             || entry_size % size_of::<u32>() != 0
             || entry_size < size_of::<EntryHeader>()
         {
             dev_err!(
                 self.cursor.dev,
                 "Firmware entry isn't 32 bit aligned, offset={:#x} size={:#x}",
                 self.cursor.pos() - size_of::<u32>(),
                 entry_size
             );
             return Err(EINVAL);
         }

         let entry_end = entry_start.checked_add(entry_size).ok_or(EINVAL)?;

         if entry_end > header_end {
             dev_err!(
                 self.cursor.dev,
                 "Firmware entry at {:#x} extends beyond header region ending at {:#x}",
                 entry_start,
                 header_end
             );
             return Err(EINVAL);
         }

         let section_hdr_size = entry_size - size_of::<EntryHeader>();

         let entry_section = {
             let mut entry_cursor = self.cursor.view(self.cursor.pos()..entry_end)?;

             match entry_section.entry_hdr.entry_type() {
                 Ok(EntryType::Iface) => Ok(EntrySection {
                     entry_hdr: entry_section.entry_hdr,
                     inner: Self::parse_section_entry(&mut entry_cursor, firmware_size)?,
                 }),
                 Ok(
                     EntryType::Config
                     | EntryType::FutfTest
                     | EntryType::TraceBuffer
                     | EntryType::TimelineMetadata
                     | EntryType::BuildInfoMetadata,
                 ) => Ok(entry_section),

                 Err(_) => {
                     if entry_section.entry_hdr.optional() {
                         Ok(entry_section)
                     } else {
                         dev_err!(
                             self.cursor.dev,
                             "Failed to handle firmware entry type: {}",
                             entry_section.entry_hdr.entry_type_raw()
                         );
                         Err(EINVAL)
                     }
                 }
             }
         };

         if entry_section.is_ok() {
             self.cursor.advance(section_hdr_size)?;
         }

         entry_section
     }

     fn parse_section_entry(
         entry_cursor: &mut Cursor<'_>,
         firmware_size: usize,
     ) -> Result<Option<ParsedSection>> {
         let section_hdr: SectionHeader = SectionHeader::new(entry_cursor)?;

         if section_hdr.data.end < section_hdr.data.start {
             dev_err!(
                 entry_cursor.dev,
                 "Firmware corrupted, data.end < data.start (0x{:x} < 0x{:x})",
                 section_hdr.data.end,
                 section_hdr.data.start
             );
             return Err(EINVAL);
         }

         if section_hdr.data.end as usize > firmware_size {
             dev_err!(
                 entry_cursor.dev,
                 "Firmware data range {:#x}..{:#x} exceeds firmware size {:#x}",
                 section_hdr.data.start,
                 section_hdr.data.end,
                 firmware_size,
             );
             return Err(EINVAL);
         }

         if section_hdr.va.start as usize % SZ_4K != 0 || section_hdr.va.end as usize % SZ_4K != 0 {
             dev_err!(
                 entry_cursor.dev,
                 "Firmware virtual address range {:#x}..{:#x} is not page aligned",
                 section_hdr.va.start,
                 section_hdr.va.end
             );
             return Err(EINVAL);
         }

         if section_hdr.section_flags.prot() {
             dev_dbg!(
                 entry_cursor.dev,
                 "Firmware protected mode entry not supported, ignoring"
             );
             return Ok(None);
         }

         if section_hdr.va.start == CSF_MCU_SHARED_REGION_START
             && !section_hdr.section_flags.shared()
         {
             dev_err!(
                 entry_cursor.dev,
                 "Interface at 0x{:x} must be shared",
                 CSF_MCU_SHARED_REGION_START
             );
             return Err(EINVAL);
         }

         if section_hdr.va.is_empty() {
             return Ok(None);
         }

         let mut vm_map_flags = VmMapFlags::empty();

         if !section_hdr.section_flags.write() {
             vm_map_flags |= VmFlag::Readonly;
         }

         if !section_hdr.section_flags.exec() {
             vm_map_flags |= VmFlag::Noexec;
         }

         // TODO: As in Panthor, map coherent firmware sections uncached until the VM
         // supports a coherent mapping attribute.
         if section_hdr.section_flags.cache_mode() != CacheMode::Cached {
             vm_map_flags |= VmFlag::Uncached;
         }

         Ok(Some(ParsedSection {
             data_range: section_hdr.data.clone(),
             va: section_hdr.va,
             vm_map_flags,
         }))
     }
 }

 /// Firmware binary header containing version and size information.
 ///
 /// The header is located at the beginning of the firmware binary and contains
 /// a magic value for validation, version information, and the total size of
 /// all structured headers that follow.
 #[expect(dead_code)]
 struct FirmwareHeader {
     /// Magic value to check binary validity.
     magic: u32,

     /// Minor firmware version.
     minor: u8,

     /// Major firmware version.
     major: u8,

     /// Padding. Must be set to zero.
     _padding1: u16,

     /// Firmware version hash.
     version_hash: u32,

     /// Padding. Must be set to zero.
     _padding2: u32,

     /// Total size of all the structured data headers at beginning of firmware binary.
     size: u32,
 }

 impl FirmwareHeader {
     const FW_BINARY_MAGIC: u32 = 0xc3f13a6e;
     const FW_BINARY_MAJOR_MAX: u8 = 0;

     /// Reads and validates a firmware header from the cursor.
     ///
     /// Verifies the magic value, version compatibility, and padding fields.
     fn new(cursor: &mut Cursor<'_>) -> Result<Self> {
         let magic = cursor.read_u32()?;
         if magic != Self::FW_BINARY_MAGIC {
             dev_err!(cursor.dev, "Invalid firmware magic");
             return Err(EINVAL);
         }

         let minor = cursor.read_u8()?;
         let major = cursor.read_u8()?;

         if major > Self::FW_BINARY_MAJOR_MAX {
             dev_err!(
                 cursor.dev,
                 "Unsupported firmware binary header version {}.{} (expected {}.x)",
                 major,
                 minor,
                 Self::FW_BINARY_MAJOR_MAX
             );
             return Err(EINVAL);
         }

         let padding1 = cursor.read_u16()?;
         let version_hash = cursor.read_u32()?;
         let padding2 = cursor.read_u32()?;
         let size = cursor.read_u32()?;

         if padding1 != 0 || padding2 != 0 {
             dev_err!(
                 cursor.dev,
                 "Invalid firmware file: header padding is not zero"
             );
             return Err(EINVAL);
         }

         let fw_header = Self {
             magic,
             minor,
             major,
             _padding1: padding1,
             version_hash,
             _padding2: padding2,
             size,
         };

         Ok(fw_header)
     }
 }

 /// Firmware section header for loading binary sections into MCU memory.
 #[derive(Debug)]
 struct SectionHeader {
     section_flags: SectionFlags,
     /// MCU virtual range to map this binary section to.
     va: Range<u32>,
     /// References the data in the FW binary.
     data: Range<u32>,
 }

 impl SectionHeader {
     /// Reads and validates a section header from the cursor.
     ///
     /// Parses section flags, virtual address range, and data range from the firmware binary.
     fn new(cursor: &mut Cursor<'_>) -> Result<Self> {
         let section_flags = SectionFlags::try_from_fw(cursor.read_u32()?)?;

         let va_start = cursor.read_u32()?;
         let va_end = cursor.read_u32()?;

         let va = va_start..va_end;

         if va.end < va.start {
             dev_err!(
                 cursor.dev,
                 "Invalid firmware file: VA end precedes start at pos {}",
                 cursor.pos(),
             );
             return Err(EINVAL);
         }

         let data_start = cursor.read_u32()?;
         let data_end = cursor.read_u32()?;
         let data = data_start..data_end;

         Ok(Self {
             section_flags,
             va,
             data,
         })
     }
 }

 /// A firmware entry containing a header and optional parsed section data.
 ///
 /// Represents a single entry in the firmware binary, which may contain loadable
 /// section data or metadata that doesn't require loading.
 struct EntrySection {
     entry_hdr: EntryHeader,
     inner: Option<ParsedSection>,
 }

 /// Header for a firmware entry, packed into a single u32.
 ///
 /// The entry header encodes the entry type, size, and optional flag in a
 /// 32-bit value with the following layout:
 /// - Bits 0-7: Entry type
 /// - Bits 8-15: Size in bytes
 /// - Bit 31: Optional flag
 struct EntryHeader(u32);

 impl EntryHeader {
     fn entry_type_raw(&self) -> u8 {
         (self.0 & 0xff) as u8
     }

     fn entry_type(&self) -> Result<EntryType> {
         let v = self.entry_type_raw();
         EntryType::try_from(v)
     }

     fn optional(&self) -> bool {
         self.0 & bit_u32(31) != 0
     }

     fn size(&self) -> u32 {
         self.0 >> 8 & 0xff
     }
 }

 #[derive(Clone, Copy, Debug)]
 #[repr(u8)]
 enum EntryType {
     /// Host <-> FW interface.
     Iface = 0,
     /// FW config.
     Config = 1,
     /// Unit tests.
     FutfTest = 2,
     /// Trace buffer interface.
     TraceBuffer = 3,
     /// Timeline metadata interface.
     TimelineMetadata = 4,
     /// Metadata about how the FW binary was built.
     BuildInfoMetadata = 6,
 }

 impl TryFrom<u8> for EntryType {
     type Error = Error;

     fn try_from(value: u8) -> Result<Self, Self::Error> {
         match value {
             0 => Ok(EntryType::Iface),
             1 => Ok(EntryType::Config),
             2 => Ok(EntryType::FutfTest),
             3 => Ok(EntryType::TraceBuffer),
             4 => Ok(EntryType::TimelineMetadata),
             6 => Ok(EntryType::BuildInfoMetadata),
             _ => Err(EINVAL),
         }
     }
 }
	// SPDX-License-Identifier: GPL-2.0 or MIT

	//! Firmware binary parser for Mali CSF (Command Stream Frontend) GPU.
	//!
	//! This module implements a parser for the Mali GPU firmware binary format. The firmware
	//! file contains a header followed by a sequence of entries, each describing how to load
	//! firmware sections into the MCU (Microcontroller Unit) memory. The parser extracts section
	//! metadata including:
	//! - Virtual address ranges where sections should be mapped
	//! - Data ranges (byte offsets) within the firmware binary
	//! - Section flags (permissions, cache modes)

	use core::{
	mem::size_of,
	ops::Range, //
	};

	use kernel::{
	bits::bit_u32,
	device::Device,
	prelude::*,
	sizes::SZ_4K, //
	};

	use crate::{
	fw::{
	CacheMode,
	SectionFlags,
	CSF_MCU_SHARED_REGION_START, //
	},
	vm::{
	VmFlag,
	VmMapFlags, //
	}, //
	};

	/// A parsed firmware section ready for loading into MCU memory.
	///
	/// Represents a single firmware section extracted from the firmware binary, containing
	/// all information needed to map the section's data into the MCU's virtual address space.
	pub(super) struct ParsedSection {
	/// Byte offset range within the firmware binary where this section's data resides.
	pub(super) data_range: Range<u32>,
	/// MCU virtual address range where this section should be mapped.
	pub(super) va: Range<u32>,
	/// Memory protection and caching flags for the mapping.
	pub(super) vm_map_flags: VmMapFlags,
	}

	/// A bare-bones `std::io::Cursor<[u8]>` clone to keep track of the current position in the
	/// firmware binary.
	///
	/// Provides methods to sequentially read primitive types and byte arrays from the firmware
	/// binary while maintaining the current read position.
	struct Cursor<'a> {
	dev: &'a Device,
	data: &'a [u8],
	pos: usize,
	}

	impl<'a> Cursor<'a> {
	fn new(dev: &'a Device, data: &'a [u8]) -> Self {
	Self { dev, data, pos: 0 }
	}

	fn len(&self) -> usize {
	self.data.len()
	}

	fn pos(&self) -> usize {
	self.pos
	}

	/// Returns a view into the cursor's data.
	///
	/// This spawns a new cursor, leaving the current cursor unchanged.
	fn view(&self, range: Range<usize>) -> Result<Cursor<'_>> {
	if range.start < self.pos \|\| range.end > self.data.len() {
	dev_err!(
	self.dev,
	"Invalid cursor range {:?} for data of length {}",
	range,
	self.data.len()
	);

	Err(EINVAL)
	} else {
	Ok(Self {
	dev: self.dev,
	data: &self.data[range],
	pos: 0,
	})
	}
	}

	/// Reads a slice of bytes from the current position and advances the cursor.
	///
	/// Returns an error if the read would exceed the data bounds.
	fn read(&mut self, nbytes: usize) -> Result<&[u8]> {
	let start = self.pos;
	let end = start + nbytes;

	if end > self.data.len() {
	dev_err!(
	self.dev,
	"Invalid firmware file: read of size {} at position {} is out of bounds",
	nbytes,
	start,
	);
	return Err(EINVAL);
	}

	self.pos += nbytes;
	Ok(&self.data[start..end])
	}

	/// Reads a little-endian `u8` from the current position and advances the cursor.
	fn read_u8(&mut self) -> Result<u8> {
	let bytes = self.read(size_of::<u8>())?;
	Ok(bytes[0])
	}

	/// Reads a little-endian `u16` from the current position and advances the cursor.
	fn read_u16(&mut self) -> Result<u16> {
	let bytes: [u8; 2] = self
	.read(size_of::<u16>())?
	.try_into()
	.map_err(\|_\| EINVAL)?;

	Ok(u16::from_le_bytes(bytes))
	}

	/// Reads a little-endian `u32` from the current position and advances the cursor.
	fn read_u32(&mut self) -> Result<u32> {
	let bytes: [u8; 4] = self
	.read(size_of::<u32>())?
	.try_into()
	.map_err(\|_\| EINVAL)?;

	Ok(u32::from_le_bytes(bytes))
	}

	/// Advances the cursor position by the specified number of bytes.
	///
	/// Returns an error if the advance would exceed the data bounds.
	fn advance(&mut self, nbytes: usize) -> Result {
	if self.pos + nbytes > self.data.len() {
	dev_err!(
	self.dev,
	"Invalid firmware file: advance of size {} at position {} is out of bounds",
	nbytes,
	self.pos,
	);
	return Err(EINVAL);
	}
	self.pos += nbytes;
	Ok(())
	}
	}

	/// Parser for Mali CSF GPU firmware binaries.
	///
	/// Parses the firmware binary format, extracting section metadata including virtual
	/// address ranges, data offsets, and memory protection flags needed to load firmware
	/// into the MCU's memory.
	pub(super) struct FwParser<'a> {
	cursor: Cursor<'a>,
	}

	impl<'a> FwParser<'a> {
	/// Creates a new firmware parser for the given firmware binary data.
	pub(super) fn new(dev: &'a Device, data: &'a [u8]) -> Self {
	Self {
	cursor: Cursor::new(dev, data),
	}
	}

	/// Parses the firmware binary and returns a collection of parsed sections.
	///
	/// This method validates the firmware header and iterates through all entries
	/// in the binary, extracting section information needed for loading.
	pub(super) fn parse(&mut self) -> Result<KVec<ParsedSection>> {
	let fw_header = self.parse_fw_header()?;
	let header_end = fw_header.size as usize;

	let mut parsed_sections = KVec::new();
	while self.cursor.pos() < header_end {
	let entry_section = self.parse_entry(header_end)?;

	if let Some(inner) = entry_section.inner {
	parsed_sections.push(inner, GFP_KERNEL)?;
	}
	}

	if parsed_sections.is_empty() {
	dev_err!(self.cursor.dev, "Firmware contains no loadable sections");
	return Err(EINVAL);
	}

	Ok(parsed_sections)
	}

	fn parse_fw_header(&mut self) -> Result<FirmwareHeader> {
	let fw_header: FirmwareHeader = match FirmwareHeader::new(&mut self.cursor) {
	Ok(fw_header) => fw_header,
	Err(e) => {
	dev_err!(self.cursor.dev, "Invalid firmware file: {}", e.to_errno());
	return Err(e);
	}
	};

	if fw_header.size as usize > self.cursor.len() {
	dev_err!(self.cursor.dev, "Firmware image is truncated");
	return Err(EINVAL);
	}
	Ok(fw_header)
	}

	fn parse_entry(&mut self, header_end: usize) -> Result<EntrySection> {
	let entry_start = self.cursor.pos();

	let entry_header_end = entry_start
	.checked_add(size_of::<EntryHeader>())
	.ok_or(EINVAL)?;

	if entry_header_end > header_end {
	dev_err!(
	self.cursor.dev,
	"Firmware entry header at {:#x} exceeds header region ending at {:#x}",
	entry_start,
	header_end
	);
	return Err(EINVAL);
	}

	let entry_section = EntrySection {
	entry_hdr: EntryHeader(self.cursor.read_u32()?),
	inner: None,
	};

	let firmware_size = self.cursor.len();
	let entry_size = entry_section.entry_hdr.size() as usize;

	if self.cursor.pos() % size_of::<u32>() != 0
	\|\| entry_size % size_of::<u32>() != 0
	\|\| entry_size < size_of::<EntryHeader>()
	{
	dev_err!(
	self.cursor.dev,
	"Firmware entry isn't 32 bit aligned, offset={:#x} size={:#x}",
	self.cursor.pos() - size_of::<u32>(),
	entry_size
	);
	return Err(EINVAL);
	}

	let entry_end = entry_start.checked_add(entry_size).ok_or(EINVAL)?;

	if entry_end > header_end {
	dev_err!(
	self.cursor.dev,
	"Firmware entry at {:#x} extends beyond header region ending at {:#x}",
	entry_start,
	header_end
	);
	return Err(EINVAL);
	}

	let section_hdr_size = entry_size - size_of::<EntryHeader>();

	let entry_section = {
	let mut entry_cursor = self.cursor.view(self.cursor.pos()..entry_end)?;

	match entry_section.entry_hdr.entry_type() {
	Ok(EntryType::Iface) => Ok(EntrySection {
	entry_hdr: entry_section.entry_hdr,
	inner: Self::parse_section_entry(&mut entry_cursor, firmware_size)?,
	}),
	Ok(
	EntryType::Config
	\| EntryType::FutfTest
	\| EntryType::TraceBuffer
	\| EntryType::TimelineMetadata
	\| EntryType::BuildInfoMetadata,
	) => Ok(entry_section),

	Err(_) => {
	if entry_section.entry_hdr.optional() {
	Ok(entry_section)
	} else {
	dev_err!(
	self.cursor.dev,
	"Failed to handle firmware entry type: {}",
	entry_section.entry_hdr.entry_type_raw()
	);
	Err(EINVAL)
	}
	}
	}
	};

	if entry_section.is_ok() {
	self.cursor.advance(section_hdr_size)?;
	}

	entry_section
	}

	fn parse_section_entry(
	entry_cursor: &mut Cursor<'_>,
	firmware_size: usize,
	) -> Result<Option<ParsedSection>> {
	let section_hdr: SectionHeader = SectionHeader::new(entry_cursor)?;

	if section_hdr.data.end < section_hdr.data.start {
	dev_err!(
	entry_cursor.dev,
	"Firmware corrupted, data.end < data.start (0x{:x} < 0x{:x})",
	section_hdr.data.end,
	section_hdr.data.start
	);
	return Err(EINVAL);
	}

	if section_hdr.data.end as usize > firmware_size {
	dev_err!(
	entry_cursor.dev,
	"Firmware data range {:#x}..{:#x} exceeds firmware size {:#x}",
	section_hdr.data.start,
	section_hdr.data.end,
	firmware_size,
	);
	return Err(EINVAL);
	}

	if section_hdr.va.start as usize % SZ_4K != 0 \|\| section_hdr.va.end as usize % SZ_4K != 0 {
	dev_err!(
	entry_cursor.dev,
	"Firmware virtual address range {:#x}..{:#x} is not page aligned",
	section_hdr.va.start,
	section_hdr.va.end
	);
	return Err(EINVAL);
	}

	if section_hdr.section_flags.prot() {
	dev_dbg!(
	entry_cursor.dev,
	"Firmware protected mode entry not supported, ignoring"
	);
	return Ok(None);
	}

	if section_hdr.va.start == CSF_MCU_SHARED_REGION_START
	&& !section_hdr.section_flags.shared()
	{
	dev_err!(
	entry_cursor.dev,
	"Interface at 0x{:x} must be shared",
	CSF_MCU_SHARED_REGION_START
	);
	return Err(EINVAL);
	}

	if section_hdr.va.is_empty() {
	return Ok(None);
	}

	let mut vm_map_flags = VmMapFlags::empty();

	if !section_hdr.section_flags.write() {
	vm_map_flags \|= VmFlag::Readonly;
	}

	if !section_hdr.section_flags.exec() {
	vm_map_flags \|= VmFlag::Noexec;
	}

	// TODO: As in Panthor, map coherent firmware sections uncached until the VM
	// supports a coherent mapping attribute.
	if section_hdr.section_flags.cache_mode() != CacheMode::Cached {
	vm_map_flags \|= VmFlag::Uncached;
	}

	Ok(Some(ParsedSection {
	data_range: section_hdr.data.clone(),
	va: section_hdr.va,
	vm_map_flags,
	}))
	}
	}

	/// Firmware binary header containing version and size information.
	///
	/// The header is located at the beginning of the firmware binary and contains
	/// a magic value for validation, version information, and the total size of
	/// all structured headers that follow.
	#[expect(dead_code)]
	struct FirmwareHeader {
	/// Magic value to check binary validity.
	magic: u32,

	/// Minor firmware version.
	minor: u8,

	/// Major firmware version.
	major: u8,

	/// Padding. Must be set to zero.
	_padding1: u16,

	/// Firmware version hash.
	version_hash: u32,

	/// Padding. Must be set to zero.
	_padding2: u32,

	/// Total size of all the structured data headers at beginning of firmware binary.
	size: u32,
	}

	impl FirmwareHeader {
	const FW_BINARY_MAGIC: u32 = 0xc3f13a6e;
	const FW_BINARY_MAJOR_MAX: u8 = 0;

	/// Reads and validates a firmware header from the cursor.
	///
	/// Verifies the magic value, version compatibility, and padding fields.
	fn new(cursor: &mut Cursor<'_>) -> Result<Self> {
	let magic = cursor.read_u32()?;
	if magic != Self::FW_BINARY_MAGIC {
	dev_err!(cursor.dev, "Invalid firmware magic");
	return Err(EINVAL);
	}

	let minor = cursor.read_u8()?;
	let major = cursor.read_u8()?;

	if major > Self::FW_BINARY_MAJOR_MAX {
	dev_err!(
	cursor.dev,
	"Unsupported firmware binary header version {}.{} (expected {}.x)",
	major,
	minor,
	Self::FW_BINARY_MAJOR_MAX
	);
	return Err(EINVAL);
	}

	let padding1 = cursor.read_u16()?;
	let version_hash = cursor.read_u32()?;
	let padding2 = cursor.read_u32()?;
	let size = cursor.read_u32()?;

	if padding1 != 0 \|\| padding2 != 0 {
	dev_err!(
	cursor.dev,
	"Invalid firmware file: header padding is not zero"
	);
	return Err(EINVAL);
	}

	let fw_header = Self {
	magic,
	minor,
	major,
	_padding1: padding1,
	version_hash,
	_padding2: padding2,
	size,
	};

	Ok(fw_header)
	}
	}

	/// Firmware section header for loading binary sections into MCU memory.
	#[derive(Debug)]
	struct SectionHeader {
	section_flags: SectionFlags,
	/// MCU virtual range to map this binary section to.
	va: Range<u32>,
	/// References the data in the FW binary.
	data: Range<u32>,
	}

	impl SectionHeader {
	/// Reads and validates a section header from the cursor.
	///
	/// Parses section flags, virtual address range, and data range from the firmware binary.
	fn new(cursor: &mut Cursor<'_>) -> Result<Self> {
	let section_flags = SectionFlags::try_from_fw(cursor.read_u32()?)?;

	let va_start = cursor.read_u32()?;
	let va_end = cursor.read_u32()?;

	let va = va_start..va_end;

	if va.end < va.start {
	dev_err!(
	cursor.dev,
	"Invalid firmware file: VA end precedes start at pos {}",
	cursor.pos(),
	);
	return Err(EINVAL);
	}

	let data_start = cursor.read_u32()?;
	let data_end = cursor.read_u32()?;
	let data = data_start..data_end;

	Ok(Self {
	section_flags,
	va,
	data,
	})
	}
	}

	/// A firmware entry containing a header and optional parsed section data.
	///
	/// Represents a single entry in the firmware binary, which may contain loadable
	/// section data or metadata that doesn't require loading.
	struct EntrySection {
	entry_hdr: EntryHeader,
	inner: Option<ParsedSection>,
	}

	/// Header for a firmware entry, packed into a single u32.
	///
	/// The entry header encodes the entry type, size, and optional flag in a
	/// 32-bit value with the following layout:
	/// - Bits 0-7: Entry type
	/// - Bits 8-15: Size in bytes
	/// - Bit 31: Optional flag
	struct EntryHeader(u32);

	impl EntryHeader {
	fn entry_type_raw(&self) -> u8 {
	(self.0 & 0xff) as u8
	}

	fn entry_type(&self) -> Result<EntryType> {
	let v = self.entry_type_raw();
	EntryType::try_from(v)
	}

	fn optional(&self) -> bool {
	self.0 & bit_u32(31) != 0
	}

	fn size(&self) -> u32 {
	self.0 >> 8 & 0xff
	}
	}

	#[derive(Clone, Copy, Debug)]
	#[repr(u8)]
	enum EntryType {
	/// Host <-> FW interface.
	Iface = 0,
	/// FW config.
	Config = 1,
	/// Unit tests.
	FutfTest = 2,
	/// Trace buffer interface.
	TraceBuffer = 3,
	/// Timeline metadata interface.
	TimelineMetadata = 4,
	/// Metadata about how the FW binary was built.
	BuildInfoMetadata = 6,
	}

	impl TryFrom<u8> for EntryType {
	type Error = Error;

	fn try_from(value: u8) -> Result<Self, Self::Error> {
	match value {
	0 => Ok(EntryType::Iface),
	1 => Ok(EntryType::Config),
	2 => Ok(EntryType::FutfTest),
	3 => Ok(EntryType::TraceBuffer),
	4 => Ok(EntryType::TimelineMetadata),
	6 => Ok(EntryType::BuildInfoMetadata),
	_ => Err(EINVAL),
	}
	}
	}