Replicant

h1. XMMBoot

{{toc}}

h2.  Introduction

For both libsamsung-ipc and the Linux driver it's interesting to understand better the boot of the modem in order to come with good names for the abstraction.

h2. Abstraction

* hci_power -> link_power

TODO:

* Find the difference between power_on and boot_power_on

** Look at the GPIOs and understand what they do

** Just read the code that use the GPIOs

** Diff both procedures

* Look which device has which XMM626X

* Add XMM6210 devices too

h2. GPIOs

h3. Devices GPIOs assignement and drivers

|_\4. Hardware |_\2. Linux |_\1. libsamsung-ipc |

|_. Variant |_. SOC |_. Modem  |_. Link |_. GPIO usage |_. GPIO assignement |_. device driver name |

| Galaxy Tab:

  GT-P1000 | Exynos 3310 | | RAM | | | aries | 

| Galaxy S:

  GT-I9000 | Exynos 3110 | "XMM6160":https://www.wikidata.org/wiki/Q88838210#Q88838210$d5389045-4624-171a-18c5-ed1b15e1b3f5 | RAM | | | aries |

| Nexus S:

  GT-I9020

  GT-I9020A

  GT-I9023 | Exynos 3110 | | RAM | | | crespo |

| Galaxy SII:

  GT-I9100 | Exynos 4210 | XMM6260 | HSIC | "CONFIG_UMTS_MODEM_XMM6260=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9100_defconfig#n1321 | | galaxys2 |

| Galaxy Note:

  GT-N7000 | Exynos 4210 | XMM6260 | HSIC | "CONFIG_UMTS_MODEM_XMM6260=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_n7000_defconfig#n1330 | | galaxys2 |

| Galaxy Nexus:

  GT-I9250 | OMAP 4460 | XMM6260 | MIPI | "CONFIG_UMTS_MODEM_XMM6260=y":https://git.replicant.us/replicant/kernel_samsung_tuna/tree/arch/arm/configs/tuna_defconfig#n1209

                                          "Makefile":https://git.replicant.us/replicant/kernel_samsung_tuna/tree/drivers/misc/modem_if/Makefile#n10

                                          "modem_modemctl_device_xmm6260.c":https://git.replicant.us/replicant/kernel_samsung_tuna/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6260.c | | maguro |

| Galaxy SIII:

  GT-I9300 | Exynos 4412 | XMM6262 | HSIC | "CONFIG_UMTS_MODEM_XMM6262=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n1350

"Makefile":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/Makefile#n10

"modem_modemctl_device_xmm6262.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6262.c | "CONFIG_SEC_MODEM_M0=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n541

"Makefile":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/Makefile#n320

"board-m0-modems.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c 

"CONFIG_MACH_M0=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n455

"gpio-midas.h":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/include/mach/gpio-midas.h#n28

"gpio-rev00-m0.h":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/include/mach/gpio-rev00-m0.h | i9300 |

| Galaxy Note 8.0 GSM:

  GT-N5100 | Exynos 4412 | XMM6262 | HSIC | "CONFIG_UMTS_MODEM_XMM6262=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_n5100_defconfig#n1335 | | n5100 |

| Galaxy Note II:

  GT-N7100 | Exynos 4412 | XMM6262 | HSIC | "CONFIG_UMTS_MODEM_XMM6262=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_n7100_defconfig#n1356 | | n7100 |

| Galaxy Tab 2:

  GT-P3100 

  GT-P5100 | OMAP 4430 | XMM6262 | MIPI | "CONFIG_UMTS_MODEM_XMM6262=y":https://git.replicant.us/replicant/kernel_samsung_espresso10/tree/arch/arm/configs/espresso_defconfig#n224 | | piranah |

h3. GPIOs usage

TODO: make sure to mention what applies to what device

* Start with I9300. Assume I9300 if device is not mentioned. Mention device when not I9300

* Add more devices and mention them

Note that we don't limit ourselves to the drivers that are in use on the devices supported by Replicant.

As Samsung wrote drivers for the modem interfaces, and that the interface is similar across many different modems, other unused drivers and their comments also gives many hints about what the GPIOs are supposed to be used for.

|_. gpio platform data name |_. present |_. absent |_. Implementation |_. comments |

| "gpio_cp_on":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | powers on the modem? in which state (PMIC?, CPU?)

                     * On GT-I9100 it's connected to the ON1 modem pin and ON2 is not connected. |

| "gpio_cp_reset":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | Resets the modem CPU? PMIC?:

                        * "''check the reset timming with C2C connection''":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6262.c#n106 : Here C2C probably means chip to chip

                        Can also read the modem CPU? and/or PMIC? reset state?

                        * "Reads from the GPIO and ''CP not ready, Active State low'' comment":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n287 |

