UTOPPYA(1) BSD General Commands Manual UTOPPYA(1)NAME
utoppya -- Topfield TF5000PVR file manipulation program
SYNOPSIS
utoppya [-f device] command ...
DESCRIPTION
utoppya is the userland interface to the utoppy(4) device driver.
The options are as follows:
-f Communicate with device instead of the default /dev/utoppy0.
Using the services of the utoppy(4) driver, utoppya can perform the following operations, specified by the command operand:
df Display disk size and free space
ls [directory]
List the files in the specified directory. Default is the Toppy's root directory.
mkdir <directory>
Make the specified directory. You must supply the full pathname to directory.
rm <pathname>
Delete the file or directory specified by pathname.
rename <source> <target>
Rename the file or directory specified by the source operand to the destination file or directory specified by the target operand.
get [-prt] <toppyfile> [localfile]
Copy toppyfile from the Toppy to localfile on the local filesystem. If localfile is omitted, the file will be copied into the cur-
rent directory and will be named using the last component of the toppyfile operand. If localfile is '-', then toppyfile will be
copied to the standard output.
The following options are available for the get command:
-p Display a progress bar.
-r This option is useful if you wish to resume a previously interrupted get command. Instead of restarting from the beginning
of the file, the transfer will resume where it left off.
-t Enable 'Turbo' mode. This instructs the Toppy to drop everything and concentrate on transferring the file as quickly as pos-
sible. You will be able to watch live TV, but all other functions, including changing channel via the remote control, will
be inoperative.
put [-prt] <localfile> <toppyfile>
Copy localfile on the local filesystem to toppyfile on the Toppy. If toppyfile specifies a directory on the Toppy, the last compo-
nent of the localfile operand will be appended to the toppyfile operand.
The options described for the get command (above) also apply to the put command.
FILES
/dev/utoppy0 The default Topfield TF5000PVR instance.
SEE ALSO usb(4), utoppy(4)HISTORY
The utoppya command first appeared in NetBSD 4.0 and was inspired by 'ftpd-topfield' written by Steve Bennett <msteveb at ozemail.com.au> and
'puppy' written by Peter Urbanec <toppy at urbanec.net>.
AUTHORS
Steve C. Woodford <scw@netbsd.org>
BSD April 3, 2006 BSD
Check Out this Related Man Page
UTOPPY(4) BSD Kernel Interfaces Manual UTOPPY(4)NAME
utoppy -- USB driver for the Topfield TF5000PVR range of digital video recorders
SYNOPSIS
utoppy* at uhub? port ?
#include <dev/usb/utoppy.h>
DESCRIPTION
The utoppy driver provides support for the Topfield TF5000PVR range of DVB recorders (nicknamed 'Toppy') which are popular in Europe and Aus-
tralia. 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 Topfield.
Existing replacements for Altair suffer from the fact that they are ultimately built on top of ugen(4). This has a number of detrimental
side-effects:
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 down-
load 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.
UTOPPY INTERFACE
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.
UTOPPYIOCANCEL void
This command can be used to abort an in-progress UTOPPYIOREADDIR, UTOPPYIOREADFILE, or UTOPPYIOWRITEFILE command.
UTOPPYIOREBOOT void
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 structure:
struct utoppy_dirent {
char ud_path[UTOPPY_MAX_FILENAME_LEN + 1];
enum {
UTOPPY_DIRENT_UNKNOWN,
UTOPPY_DIRENT_DIRECTORY,
UTOPPY_DIRENT_FILE
} 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 structure:
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 written.
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.
FILES
/dev/utoppy0 device node
SEE ALSO utoppya(1), usb(4)HISTORY
The utoppy driver appeared in NetBSD 4.0.
AUTHORS
Steve C. Woodford <scw@netbsd.org>
BSD April 3, 2006 BSD