feature: proper dos process managment

- Added `_lastReturnCode` and `_lastTerminationMode` to track the last executed child process's return code and termination mode.
- Introduced `CreateNewPsp` and `CreateChildPsp` methods for managing Program Segment Prefixes (PSPs).
- Corrected method name for consistency and added `GetReturnCode` action.
- Enhanced `TerminateAndStayResident` and `QuitWithExitCode` methods for better process termination and memory management.
- Updated `LoadAndOrExecute` method to log execution details and indicate success or failure.
- Refactored parameter preparation methods and introduced a new `DosTerminationMode` enum.

Author: maximilien-noal

src/Spice86.Core/Emulator/InterruptHandlers/Dos/DosInt21Handler.cs

@@ -38,13 +38,13 @@ public BiosLoader(IMemory memory, State state, ILoggerService loggerService) : b
     }
 
     /// <summary>
-    /// Loads the specified BIOS <paramref name="file"/> into memory and sets the entry point to the BIOS address.
+    /// Loads the specified BIOS <paramref name="filePath"/> into memory and sets the entry point to the BIOS address.
     /// </summary>
-    /// <param name="file">The path to the BIOS file to load.</param>
+    /// <param name="filePath">The absolute path to the BIOS file to load.</param>
     /// <param name="arguments">Ignored for BIOS files.</param>
     /// <returns>The loaded BIOS file as a byte array.</returns>
