How To Port OEM Specific ROMs as GSI Using ErfanGSI Tool

Updated on - 8th June 2020

Most of the people may not understand the meaning of title this post but if you ever read about Generic System Images i.e GSI then you have understood it. Back in kitkat, lollipop and Marhsmallow days people used to port ROMs, they still do from other devices with similar specifications. Its a tedious work to find phones with most similar specification and OS version. After the implementation of Treble in Oreo, it has become very easy (kind of) to port OEM specific systems. In easy words - You can port MIUI from Xiaomi, OxygenOS/HydrogenOS from One Plus, ZenUI, ZUI , Nubia UI and some more. Well, you need a treble supported phone with either 8.1, 9.0 or 10 Android Version. These GSIs will not work on Pre-Oreo Versions of Android.

ErfanGSI tool by developer Erfan Abdi is the best tool available for porting OEM specific ROMs. You can build a GSI just in just one or two minutes once you understood how it works. It is very user friendly tools where you have to just type some commands and tool will handle the rest of the porting process. Don't expect a perfectly working GSI from this tool because all OEM specific systems are different and system structure varies with each different device specially when the processor is different. Bugs will depend on the treble ROM of your device as well.

This guide is intended for users who have some idea about using linux/Ubuntu or Cloud platforms such as Google Cloud. Its possible to build on Mac as well, since I have no about it I am not going to tell about installation on Mac. This guide only ports the OEM systems which are on Android version 9 and 10. You can not port an Oreo firmwares from other OEMs with this tool. This GSI tool support building of Aonly and AB partition type GSI. It will automatically output both version, if you want to build Aonly version or AB only then you have to use some different command which you will see later in this post. If you are complete noob and have no idea about these things ,just head over to google and read about them.

The system you need to build GSI -
1. A powerful PC , 4GB RAM and dual core is not enough but it may take a lot of time. Higher the RAM and Cores lesser the build time.
2. A good internet connection , needed for downloading the OEM specific Zips which are usually more than 1GB. You can work with locally downloaded firware zips as well.
3. Ubuntu OS on your PC (thats what I use).
4. A working brain.

If you have all needed things above mentioned , I am considering that you have a good working PC setup. Now we will move to next steps of Installing some required things which will be used by the tool.

Open the terminal on your PC
First we will clone the repo with all submodule repos. It will take time in cloning and everything is around 500-700MB.

git clone --recurse-submodules https://github.com/erfanoabdi/ErfanGSIs.git

Second- Now after cloning we will move to ErfanGSIs directory with
cd ErfanGSIs
Now we going to install all the packages which are required for building the GSIs from this tool. Its fairly simple, just type -

bash setup.sh

When everything is above is installed, you are ready to build your GSI.

The next step is finding the OEM specific system zips. These are basically the OTA zips which are released by smartphone companies to upadate their phones. All you need to find is a full OTA zip which is based on Android Pie. One Plus releases all OTA zips on their website, you can find other OEMs update zips by searching on google. You need a direct link of the URL of zip or you can download the OTA zip to your PC as well. I will tell both ways of building GSI directly from a URL as well as from the OTA zip which you have downloaded locally on your PC.

The name of systems (Android Pie/Q) which are supported by ErfanGSI tool. -
1. Android Q/10
2. ColorOS
3. Flyme
4. Generic
5. MIUI
6. Nubia
7. OneUI
8. OxygenOS
9. Pixel
10. Xperia
11. ZenUI
12. ZUI

"Generic" tag is used for building GSIs based on AOSP. You can build GSIs from custom ROMS such as Havoc, Pixel Experience and more.

Generating GSI from a URL

For example if you want to generate GSI of a One Plus 7 pro OTA/Firmware, then just make sure you are in the ErfanGSIs directory first, then enter this command -

sudo ./url2GSI.sh https://oxygenos.oneplus.net/OnePlus7ProOxygen_21.O.07_OTA_007_all_1905120542_fc480574576b4843.zip OxygenOS

The above command contains 3 things. First is the url2GSI - which is a bash script that handles rest of the things. Second is the URL of the firmware (Just replace it with a any OnePlus firmware link you want), third is the type of the system/Firmware, it is basically the name of the system which I have written in list. It can change accordingly to the firmware which you are trying to port. Like if you porting a MIUI firmware then you have to type MIUI instead of OxygenOS. Above command build both A and AB both version of GSI. You will get your GSI img in the out directory. These are usually img files over 2GB. You can compress them with 7z before uploading on the internet.

