k3-bootswitch: Initial version for boot selection script
[glsdk/host-tools.git] / k3-bootswitch / README.rst
1 K3-bootswitch tool
2 ==================
4 This tool allows to boot the J7-EVM in any boot mode from command line.
5 This is useful for controlling the board remotely for individual developers
6 as well as test farm.
8 Hardware setup
9 --------------
11 * Type-C cable should be connected from the board to the Linux PC
12 * UART cable should be connected from the main_uart to Linux PC
13 * Default switch settings should be for DFU boot mode
14 * SW8 = 1000 0000    SW9 = 0010 0000    SW3 = 0101 00 1010
15 * Power supply to the board should be connected via phidget USB relay
17 Usage
18 -----
20 * Install dfu-util package on the Linux PC with
21     ``sudo apt-get install dfu-util``
22 * To boot the board in MMC bootmode, run following
23     ``sudo ./dfu-util.sh --bootmode mmc``
25   Currently supported bootmodes are: **mmc, emmc, ospi, uart, noboot**
27 * To mount the emmc from the board to the Linux PC, run following
28     ``sudo ./dfu-util.sh --mount 0``
29 * To mount the SD card from the board to the Linux PC, run following
30     ``sudo ./dfu-util.sh --mount 1``
33 Advantages
34 ----------
36 * Allows to remotely control the board by eliminating need to physically
37   change the switch settings
38 * Can be used for regular development flow, where it removes the need
39   to physically plug out the SD card for updating images.
40 * Makes it very easy to partition, format and update contents of the
41   eMMC device.
42 * Can be used for factory flashing of the OSPI/eMMC images using
43   automated scripts
45 How it works
46 ------------
47 The DFU bootmode allows to pass any custom bootloader to the board. By keeping
48 the switch settings in DFU mode, board always waits for the Linux PC to send
49 a bootloader. In J721E SoC, the BOOTMODE and MCU_BOOTMODE registers reflect the
50 values of the boot switches at the cold boot. This register can be modified and
51 the values written are retained through the warm reset. These two features
52 allows to set the bootmode from the command line PC tool.
54 In the **boot_select** directory of this tool, there are many files which act
55 as the custom bootloader every time the board boots with DFU-boot mode.
56 The custom bootloader does only two important things; First it overwrites the
57 BOOTMODE and MCU_BOOTMODE registers to change to the desired boot mode and then
58 it issues a soft reset to the SoC causing it to boot the second time with new
59 bootmode.
61 All of this happens very fast when run from a script that it does not add
62 considerable amount of time for developer bootflow.
64 The mount of SD card or eMMC is achieved using the u-boot's
65 UMS (USB Mass Storage) feature. In this case, the tool sends a real R5 u-boot as
66 bootloader, System firmware ITB, A72 u-boot images and then runs the ums command.
67 Note that all the binaries are being sent from the Linux PC, so there is
68 absolutely no dependency on the contents of SD card.
71 Customization
72 -------------
74 Default setup assumes most common setup for J7EVM. In case you are using
75 differnent mechanism, update the **dfu-boot.sh** script with following:
77 * Update the **uart_dev** variable to reflect the correct tty device
78   for main uart. (The one where all u-boot/SBL/kernel logs appear)
79 * Update the function **toggle_power** to use your custom method to toggle_power
80   remote power switch instead of the default phidget commands
84 Limitatinos
85 -----------
87 * Do not use this mechanism to measure any boot time numbers
88 * The bootloader images are specific to TI J7 EVM. Different images are required
89   to be able to mount the SD/eMMC from custom boards