-    public override byte[] LoadFile(string file, string? arguments) {
-        byte[] bios = ReadFile(file);
+    public override byte[] LoadFile(string filePath, string? arguments) {
+        byte[] bios = ReadFile(filePath);
         uint physicalStartAddress = MemoryUtils.ToPhysicalAddress(CodeSegment, 0);
         _memory.LoadData(physicalStartAddress, bios);
         SetEntryPoint(CodeSegment, CodeOffset);

src/Spice86.Core/Emulator/LoadableFile/Bios/BiosLoader.cs

@@ -5,8 +5,6 @@
 using Spice86.Shared.Interfaces;
 using Spice86.Shared.Utils;
 
-using System.IO;
-
 /// <summary>
 /// Base class for loading executable files in the VM like exe, bios, ...
 /// </summary>
@@ -43,10 +41,10 @@ protected ExecutableFileLoader(IMemory memory, State state, ILoggerService logge
     /// <summary>
     /// Loads an executable file and returns its bytes.
     /// </summary>
-    /// <param name="file">The path of the file to load.</param>
+    /// <param name="filePath">The absolute path to the executable file.</param>
     /// <param name="arguments">Optional arguments to pass to the loaded file.</param>
     /// <returns>The bytes of the loaded file.</returns>
-    public abstract byte[] LoadFile(string file, string? arguments);
+    public abstract byte[] LoadFile(string filePath, string? arguments);
 
     /// <summary>
     /// Reads the contents of a file and returns its bytes.

src/Spice86.Core/Emulator/LoadableFile/ExecutableFileLoader.cs

@@ -172,7 +172,7 @@ public Dos(Configuration configuration, IMemory memory,
         DosInt20Handler = new DosInt20Handler(_memory, functionHandlerProvider, stack, state, _loggerService);
         DosInt21Handler = new DosInt21Handler(_memory, pspTracker, functionHandlerProvider, stack, state,
             keyboardInt16Handler, CountryInfo, dosStringDecoder,
-            MemoryManager, FileManager, DosDriveManager, clock, _loggerService);
+            MemoryManager, ProcessManager, FileManager, DosDriveManager, clock, _loggerService);
         DosInt2FHandler = new DosInt2fHandler(_memory,
             functionHandlerProvider, stack, state, _loggerService, xms);
         DosInt25Handler = new DosDiskInt25Handler(_memory, DosDriveManager, functionHandlerProvider, stack, state, _loggerService);

src/Spice86.Core/Emulator/OperatingSystem/Dos.cs

@@ -0,0 +1,19 @@
+namespace Spice86.Core.Emulator.OperatingSystem.Enums;
+
+/// <summary>
+/// Drives the INT21H Load and/or exec function behavior
+/// </summary>
+public enum DosExecuteMode : byte {
+    /// <summary>
+    /// Load and execute the program
+    /// </summary>
+    LoadAndExecute = 0,
+    /// <summary>
+    /// Load, create the program header, but do not run execution
+    /// </summary>
+    LoadButDoNotRun = 1,
+    /// <summary>
+    /// Load overlay. No header created.
+    /// </summary>
+    LoadOverlay = 3
+}

src/Spice86.Core/Emulator/OperatingSystem/DosProcessManager.cs

@@ -0,0 +1,29 @@
+namespace Spice86.Core.Emulator.OperatingSystem.Enums;
+
+/// <summary>
+/// Represents the different ways a DOS process can terminate.
+/// Used by INT 21h function 4Dh (Get Return Code of Child Process).
+/// </summary>
+public enum DosTerminationMode : byte {
+    /// <summary>
+    /// Child terminated normally (that is, exited via INT 20h or INT 21h Function 00h or Function 4Ch).
+    /// </summary>
+    Normal = 0x00,
+
+    /// <summary>
+    /// Child was terminated by user's entry of a Ctrl-C.
+    /// </summary>
+    ControlC = 0x01,
+
+    /// <summary>
+    /// Child was terminated by critical error handler (either the user responded with A to the
+    /// Abort, Retry, Ignore prompt from the system's default INT 24h handler, or a custom
+    /// INT 24h handler returned to MS-DOS with action code = 02h in register AL).
+    /// </summary>
+    CriticalError = 0x02,
+
+    /// <summary>
+    /// Child terminated normally and stayed resident (that is, exited via INT 21h Function 31h or INT 27h).
+    /// </summary>
+    TerminateAndStayResident = 0x03
+}

src/Spice86.Core/Emulator/OperatingSystem/Enums/DosExecuteMode.cs

@@ -0,0 +1,112 @@
+namespace Spice86.Core.Emulator.OperatingSystem.Structures;
+
+using Spice86.Core.Emulator.Memory.ReaderWriter;
+using Spice86.Core.Emulator.ReverseEngineer.DataStructure;
+using Spice86.Shared.Emulator.Memory;
+
+/// <summary>
+/// Represents a DOS Execute Parameter Block (ExecParamRec) used for loading and executing programs.
+/// This structure is used in INT 21h function 0x4B.
+/// </summary>
+public abstract class DosExecuteParameterBlock : MemoryBasedDataStructure {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DosExecuteParameterBlock"/> class.
+    /// </summary>
+    /// <param name="byteReaderWriter">Where data is read and written.</param>
+    /// <param name="baseAddress">The base address of the data structure.</param>
+    protected DosExecuteParameterBlock(IByteReaderWriter byteReaderWriter,
+        uint baseAddress) : base(byteReaderWriter, baseAddress) {
+    }
+}
+
+/// <summary>
+/// Parameter block for loading and executing a program (AL=0) or just loading (AL=1).
+/// </summary>
+public class DosLoadOrLoadAndExecuteParameterBlock : DosExecuteParameterBlock {
+    public DosLoadOrLoadAndExecuteParameterBlock(IByteReaderWriter byteReaderWriter,
+        uint baseAddress) : base(byteReaderWriter, baseAddress) {
+    }
+
+    /// <summary>
+    /// Gets or sets the segment of environment for child process.
+    /// 0000h means use a copy of the current environment.
+    /// </summary>
+    public ushort EnvironmentSegment {
+        get => UInt16[0x0];
+        set => UInt16[0x0] = value;
+    }
+
+    /// <summary>
+    /// Gets or sets the address of command line text to place at PSP:0080.
+    /// </summary>
+    public uint CommandTailAddress {
+        get => UInt32[0x2];
+        set => UInt32[0x2] = value;
+    }
+
+    /// <summary>
+    /// Gets or sets the address of the first FCB to be placed at PSP:005C.
+    /// </summary>
+    public uint FirstFcbAddress {
+        get => UInt32[0x6];
+        set => UInt32[0x6] = value;
+    }
+
+    /// <summary>
+    /// Gets or sets the address of the second FCB to be placed at PSP:006C.
+    /// </summary>
+    public uint SecondFcbAddress {
+        get => UInt32[0xA];
+        set => UInt32[0xA] = value;
+    }
+}
+
+/// <summary>
+/// Parameter block for loading a program but not executing it (AL=1).
+/// </summary>
+public sealed class DosLoadProgramParameterBlock : DosLoadOrLoadAndExecuteParameterBlock {
+    public DosLoadProgramParameterBlock(IByteReaderWriter byteReaderWriter,
+        uint baseAddress) : base(byteReaderWriter, baseAddress) {
+    }
+
+    /// <summary>
+    /// Gets or sets the initial CS:IP of the loaded program. This is a return value.
+    /// </summary>
+    public SegmentedAddress EntryPointAddress {
+        get => SegmentedAddress32[0xE];
+        set => SegmentedAddress32[0xE] = value;
+    }
+
+    /// <summary>
+    /// Gets or sets the initial SS:SP of the loaded program. This is a return value.
+    /// </summary>
+    public SegmentedAddress StackAddress {
+        get => SegmentedAddress32[0x12];
+        set => SegmentedAddress32[0x12] = value;
+    }
+}
+
+/// <summary>
+/// Parameter block for loading an overlay (AL=3).
+/// </summary>
+public sealed class DosOverlayParameterBlock : DosExecuteParameterBlock {
+    public DosOverlayParameterBlock(IByteReaderWriter byteReaderWriter,
+        uint baseAddress) : base(byteReaderWriter, baseAddress) {
+    }
+
+    /// <summary>
+    /// Gets or sets the segment address where the file will be loaded.
+    /// </summary>
+    public ushort OverlayLoadSegment {
+        get => UInt16[0x0];
+        set => UInt16[0x0] = value;
+    }
+
+    /// <summary>
+    /// Gets or sets the relocation factor to be applied to the image.
+    /// </summary>
+    public ushort OverlayRelocationFactor {
+        get => UInt16[0x2];
+        set => UInt16[0x2] = value;
+    }
+}

src/Spice86.Core/Emulator/OperatingSystem/Enums/DosTerminationMode.cs

@@ -1,4 +1,5 @@
-namespace Spice86.Core.Emulator.OperatingSystem.Structures;
+
+namespace Spice86.Core.Emulator.OperatingSystem.Structures;
 
 using Spice86.Core.Emulator.Memory.ReaderWriter;
 using Spice86.Core.Emulator.ReverseEngineer.DataStructure;
@@ -88,9 +89,7 @@ public DosProgramSegmentPrefix(IByteReaderWriter byteReaderWriter, uint baseAddr
 
     public UInt8Array FirstFileControlBlock => GetUInt8Array(0x5C, 16);
 
-    public UInt8Array SecondFileControlBlock => GetUInt8Array(0x6C, 16);
+    public UInt8Array SecondFileControlBlock => GetUInt8Array(0x6C, 20);
 
-    public UInt8Array Unused3 => GetUInt8Array(0x7C, 4);
-
-    public DosCommandTail DosCommandTail => new (ByteReaderWriter, BaseAddress + 0x80);
-}
+    public DosCommandTail DosCommandTail => new(ByteReaderWriter, BaseAddress + 0x80);
+}