| "gpio_reset_req_n":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | |

| "gpio_pda_active":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | Tell the modem if the SOC CPUs are sleeping/active or not?

                          * "PDA == Application processor":https://android.stackexchange.com/questions/176515/what-do-the-terms-bl-ap-cp-and-csc-mean-in-odin

                          * "''PDA_ACTIVE, let cp know AP sleep'' comment in status gc1-gpio.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/gc1-gpio.c#n213

                          * "PDA_ACTIVE set to 0 right after cpu_pm_enter()":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/cpuidle-exynos4.c#n701

                          * "PDA_ACTIVE set to 1 right before cpu_pm_exit()":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/cpuidle-exynos4.c#n796

                          * GPIO direction is output on AP side and input on BP side, which is also confirmed by the "pinout table in XDA":https://forum.xda-developers.com/galaxy-s2/help/how-to-talk-to-modem-commands-t1471241/page4

                          Also indicates when the CPU is ready to process modem stuff:

                          * "set to 1 *at the end* of xmm6262_on in modem_modemctl_device_xmm6262.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6262.c#n68

                          * The CPU can't process stuff if the HSIC link is in low power mode, "as shown in set_hsic_lpa_states in board-m0-modems.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n310 so it sets gpio_pda_active to 0 in these cases. |

| "gpio_phone_active":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | Seem the modem counterpart of gpio_pda_active:

                            * See "umts_link_reconnect in board-m0-modems.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n341

                            * See also "mc_work in the unused modemctl.c driver":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/svnet/modemctl.c#n484 where that GPIO is used both to signal when the modem finished booting everything and is ready, and when the modem crashes or is reset 

                            * "phone_active_irq_handler in modem_modemctl_device_xmm6262.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6262.c#n139 seem to be doing exactly the same thing. |

| "gpio_cp_dump_int":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | |

| "gpio_flm_uart_sel":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 |\2. Only used for the Galaxy Nexus in libsamsung-ipc | | Modem download mode ? 

                                                                                                                                                                                         * FLM could be Firmware Load mode ?

                                                                                                                                                                                         * On several devices, that GPIO seem to be used to switch between different UART, and the PMIC seem involved too in some devices. Not sure how it switches |

| "gpio_cp_warm_reset":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | |

| gpio_revers_bias_clear | | | | |

| gpio_revers_bias_restore | | | | |

| "gpio_sim_detect":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n251 | | | | Detect SIM card presence ? |

| "gpio_link_enable":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n112 | | | | |

| "gpio_link_active":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n112 | | | | set to 0 when the (HSIC) link is in low power and to 1 when it's back, "like in set_hsic_lpa_states in board-m0-modems.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n304 |

| "gpio_link_hostwake":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n112 | | | | |

| "gpio_link_slavewake":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/include/linux/platform_data/modem.h#n112 | | | | |

h3. Libsamsung-ipc

|/2. ioctl / function |\8. Devices |

| GT-I9250 | GT-I9100 / GT-N7000 | GT-I9300 | GT-N5100 | GT-N7100 | GT-P3100 / GT-P5100 | Galaxy S (GT-I9000) / Galaxy Tab  | Nexus S (GT-I902x) |

| libsamsung-ipc driver | maguro | galaxys2 | i9300 | n5100 | n7100 | piranah | aries | crespo |

| open, close, read, write 

fmt/rfs

gprs

power |\6. Yes |

| boot_power

status_online_wait | Yes |\5. No |/3\2. No |

| hci_power

link_control_active

link_connected_wait

link_get_hostwake_wait |/2. No |\4. Yes |/2. No |

| link_control_enable | Yes (ignored by Linux[4][5][6]) |\3. Yes (ignored by Linux[1][2][3]) |

| psi_send | xmm626_mipi_psi_send |\4. xmm626_hsic_psi_send | xmm626_mipi_psi_send |\2. xmm616_psi_send | 

| firmware_send | xmm626_mipi_firmware_send |\4. xmm626_hsic_firmware_send | xmm626_mipi_firmware_send |\2. xmm616_firmware_send | 

| nv_data_send | xmm626_mipi_nv_data_send |\4. xmm626_hsic_nv_data_send | xmm626_mipi_nv_data_send |\2. xmm616_nv_data_send | 

TODO:

* Don't use abbreviated function names

fn1. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n221

fn2. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n218

fn3. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n136

fn4. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-u1-modems.c#n153

fn5. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-u1-modems.c#n151

fn6. https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-u1-modems.c#n139

h3. libsamsung-ipc <-> kernel functions <-> gpios

