diff --git a/README.md b/README.md index cabb3dc..6f546fb 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,10 @@ know if there is any information that you consider helpful or important to know Please refer to the [dedicated documentation](CONTRIBUTING.md). # Development +## Architecture +A dedicate [architecture document](doc/architecture.md) outlines the architecture of Bemanitools and points out the most +important aspects you should know before you get started with development. + ## API Please refer to the [API documentation](doc/api.md). diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 0000000..a129a47 --- /dev/null +++ b/doc/architecture.md @@ -0,0 +1,176 @@ +# Bemanitools architecture +This document gives you an overview of the architecture of Bemanitools (5). Why do we need this? This helps document the +various design decisions and how everything comes together, in the end. At some point when things are evolving and other +developers want to pick up the project, this might give them answers to why some things were done well or not so well. +This allows them to iterate on the current design (document) to analyze if a change they want to apply might work out +or not. + +Anway, enough preface...I guess you got the idea. This document will be split into several sections which address +different aspects of the architecture. + +## The big picture +TODO create a graphic that presents the key modules and ideas. + +## Detouring library functions, IAT hooking +One of Bemanitools's goals is to avoid patching of executables, libraries or any game data and instead rely on +intercepting calls to libraries to patch bugs or introduce new features. To support a game on a non native platform +transparently, e.g. your home desktop, this allows us to intercept I/O communication to emulate hardware or +files/filesystem features the game expects to be available. + +We create a so called "hook library/hook.dll" which gets injected to the target process (the game) before the game +runs any of its application code. This is well known by the terms of dll injection and will not be further discussed +here (google it). The injected dll will replace the function addresses in the IATs to detour any calls to our own +handler functions before, eventually, calling the real function. This way, we can intercept the call and do cool things. + +These features are covered by the modules in the following subfolders in src/main: +* hook: Essentially, this is capnhook: https://github.com/decafcode/capnhook. General tools for hooking Win32 API calls. +* hooklib: Some additional helper modules to take care of specific issues in Bemanitools, e.g. rs232 related stuff for +ACIO. + +Check the modules for details. + +## Hooking and IRP +IRP stands for "I/O request packet" and is a kernel mode structure used in Windows drivers for communication with the +OS. The data structure describes an I/O request with parameters for that request avoiding function calls with large +number of arguments to a driver. + +We make use of that "IRP pattern" by creating a flexible and maintainable abstraction layer for the following hooking +modules: +* iohook: Hook I/O (e.g. file) related calls +* d3d9: Hook d3d9 graphics API calls + +An IRP handler is implemented to handle selected IRP calls based on the specified operation type. IRP handlers can be +chained which allows splitting up different features/interceptors to different functions and modules allowing you to +create a clear structure. At the end of the forwarding chain, you the real API function that maps to the abstracted +operation is called. However, a handler can decide at any time to not forward calls which allows you to implement +emulation of access to selected files or I/O devices. + +Modules that make use of this: +* iidxhook-util/d3d9 +* ezusb-emu/device +* ezusb2-emu/device +* acioemu/emu + +## Bemanitools's hook libraries, let's glue everything together +Bemanitools dlls to be injected into target game processes are refered to as "hook dlls" and come in different flavours +targetting different games and often different versions of the same game (series), for example: +* ddrhook: Hook dll for Dance Dance Revolution games +* iidxhook1-8: Hook dlls for Beatmania IIDX, we are currently at 8 different implementations due to the various +iterations the game went through, related to software and hardware. +* sdvxhook: Hook dll for SoundVoltex series + +The following sub-sections will give you some brief insights on each hook implementation and what modules were used. + +### bsthook +TODO + +### ddrhook +TODO + +### iidxhook +IIDX went through so many hard- and software iterations, it's actually amazing that the development team(s) refactored +and improved parts of the game and hardware with each iteration. However, when facing emulation and supporting +compatibility to legacy OS platforms, it can't get any worse. On the bright side, IIDX helped shaping Bemanitools a lot +and created a solid foundation other games can build on. + +Because of that, we have 8 iidxhook implementations supporting sometimes different software features/fixes and +hardware. The following sub-sub-sections list the most relevant aspects and modules to point out common and different +higher level features. + +#### iidxhook1 (9-12) +* Ezusb C02 I/O emulation + * Setupapi emulation + * Full security emulation with SRAM and round plugs + * Full serial emulation for magstripe card readers + * Full game essential I/O emulation +* d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper) +* clock patching +* Font patching for Japanese chars +* Network related patches to enable eamuse to custom servers +* Filesystem patches to detour E and F backup drives for settings + +#### iidxhook2 (13) +* Ezusb C02 I/O emulation + * Setupapi emulation + * Full security emulation with SRAM and round plugs + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, slotted readers +* d3d8 patching and extended features (superseded by d3d9 hook module + d3d8to9 wrapper) +* clock patching +* Font patching for Japanese chars +* Network related patches to enable eamuse to custom servers +* Filesystem patches to detour E and F backup drives for settings + +#### iidxhook3 (14-17) +* Ezusb IO2 I/O emulation + * Setupapi emulation + * Full security emulation with SRAM and round plugs + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, slotted readers +* d3d9 patching and extended features +* Font patching for Japanese chars +* Network related patches to enable eamuse to custom servers +* Filesystem patches to detour E and F backup drives for settings + +#### iidxhook4 (18) +* Ezusb IO2 I/O emulation + * Setupapi emulation + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, slotted readers +* d3d9 patching and extended features +* Font patching for Japanese chars +* Filesystem patches to detour E and F backup drives for settings + +#### iidxhook5 (19) +* Ezusb IO2 I/O emulation + * Setupapi emulation + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, wave pass readers +* d3d9 patching and extended features +* Font patching for Japanese chars +* Filesystem patches to detour E and F backup drives for settings + +#### iidxhook6 (20) +* Ezusb IO2 I/O emulation + * Setupapi emulation + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, wave pass readers +* d3d9 patching and extended features +* Font patching for Japanese chars + +#### iidxhook7 (21-24) +* Ezusb IO2 I/O emulation + * Setupapi emulation + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, wave pass readers +* d3d9 patching and extended features +* Font patching for Japanese chars + +#### iidxhook8 (25-26) +* ACIO BIO2 I/O emulation + * Setupapi emulation + * Full game essential I/O emulation +* ACIO ICCA card reader emulation, wave pass readers +* d3d9 patching and extended features +* Font patching for Japanese chars + +### jbhook +TODO + +### sdvxhook +TODO + +## The ezusb (emulation) stack +TODO + +## The ACIO (emulation) stack +TODO + +## BT5 API +TODO + +## AVS and launcher +TODO + +## Inject +TODO \ No newline at end of file