TAP Programming

If you fancy yourself as developer you too can create TAPs to enhance your PVR. TAPs are like iPhone apps - they are installed onto your PVR and can provide extra functionality.

To create a TAP you will need a PC or Linux desktop, some free software that you can download, and some C or C++ knowledge. Ideally your PC will be networked to your PVR so you can quickly copy TAPs to your PVR for testing. Otherwise you will need to transfer the TAPs via USB. Additionally if your PVR is networked, you will be able to see any logging messages that your TAP may output while it is running. This is very useful while developing your TAP.

Linux

NB this is for a 32 bit system…
If you have a Linux development environment then using that will be much simpler. From the topfield site, download

test $# != 1 && echo -e "usage: `basename $0` {c_source_file}\a" >&2 && exit

SRC=$1   # .c source file
NAME=`basename $SRC   .c`_tms

API_BASE={adjust this}
TOOL_CHAIN={adjust this}
CROSS_COMPILE=$TOOL_CHAIN/bin/mipsel-linux-uclibc-

CC=${CROSS_COMPILE}gcc
CFLAGS="-Wall -W -O2 -mips32 -fPIC -D_TMS_"

LD=${CROSS_COMPILE}ld
LDFLAGS="-shared --no-undefined --allow-shlib-undefined"

TAP_INC=$API_BASE/include
TAP_LIBS="$API_BASE/tapinit.o $API_BASE/libtap.so -lc"

$CC $CFLAGS $TAP_FLAGS -I $TAP_INC -c -o $NAME.o $SRC && \
$LD $LDFLAGS -o $NAME.tap $NAME.o $TAP_LIBS && \
rm $NAME.o || \
echo -e "*** TAP BUILD FAILED ***\a" >&2

On a 64-bit version of Linux (e.g. Ubuntu), some 32-bit programs must be made executable first:

sudo dpkg --add-architecture i386
sudo apt-get update

sudo apt-get install ia32-libs  # older versions
# or
sudo apt-get install lib32z1 lib32ncurses5 lib32bz2-1.0  # newer versions

It should also be feasible to do this under OS/X but we don't know of anyone who has.

Otherwise you need a unix-type environment under Windows

Setup under MS-Windows

(Untested) Automatic installation

From the German forums info here is a tool to automatically download and install the required software. If this doesn't work for you, the manual installation method is documented below.

The original link in the forum post no longer works, so you can download this copy

The program is subject to breaking due to changes in the CygWin setup program, and is all in German. It has worked well for some people.

Requirements

Create a folder structure for your software

This is quite flexible but, for sanity, a few guidelines can be followed. If you are going to use CygWin for anything other than TAP development then keep CygWin and the TAPs separate. The automated program by default places everything under C:\TAP-Dev

  • Keep everything separate from standard Windows folder conventions (i.e. avoid C:/Program Files, My Documents, etc)
  • Folder names should not have any spaces - not compulsory, just avoids certain problems
  • The example here will use separate folder heirarchies, and will assume drive, C:, but any other HDD or partitions will do equally well, provided there is enough space. A minimal install will be less that 300MB, but if you accidentally select a full install it can exceed 30GB.
  • Create C:\CygInstall - this will be used to store all the downloaded installation files, and could be deleted or retained later.
  • Create C:\cygwin - The CygWin system will reside under here.
  • Create C:\TAPs - Your TAP source code and development will occur here.

