more documentation

Signed-off-by: Maximilien Noal <noal.maximilien@gmail.com>

src/Spice86.Core/Emulator/CPU/Alu.cs

@@ -3,7 +3,16 @@
 using System.Numerics;
 
 /// <summary>
-/// Arithmetic-logic unit
+/// Represents the Arithmetic-Logic Unit (ALU) of the CPU.
+/// <para>
+/// The ALU is a fundamental building block of the CPU, and is responsible for carrying out most of the arithmetic and logical operations, such as addition, subtraction, multiplication, division, and bitwise operations.
+/// </para>
+/// <para>
+/// This class is a generic class that can work with different types of numbers, including both signed and unsigned numbers. The type parameters TUnsigned and TSigned represent the types of the unsigned and signed numbers that this ALU can work with, respectively. The type parameters TUnsignedUpper and TSignedUpper represent the types of the upper half of the results of multiplication operations.
+/// </para>
+/// <para>
+/// The ALU also plays a role in setting the flags of the CPU based on the results of its operations. For example, it can set the zero flag if the result of an operation is zero, or the carry flag if an operation results in a carry or borrow.
+/// </para>
 /// </summary>
 public abstract class Alu<TUnsigned, TSigned, TUnsignedUpper, TSignedUpper>
  where TUnsigned : IUnsignedNumber<TUnsigned>
@@ -93,7 +102,9 @@ public TUnsigned Dec(TUnsigned value1) {
  public abstract TUnsigned Or(TUnsigned value1, TUnsigned value2);
 
  /// <summary>
- /// The XOR operation, also known as the exclusive OR operation, compares two values and returns 1 if they are equal and 0 if they are not equal.
+ /// XOR computes the exclusive OR of the two operands. Each bit of the result
+ /// is 1 if the corresponding bits of the operands are different; each bit is 0
+ /// if the corresponding bits are the same. The answer replaces the first operand.
  /// </summary>
  public abstract TUnsigned Xor(TUnsigned value1, TUnsigned value2);
 

src/Spice86.Core/Emulator/CPU/Alu16.cs

@@ -10,6 +10,10 @@ public class Alu16 : Alu<ushort, short, uint, int> {
 
  private const ushort MsbMask = 0x8000;
 
+ /// <summary>
+ /// Initializes a new instance.
+ /// </summary>
+ /// <param name="state">The CPU registers and flags</param>
  public Alu16(State state) : base(state) {
  }
 

src/Spice86.Core/Emulator/CPU/Stack.cs

@@ -4,7 +4,26 @@
 using Spice86.Shared.Utils;
 
 /// <summary>
-/// Represents the stack of the CPU
+/// Represents the stack of the CPU.
+/// In the x86 architecture, the stack grows downwards, meaning it grows from higher memory addresses to lower memory addresses. <br/>
+/// <para>
+/// Visualization: <br/><br/>
+/// 
+/// Higher Memory Addresses<br/>
+/// +-------------------+<br/>
+/// | |<br/>
+/// | |<br/>
+/// | Stack Data |<br/>
+/// | |<br/>
+/// | |<br/>
+/// +-------------------+ &lt; Stack Pointer (SP)<br/>
+/// | |<br/>
+/// | Free Space |<br/>
+/// | |<br/>
+/// | |<br/>
+/// +-------------------+<br/>
+/// Lower Memory Addresses<br/>
+/// </para>
 /// </summary>
 public class Stack {
  private readonly IMemory _memory;
@@ -47,7 +66,7 @@ public void Poke16(int index, ushort value) {
  /// <summary>
  /// Pops a 16 bit value from the stack
  /// </summary>
- /// <returns>The value retrived from the stack, read from memory</returns>
+ /// <returns>The value retrieved from the stack, therefore read from memory</returns>
  public ushort Pop16() {
  ushort res = _memory.UInt16[_state.StackPhysicalAddress];
  _state.SP = (ushort)(_state.SP + 2);
@@ -57,7 +76,7 @@ public ushort Pop16() {
  /// <summary>
  /// Pushes a 16 bit value on the stack
  /// </summary>
- /// <param name="value">The value pushed onto the stack, stored in memory.</param>
+ /// <param name="value">The value pushed onto the stack, therefore stored in memory.</param>
  public void Push16(ushort value) {
  _state.SP = (ushort)(_state.SP - 2);
  _memory.UInt16[_state.StackPhysicalAddress] = value;

src/Spice86.Core/Emulator/CPU/State.cs

@@ -8,6 +8,29 @@
 
 /// <summary>
 /// Represents the state of the CPU Registers and Flags.
+/// <para>
+/// Visualization of the 32-bit general-purpose registers:
+/// <code>
+/// +-------------------+ <br/>
+/// | EAX | <br/>
+/// +-------------------+ <br/>
+/// | EBX | <br/>
+/// +-------------------+ <br/>
+/// | ECX | <br/>
+/// +-------------------+ <br/>
+/// | EDX | <br/>
+/// +-------------------+ <br/>
+/// | ESI | <br/>
+/// +-------------------+ <br/>
+/// | EDI | <br/>
+/// +-------------------+ <br/>
+/// | ESP | <br/>
+/// +-------------------+ <br/>
+/// | EBP | <br/>
+/// +-------------------+ <br/>
+/// </code>
+/// </para>
+/// Each of these registers can be accessed as a whole (32 bits), or in parts as AX/BX/CX/DX (lower 16 bits), AH/BH/CH/DH (high 8 bits of the 16-bit register), and AL/BL/CL/DL (low 8 bits of the 16-bit register).
 /// </summary>
 public class State : IDebuggableComponent {
  /// <summary>
@@ -163,20 +186,20 @@ public class State : IDebuggableComponent {
  public ushort CS { get => SegmentRegisters.GetRegister16(SegmentRegisters.CsIndex); set => SegmentRegisters.SetRegister16(SegmentRegisters.CsIndex, value); }
 
  /// <summary>
- /// Gets or sets the Data Segment Register value.
+ /// Gets or sets the DS Register value. (DATA SEGMENT)
  /// </summary>
  public ushort DS { get => SegmentRegisters.GetRegister16(SegmentRegisters.DsIndex); set => SegmentRegisters.SetRegister16(SegmentRegisters.DsIndex, value); }
 
  /// <summary>
- /// Gets or sets the Extra segment register value.
+ /// Gets or sets the Extra segment register value. (DATA SEGMENT)
  /// </summary>
  public ushort ES { get => SegmentRegisters.GetRegister16(SegmentRegisters.EsIndex); set => SegmentRegisters.SetRegister16(SegmentRegisters.EsIndex, value); }
  /// <summary>
- /// Gets or sets the FS segment register value.
+ /// Gets or sets the FS segment register value. (DATA SEGMENT)
  /// </summary>
  public ushort FS { get => SegmentRegisters.GetRegister16(SegmentRegisters.FsIndex); set => SegmentRegisters.SetRegister16(SegmentRegisters.FsIndex, value); }
  /// <summary>
- /// Gets or sets the GS segment register value.
+ /// Gets or sets the GS segment register value. (DATA SEGMENT)
  /// </summary>
  public ushort GS { get => SegmentRegisters.GetRegister16(SegmentRegisters.GsIndex); set => SegmentRegisters.SetRegister16(SegmentRegisters.GsIndex, value); }