positron/doc/quirks.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="style.css" />
   4   <title>Positron Developer's Guide: Quirks and other Common Pitfalls</title>
   5 </head>
   6 <body>
   7 <h1>Positron Developer's Guide: Quirks and other Common Pitfalls</h1>
   8
   9 <p>
  10 As with any device, the Neuros has some quirky behavior that can trip
  11 up a developer.  This document collects these issues together.  Please
  12 help us keep this up to date!  Email
  13 <a href="volsung@xiph.org">volsung@xiph.org</a> with problems and
  14 solutions you discover.
  15 </p>
  16
  17 <h2>USB Interface</h2>
  18
  19 <p>
  20 Some of the most frequent problems experienced in testing are problems
  21 related to the USB support in the Linux kernel.  The kernel might not
  22 recognize the device as a USB Mass Storage device, the USB modules
  23 might freeze up during I/O, and sometimes the whole system might go
  24 down.  This seems to be strongly dependent upon the kernel used:
  25 <ul>
  26   <li>2.4.19-16mdk (Shipped with Mandrake 9.0) - Fails so
  27       frequently it is nearly unusable</li>
  28   <li>2.4.21-0.13mdk (Shipped with Mandrake 9.1 x86) - Works well</li>
  29   <li>2.4.21-17mdk (Shipped with Mandrake 9.1 PPC) - Works well</li>
  30   <li>2.4.20-benh10 - Works well</li>
  31   <li>2.4.20-gentoo-r3, 2.4.20-gentoo-r5 - Work well</li>
  32   <li>2.6 kernels - Seem to work much better than 2.4</li>
  33 </ul>
  34 Of course, this list is hardly exhaustive.  Please send me more reports!
  35 <p>
  36
  37 <h3>USB Issues with MacOS X</h3>
  38
  39 <p>
  40 Another class of problems is caused by a buglet in the USB code on the
  41 Neuros.  The Neuros does not respond to the "Mode Sense" command
  42 defined in the USB Mass Storage Class standard.  The Mode Sense
  43 command is used by the host to determine if the USB device is
  44 read-only or read-write.  When the host computer sends a Mode Sense
  45 command to the Neuros, the request is ignored, or fails in some other
  46 way.
  47 </p>
  48
  49 <p>
  50 Different operating systems appear to deal with this failure in
  51 different ways.  Linux and Windows just assume the device
  52 is read-write.  OS X assumes the device is read-only.  The result is
  53 that it is impossible to update the database on OS X because the
  54 Neuros cannot be written to.  Because Linux and Windows assume the
  55 device is read-write, there is no problem there.
  56 </p>
  57
  58 <p>
  59 The only OS this is known to cause a problem for is Mac OS X.
  60 Unfortunately, the workaround requires a trivial patch to the USB Mass
  61 Storage component of Darwin, which I doubt many OS X users would be
  62 willing to install.  (It might be possible to deliver the update
  63 through a friendly installer, but I don't know about all the issues
  64 and pitfalls with updating core OS components in OS X.)  Fixing the
  65 firmware is also a possibility, but there has been no timetable
  66 announced by DI for such a patch.
  67 </p>
  68
  69 <h2>Filenames</h2>
  70
  71 <p>
  72 The Neuros uses a FAT32 filesystem, so there are several things to
  73 consider while working with it from a UNIX system:
  74 </p>
  75
  76 <ul class="biglist">
  77
  78   <li>Filenames are not case sensitive and the Linux vfat drivers
  79   don't necessarily preserve case.  This most often causes problem
  80   when filenames are mistakenly compared for exact equality when a
  81   case-insensitive comparison should be used.  You can open files with
  82   any case you want, but directory listings will return filenames with
  83   cases that depend on the mount options.  See the vfat part of the
  84   mount manpage for details.</li>
  85
  86   <li>Some characters are disallowed in FAT filenames and will be
  87   rejected by the Linux vfat drivers.  These include: <tt>\ / : * ?
  88   &quot; &lt; &gt; |</tt></li>
  89
  90   <li>Some characters cause the Neuros to lockup if they are present
  91   in the filename.  These appear to be all extended ASCII characters,
  92   0x7F and higher.  While Linux will allow you to create files with
  93   these characters, trying to play these files on the Neuros won't
  94   work.</li>
  95
  96 </ul>
  97
  98
  99 <h2>Database</h2>
 100
 101 <ul class="biglist">
 102   <li>Just as with filenames, extended ASCII should also be avoided in
 103   data fields.  The Neuros cannot display it, though the issue has
 104   been acknowledged by DI and they plan to release a future firmware
 105   that addresses this.</li>
 106
 107   <li>Some versions (maybe all?) of the firmware, when required to
 108   generate new database files from scratch, produce incorrect
 109   databases.  Some of the databases will have SAI files with
 110   incorrect pointers, or MDB files with the wrong number of fields.
 111   Fortunately, this only occurs if the Neuros is booted with missing
 112   databases or if the disk is formatted.  The solution is to
 113   regenerate new databases.  Correct databases are provided with
 114   positron in the <tt>positron/test/neuros_root.zip</tt> file.</li>
 115
 116   <li>A null record in the MDB file does have a SAI record associated
 117   with it.</li>
 118
 119   <li>The null record should never be deleted.</li>
 120
 121   <li>New child databases sometimes have no PAI modules in them.
 122   Since the null record is present, there is a SAI record for it, but
 123   the PAI pointer is set to zero.  When a PAI entry for the null
 124   record needs to be added, it may be necessary to create a new PAI
 125   module and replace the zero in SAI record with the correct pointer.</li>
 126
 127   <li>A SAI record has a pointer to the first entry in the associated
 128   PAI module, <em>not to the start of the PAI module itself</em>.
 129   This is mentioned in the spec, but it is somewhat counter-intuitive,
 130   so we mention it again here.</li>
 131
 132   <li>Recent firmwares (1.45 and newer) will <em>only</em> read the
 133   contents of a changed MDB file if the isModified bit set.</li>
 134
 135 </li>
 136
 137 </body>
 138 </html>