These instructions might not be 100% up to date.

This is the second alpha of the independent TAP development kit.
It is based on the December 17th 2001 version of TAP and main
software. It is compatible with future versions of the main
software, but enables to use only the TAP API and features
available in the December 17th version of the main software.
I will try to upgrade this kit to match the February 2002
version once released by Topfield.

TAP (Topfield's customizing API) is a proprietary method
to run user or 3rd party written applications on the Topfield
TF4000PVR Set Top Box/Personal Video Recorder. The applications
are stored on the TF4000PVR hard disk and loaded to RAM before
execution. Once the application is finished, the RAM space is
reclaimed. The TAP applications are downloaded to the TF4000PVR
STB over a serial line from a PC, using the TAP Downloader application
supplied by Topfield with the original TAP sample applications.

Although Topfield has developed the TAP and released some sample
applications, they have not released any technical information
and software development tools. This is where this little kit comes
in - it enables you to develop TAP applications under Windows or Linux
with no Topfield supplied tools or documentation.

This TAP kit has been made available through SourceForge including all
sources and known documentation. This is a change of policy from
the previous version, which was been made available only by e-mail
upon request for security reasons.

Please remember: this is not a project supported by Topfield and they
have NOT provided any technical information. The whole development
was independent and based on reverse-engineering the Topfield
supplied TAP applications and the main software. For this reason,
the kit is not perfect and lacks completeness. It also means that
if you destroy your Topfield box, the Topfield authorised service
centre will probably not help you to fix it. So, use at your own
risk, you need to known what you are doing.

To develop TAP applications, you need to read and uderstand the basic
TAP architecture (see Topfield document called "Topfield's customizing
API (TAP)", which was available together with the TAP downloader. You need
the TAP downloaded, a cross-development environment for the PowerPC processor,
and this kit. The kit is designed to work with GNU C compiler and linker.

You need a working GNU cross-compilation environment for PowerPC.
I am using binutils-2.11.2 and gcc-3.0.3 (both are now obsolete, get
the recent ones). The GNU compilers
are available for many operating systems, I will concentrate on Windows
and Linux, if you use something else, you surely will know your way through.

You can either use the Cygwin version of the tools (available separately
in a tar.gz file). To install these, you need to install Cygwin first
(start at http://sources.redhat.com/cygwin) and then to add the
PowerPC cross-compilation tools from the tar. You can get the Cygwin
precompiled executables at http://www.webpark.cz/topfield/powerpc-tools.tar.gz

Get also the newlib library from http://www.webpark.cz/topfield/tf-newlib.tar.gz

To install these, run bash (the Cygwin icon), copy the
tar into your home directory, change directory to / (this is the Cygwin root,
not the root of any Windows hard drive) and untar the archive with the 
following commands:
	cd /
	tar xvfz ~/powerpc-tools.tar.gz

This installs the PowerPC tools into your /usr/local.
NB: the tools have around 8 MB!

If you use a Linux or other UNIX-compatible system, you can compile
the cross-tools under any fairly modern system from sources. Get
binutils from http://sources.redhat.com/binutils and GCC from 
http://sources.redhat.com/gcc 
(you need only the core subset, not the whole thing). To compile
and install these, follow the instructions in the documentation, but
use
	./configure --target=powerpc-unknown-elf --with-newlib
for both binutils and gcc. You have to compile and install the PowerPC binutils
before going to compile and install GCC.

The TAP is based on fully relocatable programs and a proprietary
execution file format (the .bin files). Creating TAP executables is not
the main problem, the main problem is the actual API so that you can
interface to the rest of the TF4000PVR system. The API calls are made
through an entry table at the start of the executable binary, which is
filled in by the applicatoin launcher in the TF4000PVR software. You need the
software from 17-Dec-2001 or later, the earlier versions do not support TAP at
all.

The philosophy of the TAP application is as follows:
The application has to declare 2 entry points, I have called them
	int TAP_initialize(void)
and
	int TAP_main(void)

The TAP_initialize() function is called before the TAP_main(), the return value
is actually ignored. In Topfield TAP examples, the TAP_initialize() function
initializes copies of the pointers to API functions, and comes from a
separate file than the rest of the demo; I suspect they have it in a library.
In my simplified calling mechanism, the API is called directly through the
__entrytable and the TAP_initialize() function should be empty.

The TAP_main() function launches the actual application - so it is a
counterpart to the C main() function. There are no arguments, but the return
value is extremely important - if you return 0, the application has
finished and the memory used by it is returned to the system. You
can start another application.

If you return non-0 from the TAP_main(), the application keeps running as TSR
(Terminate and Start Resident, an old term borrowed from MS-DOS times),
and is not terminated until you specifically terminate it by one of the API
calls. There is a mechanism that the application is periodically called
in system idle loop (you have to register a callback for this purpose).

To process console input and remote control commands (includes front panel),
you have to register other callbacks.

The Makefile contains the required CFLAGS for TAP applications, specifically
the -mrelocatable ensures that the application is fully relocatable. You
also have to use -ffixed-r2 and -ffixed-r13, as the main TF4000PVR software
uses the EABI conventions and these 2 registers contain pointers to
Small Data Areas. The -mcpu=403 selects which instructions are supported
by the target processor (the processor core in the TF4000PVR is actually a
401B3, but it seems to be OK).
The -msoft-float selects that there are no floating-point instructions on the
target processor and that any floating point has to be done in software (not
tested). Please avoid floating point operations if you can.

For more information, read the PowerPC ABI and the PowerPC
EABI supplement, both available on the Web from IBM. You should definitely
read the target-related part of the GCC documentaion.

The Makefile needs so more work for more complicated programs with libraries,
several source files etc. What matters are the CFLAGS and LDFLAGS definitiions
and the selection of the cross-compilation tools rathern than the native
compiler, assembler and linker.

The linker script tap.ld contains commands to create the final
.bin file from the individual .o or library files. I am not sure I have listed
all potential sections a more complex program might contain, if
you find a section not listed, you should put it into the data part
of the script. If that happens, the data are put at the end of the
executable (after the GOT), which may or may not cause problems during
execution.

The "Hello world" demo application is provided in source, object and .bin
executable format. It simply outputs "Hello, TAP world!\r\n" to the console
(the EIA-232 port on the back of the TF box, 115200 8N1 no flowcontrol).
You can remake the app by executing
	touch hello.c
and running make. Then download the hello.bin using the original Topfield TAP
downloader to your box. To run it, connect a terminal emulator to the console
port, try pressing RETURN (should say Invalid command or something like that),
to make sure it works. You can run the hello.tap application either from the
console by typing:
	exec hello.tap<RETURN>
(it should print Hello, TAP world!)
or from the remote control by pressing "0" (the digit zero), selecting
hello.tap from the list and pressing OK (again, it should print "Hello, TAP
world!" on the CONSOLE (not on the TV screen)).

If you have any problems, questions, improvements, or working applications,
please let me know at topfield@centrum.cz

Praha, 23rd February 2002
topfield@centrum.cz

