Porting VHBL to your game exploit

This guide is the second major revision of a guide I wrote a year and a half ago. In this guide I will explain how to port Half Byte Loader to your game exploit, and in particular to make it work on the PS Vita. I just updated the main file needed to create the exploit, so the timing is right.
This guide assumes that you found a user mode exploit in a game, and that you were able to write a binary loader.

So now what’s next? Well, as you probably know if you’ve gone that far, the PSP scene doesn’t really like “hello worlds”. A hello world is nice, but it accomplishes nothing, it just draws Sony’s attention to your exploit, and you know the vulnerability will be patched soon, while nobody really used the exploit.
Well, the next step is, ideally, a HEN or a custom firmware. Of course, this requires a kernel exploit, and we know how these are difficult to find. A much more doable task, that will make lots of people happy, is to port HBL to your exploit. HBL opens the door to lots of legal contents on the PSP and the Vita, and we designed it so that porting it to your game exploit can be done fairly easily.
This tutorial is valid at the time of its writing, for all games, and up to firmware 6.60 (Vita firmware 1.61). In theory, HBL will work on future firmwares, but of course new kinds of security might be introduced in new firmwares. Additionally, depending on your game (and its function imports), the compatibility and speed of homebrews might vary.

0. Easy as pie

HBL was designed to be easily ported to new game exploits. Most Game-specific files (except one) go in a subfolder that I will describe below. To complete this tutorial, you need basic shell skills, a working pspsdk, a working game exploit and the associated binary loader / hello world, a ruby interpreter, and basic ruby skills (usually, if you know any other scripting language, you’ll figure it out easily, there are not so many changes required).

1. Get the HBL sources and compile them

The first step is to get the HBL sources, compile them, and if you’re motivated, test them on an existing game exploit, to make sure the copy you have works correctly. (As I write this, it is recommended to test compilation with either the Mototrstorm or the Everybody’s tennis exploits, as we might have broken backwards compatibility with older exploits)
The sources of HBL can be downloaded here (SVN client required)
In order to compile it, you need the PSPSDK (which you probably already have if you wrote a binary loader). Compilation is fairly easy, but in order to compile the HBL for a specific exploit, you have to specify the folder of the exploit. for example, make FOLDER=lifeup will compile HBL for the Motorstorm (EU) exploit.

2. Create your own exploit’s folder

As you guessed, you will create a folder dedicated to your own exploit. Let’s imagine you game is called wololo, then you can create a subfolder “wololo” in the eLoader folder. Basically, we want to reproduce the files that are in this folder for another exploit, and adapt them to our exploit. Let’s have a look at the lifeeu folder:

The folder contains 6 files and 1 folder (which contains 1 file) that you will want to adapt to your exploit. I will describe each of them separately. Most of these files are automatically generated by a script, so this should be fairly simple.

3. Create your exploit’s files

linker_loader.x

This is the linker file for h.bin. If you created a binary loader and a hello world, you already have this file from your hello world, and most likely you named it “linker.x“. Copy linker.x from your hello world to linker_loader.x. Done!

sdk_loader.S

This is the sdk for h.bin. If you created a binary loader and a hello world, you probably already have this file, and named it sdk.S. Copy sdk.s to sdk_loader.S. If you don’t have this sdk, you can create it either by running prxtool on the EBOOT.BIN of the game, or by using the moskitool (a ruby version of the moskitool can be found in the eLoader/tools folder of the HBL). Most likely, if you created a hello world, you already have this file so I won’t give more details for now. Done!

config folder, exploit_config.h, sdk_hbl.S, loader.h,

The contents of the config folder, as well as sdk_hbl.S, loader.h, and most of exploit_config.h (details below for exploit_config.h)  are automatically generated by a ruby script that you can find in eLoader/tools/gen_exploit_config.rb.
The gen_exploit_config.rb has 2 “modes”, but I will only describe the first one, which is required the first time you adapt your exploit. You need to have a usermem dump named memdump.bin (that you acquired from psplink with the command savemem 0×08800000 0×01800000 memdump.bin). Important note: For Vita compatibility, that dump must be done on a PSP running firmware 6.60. In addition to memdump.bin, you need a list of UIDs from the same psplink session, that you will name uidlist.txt. You can get that file by typing uidlist > uidlist.txt in psplink. That file needs to be in unix format, so be sure to convert it if you are running windows. Finally, you need a file named sdk.S, which is nothing else than the sdk.S you created for your game exploit, the one we just named sdk_loader.S above.
Put these 3 files (memdump.bin and uidlist.txt obtained from the same psplink session, as well as sdk.S from your exploit) in the tools folder, and run gen_exploit_config.rb
This should display a list of addresses (you will want to copy these addresses inside the stubs array of gen_exploit_config.rb so that other people who want to improve your exploit won’t need a memory dump/uidlist anymore, although they will still need the sdk.S file), and generate a series of files in the tools/output subfolder.
The files generated by gen_exploit_config.rb in the output folder can be copied “as is” into your game’s folder.