Compressing with 7z

Just go the out folder and enter the 7z archive name and the name of the img file -
7z a [archived-filename] [names-of-file-to-be-archived]

Like if I have an img file named HydrogenOS-Aonly-9-20190614-ErfanGSI.img , I will enter this -
7z a HydrogenOS.7z HydrogenOS-Aonly-9-20190614-ErfanGSI.img

Generating Aonly or AB only GSI

Suppose you have Aonly device and you don't want to build AB version then in this case you have to use the command like this -
sudo ./url2GSI.sh https://oxygenos.oneplus.net/OnePlus7ProOxygen_21.O.07_OTA_007_all_1905120542_fc480574576b4843.zip OxygenOS Aonly

This will make only A vesion of GSI img. The same way you can use AB tag for building AB GSI img.

Modifying System Before Building GSI

With this method you can also modify the system before getting the final GSI. It is useful when the system is filled with bloat and you want to keep the GSI size smaller in order to fit into the system partition of your device. In this I am using the url of OP6T firmware.

Make sure you are in ErfanGSIs directory. I am using all commands with sudo to avoid any kind of permission/access error.
1. This steps include the downloading of the firmware. You can use this same method on locally downloaded zips. Zip will be downloaded in downloads folder. Ignore all the errors you get after executing this command.
sudo ./url2GSI.sh https://oxygenos.oneplus.net/OnePlus6Oxygen_22_OTA_031_all_1905281326_bc947291e7ba4ce3.zip

Do not type the firmware/system name in the end like we did earlier.

2. This step unzips the zip contents and converts the system to system.img and stores the system.img in cache directory.
sudo ./zip2img.sh downloads/temp.zip

3. Now make an empty system folder in ErfanGSIs directory where we will mount our system.img
mkdir system

4. This step is to for mounting the system.img to system folder. Once mounted you can make changes in system before building the final img.
sudo mount cache/system.img system

You will see a system folder now with all the contents of system. Make whatever changes you want and proceed to next step.

5. This step will give the final output of GSI img in the out folder. You can make changes in the commands according to your use.
See the basic structure of this command -
./make.sh [path to GSI system] [firmware type] [output type] [Output Dir]

-Path to GSI system: Mount GSI and set mount point
-Firmware type: Firmware mode, it means the name of the system like MIUI, ZUI, ZenUI, OxygenOS etc(see list above in post)
-Output type: AB or A-Only
-Output Dir: set output directory, we don't need it mostly because without this the img output will be in "out" folder. You can change it as you like.

Now everything is done , so my final command will look like this for OxygenOS GSI build. I am making Aonly img here. If you want to build for AB devices , just use AB instead of Aonly. If you want both , don't write Aonly or AB
sudo ./make.sh system OxygenOS Aonly

thats it, you will get your img in out folder.

Notes

1. You will not be able to build Android Q GSI because the system does not mount properly due to changes from google in the factory images of updates. This thing only applies to Android Q on Pixel Smartphones and Oneplus 7/7T. These phones comes with dynamic partitions and building from these requires some hacky workarounds. If you are still interested in building from these devices you can check out the MakeDynamic.sh script here.
2. To build HydrogenOS you should use OxygenOS:HydrogenOS as the system/firmware type name.
3. Some GSI may need for a patched surfaceflinger to boot. This is fixed now and ErfanGSI can patch surfaceflinger automatically when booting. If you get isHDRlayer error in logs or tombstone crash. Then you need to patch it, the tutorial is given here to patch it - Fixing isHDRlayer
4. ColorOS is not booting for most of the devices at this moment.

Channels for downloading GSIs

Erfan has stopped publishing OEM GSIs and he only posts Android R GSIs and Ubuntu Touch Port updated in his channel. There are some other guys who build GSIs with ErfanTool and post in their channels. I am linking some telegram channels here where you can find a lot of GSIs.
1. OEM GSIs
2. Nippon GSIs
3. Helios GSIs
4. Vega GSIs

Credits and Links

1. All credits goes to Erfan Abdi and other contributors at github.
2. Download links of already available GSIs: Lolinet
XDA thread
Telegram group
Telegram channel

If you need some help you can comment here.