How to customize OpenSTDroid distribution

Applicable for

This articles explain how you can customize the OpenSTDroid distribution. It's intent to be used by distribution package users.

1. Prerequisites[edit source]

The environment used must have been installed using the Distribution Package adapted to your microprocessor device. See Distribution_Package.

To execute the following instructions, go to your distribution root directory and initialize your environment:

 source build/envsetup.sh
 lunch aosp_<BoardId>-userdebug

Example for STM32MP257F-EV1 Evaluation board :

 lunch aosp_eval-userdebug

2. Layout configuration[edit source]

The memory layout can be configure through the android_layout.config file located in device/stm/<STM32Series>/layout (example: device/stm/stm32mp2/layout for STM32MP2 series). It contains all the necessary data.

When changes are complete, reload the environment:

 source build/envsetup.sh
 lunch aosp_<BoardId>-userdebug

Example for STM32MP257F-EV1 Evaluation board :

 lunch aosp_eval-userdebug

2.1. Memory type[edit source]

By default, the eMMC memory is used.

As the embedded eMMC memory size is not always big enough, it's possible to enable an hybrid configuration where:

eMMC is used for read-only partitions (system)
microSD card is used for read-write partitions metadata and userdata

To select this hybrid configuration, you have to update the device/stm/<STM32Series>/<STM32Boards>/aosp_<STM32Boards>.mk :

BOARD_DISK_HYBRID ?= true

In this condition, all scripts used to flash the device must be used with --hybrid option.

2.2. Memory size[edit source]

To adapt your build to your memory size, change the PART_MEMORY_SIZE parameter in the android_layout.config file. PART_MEMORY_SIZE values can be:

4GiB (4 Gbytes)
8GiB (8 Gbytes)

Its value must match the parameter of name PART_<Memory size>_MEMORY_MAX_SIZE, located at the end of the file.

It might need to be changed. For example, if the memory type was "sd" (microSD card):

PART_8GiB_MEMORY_MAX_SIZE 7432M x1 sd

The 7432M must be adapted if your memory size is lower that the value defined.

To find the correct value, execute the command below:

 sgdisk -p /dev/mmcblk<x>

It displays the following information:

Disk /dev/mmcblk0: 15433728 sectors, 7.4 GiB
Logical sector size: 512 bytes
Disk identifier (GUID): XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 15433694
Partitions will be aligned on 2-sector boundaries
Total free space is 0 sectors (0 bytes)

The first line show the microSD card available size: here 15433728 sectors.

To calculate the size in MiB (Mbytes):

size = (NbSectors * SectorSize) / 1024 / 1024
In this example: (15433728 * 512) / 1024 / 1024 = 7536 MiB

Report this value in PART_8GiB_MEMORY_MAX_SIZE:

PART_8GiB_MEMORY_MAX_SIZE 7536M x1 sd

For more details, refer to the README file located in the same folder.

2.3. Partition size[edit source]

To change the size of a partition, modify it in the android_layout.config file.

Adapt the following parameters:

PART_<NAME> <PART_SIZE> <PART_NB> <PART_LABEL> <PART_SUFFIX> <PART_ENABLE>
NAME: name of the local variable (last partition MUST start with PART_LAST_)
PART_SIZE: as xxxMB or xxxKB or xxxGB
PART_NB: number of instances of partition (x1 or x2)
PART_LABEL: name of the partition label
PART_SUFFIX (optional): name of the suffix in case PART_NB equal x2 (_a/_b by default)
PART_ENABLE (optional): device for which the partition is only applicable (sd)

Then adapt every FlashLayout_*.tsv under device/stm/<STM32Series>/layout/programmer (example: device/stm/stm32mp2/layout/programmer/ for STM32MP2 series) to match your changes.

To do this, use the device/stm/<STM32Series>/scripts/layout/build_tsv.py script (example: device/stm/stm32mp2/scripts/layout/build_tsv.py for STM32MP2 series).

2.4. Add a new partition[edit source]

To add a new partition (ex: named test), first add it in the android_layout.config file.

Add the following parameters:

PART_TEST <PART_SIZE> <PART_NB> test <PART_SUFFIX> <PART_ENABLE>

PART_SIZE: as xxxMB or xxxKB or xxxGB
PART_NB: number of instances of partition (x1 or x2)
PART_SUFFIX (optional): name of the suffix in case PART_NB equal x2 (_a/_b by default)
PART_ENABLE (optional): device for which the partition is only applicable (sd)

From this stage, the format_device and provision_device scripts can be used to flash the new partition (an image, named test.img must be available in the out/target/product/<BoardId> directory (example out/target/product/eval for STM32MP257F-EV1 Evaluation board ).

Then adapt device/stm/<STM32Series>/scripts/layout/build_tsv.py script (example: device/stm/stm32mp2/scripts/layout/build_tsv.py for STM32MP2 series):

add PART_TEST in android_allowed_part list
add "test": {"opt": "PE", "type": "FileSystem\t", "id": None}, in the tsv_dict dictionary

The partition type (FileSystem in the example) can be adapted depending on your needs: see more details in the flashlayout partition types.

Finally adapt every FlashLayout_*.tsv under device/stm/<STM32Series>/layout/programmer to match your changes (example: device/stm/stm32mp2/layout/programmer/FlashLayout_*.tsv for STM32MP2 series).

To do this, use the updated device/stm/<STM32Series>/scripts/layout/build_tsv.py script.

From this stage, the flash-device script can be used.

3. Modification of the OpenSTDroid distribution[edit source]

The list of changes performed during the <STM32Series>setup (example: stm32mp2setup for STM32MP2 series) can be adapted by modifying the android_patch.config available in device/stm/<STM32Series>/patch/android/ file (example: device/stm/stm32mp2/patch/android/android_patch.config for STM32MP2 series).

First retrieve the original configuration:

 <STM32Series>clear -p

Then adapt the file (add or/and remove list of commits and patches).

Some rules must be respected for adding patches:

Patch files shall be added with the relative path to device/stm/<STM32Series>/patch/android/ directory.
Patches shall be added in the correct order.

Some rules must the respected for removing patches:

Test the new configuration on the targeted directory by applying the patches manually (generate them again if required).
Do not remove patches and commits with do not modify mention.

When this is done, apply the new configuration:

 <STM32Series>setup

Then rebuild the distribution to take into account your changes:

 make -j