Final edits to exploit_config.h

You’re almost done, but the file exploit_config.h need to be edited in two places, that you will find because they say “TODO” in big letters.
HBL_LOAD_ADDRESS This is where you will load HBL in RAM. You want a value that is outside of the boundaries of the game, and basically, a place where the PSP will accept to alloc roughly 200kB. you can get such an address in psplink while the game is running by typing malloc 2 test l 204800
HBL_ROOT is the name of the folder where your exploited savedata is. That folder name looks like ms0:/PSP/SAVEDATA/UCUS12345000. Important note: my tutorial on how to create a binary loader assumes you will load a file named ms0:/h.bin. On the PS Vita, this is not possible anymore, so you will have to adapt your binary loader in order to load the exploit from ms0:/PSP/SAVEDATA/XXXXXXX/h.bin (where XXXX is the folder of your savedata). In the Vita version of HBL, all HBL files for in that folder, and there is no subfolder.

linker_hbl.x

copy linker_loader.x into linker_hbl.x, and replace the address value with the value of HBL_LOAD_ADDRESS that you figured out earlier while creating exploit_config.h. Done.

4. Compile

• run make FOLDER=yourfolder (alternate ways: make distrib FOLDER=yourfolder to remove debug messaging, make nonids FOLDER=yourfolder to remove NIDs-related heavy debug messaging)
  
• You’re done, grab the h.bin and hbl.bin in the root, the config folder from your exploit’s folder, and the libs_… folders from the root. You now have the meat of your HBL port ready.

5. Last but not least

HBL is licensed under the GPL. If you plan to distribute your compiled binaries, it is required that you provide your source code as well. Don’t make us ask for it
This tutorial is voluntarily vague. Porting HBL is fairly easy, but we assume that if you made it that far, you probably are skilled enough to do some research on your own. Nevertheless, don’t hesitate to ask questions if you are running into problems
You are allowed to reproduce this article on other websites and/or translate it on condition that you put a clear link to this page in your copy.

6. More details

Porting VHBL is simple in theory, but many games do not import some functions that are necessary for HBL to run properly. One goal of the script gen_exploit_config.h is to analyze the imports of your game (this is why the sdk.S is necessary), and define some workarounds in exploit_config.h in case your game does not have all the necessary exports. This should work in most cases, but that script is still experimental and might make mistakes. Below are a few details on some of the “define” sections it creates:

TH_ADDR_LIST, EV_ADDR_LIST, SEMA_ADDR_LIST, and GAME_FREEMEM_ADDR can be computed for you by the tool eLoader/tools/freemem.rb. For that you will need a memory dump and a file uidlist.txt which is the output of the uidlist command in psplink (uidlist > uidlist.txt ). It is important to note that the memory dump and the uidlist need to be from the same session, otherwise the addresses will be incorrect. If you’re on windows, also make sure that the uidlist.txt file is in the unix format (use your favorite editor to convert it if needed). For those interested, here are some technical details about those variables, but basically the tool should do it for you

TH_ADDR_LIST, is the list of threads you want to kill. Threads are defined by a SceUID, but since this value changes all the time, what we actually want is the addresses where they are defined. in psplink, while your game (or your hello world) is running, you can get a list of these thread by typing thlist. Then look for each thread’s uid in ram. The address (hopefully unique) where the thid is defined, is what you want to put in this list.
EV_ADDR_LIST is the list of events you want to kill. You get this list by typing evlist in psplink. The rest is similar to the construction of TH_ADDR_LIST
SEMA_ADDR_LIST is the list of semaphores you want to kill. You get this list by typing smlist in psplink. The rest is similar to the construction of TH_ADDR_LIST above
GAME_FREEMEM_ADDR this is the address in Ram where the game’s memory was allocated. Most game have this but for those that don’t have it (patapon2), this value can be commented out. To find this value, type uidlist” PSPLink and look under the SceSysMemMemoryBlock section. You’re looking for blocks that have a 0xFF (user) attribute (not 0×00!), and are not “stack”. In the golf exploit, this block was simply called “block” and was easy to find. Again, you’re interested in the entry address, not the uid.

UNLOAD_ADDITIONAL_MODULES : define this variable if possible. Comment it out only if you run into issues at the “free memory” stage of HBL
Other variables: The variables above are the basics of the config file. With those, HBL should basically work, or at least take you to a step where you can start debugging. But with time, HBL has grown and has been updated by several people. In order to maintain backwards compatibility and increase game coverage, the exploit_config file was added several config values. DISABLE_P5_STUBS is useful if you run into a crash/freeze even before hbl is loaded (just after firmware detection). SYSCALL_* are used for perfect syscall estimation on firmwares where this is available (TODO: explain syscalls estimation), etc… at this point you will probably need to dig in previous exploit_config.h files in order to find more on each macro you can possibly define.