From 7a2fd93d08ce8f384ecb76c9cd2cd93b18d59eb9 Mon Sep 17 00:00:00 2001
From: Thomas Harte <thomas.harte@gmail.com>
Date: Fri, 13 May 2022 10:59:36 -0400
Subject: [PATCH] Document BusHandler interface.

---
 InstructionSets/M68k/Executor.hpp | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/InstructionSets/M68k/Executor.hpp b/InstructionSets/M68k/Executor.hpp
index 11de04b10..3519f2ba1 100644
--- a/InstructionSets/M68k/Executor.hpp
+++ b/InstructionSets/M68k/Executor.hpp
@@ -28,11 +28,32 @@ enum class FunctionCode {
 	InterruptAcknowledge	= 0b111,
 };
 
+/// The Executor is templated on a class that implements bus handling as defined below;
+/// the bus handler is responsible for all reads and writes, and will also receive resets and
+/// interrupt acknowledgements.
+///
+/// The executor will provide 32-bit addresses and act as if it had a 32-bit data bus, even
+/// if interpretting the original 68000 instruction set.
 struct BusHandler {
+	/// Write @c value of type/size @c IntT to @c address with the processor signalling
+	/// a FunctionCode of @c function. @c IntT will be one of @c uint8_t, @c uint16_t
+	/// or @c uint32_t.
 	template <typename IntT> void write(uint32_t address, IntT value, FunctionCode function);
+
+	/// Read and return a value of type/size @c IntT from @c address with the processor signalling
+	/// a FunctionCode of @c function. @c IntT will be one of @c uint8_t, @c uint16_t
+	/// or @c uint32_t.
 	template <typename IntT> IntT read(uint32_t address, FunctionCode function);
+
+	/// React to the processor programmatically strobing its RESET output.
 	void reset();
-	int acknowlege_interrupt(int);
+
+	/// Respond to an interrupt acknowledgement at @c interrupt_level from the processor.
+	/// Should return @c -1 in order to trigger autovectoring, or the appropriate exception vector
+	/// number otherwise.
+	///
+	/// It is undefined behaviour to return a number greater than 255.
+	int acknowlege_interrupt(int interrupt_level);
 };
 
 /// Ties together the decoder, sequencer and performer to provide an executor for 680x0 instruction streams.