CI20 Dev Zone

Everybody is welcome, and encouraged, to contribute back to the CI20 community, no matter how big or small their contribution is.

Contributions can come as small as a bug report, to some distro or Linux kernel work, to placing a whole new OS or distro on the board.

There are a number of ways to contribute, and a number of channels to help you along.

Source Code
The linux kernel and u-boot sources for the CI20 are publically available on github.

Linux Kernel
The CI20 kernel source code is available on github.

https://github.com/MIPS/CI20_linux

There are presently two versions of the kernel
 * the ci20-v3.0.8 kernel branch as shipped by default in the Debian NAND image derived directly from the Ingenic kernel source code releases.
 * the latest kernel branch (ci20-v3.18 as of 02-03-2014) tracking mainline which is a nearly complete work in progress of upstreamable quality code to be soon pushed towards kernel.org. See details about this branch here CI20_upstream

Patches for the CI20 kernel and u-boot should be submitted to the CI20 development mailing list.

Once the CI20 code is accepted into upstream repositories and mainline kernel.org then patches should go via the appropriate upstream mailing lists and maintainers as suggested by ./scripts/get_maintainer.pl.

U-boot
The CI20 U-boot source is available on github

https://github.com/MIPS/CI20_u-boot

The ci20-v2013.10 branch of U-boot is the one shipped in the factory NAND image.

Bug reports
Bug reports for the CI20 are being taken via the github issue tracker linked to the CI20 kernel git repositories.

For linux kernel

https://github.com/MIPS/CI20_linux/issues

For u-boot

https://github.com/MIPS/CI20_u-boot/issues

Mailing lists and Forum
The CI20 has user & development mailing lists/forums via google groups

IRC
CI20 also has an IRC channel #ci20 on freenode.net

NAND Flashing SD card
The NAND Flashing SD image creates an SD card that boots via mmc and writes the NAND of the CI20.

This can be used to restore the NAND on your CI20 to the factory default state, or upgrade the NAND image to a newer factory image file.

Note: Any changes you have made to your NAND (installed programs etc) will be irrecoverably lost during the NAND flash process. This will restore the CI20 NAND OS to the clean factory image state.

Linux
1. Open a terminal

2. To determine the device name of the SD card, run lsblk which will list all block devices. Then insert the SD card, wait a few seconds, and run lsblk again. A new device plus any partitions should have appeared compared to the original list, the SD card will be the new top level device. Be sure that you have the right device name!

3. Unmount all partitions on the SD card. If the device name were sdx, this would be done with:

umount /dev/sdx*

4. Write the image file with the following (replacing sdx with the correct device name):

dd if=debian6-20130815.img of=/dev/sdx bs=8M

5. When it completes (note that dd will give no progress indication), run:

sync

6. Remove the SD card.

7. Put SD card in CI20.

8. Check the boot_sel switch is on the mmc boot mode.

9. Boot and wait (~10 minutes) for the LED to go from red to blue (nand writing) and then red!

10. The NAND has been flashed to factory default state. Power off the board. Remove the SD card. change the boot_sel switch to NAND boot mode. And boot the board.

Mac OS X
1. Open a terminal (/Applications/Utilities/Terminal.app).

2. Plug the SD card into your Macintosh. List the block devices on your system by running: diskutil list

3. Using diskutil's output, Identify the device name for the SD card by finding the entry which matches your SD card's partition name and size. The device name is of the form /dev/diskX, where X is some number. Make sure you've got the right one before continuing!

4. Unmount the mounted partitions on the SD card: diskutil unmountDisk /dev/diskX

5. Write the new image to the SD card (it might take a while to finish): sudo dd if=debian6-20130815.img of=/dev/diskX bs=8m

6. When it completes (note that dd will give no progress indication), run: sync

7. Remove the SD card.

8. Put SD card in CI20.

9. Check the boot_sel switch is on the mmc boot mode.

10. Boot and wait (~10 minutes) for the LED to go from red to blue (nand writing) and then red!

11. The NAND has been flashed to factory default state. Power off the board. Remove the SD card. change the boot_sel switch to NAND boot mode. And boot the board.

Windows
1. Download and run Win32DiskImager: http://sourceforge.net/projects/win32diskimager

2. Insert the SD card, and select the image file and the drive letter for the SD card in Win32DiskImager. Win32DiskImager may not be able to see built-in SD card slots, so if it doesn't show up, use a USB adapter instead.

4. Click Write and wait for it to complete.

5. Close the imager and then remove the SD card.

6. Put SD card in CI20.

7. Check the boot_sel switch is on the mmc boot mode.

8. Boot and wait (~10 minutes) for the LED to go from red to blue (nand writing) and then red!

