aml: lay groundwork for field reads + support system memory + IO reads

Author: IsaacWoods

aml/src/lib.rs

@@ -10,16 +10,19 @@ pub mod pci_routing;
 pub mod resource;
 
 use alloc::{
+    boxed::Box,
+    collections::btree_map::BTreeMap,
     string::{String, ToString},
     sync::Arc,
     vec,
     vec::Vec,
 };
 use bit_field::BitField;
 use core::mem;
+use log::{info, trace};
 use namespace::{AmlName, Namespace, NamespaceLevelKind};
 use object::{FieldFlags, FieldUnit, FieldUnitKind, MethodFlags, Object, ObjectType, ReferenceKind};
-use op_region::{OpRegion, RegionSpace};
+use op_region::{OpRegion, RegionHandler, RegionSpace};
 use spinning_top::Spinlock;
 
 pub struct Interpreter<H>
@@ -29,6 +32,8 @@ where
     handler: H,
     pub namespace: Spinlock<Namespace>,
     context_stack: Spinlock<Vec<MethodContext>>,
+    dsdt_revision: u8,
+    region_handlers: Spinlock<BTreeMap<RegionSpace, Box<dyn RegionHandler>>>,
 }
 
 unsafe impl<H> Send for Interpreter<H> where H: Handler + Send {}
@@ -41,11 +46,15 @@ impl<H> Interpreter<H>
 where
     H: Handler,
 {
-    pub fn new(handler: H) -> Interpreter<H> {
+    pub fn new(handler: H, dsdt_revision: u8) -> Interpreter<H> {
+        info!("Initializing AML interpreter v{}", env!("CARGO_PKG_VERSION"));
         Interpreter {
             handler,
             namespace: Spinlock::new(Namespace::new()),
             context_stack: Spinlock::new(Vec::new()),
+            dsdt_revision,
+            ops_interpreted: AtomicUsize::new(0),
+            region_handlers: Spinlock::new(BTreeMap::new()),
         }
     }
 
@@ -73,6 +82,15 @@ where
         }
     }
 
