Inside Broadway
A developers guide to the Broadway firmware.
Last edited 01/06/2012
Contact: xxx
Table of contents
Hardware platform..................................................................................................................................... 3
Firmware introduction............................................................................................................................... 4
Main services.............................................................................................................................................. 4
goahead................................................................................................................................... 4
pctv_watchdog........................................................................................................................ 6
udhcpc..................................................................................................................................... 6
pctv_staticip............................................................................................................................ 6
Other services.......................................................................................................................... 6
Flash memory access.................................................................................................................................. 7
Developer mode......................................................................................................................................... 8
Places of interest........................................................................................................................................ 8
Booting from NFS..................................................................................................................................... 9
The NFS root source directory................................................................................................ 9
Setting the bootargs option................................................................................................... 10
Setting bootargs for NFS-root.............................................................................................. 10
Hardware platform
Broadway is a so-called SoC (system on chip) platform with some extensions.
The main hardware components are:
- 384 MHz MIPS CPU (Ralink RT3052)
- 8 MB NVRAM (Flash)
- 192 KB bootloader (U-Boot)
- 64 KB Ralink config (e.g. wifi connection, static IPs)
- 64 KB factory (e.g. wifi calibration, hardware id)
- 7744 KB firmware image (LZMA packed)
- 128 KB PCTV settings (e.g. channel lists)
- 64 MB RAM
- 7-port USB hub
- external ST11 (back left connector)
- external ST10 (back right connector)
- internal Xcode (ViXS XC4105 based transcoding board - aka Hollywood)
- internal Exeter (Conexant-based ATSC/NTSC hybrid tuner board)
- external ST9 (front connector)
- internal NovaTD (Dibcom-based dual DVB-T tuner stick)
- internal not connected
- 10/100 Mbit/s Ethernet
- WLAN 802.11 b/g/n
- A/V-input with Micronas AVF4910B decoder
Firmware introduction
The Broadway firmware is based on a standard Linux kernel (version 2.6.21),
heavily modified by Ralink to run on their platform.
On top of the kernel there are some major components.
- Video 4 Linux (V4L) is a hardware abstraction layer for digital and analog tuners
- BusyBox is a multi-call binary including the most commonly used Unix command line tools
- uClibc++ is a standard C++ library optimized for use on embedded systems
Main services
The following is a list of the main services that run on Broadway during operation.
goahead
This is the web server service. Currently we use version 2.5.
- listens for HTTP requests at port 80
- handles session-based login authentication for guest / admin
There are 2 plugins, which get loaded by Goahead.
web_config.so
- handles Broadway-related REST requests
- monitors internet connectivity of the Broadway device
web_stream.so
- configures DVB tuners using V4L (Video 4 Linux) DVB API
- transcodes transport streams using ViXS Xcode4 driver
- parses transport streams for SI data in order to setup PID filter
- delivers transport streams to the network using HTTP
The code is divided into several functional classes.
- Listener – handles HDHomeRun and HTTP requests
- Tuner – configures DVB tuners and reads data from them
- TSParser – parses transport stream packets for SI data
- Transcoder – communicates with XCode driver (both for DVB transcode and AV-in capture)
- OutputSocket – sends data to the network using TCP protocol layer, has a ringbuffer to avoid data dropping when network is busy
- Scanner – handles channel scan feature using Tuner and scan tables derived from TVC
- PreviewController – builds a streaming graph for different modes (e.g. tuner or AV input, xcoded or native, FLV or TS output)
pctv_watchdog
This is a monitoring service, which ensures a healthy operation state of the system.
- observes goahead service on a regular time base
- restarts service if it does not respond or has crashed
- reboots the system if service can't be repaired
- runs pctv_ip tool on a regular time base to update information at distan.tv server
udhcpc
This is the DHCP client service, which is run for each network interface (lan / wifi).
- handles DHCP requests for getting / updating IP addresses
- receives signals from lan and wifi driver when connection state changes
and calls a given script (udhcpc.sh)
pctv_staticip
This is the replacement for udhcpc when using static IP addresses.
- receives signals from lan and wifi driver when connection state changes
and calls a given script (udhcpc.sh)
Other services
- syslogd – collects diagnostic log messages in a ringbuffer
- telnetd – Telnet daemon
- nmbd – NetBios daemon for accessing Broadway by hostname
- smbd – Samba daemon for accessing the filesystem from Windows-based systems
(runs only in developer mode)
Flash memory access
Flash memory access is spread over a wide range of code.
(
src is short for libsrc/Linux/broadway/rt3052/source)
src/linux-2.6.21.x/drivers/mtd/maps/ralink_flash.c
Kernel driver for reading/writing the flash.
The flash areas can be accessed using different character devices (/dev/mtdx).
# cat /proc/mtd
dev: size erasesize name
mtd0: 00030000 00010000 "Bootloader"
mtd1: 00010000 00010000 "Config"
mtd2: 00010000 00010000 "Factory"
mtd3: 00790000 00010000 "Kernel"
mtd4: 00020000 00010000 "PCTV"
src/lib/nvram
Library for reading/writing the flash (optionally cached).
Uses direct access to the MTD driver.
src/user/rt2880_app/nvram/nvram_daemon
Service for redirecting GPIO signals to goahead webserver (obsolete).
Uses libnvram.
src/user/rt2880_app/nvram/ralink_init (aka nvram_get/nvram_set)
Binary for reading/writing key-value-pairs from/to the Config/Bootloader flash area.
Uses libnvram.
src/user/pctv/pctv_nvram
Binary for reading/writing a single file from/to the PCTV flash area.
Uses direct access to the MTD driver.
Developer mode
To enable developer mode, telnet to Broadway and execute “
nvram_set developer 1”.
This setting will stay active until the next factory reset.
To disable developer mode, telnet to Broadway and execute “
nvram_set developer 0”.
The following features are available:
- Samba share for root directory
- Internet access to admin web pages
- External USB ports enabled
Places of interest
This is a list of modules / directories inside the SVN source tree, which are of special interest for Broadway and which were mostly modified by PCTV Systems.
(
src is short for libsrc/Linux/broadway/rt3052/source)
XCode driver – libsrc/Linux/broadway/xcode4
Goahead webserver –
src/user/goahead
I2C driver –
src/linux-2.6.21.x/drivers/char/pctv_i2c2_drv.c
Zilog IR driver -
src/linux-2.6.21.x/drivers/char/pctv_zilogir.c
Exeter driver –
src/linux-2.6.21.x/drivers/media/video/cx231xx
(symlinks to
src/v4l-dvb/linux/drivers/media/video/cx231xx)
Wifi driver –
src/linux-2.6.21.x/drivers/net/wireless/rt2860v2
USB driver –
src/linux-2.6.21.x/drivers/usb
NVRAM driver –
src/linux-2.6.21.x/drivers/mtd/maps/ralink_flash.c
Booting from NFS
Starting with SVN revision 2623 the kernel and busybox
mount contains support for NFS and CIFS as well as NFS-Root. In addition to this the kernel is able to read the
LINUX_CMDLINE environment setting provided by uboot, which reads that string out of uboot's nvram variable
bootargs, if you toggle the
CONFIG_UBOOT_CMDLINE option.
# cd
sandbox/libsrc/Linux/broadway/rt3052/source/vendors/Ralink/RT3052/config
# cp 4M_32M_config.linux-2.6.21.x.NFSROOT-FILESYSTEM 4M_32M_config.linux-2.6.21.x
# cd
sandbox/libsrc/Linux/broadway/rt3052/source
# make distclean
# ./configure
# make
NOTE: A kernel built with this setting turned on will hang at boot if there is no
LINUX_CMDLINE provided by uboot (this means: if there is no correct
bootargs value set in uboot's nvram)!
To recover from this situation you can either flash a firmware with this option turned off via tftp or set the
bootargs option via uboot menu.
NOTE: For booting via NFS it is not necessary to flash a kernel built with
CONFIG_UBOOT_CMDLINE.
It is sufficient to load the kernel via tftp.
The NFS-root source directory
To boot from a NFS directory you need to export a directory containing the contents of the
libsrc/Linux/broadway/rt3052/source/romfs directory after a successful firmware build. As the build system deletes this directory during the build process, you should NOT export this directory directly.
A good place for your broadway NFS-root is under
/tftboot.
# mkdir -p /tftpboot/broadwaynfsroot
Now you must register this directory for export via NFS. This is usually done by adding a line to the file
/etc/exports.
# echo "/tftpboot/broadwaynfsroot *(rw,async,nohide,no_subtree_check,no_root_squash,crossmnt,insecure,insecure_locks,no_acl,anonuid=0,anongid=0,fsid=0)" >> /etc/exports
NOTE: Make sure the number after fsid is unique!
Next you have to (re)start your NFS server.
# /etc/init.d/nfs-kernel-server restart
To copy the contents of the
romfs directory it is a good practice to use
rsync as it doesn't delete files in the target you have created by hand.
# rsync -avHAXS
sandbox/libsrc/Linux/broadway/rt3052/source/romfs/ /tftpboot/broadwaynfsroot/
NOTE: Do ALWAYS have the slash at the end of the paths! (rsync would create a subdirectory named
romfs inside
broadwaynfsroot if there is no trailing slash at the source-path).
Setting the bootargs option
There are two ways to set uboot nvram values.
Inside the Broadway terminal:
# nvram_set uboot bootargs "<value>"
In the uboot shell by pressing 4 at the uboot boot menu and entering the following commands:
# setenv bootargs <value>
# saveenv
# reset
The default bootargs value to boot from a SquashFS partition is:
console=ttyS1,57600n8 root=/dev/mtdblock4 ro rootfstype=squashfs
The default bootargs value to boot from a RAMFS partition is:
console=ttyS1,57600n8 root=/dev/ram0
Setting bootargs for NFS-root
Assuming
- the IP of your default gateway is 192.168.1.1
- the IP of your development machine is 192.168.1.2
- the IP Address of your Broadway is 192.168.1.3
- your netmask is 255.255.255.0
- you use network interface eth2 to connect to Broadway
- the name of your Broadway (during boot) is "dvbt"
the
bootargs nvram option for uboot should be set to the following value:
console=ttyS1,57600n8 rootdelay=2 root=/dev/nfs rw nfsroot=192.168.1.2:/tftpboot/broadwaynfsroot,v3,udp,nolock,rsize=16384,wsize=16384 ip=192.168.1.3:192.168.1.2:192.168.1.1:255.255.255.0:dvbt:eth2:any
For details see:
Sie müssen registriert sein, um Links zu sehen.
Now it is time to boot Broadway with the NFS-aware firmware.
Fingers crossed...
DD
)
rogram=16405
