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