+    pub fn install_region_handler<RH>(&self, space: RegionSpace, handler: RH)
+    where
+        RH: RegionHandler + 'static,
+    {
+        let mut handlers = self.region_handlers.lock();
+        assert!(handlers.get(&space).is_none(), "Tried to install handler for same space twice!");
+        handlers.insert(space, Box::new(handler));
+    }
+
     fn do_execute_method(&self, mut context: MethodContext) -> Result<Arc<Object>, AmlError> {
         /*
          * TODO
@@ -1342,6 +1360,10 @@ where
                         let value = u64::from_le_bytes(buffer);
                         *target = value;
                     }
+                    Object::FieldUnit(field) => {
+                        // TODO: not sure if we should convert buffers to integers if needed here?
+                        *target = self.do_field_read(field)?.as_integer()?;
+                    }
                     _ => panic!("Store to integer from unsupported object: {:?}", object),
                 },
                 Object::BufferField { .. } => match object.gain_mut() {
@@ -1366,6 +1388,131 @@ where
         }
         Ok(())
     }
+
+    /// Do a read from a field by performing one or more well-formed accesses to the underlying
+    /// operation regions, and then shifting and masking the resulting value as appropriate. Will
+    /// return either an `Integer` or `Buffer` as appropriate, guided by the size of the field
+    /// and expected integer size (as per the DSDT revision).
+    fn do_field_read(&self, field: &FieldUnit) -> Result<Arc<Object>, AmlError> {
+        let needs_buffer = if self.dsdt_revision >= 2 { field.bit_length > 64 } else { field.bit_length > 32 };
+        let access_width_bits = field.flags.access_type_bytes()? * 8;
+
+        trace!("AML field read. Field = {:?}", field);
+
+        // TODO: if the field needs to be locked, acquire/release a global mutex?
+
+        enum Output {
+            Integer([u8; 8]),
+            Buffer(Vec<u8>),
+        }
+        let mut output = if needs_buffer {
+            Output::Buffer(vec![0; field.bit_length.next_multiple_of(8)])
+        } else {
+            Output::Integer([0; 8])
+        };
+        let output_bytes = match &mut output {
+            Output::Buffer(bytes) => bytes.as_mut_slice(),
+            Output::Integer(value) => value,
+        };
+
+        match field.kind {
+            FieldUnitKind::Normal { ref region } => {
+                let Object::OpRegion(ref region) = **region else { panic!() };
+
+                /*
+                 * TODO: it might be worth having a fast path here for reads that don't do weird
+                 * unaligned accesses, which I'm guessing might be relatively common on real
+                 * hardware? Eg. single native read + mask
+                 */
+
+                /*
+                 * Break the field read into native reads that respect the region's access width.
+                 * Copy each potentially-unaligned part into the destination's bit range.
+                 */
+                let native_accesses_needed = (field.bit_length + (field.bit_index % access_width_bits))
+                    .next_multiple_of(access_width_bits)
+                    / access_width_bits;
+                let mut read_so_far = 0;
+                for i in 0..native_accesses_needed {
+                    let aligned_offset =
+                        object::align_down(field.bit_index + i * access_width_bits, access_width_bits);
+                    let raw = self.do_native_region_read(region, aligned_offset / 8, access_width_bits / 8)?;
+                    let src_index = if i == 0 { field.bit_index % access_width_bits } else { 0 };
+                    let remaining_length = field.bit_length - read_so_far;
+                    let length = if i == 0 {
+                        usize::min(remaining_length, access_width_bits - (field.bit_index % access_width_bits))
+                    } else {
+                        usize::min(remaining_length, access_width_bits)
+                    };
+
+                    trace!(
+                        "Extracting bits {}..{} from native read to bits {}..{}",
+                        src_index,
+                        src_index + length,
+                        read_so_far,
+                        read_so_far + length,
+                    );
+                    object::copy_bits(&raw.to_le_bytes(), src_index, output_bytes, read_so_far, length);
+
+                    read_so_far += length;
+                }
+
+                match output {
+                    Output::Buffer(bytes) => Ok(Arc::new(Object::Buffer(bytes))),
+                    Output::Integer(value) => Ok(Arc::new(Object::Integer(u64::from_le_bytes(value)))),
+                }
+            }
+            FieldUnitKind::Bank { ref region, ref bank, bank_value } => todo!(),
+            FieldUnitKind::Index { ref index, ref data } => todo!(),
+        }
+    }
+
+    /// Performs an actual read from an operation region. `offset` and `length` must respect the
+    /// access requirements of the field being read, and are supplied in **bytes**. This may call
+    /// AML methods if required, and may invoke user-supplied handlers.
+    fn do_native_region_read(&self, region: &OpRegion, offset: usize, length: usize) -> Result<u64, AmlError> {
+        trace!("Native field read. Region = {:?}, offset = {:#x}, length={:#x}", region, offset, length);
+
+        match region.space {
+            RegionSpace::SystemMemory => Ok({
+                let address = region.base as usize + offset;
+                match length {
+                    1 => self.handler.read_u8(address) as u64,
+                    2 => self.handler.read_u16(address) as u64,
+                    4 => self.handler.read_u32(address) as u64,
+                    8 => self.handler.read_u64(address) as u64,
+                    _ => panic!(),
+                }
+            }),
+            RegionSpace::SystemIO => Ok({
+                let address = region.base as u16 + offset as u16;
+                match length {
+                    1 => self.handler.read_io_u8(address) as u64,
+                    2 => self.handler.read_io_u16(address) as u64,
+                    4 => self.handler.read_io_u32(address) as u64,
+                    _ => panic!(),
+                }
+            }),
+            RegionSpace::PciConfig => todo!(),
+
+            RegionSpace::EmbeddedControl
+            | RegionSpace::SmBus
+            | RegionSpace::SystemCmos
+            | RegionSpace::PciBarTarget
+            | RegionSpace::Ipmi
+            | RegionSpace::GeneralPurposeIo
+            | RegionSpace::GenericSerialBus
+            | RegionSpace::Pcc
+            | RegionSpace::Oem(_) => {
+                if let Some(handler) = self.region_handlers.lock().get(&region.space) {
+                    todo!("Utilise handler");
+                } else {
+                    // TODO: panic or normal error here??
+                    panic!("Unhandled region space that needs handler!");
+                }
+            }
+        }
+    }
 }
 
 /// A `MethodContext` represents a piece of running AML code - either a real method, or the
