Re-add docs for MemoryBlockBase, rename End to EndExclusive

see 4a5ece207, 4abe3f793

src/BizHawk.BizInvoke/MemoryBlockBase.cs

@@ -17,15 +17,15 @@ namespace BizHawk.BizInvoke
 				throw new ArgumentOutOfRangeException(nameof(size), size, "cannot create 0-length block");
 			Start = start;
 			Size = WaterboxUtils.AlignUp(size);
-			End = Start + Size;
+			EndExclusive = Start + Size;
-			_pageData = new Protection[GetPage(End - 1) + 1];
+			_pageData = new Protection[GetPage(EndExclusive - 1) + 1];
 		}
 
 		/// <summary>stores last set memory protection value for each page</summary>
 		protected readonly Protection[] _pageData;
 
-		/// <summary>ending address of the memory block; equal to <see cref="Start"/> + <see cref="Size"/></summary>
+		/// <summary>end address of the memory block (not part of the block; class invariant: equal to <see cref="Start"/> + <see cref="Size"/>)</summary>
-		public readonly ulong End;
+		public readonly ulong EndExclusive;
 
 		/// <summary>total size of the memory block</summary>
 		public readonly ulong Size;
@@ -44,7 +44,7 @@ namespace BizHawk.BizInvoke
 		/// <summary>get a page index within the block</summary>
 		protected int GetPage(ulong addr)
 		{
-			if (addr < Start || End <= addr) throw new ArgumentOutOfRangeException();
+			if (addr < Start || EndExclusive <= addr) throw new ArgumentOutOfRangeException(nameof(addr), addr, "invalid address");
 			return (int) ((addr - Start) >> WaterboxUtils.PageShift);
 		}
 
@@ -52,23 +52,23 @@ namespace BizHawk.BizInvoke
 		protected ulong GetStartAddr(int page) => ((ulong) page << WaterboxUtils.PageShift) + Start;
 
 		/// <summary>Get a stream that can be used to read or write from part of the block. Does not check for or change <see cref="Protect"/>!</summary>
-		/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/>) are outside <see cref="AddressRange"/></exception>
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/> - <c>1</c>) are outside [<see cref="Start"/>, <see cref="EndExclusive"/>), the range of the block</exception>
 		public Stream GetStream(ulong start, ulong length, bool writer)
 		{
 			if (start < Start)
-				throw new ArgumentOutOfRangeException(nameof(start));
+				throw new ArgumentOutOfRangeException(nameof(start), start, "invalid address");
-			if (End < start + length)
+			if (EndExclusive < start + length)
-				throw new ArgumentOutOfRangeException(nameof(length));
+				throw new ArgumentOutOfRangeException(nameof(length), length, "requested length implies invalid end address");
 			return new MemoryViewStream(!writer, writer, (long) start, (long) length, this);
 		}
 
 		/// <summary>get a stream that can be used to read or write from part of the block. both reads and writes will be XORed against an earlier recorded snapshot</summary>
-		/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/>) are outside bounds of memory block (<see cref="Start"/> and <see cref="End"/>)</exception>
+		/// <exception cref="ArgumentOutOfRangeException"><paramref name="start"/> or end (= <paramref name="start"/> + <paramref name="length"/> - <c>1</c>) are outside [<see cref="Start"/>, <see cref="EndExclusive"/>), the range of the block</exception>
 		/// <exception cref="InvalidOperationException">no snapshot taken (haven't called <see cref="SaveXorSnapshot"/>)</exception>
 		public Stream GetXorStream(ulong start, ulong length, bool writer)
 		{
-			if (start < Start) throw new ArgumentOutOfRangeException(nameof(start));
+			if (start < Start) throw new ArgumentOutOfRangeException(nameof(start), start, "invalid address");
-			if (End < start + length) throw new ArgumentOutOfRangeException(nameof(length));
+			if (EndExclusive < start + length) throw new ArgumentOutOfRangeException(nameof(length), length, "requested length implies invalid end address");
 			if (_snapshot == null) throw new InvalidOperationException("No snapshot taken!");
 			return new MemoryViewXorStream(!writer, writer, (long) start, (long) length, this, _snapshot, (long) (start - Start));
 		}

src/BizHawk.Emulation.Cores/Waterbox/MapHeap.cs

@@ -178,7 +178,7 @@ namespace BizHawk.Emulation.Cores.Waterbox
 		{
 			// TODO: what is the expected behavior when everything requested for remap is allocated,
 			// but with different protections?
-			if (start < Memory.Start || start + oldSize > Memory.End || oldSize == 0 || newSize == 0)
+			if (start < Memory.Start || start + oldSize > Memory.EndExclusive || oldSize == 0 || newSize == 0)
 				return 0;
 
 			var oldStartPage = GetPage(start);
@@ -243,7 +243,7 @@ namespace BizHawk.Emulation.Cores.Waterbox
 
 		public bool Protect(ulong start, ulong size, MemoryBlockBase.Protection prot)
 		{
-			if (start < Memory.Start || start + size > Memory.End || size == 0)
+			if (start < Memory.Start || start + size > Memory.EndExclusive || size == 0)
 				return false;
 
 			var startPage = GetPage(start);

src/BizHawk.Emulation.Cores/Waterbox/PeRunner.cs

@@ -432,7 +432,7 @@ namespace BizHawk.Emulation.Cores.Waterbox
 
 				var start = heap.Memory.Start;
 				var end = start + heap.Used;
-				var max = heap.Memory.End;
+				var max = heap.Memory.EndExclusive;
 
 				var p = (ulong)_p;