# README-pm9263-linux.ronetix # Creating a working system with Linux kernel and so. # This guide is for PM9263 on BB9263. # # Ronetix GmbH # www.ronetix.at # August, 2011 # Table of Contents: 1. Before you start 2. Toolchain 3. U-Boot 4. Linux kernel 5. OpenEmbedded 6. Develop 7. Kernel debugging 8. PM9263 pre-built images 1. Before you start The instructions in the README files are meant to be done under GNU/Linux environment. 1.1. Connecting to the boards A serial terminal connection through RS-232 null modem cable is needed to control U-Boot and GNU/Linux. To set up U-Boot run time a serial terminal connection must be used, this is the only way you can get access to the U-Boot command line. The Linux boot messages are transmeeted to the same serial connection. The Serial Debug interface is set to 115200 bps with 8 data bits, one stop bit and no parity. Use the screen command like this "screen /dev/ttyS0 115200 cs8,-cstopb,-parenb" or minicom utility. 1.2. Networking As tftp or ftp servers are needed call your system/network administrator to give you the settings. The IP address can be obtained using DHCP service or set statical IP. After the IP address is set and know, a link to the board running GNU/Linux can be made with telent. 2. Toolchain 2.1. Description The GNU Toolchain, is a combination of multiple projects: * GCC : GCC stands for "GNU Compiler Collection". GCC is an integrated distribution of compilers for several major programming languages. These languages currently include C, C++, Objective-C, Objective-C++, Java, Fortran, and Ada. Currently the Blackfin is supported by C, and C++. * Binutils : GNU Binutils are a collection of binary tools. The main ones are: the GNU linker (ld) and the GNU assembler (as). * Debugger : GNU debugger, allows you to see what is going on `inside’ another program while it executes -- or what another program was doing at the moment it crashed. 2.2. GNU toolchain notes The pre-built GNU toolchains can be found http://download.ronetix.info/toolchains/arm/ Linux: The Linux kernel reqires a minimal GCC version in order to compile. To check that minimal versin take a look at the README file in the Linux source directory. U-Boot: U-Boot can not be compiled with some toolchains because of (E)ABI conformation. The USE_PRIVATE_LIBGCC parameter allows the usage of different run-time support library(libgcc.a). More on using this parameter see README in U-Boot source directory. 2.3. Download and install the GNU toolchain A. Installation of "KaeilOS v2010.1 SDK" This is SDK produced by OpenEmbedded recipes. It includes and package management system opkg. It includes development sources form the packages in KaeilOS. Download the two files and extract them in the "/" directory. They could be extracted in any directory, and then the file "/usr/local/kaeilos/arm/environment-setup" have to be edited and prefix the "SDK_PATH" value with the "work directory". And also remove the line which sets the CPATH environment. Before compiling execute ". /usr/local/kaeilos/arm/environment-setup". The toolchain prefix is "arm-oe-linux-gnueabi-". $ wget http://download.ronetix.info/toolchains/arm/kaeilos-2010.1/kaeilos-2010.1-20110221-i686-linux-armv5te-linux-gnueabi-toolchain-extras.tar.bz2 $ wget http://download.ronetix.info/toolchains/arm/kaeilos-2010.1/kaeilos-2010.1-20110221-i686-linux-armv5te-linux-gnueabi-toolchain.tar.bz2 $ su - # tar -C / -xjf kaeilos-2010.1-20110221-i686-linux-armv5te-linux-gnueabi-toolchain-extras.tar.bz2 # tar -C / -xjf kaeilos-2010.1-20110221-i686-linux-armv5te-linux-gnueabi-toolchain.tar.bz2 # exit $ . /usr/local/kaeilos/arm/environment-setup $ echo '#include int main(int argc, char** argv) { printf("Hello World!\n"); return 0; } ' > hello.c $ arm-oe-linux-gnueabi-gcc hello.c -o hello B. The rest of the toolchains. The toolchains will be installed in the /usr/cross directory. $ wget http://download.ronetix.info/toolchains/arm/ronetix-arm-linux-4.3.3.tar.bz2 $ su - # cd / # tar xvfj ronetix-arm-linux-4.3.3.tar.bz2 # exit Setup the path: $ export PATH=/usr/cross/arm-linux-4.3.3/bin:$PATH 3. U-Boot 3.1. Short introduction U-BOOT is used for basic initialization of the PM9G45/PM9263/PM9261 boards and for loading and starting an Operating system or an user application. The loading can be done via the various FLASH devices or the Ethernet. U-BOOT supports the following devices on the PM9G45/PM9261/PM9263 board: - NOR Flash - Dataflash - NAND flash - Ethernet - LCD - USB 3.2. Download and install the U-BOOT Some features are not in the U-Boot mainline, so you need to apply them manually. A. Get U-Boot as tar.bz2 $ wget http://download.ronetix.info/boards/linux/bootloader/u-boot-2010.09/u-boot-2010.09.tar.bz2 $ tar xjf u-boot-2010.09.tar.bz2 $ mv u-boot-2010.09 u-boot $ cd u-boot $ git init $ git add * $ git add .gitignore $ git commit -m "U-Boot v2010.09" $ git checkout -b v2010.09-pm9263 $ cd .. B. Get U-Boot with git clone For easey code management(trace and history of changes, patch submit and so) it is good to use revision control(in this case GIT). To get U-Boot using git, if you prefer tar.bz2 skip getting U-Boot using git. $ git clone git://git.denx.de/u-boot.git u-boot $ cd u-boot $ git checkout -b v2010.09-pm9263 v2010.09 $ cd .. 3.3. Apply the porvided patches $ wget http://download.ronetix.info/boards/linux/bootloader/u-boot-2010.09/u-boot-patches-bb9g45-v2010.09.tar.bz2 $ tar xjvf u-boot-patches-bb9g45-v2010.09.tar.bz2 $ cd u-boot $ for N in ../u-boot-patches-bb9g45-v2010.09/*.patch ;do git am $N ; done 3.4. Configuration The U-Boot configuration files named as the respective Ronetix CPU modules are: - include/configs/pm9g45.h - include/configs/pm9263.h - include/configs/pm9261.h The definitions in these header files are explained in the README file in the U-Boot source. If needed set the lines for the network interface as show. In the config files only the ETHADDR is set, the rest parameters can be obtained runtime in the U-Boot prompt by invoking the command "dhcp". #define CONFIG_ETHADDR 02:00:00:FE:ED:01 #define CONFIG_IPADDR 192.168.3.222 #define CONFIG_NETMASK 255.255.255.0 #define CONFIG_GATEWAYIP 192.168.3.1 #define CONFIG_SERVERIP 192.168.3.1 #define CONFIG_OVERWRITE_ETHADDR_ONCE /* Read Using it! */ These parameters can be modified later and set to a environment variables, except "ethaddr". If you do not want LCD support, comment as shown: /* No need of LCD * #define CONFIG_LCD 1 */ You may leave the configs as they are, test and then change as needed. 3.5. Configure and build $ make pm9263_config The common part for all boards: $ export USE_PRIVATE_LIBGCC=yes $ export CROSS_COMPILE=arm-oe-linux-gnueabi- $ export ARCH=arm $ make 3.6. Programming U-Boot for PM9263 The file u-boot.bin must be programmed in the FLASH at address 0x10000000. The environment of U-Boot is at address 0x10040000. If you use PEEDI the command is: A. Using PEEDI peedi> flash set 0 ; select the first flash profile peedi> flash program u-boot.bin bin 0x10000000 erase B. Using U-Boot u-boot> tftp 0x20020000 u-boot.bin u-boot> erase 0x10000000 +${filesize} u-boot> cp.b 0x20020000 0x10000000 ${filesize} 4. Linux kernel 4.1. Getting and unpacking the Linux kernel for PM9263 Linux kernel 2.6.28 $ wget http://download.ronetix.info/boards/linux/kernel/2.6.28/linux-2.6.28.tar.bz2 $ wget http://download.ronetix.info/boards/linux/kernel/2.6.28/001_linux-2.6.28-at91.patch $ wget http://download.ronetix.info/boards/linux/kernel/2.6.28/002_linux-2.6.28-exp.patch $ wget http://download.ronetix.info/boards/linux/kernel/2.6.28/003_linux-2.6.28-at91-ronetix-20112009.patch $ tar xjf linux-2.6.28.tar.bz2 $ cd linux-2.6.28 $ patch -p1 < ../001_linux-2.6.28-at91.patch $ patch -p1 < ../002_linux-2.6.28-exp.patch $ patch -p1 < ../003_linux-2.6.28-at91-ronetix-20112009.patch 4.2. Kernel config To carry into effect the default kernel configuration you have to do the following. $ make pm9263_defconfig If you want to change something in the kernel do the following: $ export ARCH=arm $ make menuconfig On exit save the changes. 4.3. Kernel build uImage is the Linux kernel packed(U-Boot wrapped zImage) in format for loading by U-Boot. The "mkimage" utility which is part of U-Boot is required to be in the executable search path(environment variable PATH). The "mkimage" can be aken from http://download.ronetix.info/boards/tools/linux/mkimage or obtained after building U-Boot for an ARM board. $ echo Make sure "mkimage" is in the executable search path! $ export CROSS_COMPILE=arm-oe-linux-gnueabi- $ make uImage The binary file for programming is arch/arm/boot/uImage. 4.4. Programming of the Kernel for PM9263 A. Using PEEDI peedi> flash set 1 ; select the second flash profile peedi> flash program B. Using U-BOOT u-boot> tftp 0x20020000 vmImage.bin u-boot> erase 0x10050000 +${filesize} u-boot> cp.b 0x20020000 0x10050000 ${filesize} 5. OpenEmbedded 5.1. Preparation First you need to prepare your host linux distribution in order to be able to get and build KaeilOS. A list of required packages for variety of host distributions is described in: http://wiki.openembedded.net/index.php/OEandYourDistro http://wiki.openembedded.net/index.php/Main_Page Lets prepare directory structure. Login on your host as ordinary user not as root(root privileges are not needed and a good practice is to avoid being root if not needed). You can login as a user you like. Starting point is being in the home directory. You may choose working directory at your decision, but be aware of the paths. Make directory for doing things and go to it: $ cd $ mkdir -p usr/src/oe $ cd usr/src/oe Now it is time to get bitbake - the building tool. All thing here are done with bitbake version 1.10.2. And don't install bitbake globally, install it as a sibling directory of openembedded/ and build/. $ git clone git://git.openembedded.org/bitbake.git $ cd bitbake $ git pull $ git checkout -b _tag_1.10.2 1.10.2 5.2. Getting openembedded - meta data, packages, relations and more Get it, go to directory openembedded/ and update. $ git clone git://git.openembedded.org/openembedded $ cd openembedded $ git pull Now you have the development branch of openembedded master. The org.openembedded.dev branch is depreciated. Check that you are in development branch. $ git branch * master $ As the OE is developing continuously sometimes the OE can not be build successfully so you can keep updating OE untill it builds or use a build verified state(commit). A. Keep updating Ao after git-clone create a branch and try to build images with it. If the building is successful keep the branch, but if building is unsuccessful keep pulling until you get a working OE commit, or you can try to fix the problem. $ git checkout -b dev_snapshoot Switched to a new branch "dev_snapshoot" $ git pull origin master:dev_snapshoot B. Use a verified state That state can be found here http://www.kaeilos.com/latest-changes It is good to to make a branch after clonning. $ git checkout -b state_070cbda $ git reset --hard 070cbda8e9c073c8fd3b89d2a4c49acbc7fb7918 FIX: This is last verified commit. Commit date: FIX: Build date: FIX: !!! BIG FAT WARNING !!! Warning: even the tested OpenEmbedded/Bitbake metadata state after "some" time can not produce the desired images, due to URL sources are not available, most probably a new version, and the old one is removed. Example of this is missing live.2010.10.15.tar.gz from recipe live555_20101015.bb. Also there is recipes referring to a source in a svn, git or other repositories, which at the build time could be with broken sources like mplayer. 5.3. Get KaeilOS settings and configuration files and then extract them $ wget ftp://ftp.koansoftware.com/public/kaeilos/kaeilos-4.05-config-files.tgz $ tar xzvf kaeilos-4.05-config-files.tgz Get custom-extra-image.bb recipe file and save it in $OEBASE/openembedded/recipes/images: $ wget http://download.ronetix.info/boards/linux/rootfs/custom-extra-image.bb \ -O openembedded/recipes/images/custom-extra-image.bb Edit the files listed below so that they contains the correct paths. Use the absolute path: - in file setup-kaeilos.sh correct BB_DIR to point to $OEBASE/btibake/ and OE_DIR to point to $OEBASE/openembedded/ - also in the same file(setup-kaeilos.sh) make it looks like: --- part of setup-kaeilos.sh lines 16:29 --- echo "Preparing KaeilOS build environment ver." $SETUP_KAEILOS_VER cd $BB_DIR # Bitbake not enymore in svn repository, not it is git one. echo "Checking bitbake" ##svn cleanup ##svn update git branch cd $OE_DIR # Do not pull, use the present state and if needed chnage manualy. echo "Checking OpenEmbedded" ##git pull git branch cd $HERE cd $1 --- part of setup-kaeilos.sh lines 16:29 --- - in build/kaeilos/conf/auto.conf you can select the machine to build KaeilOS for. The default machine is "ronetix-pm9263", to build for pm9g45 change the name "ronetix-pm9263" to "ronetix-pm9g45", and if the case is pm9261 use "ronetix-pm9261" - in build/kaeilos/conf/local.conf change DEPLOY_DIR_PSTAGE to point to "$OEBASE/build/kaeilos/tmp/pstage/", and if you work in a screen session leave the three lines below "# Enable devshell with screen and bash", in the other case comment these three lines. And please don't comment sending automatic reports. --- part of build/kaeilos/conf/local.conf lines 23:33 --- # Enable devshell with screen and bash #SCREEN_TERMCMD = 'screen -D -m -t "$TERMWINDOWTITLE" -s /bin/bash' #TERMCMD = "${SCREEN_TERMCMD}" #TERMCMDRUN = "${SCREEN_TERMCMDRUN}" # Enable this to send automatic success and failure reports #http://wiki.openembedded.net/index.php/How_do_I_send_automatic_success_and_failure_reports INHERIT += "oestats-client" OESTATS_SERVER = "tinderbox.openembedded.net" OESTATS_BUILDER = "kaeilos-user" --- part of build/kaeilos/conf/local.conf lines 23:33 --- - in the above file change the DISTRO parameter form "kaeilos" to "kaeilos-2010" - also remove "ext2" parameter in IMAGE_FSTYPES - in build/kaeilos/conf/site.conf correct DL_DIR to become "$OEBASE/sources/" and correct BBFILES = "$OEBASE/openembedded/recipes/*/*.bb" 5.4. Initial building of the system You should be in $OEBASE directory. Running this command for the first time will take a some hours to finish: $ source setup-kaeilos.sh /home/ivan/usr/src/oe/build/kaeilos $ bitbake custom-extra-image Warning: custom-extra-image.bb is recipe example, it is useful to to demonstrate how to add stuff you like/want. It is buildable with the OpenEmbedded/Bitbake latest metadata state mentioned at "2. Getting openembedded - meta data, packages, relations and more". Doe to continuous change/improvement of OE there could be a time when some packages included in the custom-extra-image.bb are not buildable, and the items in the custom-extra-image.bb have to be adopted. The "x11-image", "console-image" and "console-base-image" are general for OE. Warning: even the tested OpenEmbedded/Bitbake metadata state after "some" time can not produce the desired images, due to URL sources are not available, most probably a new version, and the old one is removed. Example of this is missing live.2010.10.15.tar.gz from recipe live555_20101015.bb. Also there is recipes referring to a source in a svn, git or other repositories, which at the build time could be with broken sources like mplayer. This initial system building is to let the OpenEmbedded build the system as it is by default, and later you can customize it. Note that toolchains installation is not required as the OE makes it. There is an option to tell OE to use external toolchains. 5.5. Kernel configuring Go to $OEBASE/build/kaeilos to configure and build your linux kernel: $ cd $OEBASE/build/kaeilos $ bitbake virtual/kernel -c menuconfig 5.6. Kernel building Next comes to compile, populate stage directory, install the kernel. Executing these task will compile kernel and modules, make head files to be in the stage directory and finally copy kernel and modules to $DEPLOY directory. $ bitbake virtual/kernel -c compile -f $ bitbake virtual/kernel 5.7. RootFS building To create RootFS go to $OEBASE/build/kaeilos: $ cd $OEBASE/build/kaeilos $ bitbake custom-extra-image The RootFS image is in the $DEPLOY directory. This is the image you should program into the NAND Flash of PM9263: KaeilOS-custom-extra-image-glibc-ipk-2009.1-test-20090914-ronetix-pm9263.rootfs.jffs2 5.8. Export SDK Creating a toolchain(SDK) is the same as creating a rootfs image. From the $OEBASE directory: $ source setup-kaeilos.sh /home/ivan/usr/src/oe/build/kaeilos $ bitbake meta-toolchain and the resulted SDK is in $DEPLOY directory. For reference: http://docs.openembedded.org/usermanual/html/commonuse_qte_sdk.html http://docs.openembedded.org/usermanual/html/ch05s08.html 5.9. ROOTFS programming into the NAND flash for PM9263 Note:The Linux kernel scans the whole rootfs partition, to create the JFFS2 file system summary, and if on that partition there are blocks from the older root file system, the new one could not be mounted properly and most probably will fail. So erase the whole Linux rootfs partition on NAND (MTD partition). PEEDI is not aware of MTD partitions, so erase the that partition size from the start of it. This applies for U-Boot, too. A. Using PEEDI peedi> flash set 2 peedi> flash erase peedi> flash program B. Using U-BOOT Caution: the RootFS image larger than 62MiB can't be programmed by U-BOOT, because it doesn't fit in the SDRAM. u-boot> nand erase clean u-boot> tftp 0x20020000 rootfs.jffs2 ; the image should less ; than 62MiB u-boot> nand write.jffs2 0x20020000 0 ${filesize} 5.10. Tips and tricks 5.10.1. Rotate KaeilOS boot logo In /etc/defaul/psplash add "--angle 90" in psplash arguments variable, so that splash screen is rotated properly. 5.10.2. Enable/Disable mouse pointer in X In /etc/matchbox/session find the line starting with "exec matchbox-window-manager" and change to "-use_cursor no" or to "-use_cursor yes" to hide or show mouse pointer. 5.10.3. To rotate X display properly you can execute this from the command line A. KDrive (now obsolete) $ sed -i '/case `module_id` in/ a\ "Ronetix PM9261" | "Ronetix PM9261/BB9261" | "Ronetix PM9263" | \\\ "Ronetix PM9263/BB9261" | "Ronetix PM9263/BB9263") \ ARGS="$ARGS -rgba bgr -screen 240/54x320/81@90x16" ;; ' /etc/X11/Xserver B. Xorg Take a look at /etc/X11/xorg.conf in Section "Device", and add or change the Option "Roatate", like this: Option "Rotate" "CCW" Adjusting touchscreen axes, in 'Section "InputDevice"' modify or add: Option "SwapAxes" "True" Option "InvertX" "True" Option "InvertY" "True" 5.10.4. Getting eth0 gateway parameter from dhcp In /etc/network/interface add "iface eth0 inet dhcp" before "iface eth0 inet static" line. Form the command line call "udhcpc" or "dhclient eth0" to set network through DHCP server. 5.10.5. Calibrating the touchscren In Kdrive the "xtscal" is used, but in Xorg "ts_calibrate" is used. A. In the first runnning of Linux, GPE login screen is preceded by touch screen calibration. B. To calibrate the screen in the login prompt touch randomly on the screen, from 30 second to 1 minute and the calibration screen will appear again. C. From a terminal using keyboard on USB port, run "xtscal" D. Form Settings/Screen Setting press the "start" button in the calibration section. 6. Develop 6.1. Compiling a simple GNU/Linux application Create a text file example.c with contents: --- example.c --- #include int main(int argc, char** argv){ printf("Hello world\n"); return 0; } --- example.c --- Compiling: Substitute "arm-oe-linux-gnueabi-gcc" with the toolchain used to build kernel and root file system utilities. $ arm-oe-linux-gnueabi-gcc -o example example.c The result is the ELF file called "example". 6.2. Transferring the executable file from the PC to the target A. Using USB stick The simples way is to use a USB stick - just copy the file example to a USB stick inserted into your PC. Unmount the stick and put it into the target board. After few seconds the USB stick will be discovered(most probably). You should have support of the file system on the USB stick, most probably it will be VFAT(FAT32). Take a look at the kernel messages to see the device node of your USB stick. Depending auto-mounter is enabled and installed on the rootfs, the USB stick could be automatically mounted. To see if it is automatically mounted: On target hachine: # mount /dev/sda1 on /media/sda1 In case it is not mounted automatically: On target machine: # mkdir /mnt/sda1 # mount /dev/sda1 /mnt/sda1 -t vfat # cp /mnt/sda1/main . # chmod +x main # ./main Hello world B. Tftp over network A tftp server should work on a host(or any development) computer. On host: $ cp hello tftp_boot_dir/ On target machine: # udhcpc # tftp -g -r tftp_boot_dir/hello -l hello 192.168.3.1 # chmod u+x hello # ./hello Hello world Alternatively to the "udhcpc" you can use "dhclient eth0". 6.3. Debugging application TODO: 7. Kernel debugging The board should be programmed with the u-boot and the binary version of the kernel. Start gdb/insight: $ arm-oe-linux-gnueabi-gdb vmlinux In the console window: (gdb) target remote peedi_ip:2000 (gdb) set $pc = 0x10000040 ; the u-boot is flashed at ; 0x10000000 (after remap) (gdb) c The board is running: first starts the u-boot, then the Linux kernel. If you have a serial console you can see that the Linux is working. Now you can halt the kernel and set breakpoints where you want. If you want to have a breakpoint before the kernel is running you have to do the following: (gdb) target remote peedi_ip:2000 (gdb) set $pc = 0x10000040 ; assuming the u-boot is flashed ; at 0x10000000 (gdb) hbreak start_kernel ; hardware breakpoint is used ; because the MMU is still not ; active (gdb) c The board is running (u-boot, then the kernel) and will stop at the start_kernel function. (gdb) delete ; delete the hardware breakpoint. Now you can use the software breakpoints. 8. PM9263 pre-built images U-Boot: http://download.ronetix.info/boards/linux/bootloader/u-boot-2010.09/pm9263_u-boot.bin Linux Kernel: http://download.ronetix.info/boards/linux/kernel/2.6.28/uImage-2.6.28-r12-ronetix-pm9263.bin RootFS: http://download.ronetix.info/boards/linux/rootfs/2.6.28-pm9263/KaeilOS-console-image-glibc-ipk-2009.1-test-20090909-ronetix-pm9263.rootfs.jffs2 or http://download.ronetix.info/boards/linux/rootfs/2.6.28-pm9263/KaeilOS-custom-extra-image-glibc-ipk-2009.1-test-20090916-ronetix-pm9263.rootfs.jffs2