Initial release

.gitignore

@@ -0,0 +1,132 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# titan
+titan/keystone

GUIDE.md

@@ -0,0 +1,123 @@
+# Titan - Xbox Setup Guide
+
+<p align="center"><img alt="The Titan-modified kernel running on an original Xbox" src="screenshots/titan_title.jpg"/></p>
+
+## 0. Preface
+
+As an initial release, setting up Titan requires a number of steps that may make the process intimidating to some users. As Xbox homebrew tools and resources are updated, I expect that Titan will become much simpler to setup.
+
+It is **strongly recommended** that you use a modchip for this mod. Softmods could work with Titan (in theory?) but are completely untested and hard to recover a failed install from.
+
+## 1. Apply Kernel Patches
+
+Titan is currently only supported for the popular M8+ BIOS. The checksums for these BIOS images have been provided below. You will have to find these files on your own as they are not included with Titan or as part of this repository.
+
+| BIOS Name                             | MD5 Hash                           |
+| ------------------------------------- | ---------------------------------- |
+| m8plus                                | `dfc6288f6b67fd021e1970491c64c0a0` |
+| m8plus (1.6)                          | `58b8782501983725f984499620ca342b` |
+
+It is recommended that you use [this guide](https://github.com/MakeMHz/xbox-hd-plus/blob/master/manual/Kernel%20Patch%20-%20m8plus.md) for learning how to pack and unpack the `m8plus_kernel.img` from the M8+ BIOS.
+
+Instead of using Lunar IPS to patch the extracted kernel per the guide above, you currently must use the Titan kernel patcher. Titan's PC-based kernel patcher is written in [Python 3](https://www.python.org/). It is *strongly recommended* that you download the [released packages](https://github.com/gaasedelen/titan/releases) which bundle the applicable dependencies for Windows, Linux, and macOS. 
+
+Example usage is provided below:
+
+```
+python3 tpatch.py m8plus_kernel.img
+```
+
+The `--udma` flag can also be used to patch the kernel to use a higher [UDMA](https://en.wikipedia.org/wiki/UDMA) transfer mode (retail is 2, maximum is 5). Please read the UDMA section of the [additional notes](https://github.com/gaasedelen/titan#additional-notes) provided in the main README for Titan.
+
+```
+python3 tpatch.py --udma 5 m8plus_kernel.img
+```
+
+Successful output should look something like the following:
+
+```
+[*] Patching with Titan v1.0 -- by Markus Gaasedelen
+[*] - Hashing kernel 'C:\titan\m8plus_kernel.img' to ensure compatibility
+[*] - 0x800243AA: Patching HddStartVerify(...)
+[*] - 0x8002443F: Patching HddVerify(...)
+[*] - 0x800244E6: Patching HddStartRw_Length(...)
+[*] - 0x80024534: Patching HddStartRw_Transfer(...)
+[*] - 0x80024632: Patching HddRw_Save(...)
+[*] - 0x8002465B: Patching HddRw_Smuggle(...)
+[*] - 0x80024485: Patching HddCompleteRw(...)
+[*] - 0x800246F3: Patching HddGetDriveGeometry(...)
+[*] - 0x8002F066: Patching HddPartitionCreate(...)
+[*] - 0x80024B5A: Patching HddCreateQuick(...)
+[*] - 0x8005546D: Patching HddCreate(...)
+[*] - 0x80027143: Patching FatxParseSupeblock(...)
+[*] - 0x80029CE5: Patching FatxStartAsyncIo(...)
+[*] - 0x80029E5B: Patching FatxAsyncIo(...)
+[+] Patching successful!
+```
+
+The resulting `m8plus_kernel.img` can now be re-packed using EVTool, as described in the previously linked [guide](https://github.com/MakeMHz/xbox-hd-plus/blob/master/manual/Kernel%20Patch%20-%20m8plus.md).
+
+The final, re-packed, M8+Titan BIOS should be 256kb and can be flashed to your modchip using any preferred method. An Xbox running the Titan-based kernel is expected to boot and operate (at minimum) identical to a system running vanilla M8+.
+
+## 2. Initializing a HDD for Titan
+
+At the time of writing, it is *strongly recommended* that you format the HDD to be used in the Titan-based Xbox with the open-source [FATX](https://github.com/mborgerson/fatx) tool created by Matt Borgeson. This is PC-based FATX tool that can be used to mount/read/write physical and virtual FATX drives. **It is also the only tool that currently supports increased cluster sizes of 128kb, 256kb, and 512kb.**
+
+If you are a Windows user, it is recommended you setup an Ubuntu Linux 20.x or 21.x virtual machine with [VMware Workstation](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html) so that you can clone, [build](https://github.com/mborgerson/fatx#how-to-build-natively), and run the FATX project.
+
+Once a virtual machine is set up, the target HDD should be connected to your PC using any [SATA-to-USB](https://www.amazon.com/Sabrent-External-Lay-Flat-Docking-Extension/dp/B08P5Z51MT) adapter:
+
+<p align="center"><img alt="Connecting a 16TB SATA-based HDD to a PC for formatting" src="screenshots/sata_usb.jpg"/></p>
+
+Most virtualization solutions will provide a way to pass physical devices attached to the Host PC through to the virtual machine. 
+
+In the GIF below, it shows how the SATA-to-USB drive can be connected to an Ubuntu virtual machine running in VMWare Workstation instead of the Host PC:
+
+<p align="center"><img alt="The Titan-modified kernel running on an original Xbox" src="screenshots/hdd_to_vm.gif"/></p>
+
+Once the HDD is connected to virtual machine, it can be formatted with the the following command:
+
+```
+sudo fatxfs XXX --format=f-takes-all --sectors-per-cluster=1024 --destroy-all-existing-data
+```
+
+Please note that`XXX` in the command above should be the path to your attached SATA-to-USB device / HDD. It will most likely be something like `/dev/sdb`, but you can use the command `lsblk -d | grep disk` to list possible devices from within the virtual machine. 
+
+```diff
+- PLEASE TRIPLE CHECK THAT YOU ARE FORMATTING THE CORRECT DRIVE ATTACHED TO YOUR VM OR HOST PC -
+- PLEASE TRIPLE CHECK THAT YOU ARE FORMATTING THE CORRECT DRIVE ATTACHED TO YOUR VM OR HOST PC -
+- PLEASE TRIPLE CHECK THAT YOU ARE FORMATTING THE CORRECT DRIVE ATTACHED TO YOUR VM OR HOST PC -
+```
+
+You can then mount the drive and copy a dashboard such as XBMC or EvoX into the C partition:
+
+```
+mkdir mountpoint
+sudo fatxfs /dev/sdb --drive=c mountpoint
+sudo cp ~/evox.xbe mountpoint/xboxdash.xbe
+sudo fusermount -u mountpoint
+```
+
+Once you have the HDD fully formatted and an `xboxdash.xbe` placed in the C partition, the drive can be disconnected from the PC and installed into the Xbox.
+
+_**NOTE: It may be possible for existing tools to format a HDD for Titan from the Xbox itself, but there are several ways I imagine they can or will fail until they are properly updated and tested. Additionally, all existing tools will max out at 64kb cluster sizes, meaning it may take several minutes for a large Titan FATX volume to be mounted on bootup/access. Attempt alternative methods at your own discretion.**_
+
+## 4. Installing the HDD
+
+Your choice of IDE-to-SATA adapter and configured UDMA speed (see comments about `--udma`) may affect the speed, performance, and stability of your drive once installed into the Xbox. 
+
+At the time of writing, only the following adapters paired with an 80 wire IDE cable have been tested with Titan:
+
+<p align="center"><img alt="IDE-to-SATA adapters commonly used by Xbox modders" src="screenshots/sata_adapters.jpg"/></p>
+
+Other adapters may work, but have not been tested. Please feel free to report any successes or failures with other types of adapters/chipsets that facilitate IDE-to-SATA communications.
+
+In the context of UDMA modes, 'unstable' means that system may not boot, or if it does, there may be transfer errors occurring while trying to use the system. This will manifest as 'long load times' (read/writes failing and having to be re-tried), erratic copy rates in DVD2Xbox, stuttering media playback, etc.
+
+<p align="center"><img alt="Overview of a Titan-based system" src="screenshots/titan_install.jpg"/></p>
+
+Please take extreme caution when installing the SATA adapter into your Xbox. Almost universally, IDE-to-SATA adapters lack any sort of backing to go between the HDD housing and exposed leads on the back of the adapter. This is extremely unsettling to install without some form of insulation between the board and the drive housing (Kapton Tape, 3D printed shroud, etc.).
+
+Assuming all of the steps were followed correctly, the Titan partition (F) should be visible and available for use.
+
+<p align="center"><img alt="A completed, 16TB Titan-based system, up and running" src="screenshots/titan_final.jpg"/></p>

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Markus Gaasedelen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,116 @@
+# Titan - Xbox Kernel Patches for Extended Storage
+
+<p align="center"><img alt="The Titan-modified kernel running on an original Xbox" src="screenshots/titan_title.jpg"/></p>
+
+## Overview
+
+Titan is a series of hand-written binary patches for the original [Microsoft Xbox](https://en.wikipedia.org/wiki/Xbox_(console)) kernel. These patches are designed to expand the  storage capabilities of the popular 2001 game console in excess of 16TB. This is achieved by modifying the kernel to support [LBA48](https://en.wikipedia.org/wiki/Logical_block_addressing#LBA48) and extending the number of addressable 512-byte disk sectors in the IO stack.
+
+Special thanks to Mike Davis for his [serial debugging](https://github.com/XboxDev/serial-usb-adapter) boards, Matt Borgerson for his tireless efforts on [XEMU](https://github.com/mborgerson/xemu) & [FATX](https://github.com/mborgerson/fatx), and finally Paul Bartholomew (oz_paulb) for his original LBA48 research from [2003](http://hackspot.net/XboxBlog/?page_id=2) which facilitated up to 2TB for the past 15+ years. All of these people and their open-source works played an important role in the creation of Titan.
+
+## Disclaimer
+
+**This project does NOT use any copyrighted code, or help circumvent security mechanisms of an Xbox console.**
+
+These patches should be considered highly experimental pending further attestation. By using this software, you accept the risk of experiencing total loss or destruction of data on the console in question.
+
+Titan may break existing Xbox homebrew, and existing homebrew may break Titan-based systems.
+
+## Usage
+
+Titan's PC-based kernel patcher is written in [Python 3](https://www.python.org/). It is *strongly recommended* that you download the [released packages](https://github.com/gaasedelen/titan/releases) which bundle the applicable dependencies for Windows, Linux, and macOS. 
+
+Example usage is provided below:
+
+```
+python3 tpatch.py m8plus_kernel.img
+```
+
+Successful output should look something like the following:
+
+```
+[*] Patching with Titan v1.0 -- by Markus Gaasedelen
+[*] - Hashing kernel 'C:\titan\m8plus_kernel.img' to ensure compatibility
+[*] - 0x800243AA: Patching HddStartVerify(...)
+[*] - 0x8002443F: Patching HddVerify(...)
+[*] - 0x800244E6: Patching HddStartRw_Length(...)
+[*] - 0x80024534: Patching HddStartRw_Transfer(...)
+[*] - 0x80024632: Patching HddRw_Save(...)
+[*] - 0x8002465B: Patching HddRw_Smuggle(...)
+[*] - 0x80024485: Patching HddCompleteRw(...)
+[*] - 0x800246F3: Patching HddGetDriveGeometry(...)
+[*] - 0x8002F066: Patching HddPartitionCreate(...)
+[*] - 0x80024B5A: Patching HddCreateQuick(...)
+[*] - 0x8005546D: Patching HddCreate(...)
+[*] - 0x80027143: Patching FatxParseSupeblock(...)
+[*] - 0x80029CE5: Patching FatxStartAsyncIo(...)
+[*] - 0x80029E5B: Patching FatxAsyncIo(...)
+[+] Patching successful!
+```
+
+For a full walkthrough of setting up an Xbox with Titan, please refer to the [GUIDE.md](GUIDE.md) provided in this repo.
+
+## Additional Notes
+
+Some additional notes about Titan are as follows:
+
+ * **Formatting**
+    * The [FATX](https://github.com/mborgerson/fatx) project is currently the only tested/supported method to format a disk for a Titan-based system
+    * XBPartitioner/XBlast/XeniumOS/FATXplorer are all considered unsupported and probably require updates
+      * I fully expect these tools to get updated releases in the near-future
+ * **Partitions**
+    * Titan is essentially hardcoded to use a 'F (Partition 6) Takes All'-esque partitioning scheme
+    * Titan could be extended to support additional partitions, but it seems unnecessary
+ * **Clusters**
+    * Titan allows increased cluster sizes of 128kb, 256kb and 512kb
+      * **It is strongly recommended to format large disks (2TB+) with 1024 sectors per cluster (512kb)**
+      * Matt's [FATX](https://github.com/mborgerson/fatx) is the only tool that can currently format disks with larger clusters 
+    * Increased cluster sizes dramatically increases the speed of mounting FATX volumes (faster bootup)
+    * Increased cluster sizes will ensure more linear reads on the disk (faster file reads, game loading, etc.)
+    * Increased cluster sizes allows for more items in the root disk directory (8192 items at 512kb clusters)
+    * If you're using Titan, you can afford the luxury of bigger clusters so stop complaining about wasted space
+    * Increased cluster sizes were never the issue for limiting drive/partition sizes, this is FUD
+      * 64kb clusters should work on the Titan partition but bootup/mounting WILL be slow for large disks
+ * **UDMA**
+    * Titan can change the [UDMA](https://en.wikipedia.org/wiki/UDMA) transfer mode used by the kernel with `--udma N`
+       * Increasing the UDMA mode has been profiled to improve some game load times in excess of 20%
+       * Increasing the UDMA mode will require an 80pin IDE cable
+    * The retail Xbox uses UDMA 2 (33mb/s) by default (as do many/all (?) modified BIOS')
+    * The maximum supported UDMA mode by the Xbox southbridge is UDMA 5 (100mb/s HDD <--> CPU)
+      * **UDMA 5 DOES NOT WORK WITH ALL IDE TO SATA ADAPTERS**
+      * UDMA 5 has been confirmed working with Startech adapters but has not been properly benchmarked
+      * UDMA 5 is unstable on RXD-629A7-7 based adapters, but UDMA 4 seems okay
+      * WLXKG-863B are the 'worst' adapters I have experienced working on Titan and are largely untested
+ * **Games**
+    * A random assortment of games have been tested to ensure some baseline on system stability
+      * I don't expect major issues here, but more testing should be obviously be done 
+ * **Dashboards**
+    * XBMC seems to work fine
+    * EvoX seems to work fine
+      * EvoX displays the incorrect disk size because it [performs](https://github.com/gaasedelen/titan/blob/main/screenshots/evox_bug.png) a modulus of 'available gigabytes' by 1000
+      * This does not mean that you formatted incorrectly, or that the HDD is corrupt
+      * FTP seems okay?
+    * Dashboard-based FTPs are probably much safer than BIOS-based FTP (eg. XeniumOS)
+    * Consider all other dashboards as untested
+  * **Other Homebrew Notes**
+    * DVD2Xbox works fine
+    * FTP via XeniumOS is probably risky. I would only use it to transfer files onto RETAIL partitions (C or E)
+    * Anything booting into a BFM BIOS (PBL, Hexen?) is totally unsupported for accessing the Titan partition (F)
+    * Consider all other homebrew as untested
+  * **Patches** 
+    * Titan is only supported on the M8+ kernel. M8+ is a modified version of the final retail kernel (5838)
+      * Titan/M8+ can be used on ALL retail hardware revisions (1.0 -> 1.6b)
+      * These patches can almost certainly be ported to other Xbox kernels, but not something I plan on doing
+    * Previous iterations of these patches modified the kernel to use 4K sectors but was deemed unnecessary
+      * The released patches can be further simplified, moving away from the original 4K implementation
+    * More experimental patches that further accelerate mounting large FATX volumes may be added later
+
+## Contributing
+
+The best thing you can do to contribute would be to test games or homebrew and report breakages. Please only file an issue if something does not behave the same on a Titan-based system versus a stock M8plus-based system.
+
+This project is permissively licensed, and the included patches are easy to read and modify. If you're feeling truly adventurous, you can try porting the patches to another popular version of the original Xbox kernel.
+
+## Authors
+
+* Markus Gaasedelen ([@gaasedelen](https://twitter.com/gaasedelen))