Add README and doc comments
Signed-off-by: Balint Dobszay <balint.dobszay@arm.com>
Change-Id: Ie4cf762558b181139e1456887a0e4687b0243564
diff --git a/src/boot_info.rs b/src/boot_info.rs
index 30850e5..446ff08 100644
--- a/src/boot_info.rs
+++ b/src/boot_info.rs
@@ -1,6 +1,21 @@
// SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
// SPDX-License-Identifier: MIT OR Apache-2.0
+//! Implementation of the FF-A Boot information protocol.
+//!
+//! An SP or SPMC could rely on boot information for their initialization e.g. a flattened device
+//! tree with nodes to describe the devices and memory regions assigned to the SP or SPMC. FF-A
+//! specifies a protocol that can be used by a producer to pass boot information to a consumer at a
+//! Secure FF-A instance. The Framework assumes that the boot information protocol is used by a
+//! producer and consumer pair that reside at adjacent exception levels as listed below.
+//! - SPMD (producer) and an SPMC (consumer) in either S-EL1 or S-EL2.
+//! - An SPMC (producer) and SP (consumer) pair listed below.
+//! - EL3 SPMC and a Logical S-EL1 SP.
+//! - S-EL2 SPMC and Physical S-EL1 SP.
+//! - EL3 SPMC and a S-EL0 SP.
+//! - S-EL2 SPMC and a S-EL0 SP.
+//! - S-EL1 SPMC and a S-EL0 SP.
+
use crate::{
ffa_v1_1::{boot_info_descriptor, boot_info_header},
Version,
@@ -10,6 +25,8 @@
use uuid::Uuid;
use zerocopy::{FromBytes, IntoBytes};
+/// Rich error types returned by this module. Should be converted to [`crate::FfaError`] when used
+/// with the `FFA_ERROR` interface.
#[derive(Debug, Error)]
pub enum Error {
#[error("Invalid standard type {0}")]
@@ -42,12 +59,14 @@
}
}
+/// Name of boot information descriptor.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum BootInfoName<'a> {
NullTermString(&'a CStr),
Uuid(Uuid),
}
+/// ID for supported standard boot information types.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u8)]
pub enum BootInfoStdId {
@@ -72,6 +91,7 @@
const HOB: u8 = 1;
}
+/// ID for implementation defined boot information type.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct BootInfoImpdefId(pub u8);
@@ -81,6 +101,7 @@
}
}
+/// Boot information type.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BootInfoType {
Std(BootInfoStdId),
@@ -122,6 +143,7 @@
const ID_MASK: u8 = 0b0111_1111;
}
+/// Boot information contents.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BootInfoContents<'a> {
Address { content_buf: &'a [u8] },
@@ -208,6 +230,7 @@
}
}
+/// Boot information descriptor.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BootInfo<'a> {
pub name: BootInfoName<'a>,
@@ -216,10 +239,15 @@
}
impl BootInfo<'_> {
+ /// Serialize a list of boot information descriptors into a buffer. The `mapped_addr` parameter
+ /// should contain the address of the buffer in the consumers translation regime (typically a
+ /// virtual address where the buffer is mapped to). This is necessary since there are
+ /// self-references within the serialized data structure which must be described with an
+ /// absolute address according to the FF-A spec.
pub fn pack(descriptors: &[BootInfo], buf: &mut [u8], mapped_addr: Option<usize>) {
// Offset from the base of the header to the first element in the boot info descriptor array
// Must be 8 byte aligned, but otherwise we're free to choose any value here.
- // Let's just pack the array right after the header.
+ // Let's just pack the array right after the header.
const DESC_ARRAY_OFFSET: usize = size_of::<boot_info_header>().next_multiple_of(8);
const DESC_SIZE: usize = size_of::<boot_info_descriptor>();
@@ -365,11 +393,10 @@
Ok(header_raw)
}
- /// Get the size of the boot information blob spanning contiguous memory.
- ///
- /// This enables a consumer to map all of the boot information blob in its translation regime
- /// or copy it to another memory location without parsing each element in the boot information
- /// descriptor array.
+ /// Get the size of the boot information blob spanning contiguous memory. This enables a
+ /// consumer to map all of the boot information blob in its translation regime or copy it to
+ /// another memory location without parsing each element in the boot information descriptor
+ /// array.
pub fn get_blob_size(buf: &[u8]) -> Result<usize, Error> {
let header_raw = Self::get_header(buf)?;
@@ -377,6 +404,7 @@
}
}
+/// Iterator of boot information descriptors.
pub struct BootInfoIterator<'a> {
buf: &'a [u8],
offset: usize,
@@ -385,6 +413,7 @@
}
impl<'a> BootInfoIterator<'a> {
+ /// Create an iterator of boot information descriptors from a buffer.
pub fn new(buf: &'a [u8]) -> Result<Self, Error> {
let header_raw = BootInfo::get_header(buf)?;