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.