====================================================================== DUNE HD STB -- BASIC DEVELOPMENT INFORMATION ====================================================================== Platforms ========= Sigma Designs 8642 platform: STB models: Base 3.0, Prime 3.0, Smart D1/H1/B1, Max, Duo CPU: MIPS 74Kf 667 MHz (little endian) Linux kernel: 2.6.22.19 Sigma Designs 8652 platform: STB models: Lite 53D CPU: MIPS 24Kf 500 MHz (little endian) Linux kernel: 2.6.22.19 Sigma Designs 8670 platform: STB models: TV-101, TV-102p, TV-201*, TV-301. CPU: MIPS 24Kf 700 MHz (little endian) Linux kernel: 2.6.29 Sigma Designs 8674 platform: STB models: TV-102, TV-202*, Connect CPU: MIPS 24Kf 700 MHz (little endian) Linux kernel: 2.6.32 Sigma Designs 8672 platform: STB models: TV-303D, Base 3D, Connect 3D* CPU: MIPS 74Kf 800 MHz (little endian) Linux kernel: 2.6.32 NOTE: the models marked with "*" are not officially launched. Toolchain ========= GCC-toolchain (Sigma Designs 864x/865x/867x): http://www.codesourcery.com/sgpp/lite/mips/portal/package4432/public/mips-linux-gnu/mips-4.3-154-mips-linux-gnu-i686-pc-linux-gnu.tar.bz2 Usage instructions: Use "-EL" compile flag. E.g.: /path/to/mips-4.3/bin/mips-linux-gnu-gcc -EL -o a a.c Telnet access to STB ==================== http://files.dune-hd.com/partners/sdk/dune_service_telnetd.dsf Put this file onto a USB flash drive and "launch" it on the STB (go to "Sources" menu, navigate into the USB flash drive, choose the file, and press "ENTER" RC button). This will enable Telnet service on the STB (kept till reboot). login: root password: IP-address of the STB: see Setup / Information. To automatically enable Telnet service on each STB boot: touch /config/telnetd sync To remove automatic enabling of Telnet service: rm -f /config/telnetd sync SSH access to STB ================= All SDK firmware versions include also a built-in SSH server, which is active by default, and support key-based authentication. For more information, please see here: http://files.dune-hd.com/partners/sdk/sdk.txt => "JS STB SDK" section => Download any js_stb_sdk-*.zip package => See js_stb_sdk-*/doc/README.txt => "SSH access to device" section Custom firmware builds can include built-in SSH server too. Standard public (retail) firmware versions do not include built-in SSH server. Filesystem and partitions overview ================================== / /bin/ /cdrom/ /dev/ /drivers/ /etc/ /fconfig/ /home/ /init* /lib/ /linuxrc -> bin/busybox* /opt/ /proc/ /root/ /sbin/ /sys/ /tmp/ /usr/ /var/ RAM disk. Initialized on Linux kernel boot (the initial image of the RAM disk is a part of the Linux kernel). Changes are lost on STB reboot. /tango -> /tango3/ /tango3/ /firmware -> /tango3/firmware/ /firmware_ext -> /tango3/firmware_ext/ Main read-only partition (CRAMFS file system) storing the main parts of the firmware. /app (Only for models based on SMP8674 and SMP8672.) Special "container" flash memory partition which stores "tango.cramfs" file containing the CRAMFS image of the "tango" filesystem. This CRAMFS image is loop-mounted to /tango. The /app partition is by default mounted as read-only. /mnt/ /config -> /mnt/config/ Small read-write partition of the NAND flash memory. Is used mostly to keep STB settings. Is always available. /flashdata/ "Flash Memory Storage" mount point, automatically mounted by Dune. A bigger read-write partition of the NAND flash memory. May not be available depending on the STB model and STB settings/state. More info: http://dune-hd.com/firmware/usb_flash_drive/ /persistfs/ "System Storage" mount point, automatically mounted by Dune. May be absent. More info: http://dune-hd.com/firmware/usb_flash_drive/ /tmp/mnt/storage/* Local storages (USB flash drives etc), automatically mounted by Dune. When a new local storage is connected to Dune, it is automatically mounted by Dune (note, it may be required to navigate in the GUI into "Sources" menu in order to force Dune to detect and automatically mount the storage). /D/ "Main Storage" mount point, automatically created by Dune. May be absent. Just an alias to one of mount points in /tmp/mnt/storage. /tmp/mnt/network/*, /tmp/mnt/smb/* Network shares (NFS and SMB), automatically mounted by Dune. Dune mounts network shares when the user navigates into the share. Storing your files on STB ========================= If you need to keep your own files in the flash memory of Dune, put them into /mnt (/config) partition. This partition typically has about 2MB of available space. If more space is needed, consider using /flashdata (if available) or /persistfs (if available). You can also use any user-visible local storage device (/tmp/mnt/* or /D). Also you can mount a network share and use it. NOTE (IMPORTANT!): Do not forget to do "sync" after each write into flash memory partition or local storage device. Manually mounting NFS share =========================== mkdir /mntpoint mount -o nolock ip-address:/path/to/dir /mntpoint NOTE: You can also mount NFS/SMB shares via STB menu (go to "Sources", press "POP UP MENU" RC button, choose "Add network folder"). Access from network to STB storage devices ========================================== All storage devices (USB HDD, USB flash drive, etc) attached to the STB are automatically exported by the STB to network via SMB and FTP protocols, and can be accessed from network via: FTP: ftp://stb-ip-address SMB: \\stb-ip-address Boot process ============ See here: http://files.dune-hd.com/partners/sdk/dune_boot_process.txt Running some code automatically on STB boot =========================================== Create the folder /config/boot/ and put executable files (e.g. shell scripts) into it. All executable files in this folder will be automatically launched by Dune on boot. (More exactly, "root" process will launch these executables on boot, before starting "shell".) Be careful: if these executables hang up or do other bad things, STB may become unusable (and emergency settings reset may be needed). Terminating Dune GUI ==================== 1. Put the STB into "software standby" mode by pressing "POWER" RC button. 2. Terminate Dune GUI processes: killall root shell NOTE: Killing just "shell" process is not enough, as "root" process will automatically restart it. Log files ========= Most log files are written into /tmp/run/. Linux kernel log messages are written into /var/log/messages (and are also accessible via "dmesg"). Built-in HTTP server ==================== The "httpd" process (simple HTTP-server based on busybox) listens on TCP port 80 and serves incoming HTTP requests on this port. Relevant locations in the filesystem: /tmp/www WWW root folder. Static files /tmp/www/path/to/file are accessible as: http://stb-ip-address/path/to/file /tmp/www/cgi-bin Folder where CGI executables can reside. Executable CGI files /tmp/www/cgi-bin/path/to/cgi-exe are accessible as: http://stb-ip-address/cgi-bin/path/to/cgi-exe By default, the HTTP server listens on all network interfaces of the STB and is accessible not only via the loopback interface (using 127.0.0.1 IP address) but also via real network interface (using real IP address (e.g. Ethernet) of the STB). If if it desired to limit the HTTP server to listen on the loopback interface only, it can be configured using a custom HTTP server configuration file (see below). During STB boot, the HTTP server is launched by "root" process (note, this may take place before the STB has IP address from DHCP server), using the following command: /usr/sbin/httpd -h /tmp/www It is possible to customize the behavior of the HTTP server by creating "/etc/httpd.conf" configuration file. The file should be created before the HTTP server is launched (or HTTP server should be restarted after creating/changing the configuration file). An appropriate place where this can be done is a boot script in "/config/boot/" directory (see "Running some code automatically on STB boot" section) or "/firmware/config/start.sh" in the custom firmware, see "Custom boot script" section here: http://files.dune-hd.com/partners/sdk/dune_custom_firmware.txt See here for additional information about HTTP server and "httpd.conf" file format: http://files.dune-hd.com/partners/sdk/httpd.txt Modifying files in root filesystem ================================== The root filesystem (/) is a RAM-disk, whose content is initialized on Linux kernel boot (the initial RAM-disk content is part of Linux kernel image). In runtime, it is possible to apply any modifications to the root filesystem. These modifications will be stored in RAM and will be lost on STB reboot. If you want to preserve the modifications on STB reboots, you can put the code which applies these modifications into autostart-on-boot scripts (see "Running some code automatically on STB boot". Modifying files in read-only /tango filesystem ============================================== The /tango filesystem (aka /tango3, also contains /firmware and /firmware_ext folders) is read-only CRAMS filesystem. So it is impossible to directly modify its content. In runtime, it is possible to apply temporary modifications to this filesystem using "bind mount". Examples: 1) Replacing a single file: mount --bind /tmp/shell /firmware/bin/shell 2) Replacing the entire folder (with all subfolders and files): mount --bind /tmp/skin /firmware/skin 3) Adding modifications to certain folder: cp -a /firmware/config /tmp/firmware_config echo "..." >/tmp/firmware_config/some_file mount --bind /tmp/firmware_config /firmware/config These temporary modifications will be lost on STB reboot. If you want to preserve the modifications on STB reboots, you can put the code which applies these modifications into autostart-on-boot scripts (see "Running some code automatically on STB boot". NOTE: the presence of such "bind mounts" may prevent /tango from unmounting and thus lead to firmware upgrade function to fail with an error. If you are affected by this, either first remove all bind-mounts before performing firmware upgrade, or use "emergency firmware recovery" procedure (which works before /tango is mounted and before autostart-on-boot scripts are launched). Alternatively, you can build you own version of /tango CRAMFS filesystem and write it directly into the flash memory of the STB. For more information on this, see "Extracting and overwriting tango filesystem image" section. Extracting and overwriting tango filesystem image ================================================= To extract /tango CRAMFS filesystem image from the flash memory of the STB, perform the following commands on the STB: # For models based on SMP8670: dd if=/dev/nblock8 of=/path/to/tango.cramfs # For models based on SMP8674 and SMP8672: cp /app/tango.cramfs /path/to/tango.cramfs To modify the /tango CRAMFS filesystem image, perform the following commands on a Linux PC: mkdir /path/to/modified-tango-dir mount --loop /path/to/tango.cramfs /tmp-dir cp -a /tmp-dir/* /path/to/modified-tango-dir/ umount /tmp-dir # here, do modifications in modified-tango-dir mkfs.cramfs -b 4096 /path/to/modified-tango-dir /path/to/tango.cramfs To write the modified /tango CRAMFS filesystem image back to the flash memory of the STB, perform the following commands on the STB: fuser -mk -9 /tango umount /tango # For models based on SMP8670: dd if=/path/to/tango.cramfs of=/dev/nblock8 # For models based on SMP8674 and SMP8672: losetup -d /dev/loop0 mount -o remount,rw /app cp /path/to/tango.cramfs /app/tango.cramfs umount /app sync reboot Creating custom firmware images =============================== See here: http://files.dune-hd.com/partners/sdk/dune_custom_firmware.txt General requirements for custom code running on STB =================================================== - Avoid writing to flash memory too often. It is generally recommended to ensure that writing to flash memory is performed not often than ~100 times per day in average in typical end user's scenarious. So, when needed, accumulates changes in RAM (or in RAM-disk) and delay writing them to flash memory till a suitable moment. - When writing to flash memory, avoid unneeded writes: if there are good chances that the new data is the same as the old data, first compare the new data and the old data and skip overwriting the old data if they are equal. - When writing to flash memory, try to do 'sync' as soon as possible, to ensure that changes are flushed into the hardware and will not be lost on STB reboot or power-off. - Note that writing to flash memory (or 'sync' command which flushes possibly previously buffered changes in flash memory) may cause short (up to 1 sec) freezes of various STB activities. In particular, playback may freeze. So, when possible, try to delay writes to flash memory to a suitable moment. E.g., when writing to flash memory is needed during playback, it may be reasonable to delay it till playback stop or channel switch. - Avoid writing too much data into /config (/mnt) partition. This partition is not big and it may contain other files besides of your files. - When writing into /config (/mnt) or /flashdata partitions, be prepared that there may not be enough space in these partitions (in case when there are other files stored there besides of your files). When possible, try to handle failed writes in as robust way as possible. - When customizing /tango, avoid putting too much extra stuff into /firmware folder, and use firmware_ext when reasonable. When preparing for firmware upgrade, the system copies the content of /firmware folder (but not /firmware_ext folder) into /tmp (RAM-disk), and if there is too much stuff there, the available RAM may be exhausted. So, everything that is not needed during firmware ugrade, is better to put into /firmware_ext rather than /firmware. - When running background processes and doing extra mounts (especially bind-mounts), take into account possible influence on firmware upgrade. During firmware upgrade, the system needs to unmount /tango partition; if this fails for some reason (e.g. some bind-mount is blocking this), the firmware upgrade will fail. - When running background processes, take into account that their CPU and RAM consumption may have influence on other processes running on the STB (especially if your background processes run concurrently with web browser, or concurrently with native Dune UI). When possible, try to minimize CPU and RAM consumption of background processes. When reasonable, start background processes using "nice" (e.g. "nice -n 19 /path/to/your/exe"). When reasonable, shutdown your processes when they are not needed. Debugging tools =============== GDB and GBD server: http://files.dune-hd.com/partners/sdk/misc/gdb.867x http://files.dune-hd.com/partners/sdk/misc/gdbserver.867x http://files.dune-hd.com/partners/sdk/misc/gdbserver.864x strace: http://files.dune-hd.com/partners/sdk/misc/strace.86xx tcpdump: http://files.dune-hd.com/partners/sdk/misc/tcpdump.86xx.tar.gz DSF file for launching custom Linux code ======================================== The following DSF file allows to run an arbitrary executable/shell-script w/o the need to use telnet/SSH access to the STB, directly from the native Dune UI. http://files.dune-hd.com/partners/sdk/misc/dune_service_exec.dsf Put this file onto a USB flash drive and "launch" it on the STB (go to "Sources" menu, navigate into the USB flash drive, choose the file, and press "ENTER" RC button). It will check for "dune_exec" executable file in the same directory where the DSF file is located, and execute it.