Goal: return 512 bytes for one admitted request
Interpret an admitted descriptor chain and return 512 bytes from the EL2 memory disk. notify is the entry, read_sector checks request meaning, and the DATA_COPY loop in main.rs transfers bytes. CHAIN_VALID establishes structural admission; this lesson then reads type and sector to determine the operation.
The disk is a fixed 2048-byte array containing four sectors. No host file is opened and no user disk is accessed. A predictable per-sector pattern makes the chosen location testable through first and last bytes and a whole-buffer hash. The goal is to explain which bytes moved where, rather than observing a generic success label.
Connect request fields to descriptor direction
The sixteen-byte header contains a 32-bit type, 32-bit reserved field, and 64-bit sector. The subset accepts type zero reads with reserved zero. Sector is measured in 512-byte units, not guest addresses or byte offsets. Starting at byte three for sector three would return incorrect content even if the destination address passed bounds checks.
The device reads the header and writes data and status. After structural admission, the operation also confirms that read data has WRITE permission. Being able to read a field does not authorize every operation it describes. Interpret the request type and descriptor direction together. Treat the three address-like quantities separately when sketching a request: sector selects bytes inside the disk array, data.addr selects a destination in shared guest RAM, and the descriptor head selects an entry in the descriptor table. Changing one does not automatically change the others. This separation is particularly useful when the requested sector is correct but the result appears at an unexpected memory location.
Use a fixed pattern to identify the transferred sector
disk fills each byte from sector-number times seventeen plus byte position, converted to u8. Sector zero begins with zero and ends with 255. Sector three begins with fifty-one and ends with fifty. The latter reflects eight-bit conversion, not an interrupted transfer. Compute the same pattern on the host and compare it with the requested sector.
The guest prefills its destination with 0xcc. Success replaces it; rejected operations preserve it. A single first-byte check cannot detect a truncated copy, so compare the recorded whole-buffer hash as well. Short visible checks and a complete-buffer comparison serve different purposes.
Normal and final-sector reads: status and used.len
blockNormal reads sector zero and blockBoundary reads sector three. Both write 512 data bytes and status zero. used.len is 513: device-written data plus the one-byte status. It excludes the sixteen-byte input header. Header length, data length, and the length reported in used are distinct quantities.
After copying, EL2 publishes the head identifier and length and prepares completion notification. Follow BLOCK_REQUEST, DATA_COPY, USED_PUBLISH, and GUEST_RECLAIM. A copy alone does not establish guest reclaim. The next lesson connects transfer with notification and recovery of ownership.
| Case | Request | Data result | Status / used.len |
|---|---|---|---|
| blockNormal | type 0, sector 0 | First 0, last 255 | 0 / 513 |
| blockBoundary | type 0, sector 3 | First 51, last 50 | 0 / 513 |
| blockRange | type 0, sector 4 | Destination remains 0xcc | 1 / 1 |
| blockWrite | type 1, sector 0 | Destination remains 0xcc | 1 / 1 |
Failures: complete range and write rejection with a result
read_sector compares sector with capacity four before multiplying by 512. Even u64::MAX is rejected before a large multiplication. Sector four returns IOERR one. Type one writes also return IOERR in this read-only implementation; a nonzero reserved field is rejected by the same pure function.
These requests still have valid chains and safe status destinations. EL2 writes status one, publishes used.len one, and sends an IRQ without copying data, preserving 0xcc. A malformed chain requiring device reset is a different failure. A used-buffer notification announces a request result; after distinguishing it from configuration change, inspect request status to determine read success.
Runnable Rust: check capacity and unchanged error buffers
This host program uses the read_sector conditions and disk pattern to test transfer results. It covers the first and last sectors, range rejection, write rejection, and the largest sector value. Checking every output byte after rejection detects implementations that return the correct status while corrupting data.
The returned pair models status and used.len arithmetic. This short program does not actually publish a used ring or inject an IRQ. The distributed QEMU project additionally checks ordered shared-memory publication and guest reclaim. Keep host output and machine UART separate and explain the boundary established by each.
fn read_sector(kind: u32, sector: u64, reserved: u32) -> Result<usize, u8> {
if kind != 0 || reserved != 0 || sector >= 4 { return Err(1); }
Ok((sector * 512) as usize)
}
fn read(kind: u32, sector: u64, out: &mut [u8;512]) -> (u8,u32) {
match read_sector(kind,sector,0) {
Ok(offset) => {
for (i,b) in out.iter_mut().enumerate() {
let absolute=offset+i;
*b=((absolute/512)*17+absolute%512) as u8;
}
(0,513)
},
Err(status) => (status,1),
}
}
fn main() {
let mut out=[0xcc;512];
assert_eq!(read(0,0,&mut out),(0,513));
assert_eq!((out[0],out[511]),(0,255));
assert_eq!(read(0,3,&mut out),(0,513));
assert_eq!((out[0],out[511]),(51,50));
out.fill(0xcc);
assert_eq!(read(0,4,&mut out),(1,1));
assert!(out.iter().all(|b|*b==0xcc));
assert_eq!(read(1,0,&mut out),(1,1));
assert!(out.iter().all(|b|*b==0xcc));
assert_eq!(read_sector(0,u64::MAX,0),Err(1));
println!("sector0=ok sector3=ok range=IOERR write=IOERR");
}Verify buffers rather than trusting a success label
When results differ, inspect BLOCK_REQUEST type and sector, then CHAIN_VALID data address and length. Check whether DATA_COPY occurred and compare the complete buffer hash. Copying 512 bytes from the wrong sector differs from copying only part of the correct sector, so investigate request meaning and transfer bounds separately. For a controlled comparison, preserve the same valid descriptor chain and change only sector from three to four. The structure should still pass, while the operation changes from a 512-byte transfer to an IOERR result. Then restore sector zero and change only the type to one. These paired inputs establish which validation layer rejected the request, and prevent a descriptor mutation from obscuring the capacity or read-only check you intended to test.
blockRange and blockWrite continue from BLOCK_REJECT into USED_PUBLISH and guest reclaim. Check status one, used.len one, and preserved data together. An error message alone would miss accidental writes or missing completion. Match the selected case ELF hash and command before comparing evidence from different builds.
Exercise: do not confuse sectors with bytes
For sectors zero, three, four, and u64::MAX, predict admission, array offset, status, used.len, and buffer contents. Change type to one and locate enforcement of the read-only contract. Explain why moving bounds checks after multiplication creates an integer-boundary concern.
For an extension, create a pattern with matching first and last bytes but different interior content. Show why visible endpoints are insufficient and compare whole-buffer hashes. Submit input, expected outcomes, observations, disagreements, and build identity. Even a small reproducible memory disk benefits from separate request, transfer, and result checks.