agesafetch 2.0.2

A tool for obtaining your firmware's embedded AGESA version on Linux.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

// SPDX-FileCopyrightText: Benedikt Vollmerhaus <benedikt@vollmerhaus.org>
// SPDX-License-Identifier: MIT
//! Optional Python bindings for the AGESA search and `agesafetch` CLI.
use std::env;
use std::fmt::{self, Display, Formatter};

use linux_memutils::agesa::{AgesaVersion, SearchError};
use pyo3::create_exception;
use pyo3::exceptions::{PyOSError, PySystemExit};
use pyo3::prelude::*;

use crate::run_cli;

create_exception!(
    agesafetch,
    DevMemOpenError,
    PyOSError,
    "Raised when the `/dev/mem` file could not be opened."
);
create_exception!(
    agesafetch,
    IomemReadError,
    PyOSError,
    "Raised when the `/dev/iomem` file could not be read."
);
create_exception!(
    agesafetch,
    ByteReadError,
    PyOSError,
    "Raised when a byte in `/dev/mem` could not be read."
);

struct PySearchError(SearchError);

impl From<PySearchError> for PyErr {
    fn from(error: PySearchError) -> Self {
        match error.0 {
            SearchError::DevMemUnopenable(source) => {
                DevMemOpenError::new_err(format!("Could not open `/dev/mem`: {source}"))
            }
            SearchError::IomemUnreadable(source) => {
                IomemReadError::new_err(format!("Could not read `/proc/iomem`: {source}"))
            }
            SearchError::ByteUnreadable(source) => {
                ByteReadError::new_err(format!("Could not read byte in `/dev/mem`: {source}"))
            }
        }
    }
}

impl From<SearchError> for PySearchError {
    fn from(error: SearchError) -> Self {
        Self(error)
    }
}

/// An AGESA version found in physical memory.
#[pyclass(name = "AGESAVersion", module = "agesafetch", get_all, str)]
struct PyAgesaVersion {
    /// The complete version string (may include trailing whitespace).
    version_string: String,
    /// The absolute start address of this version in physical memory.
    absolute_address: usize,
}

#[pymethods]
impl PyAgesaVersion {
    #[new]
    fn new(version_string: String, absolute_address: usize) -> Self {
        PyAgesaVersion {
            version_string,
            absolute_address,
        }
    }

    fn __repr__(&self) -> String {
        format!(
            "AGESAVersion('{}', absolute_address={})",
            self.version_string, self.absolute_address
        )
    }
}

impl Display for PyAgesaVersion {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} (at {:#018x})",
            self.version_string, self.absolute_address
        )
    }
}

impl From<AgesaVersion> for PyAgesaVersion {
    fn from(found_version: AgesaVersion) -> Self {
        Self {
            version_string: found_version.version_string,
            absolute_address: found_version.absolute_address,
        }
    }
}

/// Search for the `AGESA`_ version in physical memory.
///
/// .. note::
///    This requires *elevated privileges* in order to obtain a memory
///    map from `/proc/iomem` and read physical memory from `/dev/mem`.
///
/// .. _`AGESA`: https://en.wikipedia.org/wiki/AGESA
///
/// :return: An :class:`AGESAVersion` instance or ``None``
#[allow(clippy::doc_markdown)]
#[pyfunction]
fn find_agesa_version() -> Result<Option<PyAgesaVersion>, PySearchError> {
    let maybe_found_version = linux_memutils::agesa::find_agesa_version()?;
    Ok(maybe_found_version.map(PyAgesaVersion::from))
}

/// An entrypoint providing the `agesafetch` CLI to the Python package.
///
/// For details, see:
///   * <https://github.com/PyO3/maturin/issues/368>
///   * <https://www.maturin.rs/bindings#both-binary-and-library>
#[pyfunction]
fn run_py() -> PyResult<()> {
    let args = env::args_os().skip(1).collect();
    let exit_code = run_cli(args);
    Err(PySystemExit::new_err(exit_code as u8))
}

#[pymodule]
fn agesafetch(py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<PyAgesaVersion>()?;
    m.add_function(wrap_pyfunction!(find_agesa_version, m)?)?;
    m.add_wrapped(wrap_pyfunction!(run_py))?;

    m.add("DevMemOpenError", py.get_type::<DevMemOpenError>())?;
    m.add("IomemReadError", py.get_type::<IomemReadError>())?;
    m.add("ByteReadError", py.get_type::<ByteReadError>())?;

    Ok(())
}