Development Installing GSI by repacking super.img on SM-A127F and SM-A325F (Linux)

[uluruman]

repacksuper
===========
Copyleft uluruman 2021-2022

(for LINUX/WSL only)

This is the minimalistic set of tools + a script for Linux for the automated
ground-up repacking and flashing of the Samsung Galaxy super.img, replacing
the stock Android system with something much less intrusive and obtrusive
(e.g. LineageOS). Or just some other GSI (Generic System Image).

Additional included scripts (since v1.1) simplify flashing of stock firmware or
separate image files under Linux using Heimdall.

Theoretically should work for any Samsung A-series phones, and may be even for
some others. Tested on SM-A127F/DSN made in India and Vietnam and SM-A325F/DS
made in India, on Debian Linux 11 x64. There are reports of successful flashing
of SM-A127M, SM-A032M and SM-A226B.

Why this method?
----------------
Repacking of super.img is the only method which allows changing of the phone's
operating system without screwing up the Verified Boot (VB) protection
mechanism. Keeping the VB allows you to be sure that everything besides the
platform was indeed compiled by Samsung and wasn't tampered with, no matter from
where you downloaded your stock firmware.

The other reason is that although there are alternative methods of changing the
OS, for phones with dynamic partitioning and no working version of TWRP
available they may be even more complicated than repacking of super.img
externally by this script.

Requirements
------------
Install the following tools from the official repositories of your Linux distro:
simg2img xz-utils lz4 unzip gzip jq file

Basic instructions
------------------
repacksuper.sh: main script for changing your phone's operating system
heimdall_flash_stock.sh: script for flashing stock firmware under Linux
heimdall_flash.sh: script for flashing any custom image file under Linux
Just run a script without any arguments to see help.

Extra tools used (x64 binaries and sources included)
----------------------------------------------------

GitHub - LonelyFool/lpunpack_and_lpmake: android super.img tools

android super.img tools. Contribute to LonelyFool/lpunpack_and_lpmake development by creating an account on GitHub.

github.com

GitHub - amo13/Heimdall: Heimdall is a cross-platform open-source tool suite used to flash firmware (aka ROMs) onto Samsung Galaxy devices. This is a fork of the original repository with a few crucial pull requests merged.

Heimdall is a cross-platform open-source tool suite used to flash firmware (aka ROMs) onto Samsung Galaxy devices. This is a fork of the original repository with a few crucial pull requests merged....

github.com

Additional notes
----------------
The included binaries for the lpunpack, lpmake and Heimdall were compiled for
the x86_64 architecture. If your PC architecture is different (e.g. x86 32-bit
or ARM) you have to compile these tools yourself. The full source code is
included (or otherwise available on GitHub).

Spoiler: Changelog

0.9: Initial release

0.91: Non-sparse new system is now correctly moved into the super dir

0.91a: Bug in the new system file format checking fixed

0.91b: Better support for spaces in paths

0.92: Added checking for system requirements and an optional parameter for
setting of the final tar archive name.

0.92a: Fixed file ownership issues inside the tar distribution archive

0.93: Added support for SM-A325F. Several minor improvements.

0.94: Added support for gzip-packed GSI images. Packing into .tar is now done
without question if the command line parameter is given. Tar parameter
now can include the full path. Without the full path the default tar
location is now the same as the GSI. Several other minor changes.

1.0: Finally added working native Linux flashing using Heimdall (HUGE thanks
to amo13 and Benjamin Dobell). Two new options: using empty product.img
and silent (non-interactive) mode. Colored text. Bugfixes and minor
changes.

1.01: Option to specify the SUPER partition name manually (needed for flashing
SM-A127F with Heimdall). Now it is possible to place output .img and .tar
files in any directory and give them any name. Text terminology a bit
clarified, help text expanded. Done many internal optimizations,
additional sanity checks and minor changes.

1.02: Support for SM-A032F/M and similar firmwares with non-packed super.img.
Support for firmwares with/without additional partitions. Support for
arbitrary partition group names. Very experimental option to use empty
system_ext.img for additional privacy (applicable to some phone models/
regions). Lots of minor fixes.

1.03: Multiple .img files are now supported in GSI archive files (one of them
should be system.img in that case), e.g. Android AOSP zip files are now
supported directly. The logic of flashing with Heimdall now includes more
complex cases, such as flashing in two steps with a reboot. Unnecessary
code in GZ unpacking removed. Some other small fixes and optimizations.

