|
| 1 | +//! pkglength encoding and decoding. |
| 2 | +
|
| 3 | +use alloc::{vec, vec::Vec}; |
| 4 | +use bit_field::BitField; |
| 5 | +use core::fmt::{Display, Formatter}; |
| 6 | + |
| 7 | +/// Indicates an attempt to encode a pkglength that is too long (>= 2 ^ 28). |
| 8 | +#[derive(Clone, Debug)] |
| 9 | +pub struct PkglengthTooLongError {} |
| 10 | + |
| 11 | +impl Display for PkglengthTooLongError { |
| 12 | + fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result { |
| 13 | + write!(f, "pkglength too long") |
| 14 | + } |
| 15 | +} |
| 16 | + |
| 17 | +impl core::error::Error for PkglengthTooLongError {} |
| 18 | + |
| 19 | +/// Encode a pkglength field. |
| 20 | +/// |
| 21 | +/// This is a variable length field used to define the length of other variable-length items in |
| 22 | +/// ACPI - see [the spec](https://uefi.org/specs/ACPI/6.6/20_AML_Specification.html#package-length-encoding) |
| 23 | +/// for details. |
| 24 | +/// |
| 25 | +/// This is less straightforward than it could be, because pkglength needs to include the length of |
| 26 | +/// the pkglength field that gets output. This function adds that extra length. |
| 27 | +/// |
| 28 | +/// Returns an error if length >= 2^28. Otherwise, returns the encoded pkglength in a vec, LSB-first. |
| 29 | +pub fn encode(data_length: u32) -> Result<Vec<u8>, PkglengthTooLongError> { |
| 30 | + let extra_length = match data_length { |
| 31 | + 0..63 => 1, |
| 32 | + 63..0xFFE => 2, |
| 33 | + 0xFFE..0xFFFFD => 3, |
| 34 | + _ => 4, |
| 35 | + }; |
| 36 | + let result = encode_raw(data_length + extra_length); |
| 37 | + result.inspect(|result| { |
| 38 | + assert_eq!(result.len(), extra_length as usize); |
| 39 | + }) |
| 40 | +} |
| 41 | + |
| 42 | +/// Encode a pkglength field, without taking into account the extra length of the pkglength field. |
| 43 | +/// |
| 44 | +/// Most callers should use [`encode`] instead. |
| 45 | +/// |
| 46 | +/// Returns an error if length >= 2^28. Otherwise, returns the encoded pkglength in a vec, LSB-first. |
| 47 | +pub fn encode_raw(mut length: u32) -> Result<Vec<u8>, PkglengthTooLongError> { |
| 48 | + if length & 0xF0000000 != 0 { |
| 49 | + // Must be less than 2 ^ 28 |
| 50 | + return Err(PkglengthTooLongError {}); |
| 51 | + } |
| 52 | + |
| 53 | + if length < 64 { |
| 54 | + Ok(vec![length as u8]) |
| 55 | + } else { |
| 56 | + let mut result = vec![(length & 0xF) as u8]; |
| 57 | + length >>= 4; |
| 58 | + |
| 59 | + while length != 0 { |
| 60 | + result.push((length & 0xff) as u8); |
| 61 | + length >>= 8; |
| 62 | + } |
| 63 | + |
| 64 | + let num_bytes = result.len() as u8 - 1; |
| 65 | + result[0] |= num_bytes << 6; |
| 66 | + |
| 67 | + Ok(result) |
| 68 | + } |
| 69 | +} |
| 70 | + |
| 71 | +/// Decode a pkglength field from a stream |
| 72 | +/// |
| 73 | +/// If the stream returns an error, that error is returned. Otherwise, the decoded length is |
| 74 | +/// returned. |
| 75 | +/// |
| 76 | +/// `stream_next` must return the next byte in the stream when called (or an error, which is passed |
| 77 | +/// through) |
| 78 | +pub fn decode_stream<T>(mut stream_next: impl FnMut() -> Result<u8, T>) -> Result<usize, T> { |
| 79 | + let lead_byte = stream_next()?; |
| 80 | + let byte_count = lead_byte.get_bits(6..8); |
| 81 | + assert!(byte_count < 4); |
| 82 | + |
| 83 | + if byte_count == 0 { |
| 84 | + Ok(lead_byte.get_bits(0..6) as usize) |
| 85 | + } else { |
| 86 | + let mut length = lead_byte.get_bits(0..4) as usize; |
| 87 | + for i in 0..byte_count { |
| 88 | + length |= (stream_next()? as usize) << (4 + i * 8); |
| 89 | + } |
| 90 | + Ok(length) |
| 91 | + } |
| 92 | +} |
| 93 | + |
| 94 | +#[cfg(test)] |
| 95 | +mod tests { |
| 96 | + use super::*; |
| 97 | + |
| 98 | + #[test] |
| 99 | + fn basic_round_trip() { |
| 100 | + let length: u32 = 0x12345; |
| 101 | + let encoded = encode_raw(length).unwrap(); |
| 102 | + let mut i = encoded.iter(); |
| 103 | + let decoded = decode_stream(|| i.next().copied().ok_or(())).unwrap(); |
| 104 | + assert_eq!(decoded, length as usize); |
| 105 | + } |
| 106 | + |
| 107 | + #[test] |
| 108 | + fn less_than_64() { |
| 109 | + let length: u32 = 0x12; |
| 110 | + let encoded = encode_raw(length).unwrap(); |
| 111 | + assert_eq!(encoded, vec![0x12]); |
| 112 | + |
| 113 | + let mut i = encoded.iter(); |
| 114 | + let decoded = decode_stream(|| i.next().copied().ok_or(())).unwrap(); |
| 115 | + assert_eq!(decoded, 0x12); |
| 116 | + } |
| 117 | + |
| 118 | + #[test] |
| 119 | + fn encodes_zero() { |
| 120 | + let encoded = encode_raw(0).unwrap(); |
| 121 | + assert_eq!(encoded, vec![0]); |
| 122 | + } |
| 123 | + |
| 124 | + fn round_trip_length(length: u32) -> usize { |
| 125 | + let encoded = encode(length).unwrap(); |
| 126 | + let mut i = encoded.iter(); |
| 127 | + decode_stream(|| i.next().copied().ok_or(())).unwrap() |
| 128 | + } |
| 129 | + |
| 130 | + #[test] |
| 131 | + fn extra_length_correct() { |
| 132 | + assert_eq!(round_trip_length(62), 63); // An increase of a single byte |
| 133 | + // 63 bytes of payload requires two bytes of pkglength |
| 134 | + assert_eq!(round_trip_length(63), 65); |
| 135 | + |
| 136 | + // A random test: |
| 137 | + assert_eq!(round_trip_length(0x12345), 0x12348); |
| 138 | + |
| 139 | + // Simply check that there's no errors around the boundaries - this tells us the maths to |
| 140 | + // calculate `extra_length` is correct. |
| 141 | + for i in 0xFF9..0x1004 { |
| 142 | + encode(i).unwrap(); |
| 143 | + } |
| 144 | + for i in 0xFFFF9..0x100004 { |
| 145 | + encode(i).unwrap(); |
| 146 | + } |
| 147 | + } |
| 148 | +} |
0 commit comments