mirror of
https://github.com/djhackersdev/bemanitools.git
synced 2024-09-24 02:48:21 +02:00
Add initial draft of architecture document.
Still has a bunch of TODOs where more information is required. This commit adds the first few sections and some information about iidxhook.
This commit is contained in:
icex2
parent
79495ea687
commit
0a499b38a7
@ -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).
|
||||
|
||||
|
||||
176
doc/architecture.md
Normal file
176
doc/architecture.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user