1.1: New scripts heimdall_flash_stock.sh and heimdall_flash.sh added.
Lots of refactoring in repacksuper.sh (because of that there may be some
bugs left), improved and clarified UI logic, changes in where the files are
now placed (see help for details), direct work with stock Zip firmware
files, lots of minor changes.

1.11: Colored text now should be correctly displayed in almost any shell that
supports it except if it's explicitly disabled with NO_COLOR.

1.11.1: heimdall_flash.sh now can flash Super partitions unconditionally in one
step when using both the -s parameter and manually specifying parition
name (e.g. SUPER for SM-A127F).

1.12: The heimdall_flash_stock.sh script was significantly upgraded with lots of
new features. Now it theoretically allows upgrading of stock firmware
without erasing user data, keeping the GSI and custom recovery, etc.
(although it's not that straightforward, read the help for details).
A couple of fixes in the other scripts.

1.12.1: changed unlz4 to lz4 -d, as some distros don't have the needed symlink

1.13: In repacksuper.sh support added for the Vendor DLKM and ODM DLKM
partitions, as well as the experimental -v option to add or replace Vendor
DLKM with a custom image. A couple of minor fixes.

1.14: Greatly improved logic of heimdall_flash.sh, now it's possible to specify
both or either custom partition name and custom file name, and acquiring
PIT from device is done only when it's needed. Versioning scheme of the
scripts was unified: the script that was updated receives the updated
version number of the whole pack, the rest retain the old numbers.

1.15: up_param_tool.sh script was added: it allows altering of the boot
sequence images (logo, "not official" warning, etc.), as well as the
Recovery and Download internal graphics. Happy hacking, but please pay
attention to the warning displayed after extracting the JPEG files.
A couple of minor fixes in the other scripts.

1.15.1: Bug with failing LZ4 uncompression fixed in repacksuper.sh and
heimdall_flash_stock.sh.

1.15.2: Added the Ctrl+C trap in heimdall_flash_stock.sh, so now the temporarily
renamed files are correctly renamed back in case of flashing being
aborted with Ctrl+C. Upgraded Heimdall with the git pull requests, but
it seems those still do not cure the relatively rare issue when flashing
specific files gets completely stuck at some point.

1.15.3: The "file" tool used to identify PIT files was replaced with direct
reading of the file header as the first method proved to be unreliable.

1.15.4: Fixed a bug in heimdall_flash.sh (missing g flag in sed)

1.15.5: Fixed the compatibility issue with the older LZ4 compressors

1.15.6: Fixed compatibility issues with systems where /bin/sh is Bash, such as
ArchLinux

1.15.7: repacksuper.sh: fixed using the existing "repacksuper" dir as source,
also in this mode you can now specify "-" as new system image to reuse
everything inside the "super" subdir. New experimental -w parameter.
All scripts: the Ctrl+C trap now switched on and off the correct way.
Several other fixes.

1.15.8: Fixed using the heimdall_flash_stock dirs as source for repacksuper.sh.
A couple of other fixes.

1.15.9: heimdall_flash_stock.sh: fixed skipping of duplicate partitions (e.g.
vbmeta) for some shells; fixed upgrade-flashing of Galaxy A32 (default
behavior).

Spoiler: Known issues

During the script run you can see several "Invalid sparse file format at header
magic" warnings, just ignore them.

For some firmware files Heimdall may not work at all (freeze indefinitely or
exit with an error), in that case you have to resort to Odin. In many cases
Heimdall freezes when uploading files for some time, but that does not mean it
is completely frozen, just be patient.

In LineageOS, Dot OS and some other GSIs I tried on SM-127F the touch screen
remains not responsive for about 6 seconds after waking up. The problem is not
present at least with SM-127F/DSN phones made in India, but present at least in
those made in Vietnam. Another problem in the most, if not all, GSIs is that the
MTP USB file transfer does not work (at least on Linux) because of the "wrong"
(Samsung's instead of Google's) default MPT driver used by the kernel.

Both of the aforementioned problems can be solved by installing the fixed and
recompiled kernel.

For the last problem alternative solutions include using apps such as
Warpinator, Syncthing or ftpd.

Spoiler: Food for thought

When choosing a GSI to install I really don't recommend using ones which include
GApps and therefore use any of the Google services. Don't let corporations
gather your data. You bought the phone and from now on it should be all yours,
with all of its data, like a PC in the good old days. You own your device, and
nobody has the right to stick their nose into how you use your phone, gather any
statistics and push you any ads. You always have a choice to turn down
privacy-unfriendly stuff, the price of that "inconvenience" is actually
ridiculous. From my point of view, there is simply no point in using non-stock
systems if they are still littered with the privacy-unfriendly bloatware.

Older step-by-step guides are here and here. Also be sure to read this post concerning the importance of optics.img. Concerning the up_param_tool.sh be sure to read this post.

For repacking you will need the stock firmware. You can download it either from SamFw or using Samloader (if you'll figure out how to use it). I don't recommend using the popular shady closed-source utilities made by hackers as, for example, the popular Frija Tool is hosted on GitHub but none of its source code is published there, Samfirm tool looks open-source at first glance but includes several suspicious closed-source DLL files, etc. Downloading from SamFw should be safe as all the firmware data is signed and checked before flashing against the signatures of the previously flashed firmware.

The included binaries for the lpunpack, lpmake and Heimdall were compiled for the x86_64 architecture. If your PC architecture is different (e.g. x86 32-bit or ARM) you have to compile these tools yourself. The full source code is included (or otherwise available on GitHub).

 

[uluruman]

Latest stable combinations of stock firmware and LineageOS (updated February 5, 2023):

• SM-A127F: A127FXXU7BVI4 + LineageOS 20.0-td 20230115 arm64 bvS
• SM-A325F: A325FXXU2CVK3+ LineageOS 20.0-td 20230115 arm64 bvS

Some recommendations (updated February 5, 2023):

1. If you are a newbie and don't know how to do unlock the bootloader and other such stuff, here is a good guide by LAST_krypton (follow the "Unlocking the booloader" section) or a shorter guide by cldkrs.
2. First flash the phone with the whole set of stock firmware using the heimdall_flash_stock.sh (Linux only) script with the -d parameter: the latter forces flashing the unsafe partitions, which are needed for complete re-flashing.
3. If you're on Windows use Odin instead. Although there is a "leaked" Linux version of Odin, it's still closed-source (of course), so I don't recommend using it on your main Linux PC. For using the Windows version of Odin on Linux you have to either use Windows in QEMU (tested and works) or probably Wine (untested). When using QEMU remember to add the SUBSYSTEM=="usb", ATTRS{idVendor}=="04e8", ATTRS{idProduct}=="685d", MODE:="0666" line to the udev rules (e.g. /etc/udev/rules.d/30-qemu.rules) to enable the write access to the phone.
4. Sometimes Heimdall cannot flash the stock firmware and gets stuck at some particular file. Although you can successfully flash such a firmware using Odin, I recommend to better to find another firmware, may be one release older, because that may indicate some sort of incompatibility with your particular version of the phone.
5. The stock firmware comes in different revision numbers (also known as the baseband version), which are upgraded about once a year. Generally it should be beneficial to use the latest revision, but note that once you have upgraded it to a later revision there is no way back (at least known to me). In case you want to experiment with flashing of special kernels and other flavors provided by the XDA developers, if possible, you should probably stick to the very first revision.
6. If you already have the bootloader unlocked (OEM unlock) then after flashing the stock firmware there is no need to set up the Android, just go straight into the download mode again and flash the repacked super.img.
7. When downloading LineageOS or any other GSI select the normal arm64 bvS version, not vndklite version.
8. After flashing the OS go into the Recovery mode (hold volume up and power when rebooting) straight away and do the Factory reset. If you cannot get into the Recovery mode be sure to connect the USB cable before trying to.
9. If flashing with Heimdall completely freezes at some point make sure you've downloaded and repacked the correct arm64 b or a/b GSI and not arm and not a or a-only variant. If "sw rev check fail" message appears on the screen at some point just ignore it.
10. You can forcefully reboot your phone at any time, even if it seems bricked, by holding the volume down and power buttons for several seconds.
11. To upgrade your system to the recent version of the same OS just repackage it again using the same script and flash it normally. If the phone does not boot, get into the Recovery mode and try wiping the Cache partition (all your apps and settings should remain intact).
12. Most probably you don't need TWRP or any other 3rd party recovery tool at all, as the stock recovery tool works fine for just the factory reset after flashing the super file.
13. Try to avoid using Magisk if you just want to install another OS and nothing else. It is also not needed for LineageOS bvS version as it already has the su utility integrated, you just need to install the additional Superuser app by Pierre-Hugues HUSSON from the F-Droid store (although it's very old it works just fine).
14. It's possible that SM-127F/DSN internally is not A12 but actually M12, at least most of the tools and kernels made for M12 work on SM-127F/DSN while those made specifically for SM-125 and even other SM-127 versions do not. Therefore you can find more relevant info and tools in the corresponding XDA thread (my script is still remains relevant though).

 

[physwizz]

I should test this for a127f

 

[uluruman]

Bugs fixed: v0.91 & v0.91a

 

[uluruman]

Bug fixed: v0.91b

 

[uluruman]

Added the "file" utility to the list of requirements, updated readme.txt.

 

[IchZerowan]

Thanks A LOT, this works! I am finally able to run LineageOS on my phone!

For Windows 10+ users: WSL runs this script just fine with a few additional steps.
1. Install WSL 2 and any Linux distribution from Microsoft Store
2. Run the distribution to finish setup
3. Install the required packages from the post (sudo apt install for Ubuntu/Debian)
4. Shift + Right Click in the folder where you have the script, the AP and the GSI packages
5. Open Linux shell there
6. Unpack & run script as stated in its help

Voila!

 

[jadfa]

Wow ! Great job! I want to try it, but i'm getting many "Invalid sparse file format at header magic" while running the script, is it OK to flah the super.tar anyway?

 

[IchZerowan]

Wow ! Great job! I want to try it, but i'm getting many "Invalid sparse file format at header magic" while running the script, is it OK to flah the super.tar anyway?

It is totally OK

 

[uluruman]

Wow ! Great job! I want to try it, but i'm getting many "Invalid sparse file format at header magic" while running the script, is it OK to flah the super.tar anyway?

Yes, it is fine. These are just warnings produced by lpmake, they can not be suppressed. I could only suppress all the stdout/stderr from lpmake but it's no good in case of more serious warnings.

 

[uluruman]

Updated to v0.92 with a couple of minor improvements.

 

[ANDARXapi]

What should I do next with the raw file?
"Unknown super file format" is this how it should be?

 

[uluruman]

View attachment 5490897What should I do next with the raw file?
"Unknown super file format" is this how it should be?

Of course not. The format of each file is checked using the "file" utility, it should return the string "Android super image". Try to run file /home/toor/APfilles/super.stock.raw . What is the response? And try doing it all without sudo. There is no need in root privileges.

 

[ANDARXapi]

Of course not. The format of each file is checked using the "file" utility, it should return the string "Android super image". Try to run file /home/toor/APfilles/super.stock.raw . What is the response? And try doing it all without sudo. There is no need in root privileges.

The raw file opens as a picture

 

[ANDARXapi]

Of course not. The format of each file is checked using the "file" utility, it should return the string "Android super image". Try to run file /home/toor/APfilles/super.stock.raw . What is the response? And try doing it all without sudo. There is no need in root privileges.

run without sudo: 168: ./lpunpack_and_lpmake/lpunpack: Permission denied Cannot correctly unpack the super file. Exiting ...

 

[ANDARXapi]

I managed to fix the script, you just need to give chmod +x rights to the files in the folder "lpunpack_and_lpmake": lpunpack, lpmake, lpflash, lpdump, lpadd

 

[uluruman]

I managed to fix the script, you just need to give chmod +x rights to the files in the folder "lpunpack_and_lpmake": lpunpack, lpmake, lpflash, lpdump, lpadd

Hmmm. I have updated it, may be it'll help. Could you please test the latest version (v0.92a)? I want to work it out of the box for everyone, without sudo or any tweaks.

 

[ANDARXapi]

Hmmm. I have updated it, may be it'll help. Could you please test the latest version (v0.92a)? I want to work it out of the box for everyone, without sudo or any tweaks.

Okay, I'll test it tomorrow, today I want to relax at the computer all day

 

[ANDARXapi]

Hmmm. I have updated it, may be it'll help. Could you please test the latest version (v0.92a)? I want to work it out of the box for everyone, without sudo or any tweaks.

Checked, it works right away

 

[ANDARXapi]

Is there a way to install magisk and root?