opentitanlib/util/
status.rs

1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5// This utility handles the various aspect of the status_t type used in
6// the device code.
7
8use std::convert::TryFrom;
9use std::ffi::CString;
10use std::path::PathBuf;
11
12use anyhow::{Context, Result, bail};
13use bindgen::status::{ot_status_create_record_t, status_create, status_err, status_extract};
14use object::{Object, ObjectSection};
15use zerocopy::FromBytes;
16
17pub use bindgen::status::absl_status_t as RawStatusCode;
18pub use bindgen::status::status_t as RawStatus;
19
20// FIXME: is there a better way of doing this? bindgen CLI does not
21// support adding custom derive to a type.
22#[derive(Debug, serde::Serialize, serde::Deserialize, strum::FromRepr, PartialEq, Eq)]
23#[repr(u32)]
24pub enum StatusCode {
25    Ok = bindgen::status::absl_status_code_kOk,
26    Cancelled = bindgen::status::absl_status_code_kCancelled,
27    Unknown = bindgen::status::absl_status_code_kUnknown,
28    InvalidArgument = bindgen::status::absl_status_code_kInvalidArgument,
29    DeadlineExceeded = bindgen::status::absl_status_code_kDeadlineExceeded,
30    NotFound = bindgen::status::absl_status_code_kNotFound,
31    AlreadyExists = bindgen::status::absl_status_code_kAlreadyExists,
32    PermissionDenied = bindgen::status::absl_status_code_kPermissionDenied,
33    ResourceExhausted = bindgen::status::absl_status_code_kResourceExhausted,
34    FailedPrecondition = bindgen::status::absl_status_code_kFailedPrecondition,
35    Aborted = bindgen::status::absl_status_code_kAborted,
36    OutOfRange = bindgen::status::absl_status_code_kOutOfRange,
37    Unimplemented = bindgen::status::absl_status_code_kUnimplemented,
38    Internal = bindgen::status::absl_status_code_kInternal,
39    Unavailable = bindgen::status::absl_status_code_kUnavailable,
40    DataLoss = bindgen::status::absl_status_code_kDataLoss,
41    Unauthenticated = bindgen::status::absl_status_code_kUnauthenticated,
42}
43
44// Safe abstraction over status_create
45fn status_create_safe(code: StatusCode, mod_id: u32, file: String, arg: i32) -> RawStatus {
46    // We do not expect an error since it is a valid String.
47    let file = CString::new(file).expect("CString::new failed");
48    // SAFETY: the function expects a valid readonly C-string which is exactly what
49    // CString:as_ptr() provides.
50    unsafe { status_create(code as u32, mod_id, file.as_ptr(), arg) }
51    // Note: file is dropped here so the C-string pointer is valid accross the function call.
52}
53
54// Convert an array of i8 to a string. This function will stop at first 0 (or at the
55// end of the array if it contains no zero).
56fn c_string_to_string(array: &[i8]) -> String {
57    let array = array
58        .iter()
59        .map(|c| *c as u8)
60        .take_while(|c| *c != 0u8)
61        .collect::<Vec<_>>();
62    String::from_utf8_lossy(&array).to_string()
63}
64
65#[derive(Debug, serde::Serialize, serde::Deserialize)]
66/// Hold a completely decoded status.
67pub struct Status {
68    // Module ID if present.
69    pub module_id: String,
70    // Status argument. Note that depending on whether this is an error status or ok
71    // status, the maximum value that can fit is different.
72    pub arg: i32,
73    // Error code of the status.
74    pub code: StatusCode,
75}
76
77// Safe abstraction over status_extract.
78impl Status {
79    pub fn from_raw_status(status: RawStatus) -> Result<Status> {
80        // We do not care about the code string but status_extract expects a non-null pointer.
81        let mut code_str: *const std::os::raw::c_char = std::ptr::null();
82        let mut arg = 0i32;
83        let mut mod_id: [std::os::raw::c_char; 3] = [0; 3];
84        let mod_id_ptr = &mut mod_id as *mut i8;
85        // SAFETY: status_extract expects:
86        // - a non-null pointer to string pointer that will be updated to point
87        //   to the english name of the error code,
88        // - a non-null pointer to an integer (argument),
89        // - a non-null pointer to a char[3] buffer that is filled with the module ID.
90        let is_err_status = unsafe { status_extract(status, &mut code_str, &mut arg, mod_id_ptr) };
91        let code = match is_err_status {
92            false => StatusCode::Ok,
93            true => {
94                // SAFETY: nothing unsafe except that it's an FFI call.
95                let raw_code = unsafe { status_err(status) };
96                StatusCode::from_repr(raw_code)
97                    .with_context(|| format!("invalid status code value {raw_code}"))?
98            }
99        };
100        Ok(Status {
101            module_id: c_string_to_string(&mod_id),
102            arg,
103            code,
104        })
105    }
106
107    pub fn from_u32(status: u32) -> Result<Status> {
108        Self::from_raw_status(RawStatus {
109            value: status as i32,
110        })
111    }
112}
113
114#[cfg(test)]
115mod test {
116    use super::*;
117
118    #[test]
119    fn status_manip_test_good() {
120        // Make sure that we can correctly decode a status. For this, we first need to
121        // create it.
122        const CODE: StatusCode = StatusCode::PermissionDenied;
123        const MOD_ID: &str = "abc";
124        const ARG: i32 = 42;
125        let mod_id_bytes = MOD_ID.as_bytes();
126        assert_eq!(mod_id_bytes.len(), 3);
127        // The following reimplement the MAKE_MODULE_ID macro in rust.
128        let mod_id_val = ((mod_id_bytes[0].to_ascii_uppercase() as u32) << 16)
129            | ((mod_id_bytes[1].to_ascii_uppercase() as u32) << 8)
130            | (mod_id_bytes[2].to_ascii_uppercase() as u32);
131        let raw_status = status_create_safe(CODE, mod_id_val, "".to_string(), ARG);
132
133        // Now decode status.
134        let decoded_status = Status::from_raw_status(raw_status);
135        assert!(decoded_status.is_ok());
136        let decoded_status = decoded_status.unwrap();
137        assert_eq!(decoded_status.module_id, MOD_ID.to_ascii_uppercase());
138        assert_eq!(decoded_status.code, CODE);
139        assert_eq!(decoded_status.arg, ARG);
140    }
141}
142
143#[derive(Debug, serde::Serialize, serde::Deserialize)]
144/// Hold a status creation record as stored in the special ELF section of an executable.
145pub struct StatusCreateRecord {
146    // Module ID, or None if it is not specified (in which case it computed at runtime
147    // by status_create based on the filename).
148    pub module_id: Option<u32>,
149    // Name of the file that creates this status.
150    pub filename: String,
151}
152
153impl StatusCreateRecord {
154    /// Compute the Module ID actually created by status_create on device, that is either the
155    /// module_id or comes from the filename.
156    pub fn get_module_id(&self) -> Result<String> {
157        // In order to avoid reimplementing the algorithm, we first create a temporary
158        // status with status_create that we then decode using status_extract.
159        // If the value of MODULE_ID was not overriden in the file, then it is defined as
160        //   extern const uint32_t MODULE_ID;
161        // in status.h, and therefore it is not known at compile time. In this case, on the
162        // actual device, the value of MODULE_ID is 0.
163        const DEFAULT_MODULE_ID: u32 = 0;
164
165        let mod_id = self.module_id.map_or(DEFAULT_MODULE_ID, |mod_id| mod_id);
166        // We need to use a non-ok error code, otherwise the module ID is not stored.
167        let status = status_create_safe(StatusCode::Unknown, mod_id, self.filename.clone(), 0);
168        let status = Status::from_raw_status(status)?;
169        Ok(status.module_id)
170    }
171}
172
173// Fields that are unknown at compile time use special value.
174const UNKNOWN_MODULE_ID: u32 = bindgen::status::ot_status_create_record_magic_OT_SCR_UNKNOWN_MOD_ID;
175
176impl TryFrom<ot_status_create_record_t> for StatusCreateRecord {
177    type Error = anyhow::Error;
178
179    fn try_from(record: ot_status_create_record_t) -> Result<StatusCreateRecord> {
180        // A C string is an array of char so bindgen creates an array of i8, so we need to
181        // convert it to an array of u8. Furthermore, since it is a fixed-size array, it contains
182        // a lot of zeroes at the end which CString does not like and that we need to remove.
183        let filename = c_string_to_string(&record.filename);
184
185        Ok(StatusCreateRecord {
186            module_id: Some(record.module_id).filter(|mod_id| mod_id != &UNKNOWN_MODULE_ID),
187            filename,
188        })
189    }
190}
191
192#[derive(Debug, serde::Serialize, serde::Deserialize)]
193/// Hold a collection of status creation records
194pub struct StatusCreateRecords {
195    pub records: Vec<StatusCreateRecord>,
196}
197
198impl StatusCreateRecords {
199    /// Return the name of the file(s) that match a given module ID.
200    pub fn find_module_id(&self, mod_id: &String) -> Vec<String> {
201        let iter = self
202            .records
203            .iter()
204            .filter(|rec| rec.get_module_id().is_ok_and(|id| id == *mod_id))
205            .map(|rec| rec.filename.clone());
206        std::collections::HashSet::<String>::from_iter(iter)
207            .into_iter()
208            .collect()
209    }
210}
211
212pub fn load_elf(elf_file: &PathBuf) -> Result<StatusCreateRecords> {
213    let file_data = std::fs::read(elf_file)
214        .with_context(|| format!("Could not read ELF file {}.", elf_file.display()))?;
215    let file = object::File::parse(&*file_data)
216        .with_context(|| format!("Could not parse ELF file {}", elf_file.display()))?;
217    // Try to find the .ot.status_create_record section.
218    let section = file
219        .section_by_name(".ot.status_create_record")
220        .ok_or_else(|| {
221            anyhow::anyhow!("ELF file should have a .ot.status_create_record section")
222        })?;
223    let status_create_records = section
224        .data()
225        .context("cannot read .ot.status_create_record section data")?;
226    // Make sure that the section size is a multiple of the record size.
227    const RECORD_SIZE: usize = std::mem::size_of::<ot_status_create_record_t>();
228    if status_create_records.len() % RECORD_SIZE != 0 {
229        bail!(
230            ".ot.status_create_record section size ({}) is not a multiple of the ot_status_create_record_t size ({})",
231            status_create_records.len(),
232            RECORD_SIZE
233        );
234    }
235    // Conversion is unsafe but since the structure is packed and contains only POD,
236    // it really is safe.
237    let records = status_create_records
238        .chunks(RECORD_SIZE)
239        .map(|chunk| ot_status_create_record_t::read_from_bytes(chunk).unwrap())
240        .map(StatusCreateRecord::try_from)
241        .collect::<Result<_>>()?;
242    Ok(StatusCreateRecords { records })
243}
opentitanlib/util/status.rs

opentitanlib/util/
status.rs
