├── LICENSE.md ├── OP-TEE └── OP-TEE.md ├── README.md ├── android ├── ANDROID-Build.md ├── ANDROID-Flash.md ├── INTEGRATION.md └── STATUS.md └── debian ├── debian_build_instructions.md ├── debian_installation.md └── debian_recovery.md /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Licence 2 | 3 | Unless otherwise specified, everything in this repository is covered by the following licence: 4 | 5 | [![Creative Commons Licence](https://licensebuttons.net/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 6 | 7 | ***96Boards Documentation*** by the [96Boards](https://www.96boards.org/) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/). 8 | 9 | Based on a work at https://github.com/96Boards/documentation 10 | -------------------------------------------------------------------------------- /OP-TEE/OP-TEE.md: -------------------------------------------------------------------------------- 1 | # Build and Run OP-TEE on Poplar 2 | 3 | Before trying to build and run OP-TEE on Poplar, please read and complete the 4 | [instructions](../debian/debian_build_instructions.md) for general setup of working 5 | directory, toolchain and installation. 6 | 7 | ## Get the source code 8 | 9 | ```shell 10 | cd ${TOP} 11 | git clone https://github.com/OP-TEE/optee_os 12 | git clone https://github.com/OP-TEE/optee_client 13 | git clone https://github.com/OP-TEE/optee_test 14 | ``` 15 | ## Build OP-TEE OS 16 | 17 | The result of this process will be a file `tee-pager.bin` that will 18 | be incorporated into a FIP file created for ARM Trusted Firmware code. 19 | 20 | ```shell 21 | cd ${TOP}/optee_os 22 | rm -rf out 23 | 24 | make PLATFORM=poplar CFG_ARM64_core=y CROSS_COMPILE=${CROSS_32} \ 25 | CROSS_COMPILE_core=${CROSS_64} CROSS_COMPILE_ta_arm64=${CROSS_64} \ 26 | CROSS_COMPILE_ta_arm32=${CROSS_32} CFG_TEE_CORE_LOG_LEVEL=2 27 | 28 | # Option CFG_DRAM_SIZE_GB=1 is there for board with 1GB DDR. For 2GB board, 29 | # simply drop the option. 30 | make PLATFORM=poplar CFG_ARM64_core=y CROSS_COMPILE=${CROSS_32} \ 31 | CROSS_COMPILE_core=${CROSS_64} CROSS_COMPILE_ta_arm64=${CROSS_64} \ 32 | CROSS_COMPILE_ta_arm32=${CROSS_32} CFG_TEE_CORE_LOG_LEVEL=2 \ 33 | CFG_DRAM_SIZE_GB=1 34 | ``` 35 | 36 | ## Build ARM Trusted Firmware with OP-TEE OS included 37 | 38 | To build ARM Trusted Firmware with OP-TEE OS included, build options "SPD" and 39 | "BL32" need to be set up properly. The following example builds u-boot and 40 | OP-TEE OS built above into ARM Trusted Firmware. 41 | 42 | ```shell 43 | cd ${TOP}/arm-trusted-firmware 44 | make distclean 45 | make CROSS_COMPILE=${CROSS_64} all fip DEBUG=1 PLAT=poplar SPD=opteed \ 46 | BL33=${TOP}/u-boot/u-boot.bin \ 47 | BL32=${TOP}/optee_os/out/arm-plat-poplar/core/tee-header_v2.bin \ 48 | BL32_EXTRA1=${TOP}/optee_os/out/arm-plat-poplar/core/tee-pager_v2.bin \ 49 | BL32_EXTRA2=${TOP}/optee_os/out/arm-plat-poplar/core/tee-pageable_v2.bin 50 | ``` 51 | 52 | ## Build "l-loader" with OP-TEE OS included 53 | 54 | Follow the instructions in [Step 3: Build "l-loader"](../debian/debian_build_instructions.md#step-3-build-l-loader) section of [debian_build_instructions.md](../debian/debian_build_instructions.md). 55 | 56 | ## Build image file with OP-TEE OS 57 | 58 | ```shell 59 | cd ${TOP}/recovery 60 | cp ${TOP}/l-loader/l-loader.bin . 61 | bash ./poplar_recovery_builder.sh loader 62 | ``` 63 | 64 | ## Copy image file with OP-TEE OS to the TFTP home directory 65 | 66 | Follow the instructions in [Step 7: Copy image files to the TFTP home directory](../debian/debian_build_instructions.md#step-7-copy-image-files-to-the-tftp-home-directory) section of [debian_build_instructions.md](../debian/debian_build_instructions.md). 67 | 68 | ## Flash image with OP-TEE OS onto the Poplar board eMMC 69 | 70 | Follow the instructions in the [Flash images onto the Poplar board eMMC](../debian/debian_build_instructions.md#flash-images-onto-the-poplar-board-emmc) section of [debian_build_instructions.md](../debian/debian_build_instructions.md). 71 | 72 | After `reset`, you should have now booted your Poplar board with an image that 73 | supports OP-TEE OS. 74 | 75 | ## Test OP-TEE 76 | 77 | ### Step 1: Build OP-TEE client 78 | 79 | ```shell 80 | cd ${TOP}/optee_client 81 | rm -rf out 82 | make CROSS_COMPILE=${CROSS_64} 83 | ``` 84 | 85 | ### Step 2: Build OP-TEE test 86 | 87 | ```shell 88 | cd ${TOP}/optee_test 89 | rm -rf out 90 | make CROSS_COMPILE_HOST=${CROSS_64} CROSS_COMPILE_TA=${CROSS_32} \ 91 | TA_DEV_KIT_DIR=${TOP}/optee_os/out/arm-plat-poplar/export-ta_arm32 \ 92 | OPTEE_CLIENT_EXPORT=${TOP}/optee_client/out/export 93 | ``` 94 | 95 | ### Step 3: Build OP-TEE Debian package 96 | 97 | ```shell 98 | export OPTEE_PKG_VERSION=$(cd ${TOP}/optee_os && git describe)-0 99 | 100 | cd ${TOP} 101 | mkdir -p debpkg/optee_${OPTEE_PKG_VERSION}/usr/bin 102 | mkdir -p debpkg/optee_${OPTEE_PKG_VERSION}/usr/lib/aarch64-linux-gnu 103 | mkdir -p debpkg/optee_${OPTEE_PKG_VERSION}/lib/optee_armtz 104 | mkdir -p debpkg/optee_${OPTEE_PKG_VERSION}/DEBIAN 105 | 106 | cd ${TOP}/debpkg/optee_${OPTEE_PKG_VERSION}/usr/bin 107 | cp -f ${TOP}/optee_client/out/export/bin/tee-supplicant . 108 | cp -f ${TOP}/optee_test/out/xtest/xtest . 109 | 110 | cd ${TOP}/debpkg/optee_${OPTEE_PKG_VERSION}/usr/lib/aarch64-linux-gnu 111 | cp -f ${TOP}/optee_client/out/export/lib/libtee* . 112 | 113 | cd ${TOP}/debpkg/optee_${OPTEE_PKG_VERSION}/lib/optee_armtz 114 | find ${TOP}/optee_test/out/ta -name "*.ta" -exec cp {} . \; 115 | 116 | cd ${TOP}/debpkg/optee_${OPTEE_PKG_VERSION}/DEBIAN 117 | echo "Package: op-tee" > control 118 | echo "Version: ${OPTEE_PKG_VERSION}" >> control 119 | echo "Section: base" >> control 120 | echo "Priority: optional" >> control 121 | echo "Architecture: arm64" >> control 122 | echo "Depends:" >> control 123 | echo "Maintainer: OP-TEE " >> control 124 | echo "Description: OP-TEE client binaries, test program and Trusted Applications" >> control 125 | echo " Package contains tee-supplicant, libtee.so, xtest and a set of" >> control 126 | echo " Trusted Applications." >> control 127 | echo " NOTE! This package should only be used for testing and development." >> control 128 | 129 | cd ${TOP}/debpkg 130 | dpkg-deb --build optee_${OPTEE_PKG_VERSION} 131 | cp -f optee_${OPTEE_PKG_VERSION}.deb ${TOP}/recovery/recovery_files/ 132 | ``` 133 | 134 | ### Step 4: Install OP-TEE Debian package 135 | Boot board to command prompt. 136 | Run `ifconfig` and note its IP address. 137 | 138 | From the PC: 139 | 140 | ```shell 141 | cd ${TOP}/recovery/recovery_files 142 | scp optee_${OPTEE_PKG_VERSION}.deb linaro@:/tmp 143 | ``` 144 | 145 | From the board: 146 | 147 | ```shell 148 | cd /tmp 149 | dpkg --force-all -i optee*.deb 150 | ``` 151 | 152 | ### Step 5. Run OP-TEE test 153 | From the board: 154 | 155 | ```shell 156 | tee-supplicant & 157 | xtest 158 | ``` 159 | 160 | Towards the end of the test, you should see something like: 161 | 162 | ```shell 163 | +----------------------------------------------------- 164 | Result of testsuite regression: 165 | regression_1001 OK 166 | regression_1002 OK 167 | ... 168 | regression_8002 OK 169 | +----------------------------------------------------- 170 | 15677 subtests of which 0 failed 171 | 68 test cases of which 0 failed 172 | 0 test case was skipped 173 | ``` 174 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Using the Poplar 2 | 3 | A comprehensive guide to using [Poplar](https://www.96boards.org/product/poplar/) Consumer Edition development board. 4 | 5 | ## Documentation 6 | 7 | - [Debian](debian/) 8 | 9 | Describes how to download, build, install and recover Debian on the Poplar 10 | board. 11 | 12 | - [Android](android/) 13 | 14 | Describes how to download, build, and install Android on the Poplar board. 15 | 16 | ## License 17 | 18 | Unless otherwise specified, everything in this repository is covered by the following licence: 19 | 20 | [![Creative Commons Licence](https://licensebuttons.net/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 21 | 22 | ***96Boards Documentation*** by [96Boards](https://www.96boards.org/) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/). 23 | 24 | Based on a work at https://github.com/96Boards/documentation 25 | -------------------------------------------------------------------------------- /android/ANDROID-Build.md: -------------------------------------------------------------------------------- 1 | # Poplar Android Build 2 | 3 | The following instructions are provided as guidence to download, build, and install Android on the Poplar board. 4 | 5 | For general set up, refer to [official Android doc](https://source.android.com/source/initializing). 6 | 7 | ## Compiling userspace 8 | 9 | 1. Get AOSP 10 | ``` 11 | mkdir -p ~/poplar 12 | cd ~/poplar 13 | repo init -u https://android.googlesource.com/platform/manifest.git -b master 14 | repo sync -j8 15 | ``` 16 | 17 | 2. Add Poplar device and Pre-built 4.9 kernel/dtb 18 | 19 | ``` 20 | mkdir device/hisilicon 21 | git clone https://github.com/96boards-poplar/poplar-device.git device/hisilicon/poplar 22 | git clone https://github.com/96boards-poplar/poplar-kernel.git device/hisilicon/poplar-kernel 23 | ``` 24 | 25 | 3. Build 26 | ``` 27 | source build/envsetup.sh 28 | lunch poplar-eng 29 | make -j8 30 | ``` 31 | 32 | ## Installing partition table and bootloader 33 | 34 | see [Installing partition table and bootloader](ANDROID-Flash.md#installing-partition-table-and-bootloader) 35 | 36 | ## Flashing Android images 37 | 38 | 1. Put board into fastboot mode. 39 | 40 | During boot up, interrupt the normal boot flow and get into the the uboot console, type: 41 | 42 | ``` 43 | usb reset 44 | fastboot 0 45 | 46 | ``` 47 | 48 | 2. Flash from the host 49 | 50 | Check if device is in fastboot mode using follow command, you should get a fastboot device. 51 | 52 | ``` 53 | $sudo fastboot devices 54 | 0123456789POPLAR fastboot 55 | ``` 56 | 57 | Then, flash using `fastboot flash` command: 58 | 59 | ```bash 60 | cd `$OUT` 61 | sudo fastboot flash mmcsda2 boot.img 62 | sudo fastboot flash mmcsda3 system.img 63 | sudo fastboot flash mmcsda5 vendor.img 64 | sudo fastboot flash mmcsda6 cache.img 65 | sudo fastboot flash mmcsda7 userdata.img 66 | ``` 67 | 68 | ## Building the kernel 69 | 70 | 1. Download the necessary toolchain 71 | 72 | Download a 64-bit GCC toolchain from Linaro, and extract 73 | it under the /opt directory (or anywhere you prefer) on your build system: 74 | 75 | ```shell 76 | cd /tmp 77 | wget https://releases.linaro.org/components/toolchain/binaries/7.1-2017.08/aarch64-linux-gnu/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 78 | sudo mkdir -p /opt 79 | sudo tar -C /opt -xJf /tmp/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 80 | rm /tmp/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 81 | ``` 82 | 83 | And, set up the `CROSS_64` enviroment variable that will be used in building kernel below. 84 | 85 | ```shell 86 | CROSS_64=/opt/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu- 87 | ``` 88 | 89 | 2. Download and build Poplar kernel: 90 | 91 | ``` 92 | git clone -b poplar-android-4.9 https://github.com/96boards-poplar/linux.git 93 | cd linux 94 | make ARCH=arm64 poplar_defconfig 95 | make ARCH=arm64 CROSS_COMPILE=${CROSS_64} -j8 96 | ``` 97 | 98 | 3. Copy new pre-built kernel and device tree files to the Android tree 99 | 100 | ``` 101 | POPLAR_PREBUILT_KERNEL=${ANDROID_BUILD_TOP}/device/hisilicon/poplar-kernel 102 | cp ./arch/arm64/boot/Image ${POPLAR_PREBUILT_KERNEL}/Image 103 | cp ./arch/arm64/boot/dts/hisilicon/hi3798cv200-poplar.dtb ${POPLAR_PREBUILT_KERNEL}/hi3798cv200-poplar.dtb 104 | ``` 105 | 106 | 4. Make the boot image: 107 | 108 | ``` 109 | make bootimage -j8 110 | ``` 111 | 112 | ## Known Issue 113 | 114 | 1. The boot ROM can't recognize certain type of USB disk, the consequence is you can't use that usb disk for recovery flash. The exactly reason and what type of USB disk can't recognized isn't clear at the moment. 115 | 116 | 2. No serial output if the device is rebooted by power off and on when both USB2 and MicroUSB are connected at the same time. You have to unplug the USB2 to make sure the board completely lose power before rebooting and then reconnect the USB2 cable. An alternative, actually the recommend way is to reboot the device using software reboot command, that is `reboot` in linux console or `reset` in u-boot console. 117 | -------------------------------------------------------------------------------- /android/ANDROID-Flash.md: -------------------------------------------------------------------------------- 1 | # Recovery Android to the Poplar Board 2 | 3 | ## Create a USB drive for flashing 4 | 5 | To allow recovery of a Poplar board in a "bricked" state, or to flash the Poplar board with an Android image, prepare a USB flash drive. 6 | 7 | ### Step 1: Identify your USB flash drive device 8 | 9 | Insert the USB flash drive into your host system, and identify 10 | your USB device: 11 | 12 | ```shell 13 | grep . /sys/class/block/sd?/device/model 14 | ``` 15 | If you recognize the model name as your USB flash device, then 16 | you know which "sd" device to use. Here's an example: 17 | 18 | ```shell 19 | /sys/class/block/sdh/device/model:Patriot Memory 20 | ^^^ 21 | ``` 22 | I had a Patriot Memory USB flash drive, and the device name 23 | I'll want is "/dev/sdh" (based on "sdh" above). Record this name: 24 | 25 | ```shell 26 | USBDISK=/dev/sdh # Make sure this is *your* device 27 | ``` 28 | 29 | The instructions that follow assume your USB flash drive needs to be 30 | formatted "from scratch." Once formatted, all that's required is to 31 | copy "fastboot.bin" to the first partition on the drive, and then 32 | properly eject the medium before removing the USB drive. 33 | 34 | ### Step 2: Format the flash drive using MBR partitioning. 35 | 36 | THIS IS VERY IMPORTANT. The following commands will COMPLETELY 37 | ERASE the contents of whatever device you specify here. So be 38 | sure USBDISK defines the flash device you intend to erase. 39 | 40 | You will need superuser access. First, unmount anything mounted 41 | on that device: 42 | 43 | ```shell 44 | sudo umount ${USBDISK}? 45 | ``` 46 | 47 | Next, clobber any existing partitioning information that might be 48 | found at the beginning of the device: 49 | 50 | ``` 51 | sudo dd if=/dev/zero of=${USBDISK} bs=2M count=1 status=none 52 | ``` 53 | 54 | Create a DOS MBR partition table on the USB flash drive with a 55 | single partition, and format that partition using FAT32. 56 | 57 | ```shell 58 | { echo label:dos 59 | echo 1: start=8 size=62496KiB type=0x0c 60 | echo write 61 | } | sudo sfdisk --label dos ${USBDISK} 62 | sudo mkfs.fat -F 32 ${USBDISK}1 63 | ``` 64 | 65 | You now have a properly formated USB drive that is ready to be used for flashing the recovery files and Android Images to a Poplar board. 66 | 67 | ## Installing partition table and bootloader 68 | 69 | ### Step 1: Download partition table recovery files and copy them to the USB disk created previously (see [Create a USB drive for flashing](#create-a-usb-drive-for-flashing)) 70 | 71 | ``` 72 | git clone https://github.com/96boards-poplar/l-loader.git 73 | cp -r l-loader/installer/* ${your_usb_mount_point} 74 | sync 75 | ``` 76 | 77 | * An USB automount point on Ubuntu: /media/username/631B-5041 78 | 79 | ### Step 2: Install partition table 80 | 81 | Following [instruction here](#put-board-in-recovery-or-flashing-state) to put board in recovery or flashing state: 82 | 83 | ``` 84 | usb reset 85 | fatload usb 0:1 ${scriptaddr} recovery_files/install.scr 86 | source ${scriptaddr} 87 | ``` 88 | 89 | ### Step 3: Install bootloader 90 | 91 | Right after partition table installation, you can choose to install bootloader built from source by yourself, or prebuilt ones in l-loader/prebuilts/, using fastboot. 92 | 93 | Device side, U-Boot command: 94 | 95 | ``` 96 | poplar# fastboot 0 97 | ``` 98 | 99 | Host side, fastboot command: 100 | 101 | ``` 102 | $ fastboot flash mmcsda1 loader.bin 103 | ``` 104 | 105 | In addition to bootloader installation, you also have to setup the correct u-boot bootcmd, so it can auto boot the android once the images are flashed. 106 | 107 | ``` 108 | env set bootcmd run bootai 109 | env save 110 | ``` 111 | 112 | ## Put board in recovery or flashing state 113 | 114 | If a Poplar board is in a "bricked" state, it can be booted using 115 | the USB flash drive prepared above. 116 | 117 | ### Step 1: Prepare the Poplar board for power-on 118 | 119 | - The Poplar board should be powered off. You should have a cable 120 | from the Poplar's micro USB based serial port to your host 121 | system so you can connect and observe activity on the serial port. 122 | For me, the board console shows up as /dev/ttyUSB0 when the USB 123 | cable is connected. The serial port runs at 115200 baud. I use 124 | this command to see what's on the console: 125 | 126 | ```shell 127 | screen /dev/ttyUSB0 115200 128 | ``` 129 | 130 | ### Step 2: Insert the USB flash drive on the Poplar board 131 | 132 | - There are a total of 4 USB connectors on the Poplar board. Two 133 | are USB 2.0 ports, they're stacked on top of each other. Insert 134 | the USB memory stick into one of these two. 135 | 136 | - There is a "USB_BOOT" button on the board. It is one of two 137 | buttons on same side of the boards as the stacked USB 2.0 ports. 138 | To boot from the memory stick, this button needs to be depressed 139 | at power-on. You only need to hold it for about a second; 140 | keeping it down a bit longer does no harm. 141 | 142 | - Next you will be powering on the board, but you need to interrupt 143 | the automated boot process. To do this, be prepared to press a 144 | key, perhaps repeatedly, in the serial console window until you 145 | find the boot process has stopped. 146 | 147 | ### Step 3: Boot the Poplar board from the USB flash drive 148 | 149 | - Power on the Poplar board (while pressing the USB_BOOT button), 150 | and interrupt its automated boot with a key press. This should 151 | lead to a "poplar# " prompt. 152 | -------------------------------------------------------------------------------- /android/INTEGRATION.md: -------------------------------------------------------------------------------- 1 | # Poplar Android Integration 2 | 3 | This page cover all the things related with the integration of Aspen project, mostly focus on kernel and user space HAL. It will over test cases, known issues, how to report issue, capture logs, etc. 4 | 5 | It's not our intention here to provide a full set of test cases to validate a android product. Rather the goal here is provide minimal test cases and steps that can be used to 1) validate the basic kernel interfaces, when we doubt something might be wrong with the kernel; 2) validate the basic features from user's point of view such as play a youtube video. 6 | 7 | We will keep it simple but useful. 8 | 9 | ## Smoke Test 10 | 11 | Following test is required to run for any patch submission. 12 | 13 | TBD: 14 | 15 | ## Test Video/Video 16 | 17 | ### 1.1 Unit Test audio 18 | 19 | 1. (host) 20 | Download any .wav file, call it `test_audio.wav`. 21 | ``` 22 | adb push test_audio.wav /sdcard/test.wav 23 | ``` 24 | 25 | 2. on poplar console, after board booting up 26 | ``` 27 | # su 28 | # tinyplay /sdcard/test.wav 29 | Playing sample: 2 ch, 44100 hz, 16 bit 30 | ``` 31 | 32 | What to Expect: 33 | 34 | You should hear the audio in both HDMI and audio line out interface. 35 | 36 | ### 1.2 Play mp3 file 37 | 38 | 1. (host) 39 | Download [Wheels on the Bus](http://billysworld.biz/wp-content/uploads/2014/12/WheelsOn-the-Bus.1.mp3) 40 | 41 | ``` 42 | adb push WheelsOn-the-Bus.1.mp3 /sdcard/wheels.mp3 43 | ``` 44 | 45 | 2. on poplar console, after board boot up 46 | 47 | ``` 48 | # su 49 | # stagefright -a -o /sdcard/wheels.mp3 50 | ``` 51 | 52 | If you don't have access the console, you can use apps to play it. Reboot the board, open "Downloads" app, click "Audio", go through the dir hierarchy : `Unknown` -> `0 `-> `wheels.mp3`, and double click it. 53 | 54 | What to Expect: 55 | 56 | You should hear the audio in both HDMI and audio line out interface. 57 | 58 | ### 1.3 test local media playback 59 | 60 | 1. Download the one of mp4 video from [1], call it `test_video.mp4` 61 | 62 | 2. (host) `adb push test_video.mp4 /sdcard/test.mp4` 63 | 64 | 3. Reboot the poplar board to make sure the new pushed media will be picked by the media player apps. 65 | 66 | 4. Plug in usb mouse (make sure your kernel has patch made ehci controller builtin) 67 | 68 | 4. Open Gallery app, click the video 69 | 70 | What to Expect: 71 | 72 | You should see the video playing and hear the audio in both HDMI and audio line out interface. 73 | 74 | [1]http://www.mobiles24.co/downloads/tag/the+simpsons/mp4-videos 75 | 76 | ### 1.3 Test web media playback 77 | 78 | 1. Open web browser, to make sure we're testing the same video, type https://goo.gl/o8ErmS, which is `Taylor Swift - Look What You Made Me Do` in youtube. 79 | 80 | What to Expect: 81 | 82 | You should see the video playing and hear the audio in both HDMI and audio lineout interface. 83 | 84 | ## Test Graphics 85 | 86 | ## Test Wifi 87 | 88 | ## Test BlueTooth 89 | 90 | ## Report Issues 91 | 92 | ### Debug & capture logs 93 | 94 | General Preparation: 95 | 96 | - power on the board, and it will stop at the u-boot console 97 | - set up the serial tool, the instruction depend on the serial console tool you used. for minicom, `ctrl-A`, then `L`, then the log file name. 98 | - boot android, either using `run setupa; run boota` or `run bootai` 99 | 100 | For start up issues: 101 | 102 | - Waiting android booting, *as soon as* you can get the console, type `logcat`, wait the log dumping (may take ~10 seconds), `ctrl+c` to kill the `logcat` 103 | - type `ps` to get all the running process. 104 | 105 | For specific issues: 106 | 107 | - start logcat and make sure the log is captured 108 | - reproduce the issue 109 | - send the logcat information for analysis 110 | 111 | It is always a good idea to provide the start up logs as well to make sure the issue isn't caused in early phase (case study: not able the get dhcp address is due to mounting failure in data partition). 112 | 113 | ### debug audio 114 | 115 | Play the media as described in 1.2, 1.3. Make sure the media is keep playing during following log capture process. The youtube one is long enough (~4 minutes). 116 | 117 | When the media is playing, do following in the host. 118 | 119 | ``` 120 | (host) 121 | adb shell ps >> log_no_audio 122 | adb shell dumpsys media.audio_flinger >> log_no_audio 123 | adb shell dumpsys media.audio_flinger >> log_no_audio 124 | adb logcat >> log_no_audio 125 | ``` 126 | 127 | `ctrl+c` to kill logcat and send along the `log_no_audio` file. 128 | 129 | 130 | ## Misc 131 | 132 | ### ADB over Ethernet 133 | 134 | If for some reason you want to use ADB over Ethernet than USB, here are the steps to set it up. 135 | 136 | 1. Plug an Ethernet cable to your board and make sure eth0 is getting its address 137 | 138 | ``` 139 | poplar:/ # ifconfig eth0 | grep "inet addr" 140 | inet addr:192.168.0.18 Bcast:192.168.0.255 Mask:255.255.255.0 141 | ``` 142 | 143 | 2. Write down the ip address, 192.168.0.18 in this case 144 | 145 | 3. On you developer machine: 146 | 147 | ``` 148 | $adb connect ${poplar_ip_addr} #192.168.0.18 149 | ``` 150 | 151 | And, check with `adb devices` 152 | 153 | ``` 154 | $ adb devices 155 | List of devices attached 156 | 192.168.0.18:5555 device 157 | ``` 158 | 159 | 4. Now, adb is ready for you to use, use `adb help` for more information. 160 | 161 | ``` 162 | $adb remount 163 | $adb push path/to/your/tools /system/bin 164 | ``` 165 | -------------------------------------------------------------------------------- /android/STATUS.md: -------------------------------------------------------------------------------- 1 | # Poplar Andriod Status 2 | 3 | ## Andriod build with 4.9 kernel (master) 4 | 5 | | Features | Status | 6 | | -------- | -------------| 7 | | OpenGL | Y | 8 | | FB dev | Y | 9 | | HDMI Display | Y | 10 | | HDMI Audio | Y | 11 | | Audio Decoder - SW | Y | 12 | | Audio Decoder - HW | N | 13 | | Video Decoder - SW | Y | 14 | | Video Decoder - HW | Y | 15 | | Ethernet | Y | 16 | | USB Mouse/Keyboard | Y | 17 | | IR/Remote Control | Y | 18 | | Wifi | N | 19 | | BT | N | 20 | 21 | ## Known Issues 22 | 23 | 1. USB 2 port host mode will not work by default, enable it using following command. Alternatively, you can use USB3 port (for host mode) if you need to use keyboard/mouse. 24 | 25 | ``` 26 | echo host > /sys/kernel/debug/hisi_inno_phy/role 27 | ``` 28 | 29 | USB2 port will be default to OTG mode. 30 | -------------------------------------------------------------------------------- /debian/debian_build_instructions.md: -------------------------------------------------------------------------------- 1 | # Building Poplar Debian System Media From Source 2 | 3 | The instructions that follow describe the process for creating image 4 | files suitable for use in a Poplar system. 5 | 6 | ## Gather required sources 7 | 8 | First you'll gather the source code and other materials required to 9 | build the images. These instructions assume you are using Linux based 10 | OS on your host machine. 11 | 12 | ### Step 1: Make sure you have needed tools installed 13 | 14 | This list may well grow, but at least you'll need the following: 15 | 16 | ```shell 17 | sudo apt-get update 18 | sudo apt-get upgrade 19 | sudo apt-get install device-tree-compiler libssl-dev u-boot-tools 20 | sudo apt-get install screen simg2img 21 | ``` 22 | 23 | ### Step 2: Set up the working directory. 24 | 25 | ```shell 26 | mkdir -p ~/src/poplar 27 | cd ~/src/poplar 28 | TOP=$(pwd) 29 | ``` 30 | 31 | ### Step 3: Download a root file system image to use. 32 | These are available from Linaro, under here: 33 | http://snapshots.linaro.org/debian/images/stretch/developer-arm64/ 34 | These images change regularly, and the latest version is always 35 | available under a folder named "latest". For the purposes of this 36 | document we assume that build 80 is used. If you download this 37 | file by some means other than "wget" shown below, please ensure it 38 | gets place in the `recovery` directory created here. 39 | 40 | ```shell 41 | mkdir ${TOP}/recovery 42 | wget -P ${TOP}/recovery \ 43 | http://snapshots.linaro.org/debian/images/stretch/developer-arm64/80/linaro-stretch-developer-20170914-80.tar.gz 44 | ``` 45 | 46 | ### Step 4: Get the source code. 47 | 48 | ```shell 49 | cd ${TOP} 50 | git clone https://github.com/ARM-software/arm-trusted-firmware 51 | git clone https://github.com/96boards-poplar/poplar-tools.git 52 | git clone https://github.com/96boards-poplar/l-loader.git 53 | git clone https://github.com/96boards-poplar/u-boot.git 54 | git clone https://github.com/96boards-poplar/linux.git -b poplar-4.9 55 | ``` 56 | 57 | ### Step 5: Set up toolchains for building 58 | Almost everything uses aarch64, but one item (l-loader.bin) must 59 | be built for 32-bit ARM. 60 | 61 | Download a recent 64-bit GCC toolchain from Linaro, and extract 62 | it under the /opt directory on your build system: 63 | ```shell 64 | cd /tmp 65 | wget https://releases.linaro.org/components/toolchain/binaries/7.1-2017.08/aarch64-linux-gnu/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 66 | sudo mkdir -p /opt 67 | sudo tar -C /opt -xJf /tmp/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 68 | rm /tmp/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu.tar.xz 69 | ``` 70 | 71 | Download a recent 32-bit GCC toolchain from Linaro, and extract it 72 | under the /opt directory on your build system: 73 | ```shell 74 | cd /tmp 75 | wget https://releases.linaro.org/components/toolchain/binaries/7.1-2017.08/arm-linux-gnueabihf/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf.tar.xz 76 | sudo tar -C /opt -xJf /tmp/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf.tar.xz 77 | rm /tmp/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf.tar.xz 78 | ``` 79 | 80 | Finally, set some environment variables used to specify the path 81 | (and file name prefix) for accessing the 32-bit and 64-bit cross 82 | compiler tool chains in the instructions that follow: 83 | 84 | ```shell 85 | CROSS_32=/opt/gcc-linaro-7.1.1-2017.08-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- 86 | CROSS_64=/opt/gcc-linaro-7.1.1-2017.08-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu- 87 | ``` 88 | 89 | ## Build everything 90 | 91 | ### Step 1: Build U-Boot. 92 | The result of this process will be a file `u-boot.bin` that will 93 | be incorporated into a FIP file created for ARM Trusted Firmware code. 94 | 95 | ```shell 96 | # This produces one output file, which is used when building ARM 97 | # Trusted Firmware, next: 98 | # u-boot.bin 99 | cd ${TOP}/u-boot 100 | make distclean 101 | make CROSS_COMPILE=${CROSS_64} poplar_defconfig 102 | make CROSS_COMPILE=${CROSS_64} 103 | ``` 104 | 105 | ### Step 2: Build ARM Trusted Firmware components. 106 | The result of this process will be two files `bl1.bin` and 107 | `fip.bin`, which will be incorporated into the image created for 108 | `l-loader` in the next step. The FIP file packages files `bl2.bin` 109 | and `bl31.bin` (built here) along with `u-boot.bin` (built earlier). 110 | 111 | ```shell 112 | # This produces two output files, which are used when building 113 | # "l-loader", next: 114 | # build/poplar/debug/bl1.bin 115 | # build/poplar/debug/fip.bin 116 | cd ${TOP}/arm-trusted-firmware 117 | make distclean 118 | make CROSS_COMPILE=${CROSS_64} all fip DEBUG=1 PLAT=poplar SPD=none \ 119 | BL33=${TOP}/u-boot/u-boot.bin 120 | ``` 121 | 122 | ### Step 3: Build "l-loader" 123 | This requires the two ARM Trusted Firmware components you built 124 | earlier. So start by copying them into the `atf` directory. Note 125 | that `l-loader` is a 32-bit executable, so you need to use a 126 | different tool chain. 127 | 128 | ```shell 129 | # This produces one output file, which is used in building the 130 | # flash images: 131 | # l-loader.bin 132 | cd ${TOP}/l-loader 133 | cp ${TOP}/arm-trusted-firmware/build/poplar/debug/bl1.bin atf/ 134 | cp ${TOP}/arm-trusted-firmware/build/poplar/debug/fip.bin atf/ 135 | make clean 136 | make CROSS_COMPILE=${CROSS_32} 137 | ``` 138 | 139 | ### Step 4: Build Linux. 140 | The result of this process will be two files: `Image` contains the 141 | kernel image; and `hi3798cv200-poplar.dtb` containing the 142 | flattened device tree file (device tree binary). A Linux build is 143 | sped up considerably by running `make` with multiple concurrent 144 | jobs. JOBCOUNT is set below to something reasonable to benefit 145 | from this. 146 | 147 | ```shell 148 | # This produces two output files, which are used when building 149 | # the flash images: 150 | # arch/arm64/boot/Image 151 | # arch/arm64/boot/dts/hisilicon/hi3798cv200-poplar.dtb 152 | cd ${TOP}/linux 153 | JOBCOUNT=$(grep ^processor /proc/cpuinfo | wc -l) 154 | make ARCH=arm64 distclean 155 | make ARCH=arm64 CROSS_COMPILE="${CROSS_64}" poplar_defconfig 156 | make ARCH=arm64 CROSS_COMPILE="${CROSS_64}" all dtbs modules -j ${JOBCOUNT} 157 | ``` 158 | 159 | ### Step 5: Gather the required components you built above 160 | First gather the files that will be required to create the Poplar 161 | image files. The root file system image should already have been 162 | placed in the `recovery` directory. 163 | 164 | ```shell 165 | cd ${TOP}/recovery 166 | cp ${TOP}/poplar-tools/poplar_recovery_builder.sh . 167 | cp ${TOP}/l-loader/l-loader.bin . 168 | cp ${TOP}/linux/arch/arm64/boot/Image . 169 | cp ${TOP}/linux/arch/arm64/boot/dts/hisilicon/hi3798cv200-poplar.dtb . 170 | ``` 171 | 172 | ### Step 6: Build image files used for installation 173 | You need to supply the root file system image you downloaded 174 | earlier (whose name may be different from what's shown below). 175 | This will also require superuser privilege to complete. 176 | 177 | ```shell 178 | # This produces a directory "recovery_files". In that directory, 179 | # "fastboot.bin" can be placed on a USB flash drive (formatted 180 | # with an MBR with a single FAT32 file system partition) that can 181 | # be used to boot a Poplar board in a "bricked" state. The 182 | # remaining files are used in populating the eMMC media with a 183 | # bootable Linux system. 184 | # recovery_files/fastboot.bin 185 | # recovery_files/install.scr 186 | # recovery_files/install-*.scr 187 | # recovery_files/partition1-1of1.gz 188 | # ... 189 | bash ./poplar_recovery_builder.sh all \ 190 | linaro-stretch-developer-20170914-80.tar.gz 191 | ``` 192 | 193 | **NOTE**: If you are running Ubuntu 14.04, sfdisk needs to be upgraded 194 | to a newer version like 2.26.2 in following steps. 195 | 196 | ```shell 197 | wget https://www.kernel.org/pub/linux/utils/util-linux/v2.26/util-linux-2.26.2.tar.xz 198 | tar xf util-linux-2.26.2.tar.xz 199 | cd util-linux-2.26.2 200 | ./configure 201 | make sfdisk 202 | export PATH=/path/to/util-linux-2.26.2:$PATH 203 | ``` 204 | 205 | **NOTE**: If you get below error, that means your `mkimage` version is 206 | too old, e.g. if you using Ubuntu 14.04. Use the one you just built in 207 | `${TOP}/u-boot/tools` instead. 208 | 209 | ```shell 210 | Invalid CPU Type - valid names are: alpha, arm, x86, ia64, m68k, microblaze, mips, mips64, nios2, powerpc, ppc, s390, sh, sparc, sparc64, blackfin, avr32, nds32, or1k, sandbox 211 | Usage: mkimage -l image 212 | -l ==> list image header information 213 | mkimage [-x] -A arch -O os -T type -C comp -a addr -e ep -n name -d data_file[:data_file...] image 214 | -A ==> set architecture to 'arch' 215 | -O ==> set operating system to 'os' 216 | -T ==> set image type to 'type' 217 | -C ==> set compression type 'comp' 218 | -a ==> set load address to 'addr' (hex) 219 | -e ==> set entry point to 'ep' (hex) 220 | -n ==> set image name to 'name' 221 | -d ==> use image data from 'datafile' 222 | -x ==> set XIP (execute in place) 223 | mkimage [-D dtc_options] [-f fit-image.its|-F] fit-image 224 | -D => set options for device tree compiler 225 | -f => input filename for FIT source 226 | Signing / verified boot not supported (CONFIG_FIT_SIGNATURE undefined) 227 | mkimage -V ==> print version information and exit 228 | ``` 229 | 230 | **NOTE**: It is normal to see below warning during this step. 231 | 232 | ```shell 233 | recovery_files/partition3 is not a block special device. 234 | Proceed anyway? (y,n) 235 | ``` 236 | 237 | ### Step 7: Copy image files to the TFTP home directory 238 | The flashing process depends on transferring files to the Poplar 239 | board via Ethernet using TFTP. The `recovery_files` directory 240 | must be copied to the root of the TFTP directory. 241 | 242 | ```shell 243 | cd ${TOP}/recovery 244 | sudo rm -rf ~tftp/recovery_files 245 | sudo cp -a recovery_files ~tftp 246 | sudo chown -R tftp.tftp ~tftp/recovery_files 247 | ``` 248 | 249 | ## Flash images onto the Poplar board eMMC 250 | 251 | 252 | ### Step 1: Prepare the Poplar board for power-on 253 | 254 | - The Poplar board should be powered off. You should have a cable 255 | from the Poplar's micro USB based serial port to your host 256 | system so you can connect and observe activity on the serial port. 257 | For me, the board console shows up as /dev/ttyUSB0 when the USB 258 | cable is connected. The serial port runs at 115200 baud. I use 259 | this command to see what is on the console: 260 | 261 | ```shell 262 | screen /dev/ttyUSB0 115200 263 | ``` 264 | 265 | ### Step 2: Boot the Poplar board into the u-boot prompt where flashing to eMMC is possible 266 | 267 | - Power on the Poplar board and interrupt its automated boot with a key 268 | press. This should lead to a `poplar# ` prompt. 269 | 270 | The files required for partitioning and re-flashing the content of 271 | eMMC media on the Poplar board were produced earlier, and should 272 | now be present in ~tftp/recovery_files. The Ethernet interface on 273 | the Poplar board must be configured, and then an installer script 274 | will be downloaded and executed. 275 | 276 | ### Step 3: Configure the Poplar Ethernet interface 277 | 278 | The following assumes you know your network configuration, and that 279 | you have an IP address in that network to use for the Poplar board. 280 | 281 | - Inform U-Boot about the network parameters to use. Use values for 282 | the following environment variables that are appropriate for your 283 | network. The IP address for the Poplar board is assigned with 284 | `ipaddr`; the netmask for the network is defined by `netmask`; and 285 | the IP address of the TFTP server containing the image files 286 | (probably your development/build machine) is `serverip`. 287 | 288 | Enter the following commands in the Poplar serial console to 289 | configure the Ethernet interface. 290 | ```shell 291 | env set ipaddr 192.168.0.2 292 | env set netmask 255.255.255.0 293 | env set serverip 192.168.0.1 294 | ``` 295 | 296 | - Verify your network connection is operational. 297 | ```shell 298 | ping ${serverip} 299 | ``` 300 | 301 | ### Step 4: Run the installer 302 | 303 | - Load an install script using TFTP, and run it. 304 | ```shell 305 | tftp ${scriptaddr} recovery_files/install.scr 306 | source ${scriptaddr} 307 | ``` 308 | It will take about 5-10 minutes to complete writing out the contents 309 | of the disk. The result should look a bit like this: 310 | 311 | ```shell 312 | --------------------------- 313 | | poplar# source ${scriptaddr} 314 | | ## Executing script at 32000000 315 | | ETH1: PHY(phyaddr=3, rgmii) link UP: DUPLEX=FULL : SPEED=1000M 316 | | Using gmac1 device 317 | | TFTP from server 172.22.22.5; our IP address is 172.22.22.154 318 | | Filename 'recovery_files/install-layout.scr'. 319 | | Load address: 0x7800000 320 | | Loading: # 321 | | 359.4 KiB/s 322 | | done 323 | | Bytes transferred = 368 (170 hex) 324 | | ## Executing script at 07800000 325 | | ETH1: PHY(phyaddr=3, rgmii) link UP: DUPLEX=FULL : SPEED=1000M 326 | | Using gmac1 device 327 | | TFTP from server 172.22.22.5; our IP address is 172.22.22.154 328 | | Filename 'recovery_files/mbr.bin.gz'. 329 | | Load address: 0x8000000 330 | | Loading: # 331 | | 98.6 KiB/s 332 | | done 333 | | Bytes transferred = 101 (65 hex) 334 | | Uncompressed size: 512 = 0x200 335 | | 336 | | MMC write: dev # 0, block # 0, count 1 ... 1 blocks written: OK 337 | | . . . 338 | ``` 339 | 340 | - When this process completes, reset your Poplar board. You can reset it in 341 | one of three ways: press the reset button; power the board off and on again; 342 | or run this command in the serial console window: 343 | ```shell 344 | reset 345 | ``` 346 | 347 | At this point, Linux should automatically boot from the eMMC. 348 | 349 | You have now booted your Poplar board with open source code that you 350 | have built yourself. 351 | 352 | -------------------------------------------------------------------------------- /debian/debian_installation.md: -------------------------------------------------------------------------------- 1 | # Installing Poplar Debian Images 2 | 3 | ## Step 1: Download images 4 | Download prebuilt images from https://releases.linaro.org (coming soon! 5 | Until then, please build from source using the build instructions 6 | in [debian_build_instructions.md](debian_build_instructions.md). 7 | 8 | ## Step 2: Prepare the images directory 9 | Follow [Step 7](debian_build_instructions.md#step-7-copy-image-files-to-the-tftp-home-directory) 10 | in the [Build everything](debian_build_instructions.md#build-everything) 11 | section of [debian_build_instructions.md](debian_build_instructions.md) 12 | to place the images to the TFTP directory. 13 | 14 | ## Step 3: Install images 15 | Follow the [Flash images onto the Poplar board eMMC](debian_build_instructions.md#flash-images-onto-the-poplar-board-emmc) 16 | section in [debian_build_instructions.md](debian_build_instructions.md) 17 | until the end of the document. 18 | -------------------------------------------------------------------------------- /debian/debian_recovery.md: -------------------------------------------------------------------------------- 1 | # Building Poplar Debian System Recovery Media From Source 2 | 3 | The instructions that follow describe the process for creating a USB 4 | flash drive suitable for use in recovering a Poplar system from a 5 | "bricked" state. The USB memory stick must be at least 2 GB. 6 | 7 | ## Using prebuilt image files 8 | 9 | ### Step 1: Download images 10 | Download prebuilt images from https://releases.linaro.org (coming soon! 11 | Until then, please build from source using the instructions in the 12 | [Building the image files from source](#building-the-image-files-from-source) 13 | section below. 14 | 15 | ### Step 2: Prepare the images directory 16 | Follow [Step 7](debian_build_instructions.md#step-7-copy-image-files-to-the-tftp-home-directory) 17 | in the [Build everything](debian_build_instructions.md#build-everything) 18 | section of [debian_build_instructions.md](debian_build_instructions.md) 19 | to place the images to the TFTP directory. 20 | 21 | ### Step 3: Recover board 22 | Follow the [prepare a USB flash drive](#to-allow-recovery-of-a-poplar-board-in-a-bricked-state-prepare-a-usb-flash-drive) 23 | section below until the end of the document. 24 | 25 | In the [Step 3: Copy "fastboot.bin" to the drive](#step-3-copy-fastbootbin-to-the-drive) 26 | section, you can use 27 | https://github.com/96boards-poplar/l-loader/raw/master/installer/fastboot.bin 28 | rather than build the "fastboot.bin" file yourself. 29 | 30 | ## Building the image files from source 31 | 32 | Follow the instructions in [debian_build_instructions.md](debian_build_instructions.md) 33 | to create image suitable for use in a Poplar system, with the following 34 | exceptions: 35 | 36 | ### Step 1: Build ARM Trusted Firmware components for recovery. 37 | Add `POPLAR_RECOVERY=1` to the end of the `make` command, as shown below: 38 | 39 | ```shell 40 | cd ${TOP}/arm-trusted-firmware 41 | make distclean 42 | make CROSS_COMPILE=${CROSS_64} all fip DEBUG=1 PLAT=poplar SPD=none \ 43 | BL33=${TOP}/u-boot/u-boot.bin POPLAR_RECOVERY=1 44 | ``` 45 | 46 | ### Step 2: Build "l-loader" for recovery 47 | Add `RECOVERY=1` to the end of the `make` command, as shown below: 48 | 49 | ```shell 50 | cp ${TOP}/arm-trusted-firmware/build/poplar/debug/bl1.bin atf/ 51 | cp ${TOP}/arm-trusted-firmware/build/poplar/debug/fip.bin atf/ 52 | make clean 53 | make CROSS_COMPILE=${CROSS_32} RECOVERY=1 54 | ``` 55 | 56 | Once you are done with [Step 7](debian_build_instructions.md#step-7-copy-image-files-to-the-tftp-home-directory) 57 | in the [Build everything](debian_build_instructions.md#build-everything) 58 | section, come back to this document. 59 | 60 | ## To allow recovery of a Poplar board in a "bricked" state, prepare a USB flash drive. 61 | 62 | ### Step 1: Identify your USB flash drive device 63 | 64 | Insert the USB flash drive into your host system, and identify 65 | your USB device: 66 | 67 | ```shell 68 | grep . /sys/class/block/sd?/device/model 69 | ``` 70 | If you recognize the model name as your USB flash device, then 71 | you know which "sd" device to use. Here is an example: 72 | 73 | ```shell 74 | /sys/class/block/sdh/device/model:Patriot Memory 75 | ^^^ 76 | ``` 77 | I had a Patriot Memory USB flash drive, and the device name 78 | I will want is "/dev/sdh" (based on "sdh" above). Record this name: 79 | 80 | ```shell 81 | USBDISK=/dev/sdh # Make sure this is *your* device 82 | ``` 83 | 84 | The instructions that follow assume your USB flash drive needs to be 85 | formatted "from scratch." Once formatted, all that is required is to 86 | copy `fastboot.bin` to the first partition on the drive, and then 87 | properly eject the medium before removing the USB drive. 88 | 89 | ### Step 2: Format the flash drive using MBR partitioning. 90 | 91 | THIS IS VERY IMPORTANT. The following commands will COMPLETELY 92 | ERASE the contents of whatever device you specify here. So be 93 | sure USBDISK defines the flash device you intend to erase. 94 | 95 | You will need superuser access. First, unmount anything mounted 96 | on that device: 97 | 98 | ```shell 99 | sudo umount ${USBDISK}? 100 | ``` 101 | 102 | Next, clobber any existing partitioning information that might be 103 | found at the beginning of the device: 104 | 105 | ```shell 106 | sudo dd if=/dev/zero of=${USBDISK} bs=2M count=1 status=none 107 | ``` 108 | 109 | Create a DOS MBR partition table on the USB flash drive with a 110 | single partition, and format that partition using FAT32. 111 | ```shell 112 | { echo label:dos 113 | echo 1: start=8 size=62496KiB type=0x0c 114 | echo write 115 | } | sudo sfdisk --label dos ${USBDISK} 116 | sudo mkfs.fat -F 32 ${USBDISK}1 117 | ``` 118 | 119 | ### Step 3: Copy "fastboot.bin" to the drive 120 | 121 | Finally, mount that partition and copy `fastboot.bin` into it. 122 | Once the partition has been unmounted and the device has been 123 | ejected, the USB stick can be removed. 124 | 125 | ```shell 126 | cd ${TOP}/recovery/recovery_files 127 | mkdir -p /tmp/usbdisk 128 | sudo mount -t vfat ${USBDISK}1 /tmp/usbdisk 129 | 130 | sudo cp fastboot.bin /tmp/usbdisk 131 | 132 | sudo umount /tmp/usbdisk 133 | rmdir /tmp/usbdisk 134 | sudo eject ${USBDISK} 135 | ``` 136 | 137 | (For a previously-formatted drive, simply inserting it will cause 138 | it be mounted automatically--normally under `/media/...` somewhere.) 139 | 140 | Remove the USB flash drive from your host system. 141 | 142 | ## De-brick a Poplar board in a "bricked" state 143 | 144 | If a Poplar board is in a "bricked" state, it can be booted using 145 | the USB flash drive prepared above. 146 | 147 | ### Step 1: Prepare the Poplar board for power-on 148 | 149 | - The Poplar board should be powered off. You should have a cable 150 | from the Poplar's micro USB based serial port to your host 151 | system so you can connect and observe activity on the serial port. 152 | For me, the board console shows up as /dev/ttyUSB0 when the USB 153 | cable is connected. The serial port runs at 115200 baud. I use 154 | this command to see what's on the console: 155 | 156 | ```shell 157 | screen /dev/ttyUSB0 115200 158 | ``` 159 | 160 | ### Step 2: Insert the USB flash drive on the Poplar board 161 | 162 | - There are a total of 4 USB connectors on the Poplar board. Two 163 | are USB 2.0 ports, they are stacked on top of each other. Insert 164 | the USB memory stick into one of these two. 165 | 166 | - There is a "USB_BOOT" button on the board. It is one of two 167 | buttons on same side of the boards as the stacked USB 2.0 ports. 168 | To boot from the memory stick, this button needs to be depressed 169 | at power-on. You only need to hold it for about a second; 170 | keeping it down a bit longer does no harm. 171 | 172 | - Next you will be powering on the board, but you need to interrupt 173 | the automated boot process. To do this, be prepared to press a 174 | key, perhaps repeatedly, in the serial console window until you 175 | find the boot process has stopped. 176 | 177 | ### Step 3: Boot the Poplar board from the USB flash drive 178 | 179 | - Power on the Poplar board (while pressing the USB_BOOT button), 180 | and interrupt its automated boot with a key press. This should 181 | lead to a `poplar# ` prompt. 182 | 183 | - If the board does not power up properly, something is wrong with the 184 | images built or USB flash drive created. The console log should give 185 | some details regarding the error. 186 | 187 | ## Re-flash images onto the Poplar board eMMC 188 | 189 | Follow [Steps 3-4](debian_build_instructions.md#step-3-configure-the-poplar-ethernet-interface) 190 | of the [Flash images onto the Poplar board eMMC](debian_build_instructions.md#flash-images-onto-the-poplar-board-emmc) 191 | section in [debian_build_instructions.md](debian_build_instructions.md) 192 | to re-flash working images onto the board. 193 | 194 | ## Additional information about the recovery files 195 | 196 | The following paragraphs provide some more information about the 197 | files found in the `recovery_files` directory. 198 | 199 | #### fastboot.bin 200 | When this file is placed in the first partition of a USB memory 201 | stick formatted with a FAT32 file system, that memory stick can 202 | be used to boot the Poplar board. This is useful if the board 203 | has become "bricked" and is otherwise unusable. 204 | 205 | #### install, install-layout, install-partition1, install-partitionX 206 | These are human-readable versions of installer scripts used by 207 | U-Boot. The top-level installer is `install`; it loads and 208 | executes the other install scripts. Each install script has a 209 | corresponding ".scr" file (e.g., `install.scr`), which is the file 210 | that U-Boot actually uses. `install-layout` installs the Master 211 | Boot Record and the Extended Boot Records required for partitions 212 | 5 and above. `install-partitionX` contains commands to install 213 | the contents of just one partition. 214 | 215 | Each `install*.scr` file can be loaded into U-Boot and run. If 216 | the top-level `install.scr` is used, it will execute all the 217 | others. Otherwise, partial installs can be performed by, for 218 | example, loading and running `install-layout.scr` to re-write the 219 | boot records, or `install-partition2.scr` to re-write only 220 | partition 2. 221 | 222 | #### mbr.bin.gz, ebr5.bin.gz, ebr6.bin.gz 223 | These are the Master Boot Record and Extended Boot Records for 224 | partitions 5 and 6. They are compressed. They are normally 225 | loaded and flashed to eMMC using `install-layout`. 226 | 227 | #### partition1.1-of-1.gz, partition3.1-of-4.gz, etc. 228 | These are files that contain (parts of) the contents of the 229 | partitions. The contents of an entire partition can't fit 230 | entirely in memory, so large partitions are broken into pieces. 231 | Each piece is compressed. The install script for the partition 232 | takes care of uncompressing each part before writing it to eMMC. 233 | --------------------------------------------------------------------------------