From The Neuros Technology Wiki

Jump to: navigation, search
   We're working on cleaning this up, in the meantime, if you're looking for the easiest way to get started, check out OSD_Virtual_Machine_Development  
   or if you're looking to really dig in, check outDerobert's_Guide_to_Hacking_the_On-Screen_Display


General Description

With the developer board or development hardware on hand, all you need to set up the development environment with your host Linux PC is a serial cable, an Ethernet hub and two Ethernet cables. Well, you know what to do if you don't have the power adapter. ;-)

*NOTE: The OSD has an internal switch like a hub meaning you can actually connect an standard Ethernet cable directly between the PC and the OSD if you want.

Software-wise, on your host PC, you'll need to set up a TFTP server and NFS server, you'll also need a terminal program. With U-boot already installed on your Neuros target hardware, you can boot the Linux kernel via TFTP from your host PC and in turn the kernel can mount rootfs from the NFS drive. Thus you don't need to burn and FLASH every time you change the code, be it on Kernel side or the application itself.

In the following HOWTO the expression #BSP_ROOT# is to be replaced with the actual directory in which you checked out the BSP package from Neuros' CVS.


In order to set up the bsp, you'll need root permission to create the device root file system. The setup script and Makefiles use the sudo command to obtain root access.

In order for the sudo command to work correctly, you must have an entry for your user ID in /etc/sudoers. You need to edit this file as the root user. Also, you can add a default timestamp entry to disable sudo from periodically asking for your user password. The following two lines need to be added to the /etc/sudoers file.

Defaults:<user id> timestamp_timeout=-1 
<user id> ALL=(ALL) ALL 

The relevant portion of the /etc/sudoers I use is:

# Defaults specification 
Defaults:mgao timestamp_timeout=-1
# User privilege specification 
root ALL=(ALL) ALL 
mgao ALL=(ALL) ALL

Terminal program

You can choose whatever terminal program you like, I use kermit, minicom is another choice. I use /dev/ttyS0 and you need to set bps to 115200.

Instructions to set up minicom

To bring up the setup
   sudo minicom -s
go to "serial port setup"
   use /dev/ttyS0
   e->115200 8N1
   without any flowcontrol
go to "Modem" part,
   erase init/reset strings.
Save as default.

Bring up minicom
   minicom -w  #turn on word wrapping.

Instructions for kermit

Create a file called .kermrc in your home directory with the following contents:
   set line /dev/ttyS0
   set speed 115200
   set carrier-watch off
   set handshake none
   set flow-control none
   set file type bin
   set file name lit
   set rec pack 1000
   set send pack 1000
   set window 5
now start the program with kermit -c


tftp server package needs to be installed on host PC.

edit /etc/xinetd.d/tftp to,
   turn disable = no
   server_args  = -s #BSP_ROOT#
reload the config for tftp server
   ps ax | grep inetd
   kill -1 [inetd process ID]
or more easily
   sudo /etc/init.d/xinetd restart

Debian users just add the following line to /etc/inetd.conf

   tftp            dgram   udp     wait    nobody  /usr/sbin/tcpd  /usr/sbin/in.tftpd #BSP_ROOT#


