fix undef behavior caused by memory aliasing

[sklose]

to address issues #6

[edef1c]

Note that just asm!("/* {ptr} */", ptr = in(reg) = buf.ptr, options(nostack, preserves_flags)) as a barrier is enough: we don't actually need to do the pointer computation in assembly. Per the asm! spec, rustc isn't allowed to inspect the assembly and rely on those instructions being the ones actually executed, so we can use it to represent the MMU's implicit memcpy. This avoids needing architecture-specific assembly.

[sklose]

Thanks, @edef1c. I appreciate your help with this. It looks like the test is passing now. Could you give it a look over before I merge it and publish a new version?

[edef1c]

The Index/IndexMut code looks good. But I'm not sure we can hide need for fencing from the public API for as_ptr / as_mut_ptr, since users of those methods are likely to do things that require fencing themselves. The best approach I've found is explicitly exposing a pub fn fence(&self) { … } and clearly documenting the need, but we can't really stop people from shooting themselves in the foot.

The API I've adopted for the unsafe raw buffer library in my own codebases looks like this:

	/// Make the buffer contents consistent by (logically) copying memory.
	pub fn fence(&self) {
		unsafe {
			// the MMU does the actual memcpy, so this requires no CPU instructions
			asm!("/* {ptr} */", ptr = in(reg) self.ptr.as_ptr(), options(nostack, preserves_flags));
		}
	}

	/// SAFETY: The buffer segment needs to be in a consistent state, and `len` needs to be in bounds.
	pub unsafe fn get(&self, offset: usize, len: usize) -> NonNull<[u8]> {
		debug_assert!(len <= self.capacity());
		NonNull::slice_from_raw_parts(
			NonNull::new_unchecked(self.ptr.as_ptr().add(offset & self.mask.get())),
			len,
		)
	}

(nb: the SAFETY comment isn't quite right yet, since it's really about dereferenceability rather than about when get is invoked, and in principle merely producing the pointer isn't unsafe in its own right)

The discipline the calling code adopts is to invoke the fence method before making an &mut [u8] available and when committing written data to the buffer. That doesn't really gel with the Index / IndexMut API of magic-buffer, where we don't have a good place to hook the "change of control" of buffer segments, but we can get away with hiding that by fencing on both mutable and immutable indexing, as this PR does; it just doesn't carry over cleanly to the raw API.

I think we're a little stuck here, and the most pragmatic option might be to deprecate the current raw pointer APIs, and introduce new ones with clearer safety properties.