More/documentation (#548)

* Updated README.md

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

* Audio: more documentation

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

* more documentation, removed spaces after end of lines

* tests: removed spaces after end of lines

* CPU namespace: mre documentation

* ArgbPalette: inheritdoc

* more documentation

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

* more documentation

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

* more documentation

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

* Removed obsolete binary/xml [Serializable] attribute from exceptions

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

* more documentation

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

* MouseInt33Handler: formatted XML documentation

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

* GdbServer: completed XML documentation

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

* Updated SDK in CONTRIBUTING.md

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

* more documentation, removed unsed argument

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

* more documentation

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

* more documentation

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

* more documentation

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

* more documentation

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

* INT21H: Set AX to 0x0100 only on success

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

* more documentation

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

* more documentation

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

* more documentation

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

* more documentation

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

* YM7128B internal until use

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

* more documentation

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

* VGA Registers: more documentation

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

* ModRM: more accurate documentation

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

* SB Mixer: more accurate documentation

* Timer: remove obsolete doc line about VGA refresh hack

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

* README.md: updated Screen refresh section

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

* More documentation

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

---------

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

CONTRIBUTING.md

@@ -24,7 +24,7 @@ Thank you for wanting to contribute. Here are some guidelines.
 
 ### Required SDK
 
-- [.NET](https://dotnet.microsoft.com/en-us/download/dotnet/7.0)
+- [.NET](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
 
 ### What this project should do
 

README.md

@@ -261,7 +261,7 @@ The emulated Timer hardware of the PC (Intel 8259) supports measuring time from
 - The number of instructions the emulated CPU executed. This is the behaviour that is activated with parameter **--InstructionsPerSecond** and is forced when in GDB mode so that you can debug with peace of mind without the timer triggering.
 
 ### Screen refresh
-Screen is refreshed 30 times per second and each time a VGA retrace wait is detected (see IVideoCard::TickRetrace).
+Screen is refreshed 30 times per second and each time a VGA retrace wait is detected (see Renderer.cs).
 
 ### Emulator features
 CPU:
@@ -311,7 +311,7 @@ Compatibility list available [here](COMPATIBILITY.md).
 
 ### How to build on your machine
 
-- Install the .NET 7 SDK (once)
+- Install the .NET 8 SDK (once)
 - clone the repo
 - run this where Spice86.sln is located:
 

src/Bufdio.Spice86/Bindings/PortAudio/Enums/PaSampleFormat.cs

@@ -1,4 +1,4 @@
-namespace Bufdio.Spice86.Bindings.PortAudio.Enums; 
+namespace Bufdio.Spice86.Bindings.PortAudio.Enums;
 
 internal enum PaSampleFormat : long {
     paFloat32 = 0x00000001,

src/Bufdio.Spice86/Bindings/PortAudio/NativeMethods.cs

@@ -24,7 +24,7 @@ public static int PortAudioOpenStream(IntPtr stream, IntPtr inputParameters, Int
         outputParameters, sampleRate, framesPerBuffer, streamFlags, streamCallback, userData);
 
     public static int PortAudioWriteStream(IntPtr stream, IntPtr buffer, long frames) => _bindings.WriteStream(stream, buffer, frames);
-    
+
     public static int PortAudioCloseStream(IntPtr stream) => _bindings.CloseStream(stream);
 
     public static IntPtr PortAudioGetErrorText(int code) => _bindings.GetErrorText(code);
@@ -47,9 +47,9 @@ private interface INativeBindings {
         int AbortStream(IntPtr stream);
         int CloseStream(IntPtr stream);
     }
-    
+
     private static readonly INativeBindings _bindings;
-    
+
     static NativeMethods() {
         if (OperatingSystem.IsWindows()) {
             _bindings = new Windows();
@@ -73,7 +73,7 @@ public static string GetPortAudioLibName() {
             throw new PlatformNotSupportedException();
         }
     }
-    
+
     /// <summary>
     /// A callback function that is used by a stream to provide or consume audio data in real time.
     /// </summary>
@@ -166,7 +166,7 @@ public int OpenStream(IntPtr stream, IntPtr inputParameters, IntPtr outputParame
 
         public int CloseStream(IntPtr stream) => Pa_CloseStream(stream);
     }
-    
+
     [SupportedOSPlatform("Linux")]
     private partial class Linux : INativeBindings {
         [LibraryImport("libportaudio.so.2")]
@@ -212,7 +212,7 @@ private static partial int Pa_OpenStream(
 
         [LibraryImport("libportaudio.so.2")]
         private static partial int Pa_CloseStream(IntPtr stream);
-        
+
         public int Initialize() => Pa_Initialize();
 
         public int Terminate() => Pa_Terminate();
@@ -240,7 +240,7 @@ public int OpenStream(IntPtr stream, IntPtr inputParameters, IntPtr outputParame
 
         public int CloseStream(IntPtr stream) => Pa_CloseStream(stream);
     }
-    
+
     [SupportedOSPlatform("OSX")]
     private partial class MacOS : INativeBindings {
         [LibraryImport("libportaudio.2.dylib")]
@@ -286,7 +286,7 @@ private static partial int Pa_OpenStream(
 
         [LibraryImport("libportaudio.2.dylib")]
         private static partial int Pa_CloseStream(IntPtr stream);
-        
+
         public int Initialize() => Pa_Initialize();
 
         public int Terminate() => Pa_Terminate();

src/Bufdio.Spice86/Engines/AudioEngineOptions.cs

@@ -9,7 +9,7 @@ public readonly record struct AudioEngineOptions
     /// <summary>
     /// Initializes <see cref="AudioEngineOptions"/>.
     /// </summary>
-    /// <param name="defaultAudioDevice">Desired output device, see: <see cref="PortAudioLib.OutputDevices"/>.</param>
+    /// <param name="defaultOutputDevice">Desired output device, see: <see cref="PortAudioLib.OutputDevices"/>.</param>
     /// <param name="channels">Desired audio channels, or fallback to maximum channels.</param>
     /// <param name="sampleRate">Desired output sample rate.</param>
     /// <param name="latency">Desired output latency.</param>
@@ -25,7 +25,7 @@ public AudioEngineOptions(AudioDevice defaultOutputDevice, int channels, int sam
     /// Initializes <see cref="AudioEngineOptions"/> by using default output device
     /// and its default high output latency.
     /// </summary>
-    /// <param name="defaultAudioDevice">Desired output device, see: <see cref="PortAudioLib.OutputDevices"/>.</param>
+    /// <param name="defaultOutputDevice">Desired output device, see: <see cref="PortAudioLib.OutputDevices"/>.</param>
     /// <param name="channels">Desired audio channels, or fallback to maximum channels.</param>
     /// <param name="sampleRate">Desired output sample rate.</param>
     public AudioEngineOptions(AudioDevice defaultOutputDevice, int channels, int sampleRate)
@@ -38,7 +38,7 @@ public AudioEngineOptions(AudioDevice defaultOutputDevice, int channels, int sam
 
     /// <summary>
     /// Initializes <see cref="AudioEngineOptions"/> by using default output device.
-    /// Sample rate will be set to 44100, channels to 2 (or max) and latency to default high. 
+    /// Sample rate will be set to 44100, channels to 2 (or max) and latency to default high.
     /// </summary>
     public AudioEngineOptions(AudioDevice defaultOutputDevice)
     {

src/Bufdio.Spice86/PortAudioLib.cs

@@ -16,7 +16,7 @@
 /// </summary>
 public sealed class PortAudioLib : IDisposable {
     private bool _disposed;
-    
+
     internal static class Constants {
         /// <summary>
         /// 32-bit floats
@@ -29,7 +29,7 @@ internal static class Constants {
     private readonly List<AudioDevice> _outputDevices = new();
 
     /// <summary>
-    /// Gets whether or not the PortAudio library is already initialized.
+    /// Gets whether the PortAudio library is already initialized.
     /// </summary>
     public bool IsPortAudioInitialized { get; private set; }
 
@@ -71,11 +71,11 @@ public PortAudioLib(string? portAudioPath = default) {
         NativeMethods.PortAudioInitialize();
 
         int deviceCount = NativeMethods.PortAudioGetDeviceCount();
-        
+
         Ensure.That<BufdioException>(deviceCount > 0, "No output devices are available.");
 
         int defaultDevice = NativeMethods.PortAudioGetDefaultOutputDevice();
-        
+
         _defaultOutputDevice = defaultDevice.PaGetPaDeviceInfo().PaToAudioDevice(defaultDevice);
         _outputDevices = new List<AudioDevice>();
 
@@ -94,7 +94,8 @@ public PortAudioLib(string? portAudioPath = default) {
     /// </summary>
     /// <returns>A string containing the filename of the system-provided PortAudio library</returns>
     public static string GetPortAudioLibName() => NativeMethods.GetPortAudioLibName();
-
+
+    /// <inheritdoc/>
     public void Dispose() {
         // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
         Dispose(disposing: true);

src/Spice86.Core/Backend/Audio/AudioFormat.cs

@@ -13,6 +13,7 @@ public sealed record AudioFormat(int SampleRate, int Channels, SampleFormat Samp
         SampleFormat.IeeeFloat32 => 4,
         _ => 0
     };
+
     /// <summary>
     /// Gets the number of bytes per frame of the format.
     /// </summary>

src/Spice86.Core/Backend/Audio/AudioPlayer.cs

@@ -9,7 +9,7 @@ namespace Spice86.Core.Backend.Audio;
 public abstract class AudioPlayer : IDisposable
 {
     private readonly InternalBufferWriter _writer;
-    
+
     /// <summary>
     /// Whether the native resources were disposed.
     /// </summary>
@@ -49,7 +49,6 @@ protected AudioPlayer(AudioFormat format) {
     public int WriteData(Span<short> data) => _writer.WriteData(data);
 
 
-
     /// <summary>
     /// Writes the full buffer of audio data to the player/>.
     /// </summary>
@@ -68,7 +67,7 @@ public void WriteFullBuffer(Span<float> buffer) {
             }
         }
     }
-    
+
     /// <summary>
     /// Writes the full buffer of audio data to the player/>.
     /// </summary>
@@ -87,7 +86,7 @@ public void WriteFullBuffer(Span<short> buffer) {
             }
         }
     }
-    
+
 
     /// <summary>
     /// Writes the full buffer of audio data to the player/>.
@@ -129,7 +128,7 @@ public void Dispose() {
     protected virtual void Dispose(bool disposing) {
         _disposed = true;
     }
-    
+
     /// <summary>
     /// Writes the audio data to the rendering backend
     /// </summary>

src/Spice86.Core/Backend/Audio/DummyAudio/DummyAudioPlayer.cs

@@ -1,12 +1,21 @@
-namespace Spice86.Core.Backend.Audio.DummyAudio; 
+namespace Spice86.Core.Backend.Audio.DummyAudio;
 
 /// <summary>
 /// Dummy audio player with no backend
 /// </summary>
 sealed class DummyAudioPlayer : AudioPlayer {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DummyAudioPlayer"/> class.
+    /// </summary>
+    /// <param name="format">The audio playback format.</param>
     public DummyAudioPlayer(AudioFormat format) : base(format) {
     }
 
+    /// <summary>
+    /// Fakes writing data to the audio device
+    /// </summary>
+    /// <param name="data">The input audio data</param>
+    /// <returns>The data paramater length</returns>
     protected override int WriteDataInternal(Span<byte> data) {
         // Tell we wrote it all, it's all fake anyway
         return data.Length;

src/Spice86.Core/Backend/Audio/IirFilters/ComplexPair.cs

@@ -24,7 +24,7 @@ namespace Spice86.Core.Backend.Audio.IirFilters;
 using System.Numerics;
 
 /**
- * 
+ *
  * A complex pair
  *
  */

src/Spice86.Core/Backend/Audio/PortAudio/PortAudioPlayer.cs

@@ -10,6 +10,13 @@ public sealed class PortAudioPlayer : AudioPlayer {
     private readonly PortAudioEngine _engine;
     private readonly PortAudioLib _portAudioLib;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="PortAudioPlayer"/> class.
+    /// </summary>
+    /// <param name="portAudioLib">The class that represents the native PortAudio library</param>
+    /// <param name="framesPerBuffer">The number of frames in the audio buffer</param>
+    /// <param name="format">The audio playback format</param>
+    /// <param name="suggestedLatency">Desired output latency</param>
     public PortAudioPlayer(PortAudioLib portAudioLib, int framesPerBuffer, AudioFormat format, double? suggestedLatency = null) : base(format) {
         _portAudioLib = portAudioLib;
         AudioEngineOptions options = new AudioEngineOptions(_portAudioLib.DefaultOutputDevice, 2, format.SampleRate);
@@ -19,6 +26,7 @@ public PortAudioPlayer(PortAudioLib portAudioLib, int framesPerBuffer, AudioForm
         _engine = new PortAudioEngine(framesPerBuffer, options);
     }
 
+    /// <inheritdoc/>
     protected override void Dispose(bool disposing) {
         if (!_disposed) {
             if (disposing) {
@@ -29,6 +37,7 @@ protected override void Dispose(bool disposing) {
         }
     }
 
+    /// <inheritdoc/>
     protected override int WriteDataInternal(Span<byte> data) {
         Span<float> samples = data.Cast<byte, float>();
         _engine.Send(samples);

src/Spice86.Core/Backend/Audio/PortAudio/PortAudioPlayerFactory.cs

@@ -32,7 +32,7 @@ private PortAudioLib LoadPortAudioLibrary() {
             throw new PlatformNotSupportedException();
         }
     }
-    
+
     /// <summary>
     /// Creates an instance of PortAudioPlayer eventually loading the libportaudio native library if needed.
     /// </summary>

src/Spice86.Core/CLI/Configuration.cs

@@ -12,7 +12,7 @@ public class Configuration {
     /// </summary>
     [Option(nameof(A20Gate), Default = false, Required = false, HelpText = "Whether the 20th address line is silenced. Used for legacy 8086 programs.")]
     public bool A20Gate { get; init; }
-    
+
     /// <summary> Path to C drive, default is exe parent. </summary>
     [Option('c', nameof(CDrive), Default = null, Required = false, HelpText = "Path to C drive, default is exe parent")]
     public string? CDrive { get; set; }
@@ -77,7 +77,7 @@ public class Configuration {
     /// </summary>
     [Option('v', nameof(InitializeDOS), Default = null, Required = false, HelpText = "Install DOS interrupt vectors or not")]
     public bool? InitializeDOS { get; set; }
-    
+
     /// <summary>
     /// Only for <see cref="Emulator.Devices.Timer.Timer"/>
     /// </summary>
@@ -131,7 +131,7 @@ public class Configuration {
     /// </summary>
     [Option(nameof(Ems), Default = false, Required = false, HelpText = "Enable EMS")]
     public bool Ems { get; init; }
-    
+
     /// <summary>
     /// Specify the type of mouse to use.
     /// </summary>