[xiph-cvs] cvs commit: positron/doc api.html quirks.html

Mon May 26 16:31:56 PDT 2003

volsung     03/05/26 19:31:55

  Added:       doc      api.html quirks.html
  Log:
  More technical docs.

Revision  Changes    Path
1.1                  positron/doc/api.html

Index: api.html
===================================================================
<html>
<head>
  <title>Positron Documentation: API</title>
</head>
<body>
<h1>Positron API</h1>

One of the goals of positron is to provide Python modules that can be
used by others to interact with the Neuros. For this initial release,
however, we still consider the module API in a state of flux. A
future release will include a finalized API.

</body>
</html>

<p><p>1.1                  positron/doc/quirks.html

Index: quirks.html
===================================================================
<html>
<head>
  <title>Positron Documentation: Quirks and other Common Pitfalls</title>
</head>
<body>
<h1>Quirks and other Common Pitfalls</h1>

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 <a
href="volsung at xiph.org">volsung at xiph.org</a> with problems and
solutions you discover.

<h2>USB Interface</h2>

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:
<ul>
 <li>2.4.19-16mdk (Shipped with Mandrake 9.0) - Fails so frequently it is nearly unusable</li>
 <li>2.4.20-somethingmdk FIXME (Shipped with Mandrake 9.1) - Works well</li>
 <li>2.4.21-17mdk (Shipped with Mandrake 9.1 PPC) - Works well</li>
 <li>2.4.20-benh10 - Works well</li>
 <li>2.4.20-gentoo-r3 - Works well</li>
</ul>
Of course, this list is hardly exhaustive. Please send me more reports!

<h3>USB Issues with MacOS X</h3>

Another class of problems is cause by a buglet in the USB code on the
Neuros. The Neuros does not responding 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 presumably 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.

<h2>Filenames</h2>

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

<ul>

<li>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.

  <li>Some characters are disallowed in FAT filenames and will be
  rejected by the Linux vfat drivers.  These include: <tt>\ / : * ?
  " &lt; &gt; |</tt></li>

<li>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.</li>

</ul>

<p><h2>Database</h2>

<ul>
 <li>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.</li>

<li>Some versions (maybe all?) of the firmware, when required to
 generate new database files from scratch, produce incorrect
 databases. The 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 <tt>positron/test/neuros_root.zip</tt> file.</li>

  <li>A null record in the MDB file does have a SAI record associated
  with it.</li>

  <li>The null record should never be deleted.</li>

<li>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.</li>

<li>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.</li>
</li>

</body>
</html>

--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.