|_. libsamsung-ipc |_\3. Kernel |

|_. Function using the ioctl |_. ioctl name |_. pointer signature |_. GPIO used | comment |

| xmm626_kernel_smdk4412_power | IOCTL_MODEM_ON

                                 IOCTL_MODEM_OFF | <pre>int (*modem_on)(struct modem_ctl*);</pre>

                                                   <pre>int (*modem_off)(struct modem_ctl*);</pre> | gpio_cp_on

                                                                                      gpio_cp_reset

                                                                                      gpio_reset_req_n

                                                                                      gpio_pda_active |

| | | | gpio_phone_active |

| | | | gpio_cp_dump_int |

| xmm626_kernel_smdk4412_boot_power | IOCTL_MODEM_BOOT_ON

                                      IOCTL_MODEM_BOOT_OFF | <pre>int (*modem_boot_on)(struct modem_ctl*);</pre>

                                                             <pre>int (*modem_boot_off)(struct modem_ctl*);</pre> | gpio_flm_uart_sel |

| | | | gpio_cp_warm_reset |

| | | | gpio_revers_bias_clear |

| | | | gpio_revers_bias_restore |

| | | | gpio_sim_detect |

| xmm626_kernel_smdk4412_status_online_wait | IOCTL_MODEM_STATUS | int phone_state; | gpio_cp_on

                                                                                      gpio_cp_reset

                                                                                      gpio_pda_active

                                                                                      gpio_reset_req_n

                                                                                      gpio_phone_active | int phone_state get assigned the status computed from the various GPIO states

                                                                                                          xmm626_kernel_smdk4412_status_online_wait only waits for the online status    |

