Positron Developer's Guide: Quirks and other Common Pitfalls

As with any device, the Neuros has some quirky behavior that can trip up a developer. This document collects these issues together. Please help us keep this up to date! Email volsung@xiph.org with problems and solutions you discover.

USB Interface

Some of the most frequent problems experienced in testing are problems related to the USB support in the Linux kernel. The kernel might not recognize the device as a USB Mass Storage device, the USB modules might freeze up during I/O, and sometimes the whole system might go down. This seems to be strongly dependent upon the kernel used:

• 2.4.19-16mdk (Shipped with Mandrake 9.0) - Fails so frequently it is nearly unusable
• 2.4.21-0.13mdk (Shipped with Mandrake 9.1 x86) - Works well
• 2.4.21-17mdk (Shipped with Mandrake 9.1 PPC) - Works well
• 2.4.20-benh10 - Works well
• 2.4.20-gentoo-r3, 2.4.20-gentoo-r5 - Work well
• 2.6 kernels - Seem to work much better than 2.4

USB Issues with MacOS X

Another class of problems is caused by a buglet in the USB code on the Neuros. The Neuros does not respond to the "Mode Sense" command defined in the USB Mass Storage Class standard. The Mode Sense command is used by the host to determine if the USB device is read-only or read-write. When the host computer sends a Mode Sense command to the Neuros, the request is ignored, or fails in some other way.

Different operating systems appear to deal with this failure in different ways. Linux and Windows just assume the device is read-write. OS X assumes the device is read-only. The result is that it is impossible to update the database on OS X because the Neuros cannot be written to. Because Linux and Windows assume the device is read-write, there is no problem there.

The only OS this is known to cause a problem for is Mac OS X. Unfortunately, the workaround requires a trivial patch to the USB Mass Storage component of Darwin, which I doubt many OS X users would be willing to install. (It might be possible to deliver the update through a friendly installer, but I don't know about all the issues and pitfalls with updating core OS components in OS X.) Fixing the firmware is also a possibility, but there has been no timetable announced by DI for such a patch.

Filenames

The Neuros uses a FAT32 filesystem, so there are several things to consider while working with it from a UNIX system:

• Filenames are not case sensitive and the Linux vfat drivers don't necessarily preserve case. This most often causes problem when filenames are mistakenly compared for exact equality when a case-insensitive comparison should be used. You can open files with any case you want, but directory listings will return filenames with cases that depend on the mount options. See the vfat part of the mount manpage for details.
• Some characters are disallowed in FAT filenames and will be rejected by the Linux vfat drivers. These include: \ / : * ? " < > |
• Some characters cause the Neuros to lockup if they are present in the filename. These appear to be all extended ASCII characters, 0x7F and higher. While Linux will allow you to create files with these characters, trying to play these files on the Neuros won't work.

Database

• Just as with filenames, extended ASCII should also be avoided in data fields. The Neuros cannot display it, though the issue has been acknowledged by DI and they plan to release a future firmware that addresses this.
• Some versions (maybe all?) of the firmware, when required to generate new database files from scratch, produce incorrect databases. Some of the databases will have SAI files with incorrect pointers, or MDB files with the wrong number of fields. Fortunately, this only occurs if the Neuros is booted with missing databases or if the disk is formatted. The solution is to regenerate new databases. Correct databases are provided with positron in the positron/test/neuros_root.zip file.
• A null record in the MDB file does have a SAI record associated with it.
• The null record should never be deleted.
• New child databases sometimes have no PAI modules in them. Since the null record is present, there is a SAI record for it, but the PAI pointer is set to zero. When a PAI entry for the null record needs to be added, it may be necessary to create a new PAI module and replace the zero in SAI record with the correct pointer.
• A SAI record has a pointer to the first entry in the associated PAI module, not to the start of the PAI module itself. This is mentioned in the spec, but it is somewhat counter-intuitive, so we mention it again here.
• Recent firmwares (1.45 and newer) will only read the contents of a changed MDB file if the isModified bit set.