1.\" $NetBSD: utoppy.4,v 1.7 2017/07/03 21:30:58 wiz Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Steve C. Woodford. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 3, 2006 31.Dt UTOPPY 4 32.Os 33.Sh NAME 34.Nm utoppy 35.Nd USB driver for the Topfield TF5000PVR range of digital video recorders 36.Sh SYNOPSIS 37.Cd "utoppy* at uhub? port ?" 38.Pp 39.In dev/usb/utoppy.h 40.Sh DESCRIPTION 41The 42.Nm 43driver provides support for the Topfield TF5000PVR range of DVB recorders 44(nicknamed 45.Ql Toppy ) 46which are popular in Europe and Australia. 47These recorders have a 48.Tn USB 49device interface which can be used to transfer 50recordings to and from the unit's hard disk. 51The 52.Tn USB 53interface can also be used to upload binary images for execution 54on the Toppy's MIPS cpu. 55.Pp 56The Toppy's 57.Tn USB 58protocol has not been officially documented by Topfield, 59but the basic features have been reverse engineered by others in order 60to write replacements for the official 61.Ql Altair 62download/upload program from Topfield. 63.Pp 64Existing replacements for Altair suffer from the fact that they are 65ultimately built on top of 66.Xr ugen 4 . 67This has a number of detrimental side-effects: 68.Bl -enum 69.It 70Performance suffers since all Toppy command packets have to cross the 71user-kernel interface. 72.It 73The userland programs are full of clutter to deal with interpreting the 74command/status packets, not to mention byte-swapping and host endian 75issues. 76.It 77Signals can interrupt a data transfer at a critical point, leaving the 78Toppy in an undefined state. 79For example, interrupting a download with 80.Ql Turbo 81mode enabled will leave the Toppy completely unresponsive to the remote 82control, and prevent timer-based recordings from starting. 83.El 84.Pp 85The 86.Nm 87driver provides a clean and stable interface to the Toppy protocol, and 88ensures that an interrupt caused by a signal does not leave the Toppy in 89an undefined state. 90.Sh UTOPPY INTERFACE 91Use the following header file to get access to the 92.Tn utoppy 93specific structures and defines. 94.Bd -literal 95#include <dev/usb/utoppy.h> 96.Ed 97.Pp 98The 99.Nm 100driver can be accessed through the 101.Pa /dev/utoppyN 102character device. 103The primary means of controlling the driver is by issuing a series of 104.Xr ioctl 2 105system calls followed by 106.Xr read 2 107or 108.Xr write 2 109system calls as appropriate. 110.Pp 111The following 112.Xr ioctl 2 113commands are supported by the 114.Nm 115driver: 116.Bl -tag -width xxxxxx 117.It Dv UTOPPYIOTURBO Fa "int *mode" 118This command can be used to enable or disable 119.Ql Turbo 120mode for subsequent 121.Dv UTOPPYIOREADFILE 122or 123.Dv UTOPPYIOWRITEFILE 124commands (see below). 125If 126.Fa num 127is non-zero, Turbo mode will be enabled. 128Otherwise Turbo mode will be disabled. 129In non-Turbo mode, the Toppy's 130.Tn USB 131interface is capable of sustaining around 5.6 Mbit/s during a file transfer. 132With Turbo mode enabled, it can sustain just over 16 Mbit/s. 133Of course, these figures are valid only if the Toppy is connected via a 134.Tn USB 1352.0 interface. 136Performance using an older 137.Tn USB 1381 interface will be significantly lower. 139.It Dv UTOPPYIOCANCEL Fa void 140This command can be used to abort an in-progress 141.Dv UTOPPYIOREADDIR , 142.Dv UTOPPYIOREADFILE , 143or 144.Dv UTOPPYIOWRITEFILE 145command. 146.It Dv UTOPPYIOREBOOT Fa void 147This command will cause the Toppy to reboot cleanly. 148.It Dv UTOPPYIOSTATS Fa "struct utoppy_stats *stats" 149This command retrieves statistics for the Toppy's hard disk. 150.Bd -literal 151struct utoppy_stats { 152 uint64_t us_hdd_size; /* Size of the disk, in bytes */ 153 uint64_t us_hdd_free; /* Free space, in bytes */ 154}; 155.Ed 156.It UTOPPYIORENAME Fa "struct utoppy_rename *rename" 157This command is used to rename a file or directory on the Toppy's 158hard disk. 159The full pathname to each file must be provided. 160.Bd -literal 161struct utoppy_rename { 162 char *ur_old_path; /* Path to existing file */ 163 char *ur_new_path; /* Path to new file */ 164}; 165.Ed 166.It UTOPPYIOMKDIR Fa "char *path" 167This command creates the directory specified by 168.Fa path . 169.It UTOPPYIODELETE Fa "char *path" 170This command deletes the file or directory specified by 171.Fa path . 172.It UTOPPYIOREADDIR Fa "char *path" 173This command initiates a read of the contents of the directory specified by 174.Fa path . 175After issuing this command, the directory contents must be read using 176consecutive 177.Xr read 2 178system calls. 179Each 180.Xr read 2 181will transfer one or more directory entries into the user-supplied buffer. 182The buffer must be large enough to receive at least one directory entry. 183When 184.Xr read 2 185returns zero, all directory entries have been read. 186.Pp 187A directory entry is described using the following data structure: 188.Bd -literal 189struct utoppy_dirent { 190 char ud_path[UTOPPY_MAX_FILENAME_LEN + 1]; 191 enum { 192 UTOPPY_DIRENT_UNKNOWN, 193 UTOPPY_DIRENT_DIRECTORY, 194 UTOPPY_DIRENT_FILE 195 } ud_type; 196 off_t ud_size; 197 time_t ud_mtime; 198 uint32_t ud_attributes; 199}; 200.Ed 201.Pp 202The 203.Va ud_path 204field contains the name of the directory entry. 205.Pp 206The 207.Va ud_type 208field specifies whether the entry corresponds to a file or a sub-directory. 209.Pp 210The 211.Va ud_size 212field is valid for files only, and specifies the file's size in bytes. 213.Pp 214The 215.Va ud_mtime 216field describes the file or directory's modification time, specified as 217seconds from the Unix epoch. 218The timestamp is relative to the current timezone, so 219.Xr localtime 3 220can be used to convert it into human readable form. 221Note that the Toppy sets directory timestamps to a predefined value so 222they are not particularly useful. 223.Pp 224The 225.Va ud_attributes 226field is not used at this time. 227.It UTOPPYIOREADFILE Fa "struct utoppy_readfile *" 228This command is used to initiate reading a file from the Toppy's hard disk. 229The full pathname, together with the file offset at which to start reading, 230is specified using the following data structure: 231.Bd -literal 232struct utoppy_readfile { 233 char *ur_path; 234 off_t ur_offset; 235}; 236.Ed 237.Pp 238After issuing this command, the file must be read using consecutive 239.Xr read 2 240system calls. 241When 242.Xr read 2 243returns zero, the entire file has been read. 244.It UTOPPYIOWRITEFILE Fa "struct utoppy_writefile *" 245This command is used to initiate writing to a file on the Toppy's hard disk. 246The file to be written is described using the following data structure: 247.Bd -literal 248struct utoppy_writefile { 249 char *uw_path; 250 off_t uw_offset; 251 off_t uw_size; 252 time_t uw_mtime; 253}; 254.Ed 255.Pp 256The 257.Va uw_path 258field specifies the full pathname of the file to be written. 259.Pp 260The 261.Va uw_offset 262field specifies the file offset at which to start writing, assuming the file 263already exists. 264Otherwise, 265.Va uw_offset 266must be zero. 267.Pp 268The protocol requires that the Toppy must be informed of a file's size in 269advance of the file being written. 270This is accomplished using the 271.Va uw_size 272field. 273It may be possible to work around this limitation in a future version of 274the driver. 275.Pp 276The 277.Va uw_mtime 278field specifies the file's timestamp expressed as seconds from the Unix epoch 279in the local timezone. 280.El 281.Pp 282Due to limitations with the protocol, a 283.Nm 284device can be opened by only one application at a time. 285Also, only a single 286.Dv UTOPPYIOREADDIR , 287.Dv UTOPPYIOREADFILE , 288or 289.Dv UTOPPYIOWRITEFILE 290command can be in progress at any given time. 291.Sh FILES 292.Bl -tag -width /dev/utoppy0 -compact 293.It Pa /dev/utoppy0 294device node 295.El 296.Sh SEE ALSO 297.Xr utoppya 1 , 298.Xr usb 4 299.Sh HISTORY 300The 301.Nm 302driver 303appeared in 304.Nx 4.0 . 305.Sh AUTHORS 306.An Steve C. Woodford Aq Mt scw@netbsd.org 307