| xmm626_kernel_smdk4412_link_control_enable | IOCTL_LINK_CONTROL_ENABLE | <pre>int (*link_ldo_enable)(bool);</pre> | gpio_link_enable | on i9300:

                                                                                                                                        * link_ldo_enable only returns 0 and has a comment ("Exynos HSIC V1.2 LDO was controlled by kernel")

                                                                                                                                        * gpio_link_enable is set to 0 (so it's ignored) |

h3. Glossary

Terms for the modem CPU:

* BP: Baseband processor

* CP: Cellular? processor

Term for the CPU of the system on a chip running Replicant:

* AP: Application processor

TODO: move in its own page and point to it

LPA: Low power mode active (Related to ULPI specs only?)

ULPI: Probably a USB PHY spec

h3. SIM card presence detection

Do we really want to check the SIM card presence?

Would it be possible not to for privacy reasons?

Example:

* Boot a modem with a SIM

* Take away the SIM card

* Go to a protest with only the SIM card and a phone with no data on it to be able to call if necessary.

h3. TODO

* check gpio_flm_uart_sel in smdk4412 kernel too

h2. Potential privacy and security issues

h3. gpio_pda_active

From "cpuidle-exynos4.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/cpuidle-exynos4.c#n701 we have things like that:

<pre>

	cpu_pm_enter();

#if defined(CONFIG_INTERNAL_MODEM_IF) || defined(CONFIG_SAMSUNG_PHONE_TTY)

	gpio_set_value(GPIO_PDA_ACTIVE, 0);

#endif

	if (log_en)

		pr_debug("+++lpa\n")

</pre>

and:

<pre>

	if (log_en)

		pr_debug("---lpa\n");

#if defined(CONFIG_INTERNAL_MODEM_IF) || defined(CONFIG_SAMSUNG_PHONE_TTY)

	gpio_set_value(GPIO_PDA_ACTIVE, 1);

#endif

	cpu_pm_exit();

</pre>

Does it means that we are telling the modem about each time we go in suspend to RAM?

Devices affected or not affected:

|_. Device |_. Config |

| GT-I9300 | "# CONFIG_INTERNAL_MODEM_IF is not set":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n1373

             "# CONFIG_SAMSUNG_PHONE_TTY is not set":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n3039 |

h3. gpio_phone_active 

From "ehci-s5p.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/usb/host/ehci-s5p.c#n129 we have things like that:

<pre>

#if defined(CONFIG_UMTS_MODEM_XMM6262)

	if (pdata->get_cp_active_state && !pdata->get_cp_active_state()) {

		s5p_ehci_port_control(pdev, CP_PORT, 0);

		pr_err("mif: force port%d off by cp reset\n", CP_PORT);

	}

#endif

</pre>

Does it allows the modem to trigger a re-enumeration of the HSIC bus?

Devices affected or not affected:

|_. Device |_. Config |

| GT-I9300 | "CONFIG_UMTS_MODEM_XMM6262=y":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/configs/lineageos_i9300_defconfig#n1350

             ".gpio_phone_active = GPIO_PHONE_ACTIVE":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/arch/arm/mach-exynos/board-m0-modems.c#n241 |

h2. Modem partitions

|_. Name |_. Content |_. aries |_. crespo |_. GT-I9100 |_. GT-N7000 |_. GT-I9250 |_. GT-I9300 |_. GT-N7100 |_. GT-P3100 |_. GT-P5100 |_. GT-N5100 |

| ? | Partition table |\5. None |\3. [ 0x0 -> 0xfff ] | TODO |TODO |

| PSIRAM | First stage bootloader |\2. [ 0x0-> 0x4fff ] |\3. [ 0x0 -> 0xefff ] |\5. [ 0x1000 -> 0xefff ] |

| EBL | Second stage bootloader ? | | |\8. [ 0xF000 -> 0x27fff ] |

| MAIN | ? | | |\3. [ 0x28000 -> 0x9fffff ] |\5. [ 0x28000 -> 0x9ff7ff ] |

| SECPACK | ? | | |\8. [ 0x9ff800 -> 0x9fffff ] |

| NV | nvdata default values | [ 0xD80000 -> ? ] | [0xD80000 -> ? ] |\8. [ 0xa00000 -> 0xbfffff ] |

TODO: find the place in libsamsung-ipc source mentioning that

References for the table:

* https://git.replicant.us/replicant/external_libsamsung-ipc/tree/samsung-ipc/devices/i9300/i9300.h?id=9ff9785a7f48e32f107ca7fb2e298b1320ad4cbc

* https://git.replicant.us/replicant/external_libsamsung-ipc/tree/samsung-ipc/devices/n7100/n7100.h?id=9ff9785a7f48e32f107ca7fb2e298b1320ad4cbc

* Verified on GT-I9300 and GT-N7100 modem partition table

h4. GT-I9300, GT-N7100, GT-P3100 modem partition table dump

TODO:

* Send patch for the "modem-partition-tool#n33":https://git.replicant.us/contrib/GNUtoo/hardware_replicant_libsamsung-ipc/tree/tools/modem-image-tool.c?h=patches-todo/modem-partition-tool#n33

* Make sure that we know the device from the command line

* Understand the field depths along the way when supporting more devices

* Document all other devices that don't have this partition table

* Find the name of this partition table

<pre>

$ hexdump -C RADIO.img

00000000  50 53 49 52 41 4d 00 00  00 00 00 00 00 10 00 00  |PSIRAM..........|

00000010  00 00 00 00 00 e0 00 00  00 00 00 00 00 00 00 00  |................|

00000020  45 42 4c 00 00 00 00 00  00 00 00 00 00 f0 00 00  |EBL.............|

00000030  00 00 00 60 00 90 01 00  00 00 00 00 00 00 00 00  |...`............|

00000040  4d 41 49 4e 00 00 00 00  00 00 00 00 00 80 02 00  |MAIN............|

00000050  00 00 30 60 00 78 9d 00  00 00 00 00 00 00 00 00  |..0`.x..........|

00000060  53 45 43 50 41 43 4b 00  00 00 00 00 00 f8 9f 00  |SECPACK.........|

00000070  00 00 00 00 00 08 00 00  00 00 00 00 00 00 00 00  |................|

00000080  4e 56 00 00 00 00 00 00  00 00 00 00 00 00 a0 00  |NV..............|

00000090  00 00 e8 60 00 00 20 00  00 00 00 00 00 00 00 00  |...`.. .........|

000000a0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

*

[...]

</pre>

h3. Devices with a different partition table

* The devices with a Qualcomm modem like the GT-I9305 and the GT-N7105 have individual files inside the vfat modem partition. See the "Samsung_Midas_4G":https://osmocom.org/projects/quectel-modems/wiki/Samsung_Midas_4G on the quectel-modems osmocom project for more details.

h3. Unknown

We would need to get a device and dump the modem firmware to check, but given the offset of the PSIRAM, it probably contains the same header:

* Galaxy Note 8.0

* GT-P5100 is untested but but it's probably similar to the GT-P3100

h2. Links

* "modem_modemctl_device_xmm6262.c":https://git.replicant.us/replicant/kernel_samsung_smdk4412/tree/drivers/misc/modem_if/modem_modemctl_device_xmm6262.c

* https://forum.xda-developers.com/galaxy-s2/help/how-to-talk-to-modem-commands-t1471241/page4

* http://www.arteris.com/blog/bid/59433/Interchip-Connectivity-HSIC-UniPro-HSI-C2C-LLI-oh-my

** TODO: move this link somewhere where it's more useful