9. The NAND has been flashed to factory default state. Power off the board. Remove the SD card. change the boot_sel switch to NAND boot mode. And boot the board.

Toolchain
For cross-compiling code, to build the Kernel or U-Boot from sources you will need a MIPS toolchain, e.g. the Sourcery CodeBench toolchain, and u-boot-tools for mkimage

For the toolchain, use Sourcery CodeBench Lite 2013.11-36 for MIPS GNU/Linux available here

https://sourcery.mentor.com/GNUToolchain/release2640

The Getting Started guide on the link above explains the install process

Little Endian switch
Note: By default, the toolchain compiles programs for big endian configuration. The JZ4780 on the CI20 is little endian. When compiling programs, do pass -EL so the binary is little endian.

mips-linux-gnu-gcc -EL helloworld.c -o helloworldapp

Building uboot from sources
For u-boot-tools and mkimage run,

sudo apt-get install u-boot-tools

Clone the U-Boot repositories from github. For U-Boot,

To build U-Boot:

git checkout ci20-v2013.10 make ARCH=mips CROSS_COMPILE=mips-linux-gnu- ci20_mmc make ARCH=mips CROSS_COMPILE=mips-linux-gnu-

Note, the CROSS_COMPILE for the toolchain path must be set in your environment.

This will generate 2 files, spl/u-boot-spl.bin and u-boot.img. We will use them in the next sections.

Building Linux Kernel from sources
For the Linux kernel, there are 2 branches that you can use:


 * ci20-v3.0.8: Default 3.0.8 kernel. All hardware supported.
 * ci20-v3.xx: the latest kernel branch (3.16 as of 08-08-2014) tracking mainline which is a nearly complete work in progress of upstreamable quality code to be soon pushed towards kernel.org. For details on driver support, check the github branch readme page.

Note: various other branches might have wip-updates.

Clone the repository from github. To build the kernel for 3.0.8 (change branch name accordingly):

git checkout ci20-v3.0.8 make ARCH=mips ci20_defconfig make ARCH=mips CROSS_COMPILE=mips-linux-gnu- uImage

Adjust CROSS_COMPILE with the toolchain path if it isn't in your $PATH. You can also set it in your environment.

This will give you a uImage for the kernel (arch/mips/boot/uImage for 3.15 onwards, arch/mips/boot/compressed/uImage for 3.0.8).

Building GPU Kernel Module from sources
The GPU driver relies on an out of tree kernel module. The kernel module has to be recompiled when you recompile the kernel. For more details and instructions visit CI20-SGX kernel module

Making a bootable SD card from sources
To make a bootable SD card, first partition your card with an MBR such that the first partition starts at an offset of no less than 270KB. To do that,

Run

lsblk

before and after plugging your SD card writer, to check which device is your SD card.

The following example considers the SD card writer to be loaded on /dev/sdx

The following command partitions your SD card (MAKE SURE GET THE SD CARD WRITER DEVICE CORRECT!). Paste it as is

sudo sfdisk /dev/sdx -uM -L << EOF 2,,L EOF

Then create an ext4 partition using

sudo mkfs.ext4 /dev/sdx1

Then delete the old environment variables in the SD card, install U-Boot SPL & the full U-Boot image to the card like:

dd if=/dev/zero of=/dev/sdx bs=1K seek=526 count=32 dd if=spl/u-boot-spl.bin of=/dev/sdx obs=512 seek=1 dd if=u-boot.img of=/dev/sdx obs=1K seek=14 sync

Mount the ext4 partition using

mount /dev/sdx1 /mnt

Then copy your kernel image to the ext4-formatted partition.

cp /path_to_uImage /mnt/boot/vmlinux.img sync

Unmount the SD card

umount /mnt

At this point, the board will boot with u-boot and the kernel. But it will panic without a filesystem. You still need a rootfs.

You can use any existing tarball for a rootfs and extract it in the ext4 partition of the SD card. Or you can use buildroot

The following script implements these steps.

make flash card

Note on previous u-boot environment saved on SD card
If you follow the steps above again on an SD card on which you had already installed u-boot previously, you might note that the environment variables from your previous installation are already there.

The environment data for SD cards is 32KiB in size & starts 526KiB into the card (which leaves 512KiB for u-boot.img).

If you want to clear your environment when writing your card then just run dd an extra time something like this:

dd if=/dev/zero of=/dev/sdx bs=1K seek=526 count=32

Or if you want to reset to the default environment from the U-boot shell you can do something like this:

env default -a env save

Using Buildroot
Buildroot is a small rootfs which can be easily loaded to the ram and runs from there. Note, if the filesystem is built as a ramdisk, no configuration is saved if rebooted.

We can use buildroot to build a ramdisk.

