bemanitools/doc/architecture.md

# 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.

Essentially, the main module file of each iidxhook implementation just glues the APIs of the modules it requires
together. An additional configuration layer allows users to tweak some of the features.

TODO go into some more detail about some differences in the hook modules, e.g. 18 to 19 look identical
-> but different AVS versions

#### 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

#### iidxhook4-cn (18 CN)
* Ezusb IO2 I/O emulation
  * Setupapi emulation
  * Full security emulation with SRAM and round plugs
  * Full game essential I/O emulation
* 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

#### iidxhook5-cn (20 CN)
* Ezusb IO2 I/O emulation
  * Setupapi emulation
  * Full security emulation with SRAM and round plugs
  * Full game essential I/O emulation
* 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

### popnhook
TODO

### sdvxhook
TODO

## The ezusb (emulation) stack
TODO

## The ACIO (emulation) stack
TODO

## BT5 API
TODO

## AVS and launcher
TODO

## Inject
TODO