From 40418ad25d6ed1cefe8b4e6093aa8ad156440740 Mon Sep 17 00:00:00 2001 From: adelikat Date: Wed, 14 Dec 2016 09:11:07 -0600 Subject: [PATCH] More documentaiton for IEmulatorServices, related classes/interfaces, and base implementations --- .../Base Implementations/BasicServiceProvider.cs | 8 ++++++++ .../CallbackBasedTraceBuffer.cs | 14 ++++++++++++-- .../Base Implementations/InputCallbackSystem.cs | 5 +++++ .../Base Implementations/MemoryCallbackSystem.cs | 5 +++++ .../Base Implementations/MemoryDomain.cs | 14 +++++--------- .../Base Implementations/MemoryDomainImpls.cs | 3 --- .../Base Implementations/MemoryDomainList.cs | 9 ++++++--- .../Base Implementations/NullController.cs | 5 +++++ .../Base Implementations/NullSound.cs | 5 +++++ .../Base Implementations/NullVideo.cs | 6 +++++- .../Base Implementations/TraceBuffer.cs | 9 +++++---- BizHawk.Emulation.Common/CoreComms.cs | 2 ++ .../Interfaces/IAsyncSoundProvider.cs | 6 +++++- .../Interfaces/ICoreFileProvider.cs | 3 +++ .../Interfaces/IEmulatorServiceProvider.cs | 12 +++++++++++- .../Interfaces/IInputCallbackSystem.cs | 7 ++++++- .../Interfaces/IMemoryCallbackSystem.cs | 10 ++++++++++ .../Interfaces/Services/IInputPollable.cs | 3 ++- .../Interfaces/Services/ILinkable.cs | 2 +- .../Interfaces/Services/IMemoryDomains.cs | 10 ++++++---- .../Interfaces/Services/ISaveRam.cs | 5 ++--- BizHawk.Emulation.Common/ServiceInjector.cs | 4 +--- 22 files changed, 110 insertions(+), 37 deletions(-) diff --git a/BizHawk.Emulation.Common/Base Implementations/BasicServiceProvider.cs b/BizHawk.Emulation.Common/Base Implementations/BasicServiceProvider.cs index 959108a328..1d71b17849 100644 --- a/BizHawk.Emulation.Common/Base Implementations/BasicServiceProvider.cs +++ b/BizHawk.Emulation.Common/Base Implementations/BasicServiceProvider.cs @@ -4,6 +4,14 @@ using System.Linq; namespace BizHawk.Emulation.Common { + /// + /// A generic implementation of IEmulatorService provider that provides + /// this functionality to any core. + /// The provider will scan an IEmulator and register all IEmulatorServices + /// that the core object itself implements. In addition it provides + /// a Register() method to allow the core to pass in any additional services + /// + /// public class BasicServiceProvider : IEmulatorServiceProvider { private Dictionary Services = new Dictionary(); diff --git a/BizHawk.Emulation.Common/Base Implementations/CallbackBasedTraceBuffer.cs b/BizHawk.Emulation.Common/Base Implementations/CallbackBasedTraceBuffer.cs index 157bfdd29b..6f1feb5f5c 100644 --- a/BizHawk.Emulation.Common/Base Implementations/CallbackBasedTraceBuffer.cs +++ b/BizHawk.Emulation.Common/Base Implementations/CallbackBasedTraceBuffer.cs @@ -1,11 +1,21 @@ using System; using System.Collections.Generic; -using System.Linq; using BizHawk.Emulation.Common.IEmulatorExtensions; namespace BizHawk.Emulation.Common -{ +{ + /// + /// An implementation of ITraceable that is implementation using only methods + /// from IDebuggable, IMemoryDomains, and IDisassemblable + /// Useful for ported cores that have these hooks but no trace logging hook, + /// This allows for a traceable implementation without the need for additional API + /// Note that this technique will always be significantly slower than a direct implementation + /// + /// + /// + /// + /// /// public abstract class CallbackBasedTraceBuffer : ITraceable { public CallbackBasedTraceBuffer(IDebuggable debuggableCore, IMemoryDomains memoryDomains, IDisassemblable disassembler) diff --git a/BizHawk.Emulation.Common/Base Implementations/InputCallbackSystem.cs b/BizHawk.Emulation.Common/Base Implementations/InputCallbackSystem.cs index 7f09e4d496..bcb114990d 100644 --- a/BizHawk.Emulation.Common/Base Implementations/InputCallbackSystem.cs +++ b/BizHawk.Emulation.Common/Base Implementations/InputCallbackSystem.cs @@ -4,6 +4,11 @@ using System.Linq; namespace BizHawk.Emulation.Common { + /// + /// This is a generic implementation of IInputCallbackSystem that can be used + /// by any core + /// + /// public class InputCallbackSystem : List, IInputCallbackSystem { public void Call() diff --git a/BizHawk.Emulation.Common/Base Implementations/MemoryCallbackSystem.cs b/BizHawk.Emulation.Common/Base Implementations/MemoryCallbackSystem.cs index 3f9efbdd12..ec728e14b8 100644 --- a/BizHawk.Emulation.Common/Base Implementations/MemoryCallbackSystem.cs +++ b/BizHawk.Emulation.Common/Base Implementations/MemoryCallbackSystem.cs @@ -4,6 +4,11 @@ using System.Collections.Generic; namespace BizHawk.Emulation.Common { + /// + /// This is a generic implementation of IMemoryCallbackSystem + /// that can be used by used by any core + /// + /// public class MemoryCallbackSystem : IMemoryCallbackSystem { public MemoryCallbackSystem() diff --git a/BizHawk.Emulation.Common/Base Implementations/MemoryDomain.cs b/BizHawk.Emulation.Common/Base Implementations/MemoryDomain.cs index f0798f477e..ca279e389b 100644 --- a/BizHawk.Emulation.Common/Base Implementations/MemoryDomain.cs +++ b/BizHawk.Emulation.Common/Base Implementations/MemoryDomain.cs @@ -1,10 +1,12 @@ using System; -using System.Linq; -using System.Collections.Generic; -using System.Collections.ObjectModel; namespace BizHawk.Emulation.Common { + /// + /// A memory region and the functionality to read/write from it + /// as required by the IMemoryDomains service. + /// + /// public abstract class MemoryDomain { public enum Endian { Big, Little, Unknown } @@ -26,11 +28,7 @@ namespace BizHawk.Emulation.Common /// /// creates a memorydomain that references a managed byte array /// - /// - /// - /// /// if false, writes will be ignored - /// [Obsolete] public static MemoryDomain FromByteArray(string name, Endian endian, byte[] data, bool writable = true, int wordSize = 1) { @@ -42,7 +40,6 @@ namespace BizHawk.Emulation.Common /// /// must remain valid as long as the MemoryDomain exists! /// if false, writes will be ignored - /// [Obsolete] public unsafe static MemoryDomain FromIntPtr(string name, long size, Endian endian, IntPtr data, bool writable = true, int wordSize = 1) { @@ -54,7 +51,6 @@ namespace BizHawk.Emulation.Common /// /// must remain valid as long as the MemoryDomain exists! /// if false, writes will be ignored - /// [Obsolete] public unsafe static MemoryDomain FromIntPtrSwap16(string name, long size, Endian endian, IntPtr data, bool writable = true) { diff --git a/BizHawk.Emulation.Common/Base Implementations/MemoryDomainImpls.cs b/BizHawk.Emulation.Common/Base Implementations/MemoryDomainImpls.cs index 6d672d139f..a9a80e4f02 100644 --- a/BizHawk.Emulation.Common/Base Implementations/MemoryDomainImpls.cs +++ b/BizHawk.Emulation.Common/Base Implementations/MemoryDomainImpls.cs @@ -1,7 +1,4 @@ using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; namespace BizHawk.Emulation.Common { diff --git a/BizHawk.Emulation.Common/Base Implementations/MemoryDomainList.cs b/BizHawk.Emulation.Common/Base Implementations/MemoryDomainList.cs index 973adb76b7..af096f5443 100644 --- a/BizHawk.Emulation.Common/Base Implementations/MemoryDomainList.cs +++ b/BizHawk.Emulation.Common/Base Implementations/MemoryDomainList.cs @@ -1,11 +1,14 @@ using System; using System.Collections.Generic; -using System.Linq; -using System.Text; using System.Collections.ObjectModel; +using System.Linq; namespace BizHawk.Emulation.Common -{ +{ + /// + /// A generic implementation of IMemoryDomain that can be used by any core + /// + /// public class MemoryDomainList : ReadOnlyCollection, IMemoryDomains { private MemoryDomain _mainMemory; diff --git a/BizHawk.Emulation.Common/Base Implementations/NullController.cs b/BizHawk.Emulation.Common/Base Implementations/NullController.cs index 126d75c060..ae3d4269bf 100644 --- a/BizHawk.Emulation.Common/Base Implementations/NullController.cs +++ b/BizHawk.Emulation.Common/Base Implementations/NullController.cs @@ -1,5 +1,10 @@ namespace BizHawk.Emulation.Common { + /// + /// A empty implementation of IController that represents the lack of + /// a controller interface + /// + /// public class NullController : IController { public ControllerDefinition Definition { get { return null; } } diff --git a/BizHawk.Emulation.Common/Base Implementations/NullSound.cs b/BizHawk.Emulation.Common/Base Implementations/NullSound.cs index 8d34d1bb04..dc0be7c7b0 100644 --- a/BizHawk.Emulation.Common/Base Implementations/NullSound.cs +++ b/BizHawk.Emulation.Common/Base Implementations/NullSound.cs @@ -2,6 +2,11 @@ namespace BizHawk.Emulation.Common { + /// + /// A default and empty implementation of ISoundProvider + /// that simply outputs "silence" + /// + /// public class NullSound : ISoundProvider { private readonly long _spfNumerator; diff --git a/BizHawk.Emulation.Common/Base Implementations/NullVideo.cs b/BizHawk.Emulation.Common/Base Implementations/NullVideo.cs index cc5d3c8fc3..2ebcdc4862 100644 --- a/BizHawk.Emulation.Common/Base Implementations/NullVideo.cs +++ b/BizHawk.Emulation.Common/Base Implementations/NullVideo.cs @@ -1,6 +1,10 @@ namespace BizHawk.Emulation.Common { - // A default IVideoProvider implementation that simply returns a black screen + /// + /// A default IVideoProvider that simply returns + /// a black screen at an arbitruary size + /// + /// public class NullVideo : IVideoProvider { public int[] GetVideoBuffer() diff --git a/BizHawk.Emulation.Common/Base Implementations/TraceBuffer.cs b/BizHawk.Emulation.Common/Base Implementations/TraceBuffer.cs index 9f6902abb4..a57488358d 100644 --- a/BizHawk.Emulation.Common/Base Implementations/TraceBuffer.cs +++ b/BizHawk.Emulation.Common/Base Implementations/TraceBuffer.cs @@ -1,10 +1,11 @@ -using System.Collections.Generic; -using System.Linq; - -//garbage +//garbage namespace BizHawk.Emulation.Common { + /// + /// A generic implementation of ITraceable that can be used by any core + /// + /// public class TraceBuffer : ITraceable { public TraceBuffer() diff --git a/BizHawk.Emulation.Common/CoreComms.cs b/BizHawk.Emulation.Common/CoreComms.cs index 6f337f00b7..a1aa0677cb 100644 --- a/BizHawk.Emulation.Common/CoreComms.cs +++ b/BizHawk.Emulation.Common/CoreComms.cs @@ -4,9 +4,11 @@ namespace BizHawk.Emulation.Common { /// /// This object fascilitates communications between client and core + /// and is used by the IEmulator interface /// The primary use is to provide a client => core communication, such as providing client-side callbacks for a core to use /// Any communications that can be described as purely a Core -> Client system, should be provided as an IEmulatorService instead /// + /// public class CoreComm { public CoreComm(Action showMessage, Action NotifyMessage) diff --git a/BizHawk.Emulation.Common/Interfaces/IAsyncSoundProvider.cs b/BizHawk.Emulation.Common/Interfaces/IAsyncSoundProvider.cs index 1ebd908646..e06e30afb6 100644 --- a/BizHawk.Emulation.Common/Interfaces/IAsyncSoundProvider.cs +++ b/BizHawk.Emulation.Common/Interfaces/IAsyncSoundProvider.cs @@ -1,7 +1,11 @@ using System; namespace BizHawk.Emulation.Common -{ +{ + /// + /// This interface is for legacy sound implementations in some older cores + /// This needs to go away, but is provided here, for now + /// public interface IAsyncSoundProvider { void GetSamples(short[] samples); diff --git a/BizHawk.Emulation.Common/Interfaces/ICoreFileProvider.cs b/BizHawk.Emulation.Common/Interfaces/ICoreFileProvider.cs index a25fbfa927..527a576c84 100644 --- a/BizHawk.Emulation.Common/Interfaces/ICoreFileProvider.cs +++ b/BizHawk.Emulation.Common/Interfaces/ICoreFileProvider.cs @@ -2,6 +2,9 @@ namespace BizHawk.Emulation.Common { + /// + /// Defines the means by which firmware, bios and other necessary files are provided to a core that needs them + /// public interface ICoreFileProvider { /// diff --git a/BizHawk.Emulation.Common/Interfaces/IEmulatorServiceProvider.cs b/BizHawk.Emulation.Common/Interfaces/IEmulatorServiceProvider.cs index 1ef4300d67..3a16d85bd8 100644 --- a/BizHawk.Emulation.Common/Interfaces/IEmulatorServiceProvider.cs +++ b/BizHawk.Emulation.Common/Interfaces/IEmulatorServiceProvider.cs @@ -3,6 +3,16 @@ using System.Collections.Generic; namespace BizHawk.Emulation.Common { + /// + /// This interface defines the mechanism by which clients can retrive IEmulatorServices + /// from an IEmulator implementation + /// An implementation should collect all available IEmulatorService instances. + /// This interface defines only the client interaction. This interface does not specify the means + /// by which a service provider will be populated with available services. However, an implementation + /// by design must provide this mechanism + /// + /// + /// public interface IEmulatorServiceProvider { /// @@ -28,7 +38,7 @@ namespace BizHawk.Emulation.Common object GetService(Type t); /// - /// A list of all cuurently registered services available to be called + /// A list of all currently registered services available to be retrieved /// IEnumerable AvailableServices { get; } } diff --git a/BizHawk.Emulation.Common/Interfaces/IInputCallbackSystem.cs b/BizHawk.Emulation.Common/Interfaces/IInputCallbackSystem.cs index e2f80df4a6..8516bc87fb 100644 --- a/BizHawk.Emulation.Common/Interfaces/IInputCallbackSystem.cs +++ b/BizHawk.Emulation.Common/Interfaces/IInputCallbackSystem.cs @@ -3,7 +3,12 @@ using System.Collections.Generic; namespace BizHawk.Emulation.Common { - // TODO: This isn't a CoreService, it is a sub class of a core service, it would be nice to make that clear + /// + /// This is a property of IInputPollable, and defines the means by which a client + /// gets and sets input callbacks in the core. An input callback should fire any time input is + /// polled by the core + /// + /// public interface IInputCallbackSystem : ICollection { /// diff --git a/BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs b/BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs index 216bcd0033..76dc8470c9 100644 --- a/BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs +++ b/BizHawk.Emulation.Common/Interfaces/IMemoryCallbackSystem.cs @@ -3,6 +3,12 @@ using System.Collections.Generic; namespace BizHawk.Emulation.Common { + /// + /// This is a property of IDebuggable, and defines the means by which a client + /// gets and sets memory callbacks in the core. A memory callback should fire any time memory is + /// read/written/executed by the core, and depends on the type specified by the callback + /// + /// public interface IMemoryCallbackSystem : IEnumerable { /* @@ -69,6 +75,10 @@ namespace BizHawk.Emulation.Common void Clear(); } + /// + /// This service defines a memory callback used by an IMemoryCallbackSystem implementation + /// + /// public interface IMemoryCallback { MemoryCallbackType Type { get; } diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs b/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs index 2fef85bf74..9993d37164 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IInputPollable.cs @@ -4,7 +4,8 @@ /// This service specifices the interaction of the client and the core in terms of the state of input polling /// A lag frame is a frame in which input was not polled /// Input callbacks fire whenever input is polled - /// This service is used for the lag counter on the front end, if available. In addition lua script makes use of input callbacks as well as reporting lag status + /// This service is used for the lag counter on the front end, if available. In addition, + /// lua script makes use of input callbacks as well as reporting lag status /// Setters for both the count and lag flag are used by tools who offer custom notions of lag /// Additionally, movie support could in theory make use of input callbacks /// diff --git a/BizHawk.Emulation.Common/Interfaces/Services/ILinkable.cs b/BizHawk.Emulation.Common/Interfaces/Services/ILinkable.cs index e6d658c907..e0bdde9aac 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/ILinkable.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/ILinkable.cs @@ -2,7 +2,7 @@ { /// /// This service is use by link cable capable cores to manage the status of the link cable - /// If available the client will display the link cable status + /// If available, the client will display the link cable status /// public interface ILinkable : ISpecializedEmulatorService { diff --git a/BizHawk.Emulation.Common/Interfaces/Services/IMemoryDomains.cs b/BizHawk.Emulation.Common/Interfaces/Services/IMemoryDomains.cs index df81826e33..2635458e0b 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/IMemoryDomains.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/IMemoryDomains.cs @@ -3,13 +3,15 @@ namespace BizHawk.Emulation.Common { /// - /// The list of all avaialble memory domains - /// A memory domain is a byte array that respresents a distinct part of the emulated system. + /// This service manages the ability for a client to read/write to memory regions of the core, + /// It is a list of all avaialble memory domains + /// A memory domain is a byte array that respresents the memory of a distinct part of the emulated system. /// All cores sould implement a SystemBus that represents the standard cpu bus range used for cheats for that system, /// In order to have a cheat system available for the core - /// All domains should implement both peek and poke. However, if something isn't developed it should throw NotImplementedException rather than silently fail + /// All domains should implement both peek and poke. However, + /// if a domain does not implement poke, it should throw NotImplementedException rather than silently fail /// If this service is available the client will expose many RAM related tools such as the Hex Editor, RAM Search/Watch, and Cheats - /// In addition, this is an essential service for effective lua scripting + /// In addition, this is an essential service for effective lua scripting, and many other tools /// public interface IMemoryDomains : IEnumerable, IEmulatorService { diff --git a/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs b/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs index 7447674e23..b78d9d6801 100644 --- a/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs +++ b/BizHawk.Emulation.Common/Interfaces/Services/ISaveRam.cs @@ -3,9 +3,8 @@ /// /// This service provdes the system by which a client can request SRam data to be stored by the client /// SaveRam encompasses things like battery backed ram, memory cards, and data saved to disk drives - /// If available the client will provide features like sram-anchored movies, and ways to clear SaveRam - /// In addition save files and such will be automatically loaded when loading a ROM - /// + /// If available, save files will be automatically loaded when loading a ROM, + /// In addition the client will provide features like sram-anchored movies, and ways to clear SaveRam /// public interface ISaveRam : IEmulatorService { diff --git a/BizHawk.Emulation.Common/ServiceInjector.cs b/BizHawk.Emulation.Common/ServiceInjector.cs index 525bfb6d1c..862dbad141 100644 --- a/BizHawk.Emulation.Common/ServiceInjector.cs +++ b/BizHawk.Emulation.Common/ServiceInjector.cs @@ -1,8 +1,6 @@ using System; -using System.Collections.Generic; using System.Linq; -using System.Text; -using System.Reflection; + using BizHawk.Common.ReflectionExtensions; namespace BizHawk.Emulation.Common