git clone git://git.busybox.net/buildroot buildroot cd buildroot make qemu_mipsel_malta_defconfig make menuconfig

The malta_defconfig is a good basic start and boots on the ci20.

Enable the following options in buildroot

Toolchain --> Toolchain type --> External toolchain (download or select path of your preinstalled toolchain) Filesystem images --> cpio the root filesystem Kernel --> 

Exit and Save the configuration.

make

Once the build has finished, you should have an output/images/rootfs.cpio.gz file. Lets ignore it for now

To build the kernel with the Ramdisk, in the kernel sources directory, after the previous kernel compile instructions have been carried out.

make ARCH=mips CROSS_COMPILE=mips-linux-gnu- menuconfig

General setup --> Initial RAM filesystem and RAM disk (initramfs/initrd) support --> (/path_to_buildroot/arch/mips/boot/rootfs.cpio) Initramfs source files(s) Support initial ramdisks compressed using gzip ...    Built-in initramfs compression mode --> gzip

Save and Exit.

make ARCH=mips CROSS_COMPILE=mips-linux-gnu- uImage

This will generate a uImage with the ramfs. The file should be larger than the usual 3-4mb kernel as it has a ramdisk built in.

Copy the uImage file to the SD card in the /boot/vmlinux.img

Boot the board and enjoy :)

Loading the Linux Kernel over ethernet via tftp
You can load the kernel over TFTP.

First, set up a tftp server by following any of the following links :

http://askubuntu.com/questions/201505/how-do-i-install-and-run-a-tftp-server

Copy the kernel image to the root of the TFTP server and

Boot the board with serial console. Stop the auto boot during uboot and then run:

dhcp 0x88000000 :uImage bootm 0x88000000

You can set the bootcmd environment variable and save it to the SD card so that you will not need to type these commands each boot. For example:

env set bootcmd dhcp 0x88000000 :uImage\; bootm 0x88000000 env save

This will configure automatic booting over TFTP. Note that the backslash before the semicolon is important.

How to make your own rootfs
Articles describing how to generate your own rootfs can be found in the CI20 Rootfs Guides Category.
 * How to make a debian rootfs for MIPS CI20
 * How to make a buildroot rootfs for MIPS CI20

Guidelines on booting via NFS filesystem
Set up a rootfs in your nfs export directory. Here is a short version of how to do that

Do not set up the rootfs in a subdirectory. Add the following in /etc/export

/export 192.168.1.0/24(rw,fsid=0,insecure,no_subtree_check,async,no_root_squash)

Modify the IP depending on your network configuration

Restart the service

service nfs-kernel-server restart

You can use the rootfs tarball generated using How_to_make_a_buildroot_rootfs_for_MIPS_CI20.

Make sure permissions of your /export directory are 777.

Extract the tarball into /export using

tar -xapf rootfs.tar -C /export

Recompile the 3.0.8 kernel with the following options enabled. CONFIG_NFS_FS=y CONFIG_NFS_V3=y CONFIG_NFS_V4=y CONFIG_ROOT_NFS=y

These compile nfs support into the kernel.

If using 3.16, enable the following as well as they are not enabled by default in the 3.16 config. CONFIG_IP_PNP=y CONFIG_IP_PNP_DHCP=y CONFIG_MEMORY=y CONFIG_JZ47XX_NEMC=y

These compile dhcp support and external memory controller support (via which the ethernet chip is connected) into the kernel so the kernel can assign an ip to eth0 during boot.

Boot the new kernel with the following bootargs bootargs=console=ttyS4,115200 mem=256M@0x0 mem=768M@0x30000000 root=/dev/nfs nfsroot=192.168.XX.XX:/export ip=dhcp devtmpfs.mount=1 rw

Configure ttyS4/0 depending on your setup.

Configure your IP settings depending on your host system.

Note ip=dhcp can be replaced with an ip=192.168.YY.YY depending on your setup. A static ip can be assigned if dhcp is unavailable.

If you have tftp setup for transferring a kernel image, you can do the following

Boot the CI20. Stop via serial during u-boot.

dhcp 0x88000000 192.168.XX.XX:uImage; setenv bootargs console=ttyS4,115200 mem=256M@0x0 mem=768M@0x30000000 root=/dev/nfs nfsroot=192.168.154.89:/export ip=dhcp devtmpfs.mount=1 rw bootm 0x88000000;

Your board should boot into whichever rootfs you assigned.

Note: NFS can be difficult to initially setup. If kernel fails to mount nfs. It could be missing support of nfs in your kernel. Or a bad export on the server side.

You can check your export to see if it is ok using mount -t nfs localhost:/export tempdir

You can also use the init=/bin/sh option in the bootargs if something is fishy during init.