@@ -1904,6 +2051,7 @@ enum Opcode {
 pub enum AmlError {
     RunOutOfStream,
     IllegalOpcode(u16),
+    InvalidFieldFlags,
 
     InvalidName(Option<AmlName>),
 
@@ -2025,7 +2173,7 @@ mod tests {
 
     #[test]
     fn add_op() {
-        let interpreter = Interpreter::new(TestHandler);
+        let interpreter = Interpreter::new(TestHandler, 2);
         // AddOp 0x0e 0x06 => Local2
         interpreter.load_table(&[0x72, 0x0b, 0x0e, 0x00, 0x0a, 0x06, 0x62]).unwrap();
         // AddOp 0x0e (AddOp 0x01 0x03 => Local1) => Local1

aml/src/object.rs

@@ -157,6 +157,64 @@ pub enum FieldUnitKind {
 #[derive(Clone, Copy, Debug)]
 pub struct FieldFlags(pub u8);
 
+#[derive(Clone, Copy, Debug)]
+pub enum FieldAccessType {
+    Any,
+    Byte,
+    Word,
+    DWord,
+    QWord,
+    Buffer,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub enum FieldUpdateRule {
+    Preserve,
+    WriteAsOnes,
+    WriteAsZeros,
+}
+
+impl FieldFlags {
+    pub fn access_type(&self) -> Result<FieldAccessType, AmlError> {
+        match self.0.get_bits(0..4) {
+            0 => Ok(FieldAccessType::Any),
+            1 => Ok(FieldAccessType::Byte),
+            2 => Ok(FieldAccessType::Word),
+            3 => Ok(FieldAccessType::DWord),
+            4 => Ok(FieldAccessType::QWord),
+            5 => Ok(FieldAccessType::Buffer),
+            _ => Err(AmlError::InvalidFieldFlags),
+        }
+    }
+
+    pub fn access_type_bytes(&self) -> Result<usize, AmlError> {
+        match self.access_type()? {
+            FieldAccessType::Any => {
+                // TODO: given more info about the field, we might be able to make a more efficient
+                // read, since all are valid in this case
+                Ok(1)
+            }
+            FieldAccessType::Byte | FieldAccessType::Buffer => Ok(1),
+            FieldAccessType::Word => Ok(2),
+            FieldAccessType::DWord => Ok(4),
+            FieldAccessType::QWord => Ok(8),
+        }
+    }
+
+    pub fn lock_rule(&self) -> bool {
+        self.0.get_bit(4)
+    }
+
+    pub fn update_rule(&self) -> FieldUpdateRule {
+        match self.0.get_bits(5..7) {
+            0 => FieldUpdateRule::Preserve,
+            1 => FieldUpdateRule::WriteAsOnes,
+            2 => FieldUpdateRule::WriteAsZeros,
+            _ => unreachable!(),
+        }
+    }
+}
+
 #[derive(Clone, Copy, Debug)]
 pub struct MethodFlags(pub u8);
 
@@ -206,7 +264,13 @@ pub enum ObjectType {
 /// Copy an arbitrary bit range of `src` to an arbitrary bit range of `dst`. This is used for
 /// buffer fields. Data is zero-extended if `src` does not cover `length` bits, matching the
 /// expected behaviour for buffer fields.
-fn copy_bits(src: &[u8], mut src_index: usize, dst: &mut [u8], mut dst_index: usize, mut length: usize) {
+pub(crate) fn copy_bits(
+    src: &[u8],
+    mut src_index: usize,
+    dst: &mut [u8],
+    mut dst_index: usize,
+    mut length: usize,
+) {
     while length > 0 {
         let src_shift = src_index & 7;
         let mut src_bits = src.get(src_index / 8).unwrap_or(&0x00) >> src_shift;
@@ -239,6 +303,26 @@ fn copy_bits(src: &[u8], mut src_index: usize, dst: &mut [u8], mut dst_index: us
     }
 }
 
+#[inline]
+pub(crate) fn align_down(value: usize, align: usize) -> usize {
+    assert!(align == 0 || align.is_power_of_two());
+
+    if align == 0 {
+        value
+    } else {
+        /*
+         * Alignment must be a power of two.
+         *
+         * E.g.
+         * align       =   0b00001000
+         * align-1     =   0b00000111
+         * !(align-1)  =   0b11111000
+         * ^^^ Masks the value to the one below it with the correct align
+         */
+        value & !(align - 1)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

aml/src/op_region.rs

@@ -1,3 +1,5 @@
+use crate::AmlError;
+
 #[derive(Debug)]
 pub struct OpRegion {
     pub space: RegionSpace,
@@ -6,7 +8,12 @@ pub struct OpRegion {
     // parent_device
 }
 
-#[derive(Clone, Copy, PartialEq, Debug)]
+pub trait RegionHandler {
+    fn read(&self, region: &OpRegion) -> Result<(), AmlError>;
+    fn write(&self, region: &OpRegion) -> Result<(), AmlError>;
+}
+
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 pub enum RegionSpace {
     SystemMemory,
     SystemIO,

tests/fields.asl

@@ -1,4 +1,14 @@
 DefinitionBlock("fields.aml", "DSDT", 1, "RSACPI", "BUFFLD", 1) {
+    OperationRegion(MEM, SystemMemory, 0x40000, 0x1000)
+    Field(MEM, WordAcc, NoLock, Preserve) {
+        , 7,
+        A, 15,
+        , 8,
+        B, 1,
+        , 1,
+        C, 35
+    }
+
     OperationRegion(GIO0, SystemIO, 0x125, 0x100)
 
     Field(GIO0, ByteAcc, NoLock, Preserve) {
@@ -31,4 +41,13 @@ DefinitionBlock("fields.aml", "DSDT", 1, "RSACPI", "BUFFLD", 1) {
         , 7,
         FET4, 1
     }
+
+    Name(RESA, 0)
+    Name(RESB, 0)
+    Name(RESC, 0)
+    Method(MAIN, 0, NotSerialized) {
+        RESA = A
+        RESB = B
+        RESC = C
+    }
 }

tools/aml_tester/Cargo.toml

@@ -5,7 +5,7 @@ authors = ["Isaac Woods"]
 edition = "2018"
 
 [dependencies]
+aml = { path = "../../aml" }
 clap = "4"
 termion = "1"
 log = "0.4"
-aml = { path = "../../aml" }