Updated: 2021/Apr/14

UTOPPY(4)                    Device Drivers Manual                   UTOPPY(4)

     utoppy - USB driver for the Topfield TF5000PVR range of digital video

     utoppy* at uhub? port ?

     #include <dev/usb/utoppy.h>

     The utoppy driver provides support for the Topfield TF5000PVR range of
     DVB recorders (nicknamed `Toppy') which are popular in Europe and
     Australia.  These recorders have a USB device interface which can be used
     to transfer recordings to and from the unit's hard disk.  The USB
     interface can also be used to upload binary images for execution on the
     Toppy's MIPS cpu.

     The Toppy's USB protocol has not been officially documented by Topfield,
     but the basic features have been reverse engineered by others in order to
     write replacements for the official `Altair' download/upload program from

     Existing replacements for Altair suffer from the fact that they are
     ultimately built on top of ugen(4).  This has a number of detrimental

     1.   Performance suffers since all Toppy command packets have to cross
          the user-kernel interface.

     2.   The userland programs are full of clutter to deal with interpreting
          the command/status packets, not to mention byte-swapping and host
          endian issues.

     3.   Signals can interrupt a data transfer at a critical point, leaving
          the Toppy in an undefined state.  For example, interrupting a
          download with `Turbo' mode enabled will leave the Toppy completely
          unresponsive to the remote control, and prevent timer-based
          recordings from starting.

     The utoppy driver provides a clean and stable interface to the Toppy
     protocol, and ensures that an interrupt caused by a signal does not leave
     the Toppy in an undefined state.

     Use the following header file to get access to the utoppy specific
     structures and defines.

     #include <dev/usb/utoppy.h>

     The utoppy driver can be accessed through the /dev/utoppyN character
     device.  The primary means of controlling the driver is by issuing a
     series of ioctl(2) system calls followed by read(2) or write(2) system
     calls as appropriate.

     The following ioctl(2) commands are supported by the utoppy driver:

     UTOPPYIOTURBO int *mode
             This command can be used to enable or disable `Turbo' mode for
             subsequent UTOPPYIOREADFILE or UTOPPYIOWRITEFILE commands (see
             below).  If num is non-zero, Turbo mode will be enabled.
             Otherwise Turbo mode will be disabled.  In non-Turbo mode, the
             Toppy's USB interface is capable of sustaining around 5.6 Mbit/s
             during a file transfer.  With Turbo mode enabled, it can sustain
             just over 16 Mbit/s.  Of course, these figures are valid only if
             the Toppy is connected via a USB 2.0 interface.  Performance
             using an older USB 1 interface will be significantly lower.

             This command can be used to abort an in-progress UTOPPYIOREADDIR,

             This command will cause the Toppy to reboot cleanly.

     UTOPPYIOSTATS struct utoppy_stats *stats
             This command retrieves statistics for the Toppy's hard disk.

             struct utoppy_stats {
                     uint64_t us_hdd_size;   /* Size of the disk, in bytes */
                     uint64_t us_hdd_free;   /* Free space, in bytes */

     UTOPPYIORENAME struct utoppy_rename *rename
             This command is used to rename a file or directory on the Toppy's
             hard disk.  The full pathname to each file must be provided.

             struct utoppy_rename {
                     char *ur_old_path;      /* Path to existing file */
                     char *ur_new_path;      /* Path to new file */

     UTOPPYIOMKDIR char *path
             This command creates the directory specified by path.

     UTOPPYIODELETE char *path
             This command deletes the file or directory specified by path.

     UTOPPYIOREADDIR char *path
             This command initiates a read of the contents of the directory
             specified by path.  After issuing this command, the directory
             contents must be read using consecutive read(2) system calls.
             Each read(2) will transfer one or more directory entries into the
             user-supplied buffer.  The buffer must be large enough to receive
             at least one directory entry.  When read(2) returns zero, all
             directory entries have been read.

             A directory entry is described using the following data

             struct utoppy_dirent {
                     char ud_path[UTOPPY_MAX_FILENAME_LEN + 1];
                     enum {
                     } ud_type;
                     off_t ud_size;
                     time_t ud_mtime;
                     uint32_t ud_attributes;

             The ud_path field contains the name of the directory entry.

             The ud_type field specifies whether the entry corresponds to a
             file or a sub-directory.

             The ud_size field is valid for files only, and specifies the
             file's size in bytes.

             The ud_mtime field describes the file or directory's modification
             time, specified as seconds from the Unix epoch.  The timestamp is
             relative to the current timezone, so localtime(3) can be used to
             convert it into human readable form.  Note that the Toppy sets
             directory timestamps to a predefined value so they are not
             particularly useful.

             The ud_attributes field is not used at this time.

     UTOPPYIOREADFILE struct utoppy_readfile *
             This command is used to initiate reading a file from the Toppy's
             hard disk.  The full pathname, together with the file offset at
             which to start reading, is specified using the following data

             struct utoppy_readfile {
                     char *ur_path;
                     off_t ur_offset;

             After issuing this command, the file must be read using
             consecutive read(2) system calls.  When read(2) returns zero, the
             entire file has been read.

     UTOPPYIOWRITEFILE struct utoppy_writefile *
             This command is used to initiate writing to a file on the Toppy's
             hard disk.  The file to be written is described using the
             following data structure:

             struct utoppy_writefile {
                     char *uw_path;
                     off_t uw_offset;
                     off_t uw_size;
                     time_t uw_mtime;

             The uw_path field specifies the full pathname of the file to be

             The uw_offset field specifies the file offset at which to start
             writing, assuming the file already exists.  Otherwise, uw_offset
             must be zero.

             The protocol requires that the Toppy must be informed of a file's
             size in advance of the file being written.  This is accomplished
             using the uw_size field.  It may be possible to work around this
             limitation in a future version of the driver.

             The uw_mtime field specifies the file's timestamp expressed as
             seconds from the Unix epoch in the local timezone.

     Due to limitations with the protocol, a utoppy device can be opened by
     only one application at a time.  Also, only a single UTOPPYIOREADDIR,
     UTOPPYIOREADFILE, or UTOPPYIOWRITEFILE command can be in progress at any
     given time.

     /dev/utoppy0  device node

     utoppya(1), usb(4)

     The utoppy driver appeared in NetBSD 4.0.

     Steve C. Woodford <scw@netbsd.org>

NetBSD 9.99                      April 3, 2006                     NetBSD 9.99