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.
The linux kernel and u-boot sources for the CI20 are publically available on github.
The CI20 kernel source code is available on github.
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.
The CI20 U-boot source is available on github
The ci20-v2013.10 branch of U-boot is the one shipped in the factory NAND image.
Bug reports for the CI20 are being taken via the github issue tracker linked to the CI20 kernel git repositories.
For linux kernel
Mailing lists and Forum
The CI20 has user & development mailing lists/forums via google groups
|List name||Description||Forum link||Subscribe via web||Subscribe via email||Feed|
|mips-creator-ci20||For general discussion & support||Forum||Subscribe||Subscribe via email||Atom|
|mips-creator-ci20-dev||For submission & review of patches||Forum||Subscribe||Subscribe via email||Atom|
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.
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:
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:
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:
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:
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.
1. Download and run 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.
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
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,
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
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.
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
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 --> <Disable the Linux kernel option. We built our own>
Exit and Save the configuration.
Once the build has finished, you should have an
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 :
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 <server IP>: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 <server IP>: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.
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
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.