The nfs server package needs to be installed on host PC. Install it (if it isn't already). In some distributions (like debian) it's called nfs-kernel-server instead of just nfs. Be sure to install the nfs server that runs in kernel space. The user space version (nfs-user-server) is harder to configure.

Edit /etc/exports and add something like the following:

   # NFS access dir

where #BSP_ROOT# is the directory you are exporting to the OSD (BSP Root) and is the IP address of the OSD.

Then, start, restart, or reload the nfs server by running

   /etc/init.d/nfs restart

(Again, it might be may be called nfs-kernel-server instead of nfs)


At this point, you should build your environment, if you have not yet done so. Follow the instructions in the README file in #BSP_ROOT#.

There is a seperate document for build instructions: Main-app Build Instructions


After attaching the serial cable and starting the terminal program, power on your device. You should see in the terminal uboot output, then you'll have to interrupt the countdown within three seconds to stop the boot process.

After interrupting the countdown, you need to check that uBoot is configured correctly to be able to boot from the network. You can view the current uBoot settings with printenv.

First set the correct IP addresses:

set ipaddr #this is the target board IP
set serverip #your host PC IP
set nfs_serverip #your host PC IP

Then the paths to retrieve kernel via TFTP and filesystem via NFS (the tftp_root is generally already ok) and to run it:

set nfs_root  #BSP_ROOT#/rootfs/fs
set tftp_root images
set bootcmd run devkernel

Then save the settings permanently. You won't need to repeat this whole uBoot setup step again.

run update-ipstatic
run update-locs

Finally let's try to get this thing rolling


Please follow U-boot manuals for more details on stuff you can set.

What to do next

Once you have the development environment set up and everthing is working, you may want to burn your 'code' on to the board, you have the following options from U-boot prompt,

  • generate installation images

This will properly strip binaries and create various images ready to be installed.

cd neuros-bsp
make install
  • update kernel
run update-kernel #this burns the kernel onto FLASH.
  • update root file system
run update-cramfs #this burns the /rootfs/fs/ files onto FLASH.

Beware that there is only 0x120000 bytes (1152kB) available for the kernel and only 0x00610000 bytes (6208 kB) for the root.cramfs on the OSD. The images can be found in #BSP-ROOT/images so be sure to check their size before burning the FLASH. Neuros group page

  • When you are ready set the U-boot variables so it will stop loading from TFTP and NFS but from FLASH again:
set bootcmd run cramfs_boot
run update-locs

If you really (_really_) know what you are doing, you can update your U-boot as well,

run update-uboot #WARNING: if you break U-boot badly enough, you'll kill the board
and only an emulator can help.


Common reasons for NFS not to work:

- /etc/exports not set up correctly:
  <directory> <ip-address> (rw,no_root_squash,sync)

- directory privileges:
  chmod 777 <directory>

- NFS server not running:
  chkconfig --list | grep nfs 
  chkconfig nfs --level 2345 on
  service nfs start (fc only)

- Firewall.  It is not sufficent to poke holes in the firewall for
  NFS because during the initial mount, the RPC port mapper
  can assign ports most anywhere.  You have to disable the 
  firewall OR disable the port mapper by using -o nolock in the
  mount command

- Kernel is not configured properly:

- Plus, for root mount:
  CONFIG_IP_PNP_RARP=y (probably)

- mount command:
  mount -t nfs -o nolock <ip-adress>:<directory> <mount point>

The resolve.conf problem can be resolv.conf problem can be resolved in a couple of ways:

- replace /etc/resolv.conf with a link to /var/etc/resolv.conf and mount a ramdisk 
  at /var

- Use NFS root mount -- why not just NFS mount the whole filesystem so that   
  everything is writable.  You should just need to change the linux command line to 
  something like:

   root=/dev/nfs nfsroot=<-host-ip-address>:<directory> rw

Last resort restore-to-factory settings:

With your OSD connected to ethernet and BSP built, run:

   run update-defenv

This will restore the factory-default uBoot environment from the file included in the BSP checkout. Use this procedure if your kernel command line (show at about line 17 during kernel boot) gets corrupted for some reason, or you accidentally overwrite something in your environment with an update-<foo> or saveenv command.


TFTP is far to simple to cause any real problems. But when you encounter some errors be sure the permissions are set correctly on the shared directories and that the path is correct. Sometimes the tftp path should be set to /images.

Serial woes

  • If you are having trouble with your serial connection, make sure your config is set correctly, HW and SW flow control must be off for example.
  • There are also problems reported with serial-PCI cards. They probably have hardware flowcontrol which causes problems seeing output from U-Boot. However, when U-boot finished loading normal output can be seen. Try an onboard serial port. Neuros group page

This wiki is user updated and the information here cannot be considered official Neuros communication

Personal tools