| blob | 832bc1cbff6052da5ca1837b37f5a85c88ad5de6 |
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 .\"
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
41 The
42 .Nm
43 driver provides support for the Topfield TF5000PVR range of DVB recorders
44 (nicknamed
45 .Ql Toppy )
46 which are popular in Europe and Australia.
47 These recorders have a
48 .Tn USB
49 device interface which can be used to transfer
50 recordings to and from the unit's hard disk.
51 The
52 .Tn USB
53 interface can also be used to upload binary images for execution
54 on the Toppy's MIPS cpu.
55 .Pp
56 The Toppy's
57 .Tn USB
58 protocol has not been officially documented by Topfield,
59 but the basic features have been reverse engineered by others in order
60 to write replacements for the official
61 .Ql Altair
62 download/upload program from Topfield.
63 .Pp
64 Existing replacements for Altair suffer from the fact that they are
65 ultimately built on top of
66 .Xr ugen 4 .
67 This has a number of detrimental side-effects:
68 .Bl -enum
69 .It
70 Performance suffers since all Toppy command packets have to cross the
71 user-kernel interface.
72 .It
73 The userland programs are full of clutter to deal with interpreting the
74 command/status packets, not to mention byte-swapping and host endian
75 issues.
76 .It
77 Signals can interrupt a data transfer at a critical point, leaving the
78 Toppy in an undefined state.
79 For example, interrupting a download with
80 .Ql Turbo
81 mode enabled will leave the Toppy completely unresponsive to the remote
82 control, and prevent timer-based recordings from starting.
83 .El
84 .Pp
85 The
86 .Nm
87 driver provides a clean and stable interface to the Toppy protocol, and
88 ensures that an interrupt caused by a signal does not leave the Toppy in
89 an undefined state.
90 .Sh UTOPPY INTERFACE
91 Use the following header file to get access to the
92 .Tn utoppy
93 specific structures and defines.
94 .Bd -literal
95 #include \*[Lt]dev/usb/utoppy.h\*[Gt]
96 .Ed
97 .Pp
98 The
99 .Nm
100 driver can be accessed through the
101 .Pa /dev/utoppyN
102 character device.
103 The primary means of controlling the driver is by issuing a series of
104 .Xr ioctl 2
105 system calls followed by
106 .Xr read 2
107 or
108 .Xr write 2
109 system calls as appropriate.
110 .Pp
111 The following
112 .Xr ioctl 2
113 commands are supported by the
114 .Nm
115 driver:
116 .Bl -tag -width xxxxxx
117 .It Dv UTOPPYIOTURBO Fa "int *mode"
118 This command can be used to enable or disable
119 .Ql Turbo
120 mode for subsequent
121 .Dv UTOPPYIOREADFILE
122 or
123 .Dv UTOPPYIOWRITEFILE
124 commands (see below).
125 If
126 .Fa num
127 is non-zero, Turbo mode will be enabled.
128 Otherwise Turbo mode will be disabled.
129 In non-Turbo mode, the Toppy's
130 .Tn USB
131 interface is capable of sustaining around 5.6 Mbit/s during a file transfer.
132 With Turbo mode enabled, it can sustain just over 16 Mbit/s.
133 Of course, these figures are valid only if the Toppy is connected via a
134 .Tn USB
135 2.0 interface.
136 Performance using an older
137 .Tn USB
138 1 interface will be significantly lower.
139 .It Dv UTOPPYIOCANCEL Fa void
140 This command can be used to abort an in-progress
141 .Dv UTOPPYIOREADDIR ,
142 .Dv UTOPPYIOREADFILE ,
143 or
144 .Dv UTOPPYIOWRITEFILE
145 command.
146 .It Dv UTOPPYIOREBOOT Fa void
147 This command will cause the Toppy to reboot cleanly.
148 .It Dv UTOPPYIOSTATS Fa "struct utoppy_stats *stats"
149 This command retrieves statistics for the Toppy's hard disk.
150 .Bd -literal
151 struct 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"
157 This command is used to rename a file or directory on the Toppy's
158 hard disk.
159 The full pathname to each file must be provided.
160 .Bd -literal
161 struct 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"
167 This command creates the directory specified by
168 .Fa path .
169 .It UTOPPYIODELETE Fa "char *path"
170 This command deletes the file or directory specified by
171 .Fa path .
172 .It UTOPPYIOREADDIR Fa "char *path"
173 This command initiates a read of the contents of the directory specified by
174 .Fa path .
175 After issuing this command, the directory contents must be read using
176 consecutive
177 .Xr read 2
178 system calls.
179 Each
180 .Xr read 2
181 will transfer one or more directory entries into the user-supplied buffer.
182 The buffer must be large enough to receive at least one directory entry.
183 When
184 .Xr read 2
185 returns zero, all directory entries have been read.
186 .Pp
187 A directory entry is described using the following data structure:
188 .Bd -literal
189 struct 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
202 The
203 .Va ud_path
204 field contains the name of the directory entry.
205 .Pp
206 The
207 .Va ud_type
208 field specifies whether the entry corresponds to a file or a sub-directory.
209 .Pp
210 The
211 .Va ud_size
212 field is valid for files only, and specifies the file's size in bytes.
213 .Pp
214 The
215 .Va ud_mtime
216 field describes the file or directory's modification time, specified as
217 seconds from the Unix epoch.
218 The timestamp is relative to the current timezone, so
219 .Xr localtime 3
220 can be used to convert it into human readable form.
221 Note that the Toppy sets directory timestamps to a predefined value so
222 they are not particularly useful.
223 .Pp
224 The
225 .Va ud_attributes
226 field is not used at this time.
227 .It UTOPPYIOREADFILE Fa "struct utoppy_readfile *"
228 This command is used to initiate reading a file from the Toppy's hard disk.
229 The full pathname, together with the file offset at which to start reading,
230 is specified using the following data structure:
231 .Bd -literal
232 struct utoppy_readfile {
233 char *ur_path;
234 off_t ur_offset;
235 };
236 .Ed
237 .Pp
238 After issuing this command, the file must be read using consecutive
239 .Xr read 2
240 system calls.
241 When
242 .Xr read 2
243 returns zero, the entire file has been read.
244 .It UTOPPYIOWRITEFILE Fa "struct utoppy_writefile *"
245 This command is used to initiate writing to a file on the Toppy's hard disk.
246 The file to be written is described using the following data structure:
247 .Bd -literal
248 struct 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
256 The
257 .Va uw_path
258 field specifies the full pathname of the file to be written.
259 .Pp
260 The
261 .Va uw_offset
262 field specifies the file offset at which to start writing, assuming the file
263 already exists.
264 Otherwise,
265 .Va uw_offset
266 must be zero.
267 .Pp
268 The protocol requires that the Toppy must be informed of a file's size in
269 advance of the file being written.
270 This is accomplished using the
271 .Va uw_size
272 field.
273 It may be possible to work around this limitation in a future version of
274 the driver.
275 .Pp
276 The
277 .Va uw_mtime
278 field specifies the file's timestamp expressed as seconds from the Unix epoch
279 in the local timezone.
280 .El
281 .Pp
282 Due to limitations with the protocol, a
283 .Nm
284 device can be opened by only one application at a time.
285 Also, only a single
286 .Dv UTOPPYIOREADDIR ,
287 .Dv UTOPPYIOREADFILE ,
288 or
289 .Dv UTOPPYIOWRITEFILE
290 command can be in progress at any given time.
291 .Sh FILES
292 .Bl -tag -width /dev/utoppy0 -compact
293 .It Pa /dev/utoppy0
294 device node
295 .El
296 .Sh SEE ALSO
297 .Xr utoppya 1 ,
298 .Xr usb 4
299 .Sh HISTORY
300 The
301 .Nm
302 driver
303 appeared in
304 .Nx 4.0 .
305 .Sh AUTHORS
306 .An Steve C. Woodford Aq scw@netbsd.org