Install Cygwin

  • Download setup-x86.exe from the Cygwin site and place in C:\CygInstall. Do not use the 64-bit setup, even if you have a 64-bit OS.
  • Run the setup-x86 program, telling it to install into C:\cygwin and the local package directory is C:\CygInstall
  • Choose a suitable mirror (the current up to date mirrors can be found listed in the Cygwin site.
  • When the Select Package screen is displayed you should leave nearly everything at "Default", but you need make. So…
  • expand the Devel tree and scroll down to make: The GNU version of the 'make' utility.. click once where it says "skip" and the latest version number should be listed. The bin? box should have a cross, and the src? box should be empty.
  • There are docs on the web that suggest a list of about 10 packages to be selected from the Devel category. As far as I can tell, these are only required if you wish to recompile the cross-compiler.
  • click next and it will start downloading and installing.
  • When it has finished you should add an icon to the desktop or start menu.

Install crosstool - the cross-compiler for the Topfield CPUs.

  • create a folder C:/cygwin/opt
  • copy the crosstool_cygwin download here.
  • the download comes as a .tar.gz file. Gui programs such as 7-zip can uncompress this format, otherwise you can do it using cygwin utilities.
Start a cygwin terminal, end execute the following commands
$ cd /opt
$ tar zxvf crosstool_cygwin.tar.gz

This should show you a list of files as they are being extracted.
  • Whichever way you have extracted the files, you should end up with a hierarchy looking like: C:\cygwin\opt\crosstool, which contains folders bin, include etc
  • You need to include the cross-compiler files in the execution path: Either add C:\cygwin\opt\crosstool\bin to the Windows environment, or change the cygwin version, as follows:
  • Create a text file named local.sh in the folder C:\cygwin\etc\profile.d and add the following.
PATH=${PATH}:/opt/crosstool/bin
  • this file needs to have unix-style line-endings, so you need to use a text editor that understands the difference and can convert between them (vim, notepad++ Edit->EOL conversion, or ?)

Test installation with examples.

  • create a folder: C:\TAPs\examples and extract the Topfield example code there - make sure you retain the folder structure.
  • Start a cygwin terminal session, and
$ cd  /cygdrive/c/TAPs/examples
$ make clean
$ make
  • The examples come with TAPs already built, so a make by itself does nothing. The initial make clean will remove intermediate object files and TAPs, allowing a rebuild to proceed.
  • Look for error messages indicating an incomplete installation and check that the bin subfolders contain fresh .tap binaries. Expect some warnings about unused variables, which can be ignored.
  • to build your own code, you will need: the contents of the include folder; libtap.so and tapinit.o from the example folder top level.

Install FireBirdLib

  • Create a folder C:\TAPs\FireBirdLib
  • Download the zip file and extract into that folder
  • Note, there are many assumptions about file structure made in the bat files and makefiles, some of which seem contradictory. The contradiction was resolved in the past by a permanent mount to remap /tapapi to somewhere else. This seems to relate to past coding structures and seems needlessly complicated now; putting everything directly into /tapapi seems to work. If you want to use the .BAT files then they will each need to be edited first, no matter what layout you choose.
  • Various files are assumed to reside under /tapapi/TMS of the CygWin system. These include, tapinit.o, the C header (.h) files as well as tools.mk which is included by the Makefiles and defines the cross-compilers etc to use.
  • from the topfield examples, copy the entire "include" folder to /tapapi/TMS (so that the .h files sit in /tapapi/TMS/include )
  • from the topfield examples, copy tapinit.o and libtap.so to /tapapi/TMS
  • from FireBirdLib, copy libFirebird.a into /opt/crosstool/lib
  • from FireBirdLib, copy libFirebird.h into /tapapi/TMS/include
  • from FireBirdLib/devutils, copy JailBreak.exe into /opt/crosstool/bin and then, so that the existing makefiles can find it, add a line into /tapapi/TMS/include/tool.mk that says
JB = JailBreak
  • from FireBirdLib/devutils, copy tap.h into /tapapi/TMS/include. This will overwrite the Topfield file of the same name. FireBird has added extra definitions, so this file should be backwards compatible with Topfield's version.

Test Firebird

  • Now that the installation is over, start a cygwin shell, cd to FireBirds _test folder and delete the last line of Makefile (because there is no make macro RMDIR defined in tool.mk)
  • then type "make" and, if it all goes well, you will see output like this …
$ make
[Compiling... LinkerTest.o]
[Linking... LinkerTest.tap]
JailBreak: ioctl, dlerror, utime, truncate, readlink, remove, mmap, dlclose, rename, write, lstat, read, dlopen, unlink, fread, dlsym, fopen, fclose, fwrite, open, mkdir, close
JailBreak: Successfully patched!
[Cleaning up...]
  • Now cd to FireBird's _Demo\ColorCheck folder and type "make"
  • If it all goes well, then you will see output like this …
$ make
[Compiling... ColorPickerTest.o]
[Linking... ColorPickerTest.tap]
mipsel-linux-uclibc-ld -shared --no-undefined --allow-shlib-undefined -o ColorPickerTest.tap ColorPickerTest.o /tapapi/TMS/tapinit.o /tapapi/TMS/libtap.so -lFireBird -ldl -lc
JailBreak ColorPickerTest.tap
JailBreak: dlerror, utime, dlclose, write, lstat, read, dlopen, fread, dlsym, fopen, fclose, fwrite, open, mkdir, close
JailBreak: Successfully patched!
[Cleaning up...]
  • check for errors, especially "cannot find file" types. These most likely indicate problems copying files above.
  • if you see any error like
[Linking... FlashDecode.tap]
mipsel-linux-uclibc-ld: cannot find -lmxml

then it means a library is missing. If it refers to -lfirebird then something went wrong with the above instructions. In this example case the mxml library is not there. I suspect it needs to be separately compiled. Do not be tempted to try to find one using CygWin setup, because any you find there will only be intel code.
  • Some other demo code also fails, like CrashCheck and EPG failed to compile because the code is not up to date with changes to Firebirdlib. HDD_TAP_Start fails because it is not designed for TMS architecture.
  • The remainder seem to compile, with nothing more than the occasional warning.

Using an editor/development environment

  • editing source code - any text editor would do, but there are plenty of editors capable of syntax-highlighting that are more helpful: you probably have your favourite already.
  • IDE - not normally used - if you have any success then mention it here.

Testing

Network your PVR to your PC

Use an FTP program to transfer TAPs

Using telnet to view output

Deploying

Versioning

Program Files or AutoStart

Integrating with TAPtoDate

Integrating with TMSCommander

Supporting TMSCommander in your TAP is a good idea if you have a menu to configure its options. TMSCommander can be used as a central TAP management tool that can call your TAP's menu up saving you the headache of trying to reserve a key to call it up.
Adding support for TMSCommander is very simple. All you need to do is to:

  • get a copy of TMSCommander.h from the TMSCommander kit
  • add a #include "TMSCommander.h" to your program source
  • add the following section to your TAP_EventHandler:
 if (event == EVT_TMSCommander)
      return TMSCommander_handler( param1 )
  • add the following function to your program source:
//--------------------------------------------------------------------------------
// TMSCommander_handler -
//--------------------------------------------------------------------------------
static dword TMSCommander_handler( dword param1 )
{
        switch (param1)
        {
           case TMSCMDR_Capabilities:
               return (dword)(TMSCMDR_HaveMenu | TMSCMDR_CanBeStopped);
           case TMSCMDR_Menu:
               //call your TAP's menu
               //eg. CallMyMenu();
               return TMSCMDR_OK;
           case TMSCMDR_Stop:
               //Exit your TAP
               //eg. TAP_Exit();
               return TMSCMDR_OK;
           case TMSCMDR_UserEvent:
               //call your TAP's userevent
               return TMSCMDR_OK;
           case TMSCMDR_Exiting:
               //TMSCommander is exiting - do you want to do anything?
               return TMSCMDR_OK;
           default:
               //unknown TMSCommander function
               return TMSCMDR_UnknownFunction;
        }
}

Reverse Engineering Firmware code

Sometimes it is useful to see what a firmware function is doing, so that you can either use it in your own code, or try and copy what it does. Also it is useful to dump the symbol table to what the obfuscated functions are called if you need to call them yourself. To do this you need to:

  • Get a copy of the firmware (the .tfd file)
  • Get a copy of VegaPack
  • Open the tfd with VegaPack and "Save - Firmware BIN" as "vmlinux.gz"
  • continue…
  • Start bash (cygwin) and apply the unpack script
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License