-------
License
-------

Copyright (C) Geoff Oakham, 2004; <oakhamg@users.sourceforge.net>

This driver is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; only version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License in the files
"COPYING" or "COPYING.iriverfs"; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

--------------------------
Release notes for iRiverFS
--------------------------

Oct 23, 2004 (version 0.1.0.1)
	-fixed support for older and newer kernels (pre and post 2.6.8.1) 
	-made 'delta' more flexible in the data it accepts.  (Backpatched
	from the 'dev' branch.)
	-more documentation of the USB timing bug.  (See the developing
	branch for more information.)

Oct  6, 2004 (version 0.1.0.0)
	(no changes)

Oct  4, 2004 (version 0.1.0.0pre7)
	-port to linux-2.6.9pre3

Sep 30, 2004 (version 0.1.0.0pre6)
	-gcc-2.95 preprocessor bug fix didn't make it into pre5. (Fixed)
	-added support for renaming directories
	-fixed a file renaming bug.  (Involved moving files to or from '\')
	-changed the public api for renaming files/directories

Sep 27, 2004 (version 0.1.0.0pre5)
	-mount now returns 'busy' when the device fails startup test.  (Of all
	the error messages mount(5) returns, this one seems the best fitting.)
	-fixed static linking (ie, non-module) the driver.
	-fixed gcc-2.95 preprocessor bug
	-added security options
	-disabled directory renaming (Because it doesn't work.)

	-documented konqueror's chopy behaviour during file uploads

	(Footnote: there were several different patches in circulation
	with the name 'pre5'.  "pre5" and "pre5c" were private releases,
	while "pre5b" was the official release.)

Sep 21, 2004 (version 0.1.0.0pre4)
	-hot-unplugging is now handled gracefully.  (Well, more graceful than segfaulting.)
	-no longer attempts usb_reset() if the device is busy.
	-"halted endpoints" are now checked for and handled.
	-fixed 'du' problem

Sep 18, 2004 (version 0.1.0.0pre3)
	-fixed segfault-on-insmod that existed in pre1 and pre2.  (I left the
	memory allocation debugging flag on, which doesn't play nicely with
	kernels that aren't configured to support it.  My bad.)

	-added kconfig dependency on 'experimental' and 'usb'.

Sep 14, 2004 (version 0.1.0.0pre2)

	-fixed bug in iriver_lookup: there was a problem when looking up
	non-existant entries in unloaded directories.  Test case: mkdir
	/mnt/a/debug/d1/d5 (where d5 didn't exist before).

	-applied a temporary work-around that deals with usb_control_msg
	returning '-EPIPE'.  (See BUGS)

Sep 3, 2004 (Forth public release; first SourceForge release; version 0.1.0.0pre1)

	The biggest news is I've joined the ifp-driver project and this project
	has become a package of ifp-driver.  I owe a big thanks to Jun and the
	ifp-driver mailing list for making it this far.

	From here, I hope to stabilize the codebase within a few releases and
	fork the first 'stable' branch: ifp-linux-filesystem-0.1.0.0

	----------
	change log
	----------

	-"find bug" squished
	-"konqueror bug" and stability problems are gone
	-data corruption -- missing; hopefully squished
	-improved self-testing on mount
	-new info I've code-named "delta" is printed on mount.  (On my ifp5xx,
	delta is always 1.8.6.22.  I'm curious what other devices return.)
	-more stack abuse eliminated
	-more ifp-specific code removed from inode.c
	-inode/dentry refrence counting fixed

	This release was tested with linux-2.6.8.1

Aug 2, 2004 (Third public release)

	----------
	change log
	----------

	-[new!] File rename support.  (Directory renaming is untested.)

	-reading mp3 files on old device is now possible if you rename
	them.  (In the future, the driver could do this automatically.)

	-improvements in stability and memory management.

	----------------
	outstanding bugs
	----------------
	[For more details, see the 'bugs' section below.]

	-Using Konqueror locks up the system. [still]

	-Data corruption bug.  (Rare, and relatively harmless for music.)

July 23, 2004 (Second public release)

	----------
	change log
	----------

	-Support for ifp7xx/8xx devices has been added.  (Thanks to David for
	pointing out this was missing, and then helping me fix it!)

	-"It seems there's a matter with df." [fixed]  Thanks to Boris for
	brining this to my attention.

	-Bug fixed that prevented a new directory from being created inside
	another new directory. [found by David and Jim]

	-Stack abuse [using the kernel call stack to allocate large buffers] is
	gone. [found by segfault]

	-CPU abuse fixed--driver now sleeps while waiting for flush() to
	complete.

	-interal refactoring--I'm slowly separating kernel-specific code from
	iFP-specific code.  In the future, it might be possible for ifp-line
	and this driver to share some source code.

July 14, 2004 (First public release)

	-------
	summary
	-------

	This driver mounts iRiver "iFP" mp3 players as filesystems.  It is
	intended as a replacement for iRiver's "Manager" software available for
	other platforms.
	
	This project his reached "dogfood" status for me, so I'm releasing it
	for public comment and [dis]approval.  I haven't tested it with any
	other computer or player, so I'd very much appreciate feedback from
	others.

	I hope you find this useful,

	Geoff Oakham <oakhamg@users.sourceforge.net>

Requirements:

	-linux 2.6.x
	-kernel sourcecode [enough to compile modules]
	-development tools (gcc, etc.)
	-iRiver flash player (aka "iFP")
	-virtual memory, enough to temporarily hold entire files*

	This driver has been reported to work with iFP3xx, 5xx, 7xx and 8xx models.

* modern desktops shouldn't have a problem with memory use.  This warning is
  for people attempting to use this on a 486: you will need a swap partition..
  if not two.

BUGs & other unresolved problems:

	Konqueror's progress metre:
		Currently, when Konqueror uploads files to the device, its
		progress metre "jumps" after writing each file.  The jerky
		behaviour confuses Konqueror and prevents it from esitmating
		the total transfer time.  (Instead is displays "stalled"..
		which is disconcerting to the user.)

		This is a quirk of the current implementation.  It would be
		possible (and relatively easy) to fix if someone discovered how
		to append to exisiting files.  (This would allow uploads to
		happen in several steps, instead of all at once.  That would
		also mean the device wouldn't have to lock up during uploads.)

		[no intention of fixing.. see above discussion.]

	usb protocol stall:
		It appears during large downloads on a moderately loaded system,
		my ifp device does a "usb protocol stall".  (This only happens
		with my uhci host--my ohci host hasn't done this yet.)

		Details:
			-when sending the 'DOWNLOAD' control message, the system
			returns EPIPE, which in this context means "protocol stall"
			(according to the USB spec, and I've verified with code
			it isn't a functional staff.. aka 'halt').

			-sleep()ing for a few cycles and re-issuing the control
			code seems to work around the problem 90% of the time.
			(At most.)

			-The other 10% of the time, we reach EOF one block ahead
			of schedual.  (To me, this means that one of those
			control messages I presumed failed, succeeded eventually.)

			-According to the USB spec, 'protocol stall' is
			supposed be returned when the command we sent isn't
			valid.  (Either the command or its parameters.)

		Thoughts:
			I haven't seen a way for the device to tell us "wait,
			I'm not ready to send you more data"; however, that's
			supposed to be built-in to the usb protocol itself.
			(On the other hand, they didn't appear to use this
			feature for uploading.. but they might be buffering
			data in RAM.  *shrug*)

			A potential short-term solution is to pace requests for
			data.  (Ie cap our bandwidth usage.)

		[update oct 3, 2004]
			Doesn't seem to be related to usb changes mentioned
			below.

		[update oct 6, 2004]
			In a discussion on linux-usb-devel, we suspect this
			is a timing issue.  Here's a quick test I ran:

			wall time | speed Bps | EPIPEs | changes
			------------------------------ low load, no limit
			37.628157 | 544772    | 0
			37.797504 | 541835    | 1
			37.613491 | 544984    | 0
			37.807000 | 542195    | 0
			------------------------------ low load, ohcl host
			51.061969 | 401449    | 0
			50.537478 | 405615    | 0
			50.677527 | 404494    | 0
			50.502911 | 405893    | 0
			------------------------------ no load, schedule()
			37.810688 | 542142    | 0
			37.868029 | 541321    | 0
			37.958808 | 540026    | 1
			37.770085 | 542725    | 0
			------------------------------ high load, no limit
			45.54988  | 450029    | 1
			56.863098 | 360493    | 1
			83.509111 | 245467    | 1
			82.827214 | 247488    | 0
			------------------------------ high load, sleep(50ms)
			100.767380| 203427    | 0
			100.870890| 203218    | 0
			100.739756| 203482    | 0
			------------------------------ high load, sleep(10ms)
			50.597539 | 405134    | 0
			50.372042 | 406947    | 0
			50.594270 | 405160    | 0
			------------------------------ high load, sleep(5ms)
			44.373462 | 461960    | 0
			44.576646 | 459854    | 0
			44.452869 | 461135    | 0
			------------------------------ high load, schedule()
			78.141574 | 262328    | 0
			76.179661 | 269084    | 0
			79.868304 | 256657    | 0
			84.962858 | 241267    | 0

	doesn't compile with 2.6.9pre3:
		The issues are:
			1. missing 'usb_endpoint_halted'
			2. warning about incompatible pointers for __le16_to_cpup

		Changelog of linux-2.6.9pre1:
			<stern@rowland.harvard.edu>
			[PATCH] USB: Don't track endpoint halts in usbcore

			This patch is a repeat of as331 as described in

			http://marc.theaimsgroup.com/?l=linux-usb-devel&m=108811725219677&w=2

			It has been updated slightly to match the current
			source.  It should be non-controversial; it has nothing
			to do with hubs or locking.  Please apply.

			Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
			Signed-off-by: Greg Kroah-Hartman <greg@kroah.com>

		[the above mentioned bug report]
			
			List:       linux-usb-devel
			Subject:    [linux-usb-devel] PATCH: (as331) Don't track endpoint halts in usbcore
			From:       Alan Stern <stern () rowland ! harvard ! edu>
			Date:       2004-06-24 20:51:04
			Message-ID: <Pine.LNX.4.44L0.0406241644360.634-100000 () ida ! rowland ! org>

			The current mechanism for keeping track of which
			endpoints in a device are halted is both flawed and
			unnecessary.  It's flawed because devices are free to
			change the endpoint status whenever they want without
			telling us, and it's unnecessary because an URB
			submitted for a halted endpoint will quickly receive an
			error indication.

			This patch removes the code associated with tracking
			halts: the halted[] member of usb_device, the
			usb_endpoint_halt, usb_endpoint_halted, and
			usb_endpoint_running macros, all the places where they
			are used or checked, and the places in the host
			controller drivers where they get set.

			This is part of my ongoing program for cleaning up
			usbcore.  Please apply.

			Alan Stern


	missing blocks:
		The space used reported by df and du is off by a fair bit (10%
		of capacity on my device).  Since we don't know the internal
		filesystem iRiver uses, some difference is expected.. but not
		that much.  This could be an indication of a problem.  A minor
		problem, I hope.

		tought: I believe this has something to do with the reported
		blocksize.  in userland 'stat' always reports the blocksize as
		'512' no matter what I set it to.  I don't know if that's
		enough to throw the used space off by that much, but it's
		probably a good place to start looking.

	requires GCC 3.0+:
		This needs to be fixed because Linux 2.6 cites 2.95.3 as the minimum
		version.

		[fixed: I didn't have a space between "__FUNCTION__" and ","]

	Filemode details:
		-new mp3 files aren't made non-readable the way existing files are.

		[low priority]

	Security:
		-default owner/group (0/0) is not configurable
		-default umask (0777) is not configurable
		-normal users can chmod files [unconfirmed]

		[fixed]

	Device left in bad state:
		If you unmount iriverfs immediately after uploading a file,
		the device is left in a bad state.  Temporary solution
		involves disconnecting and reconnecting device.

		thought: ifp-line issues a reset() on exit.  Perhaps we should
		do the same?

	Filename length:
		no known issues.. but this must be tested at some point.

        	[needs testing]

	Directory renaming:
        	[disabled]

	Data corruption:
		Occationally during upload, four bytes of a file are changed to
		"02 00 00 00"---otherwise known as ((int)2).  (It always seems
		to be a single-digit integer.)  

        	[appears to be fixed]

	Stability:
		Stability no longer appears to be a major issue.  (This is a good
		thing, but I'm leaving this bug "open" for the time being.)

		[appears to be fixed]


Unimplemented features:

	- renaming directories
	- mp3 file reading [work around: rename it first]
	- modification of existing files
	- support for multiple devices
	- Konqueror's progress metre/device lockup on file close()

Instructions:

	1. patch your kernel
	2. run 'make [menu|x]config' to enable 'file systems'=>'iRiverFS' as a module.
	3. make modules; make modules install; insmod /lib/modules/.../fs/iriver/iriver.ko
	4. mount -t iriver none /mnt/somewhere
	5. ls /mnt/somewhere

	You can also compile the driver directly into the kernel.

	MOUNT OPTIONS

	dmask=###	-- The permission mask for directories.
	fmask=###	-- The permission mask for files.
	uid=# gid=#	-- The owner and group of the files.  (Default
			values are the user that mounted the filesystem.)

Troubleshooting:

	- take a look at the kernel log files.  (`dmesg` or /var/log/kern.log)
	- reset the device or unplug it & try again.  (If mount reports the
	  device is "busy" and you aren't using it elsewhere, try this.)

	If you still can't get it working, please email me with your
		-kernel messages [relavent ones]
		-kernel version
		-the patch version
		-iFP model number
		-iFP firmware version
		-your favourite colour
	
	In particular, please email me these lines from the kernel messages:

		iRiverFS: detected a iFP-0xx series device.
		iRiverFS: model IFP-007T, firmware 1.14, battery =[####], delta 1.8.4.42

Credits:

	Special thanks to Boris and Jim who were the first brave souls to try
	the driver.  Thanks to David who took the time to debug iFP8xx support
	and to the folks on #kernelnewbies who made helpful suggestions when I
	was stuck.  Everyone has been encouraging and helpful with their
	feedback, and is much appreciated.

	Lastly, thanks to Jordan who bought me the mp3 player.  You know how
	kids often enjoy playing with the box more than the toy inside?  Well,
	writing the driver has been a neat learning experience.. and the
	packaging came with top-grade bubblewrap. :)

Bibliography:
    -ifp-driver by Pavel Kriz and Yamashiro, Jun
    -ramfs driver by Linus Torvalds and David Gibson
    -Discussion on the ifp-driver mailing list.
    -"understanding the linux kernel"
    
Thoughts:

This was my main concern when I started writing this driver.  I don't believe
this is much of an issue anymore, but I'd like to keep the notes around until
they've been ruled out.

/*
 * Notes about iRiver's hardware:
 *
 * I've found the hardware frequently goes 'out to lunch' at which point it is
 * mostly useless until it is reset().  (Unfortunately, reset() doesn't always
 * fix the problem.)
 *
 * 'Out to lunch' behaviour has included:
 *
 *      -directory listings return garbage strings as filenames
 *      -directory listings return the filenames for a previous
 *       listing.
 *      -uploaded files are renamed or moved.  Eg:
 *              requested: '\overtures\6.Mozart-Marriage_of_Figaro.ogg'
 *              actual:    '\f_Figaro.ogg'
 *      -uploaded files don't.  Zero-byte files are created instead.
 *       The user might notice the transfer was faster than normal.
 *
 * To cope with this, the driver keeps all inodes and dentries in memory to
 * minimize interaction with the hardware.  Future development could use the
 * cache to detect 'out to lunch' behaviour.
 *
 * Note that the device can silently go 'out to lunch', particularily during a
 * file transfer.  I think the best way of copeing is to detect this early and
 * alert the user so they don't waste time using a device they believe to be
 * functional.
 *
 */

