blob: a6d438b5a9dbba760133a8baa3c1384cf6e4a4fe [file] [log] [blame]
Linus Walleij0dd71e92006-05-04 18:47:07 +00001Building and Installing
2-----------------------
Linus Walleij6fd2f082006-03-28 07:19:22 +00003
Linus Walleij0dd71e92006-05-04 18:47:07 +00004See the "INSTALL" file.
5
6
7Heritage
8--------
9
10libmtp is based on several ancestors:
11
12* libptp2 by Mariusz Woloszyn was the starting point used
13 by Richard A. Low for the initial starter port. You can
14 find it at http://libptp.sourceforge.net/
15
16* libgphoto2 by Mariusz Woloszyn and Marcus Meissner was
17 used at a later stage since it was (is) more actively
18 maintained. libmtp tracks the PTP implementation in
19 libgphoto2 and considers it an upstream project. We will
20 try to submit anything generally useful back to libgphoto2
21 and not make double efforts. In practice this means we
22 use ptp.c, ptp.h and ptp-pack.c verbatim from the libgphoto2
23 source code. If you need to change things in these files,
24 make sure it is so general that libgphoto2 will want to
25 merge it to their codebase too. You find libgphoto2 as part
26 of gPhoto: http://gphoto.sourceforge.net/
27
28* libnjb was a project that Richard and Linus were working
Linus Walleijfcf88912006-06-05 13:23:33 +000029 on before libmtp. When Linus took Richards initial port
Linus Walleij0dd71e92006-05-04 18:47:07 +000030 and made an generic C API he re-used the philosophy and
31 much code from libnjb. Many of the sample programs are for
32 example taken quite literally from libnjb. You find it here:
33 http://libnjb.sourceforge.net/
34
35
Linus Walleijea7d45b2009-02-23 22:26:09 +000036Contacting and Contributing
37---------------------------
38
39See the project page at http://libmtp.sourceforge.net/
40We always need your help. There is a mailinglist and a
41bug report system there.
42
43People who want to discuss MTP devices in fora seem to
44hang out on the forums at AnythingbutiPod:
45http://www.anythingbutipod.com/forum/
46
47
Linus Walleij0dd71e92006-05-04 18:47:07 +000048Compiling programs for libmtp
49-----------------------------
50
51libmtp has support for the pkg-config script by adding a libmtp.pc
52entry in $(prefix)/lib/pkgconfig. To compile a libmtp program,
53"just" write:
54
55gcc -o foo `pkg-config --cflags --libs libmtp` foo.c
56
57This also simplifies compilation using autoconf and pkg-config: just
58write e.g.
59
60PKG_CHECK_MODULES(MTP, libmtp)
61AC_SUBST(MTP_CFLAGS)
62AC_SUBST(MTP_LIBS)
63
64To have libmtp LIBS and CFLAGS defined. Needless to say, this will
65only work if you have pkgconfig installed on your system, but most
66people have nowadays.
67
68If your library is installed in e.g. /usr/local you may have to tell
69this to pkgconfig by setting the PKG_CONFIG_PATH thus:
70
71export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
72
73
74Documentation
75-------------
76
77Read the API documentation that can be generated with doxygen.
78It will be output in doc/html if you have Doxygen properly
79installed. (It will not be created unless you have Doxygen!)
80
81For information about the Media Transfer Protocol, see:
82http://en.wikipedia.org/wiki/Media_Transfer_Protocol
83
Linus Walleij7a83e552008-07-29 21:30:43 +000084The official 1.0 specification for MTP was released by the
85USB Implementers Forum in may, 2008. Prior to this, only a
86proprietary Microsoft version was available, and quite a few
87devices out there still use some aspects of the Microsoft
88version, which deviates from the specified standard. You can
89find the official specification here:
90http://www.usb.org/developers/devclass_docs/MTP_1.0.zip
Linus Walleij0dd71e92006-05-04 18:47:07 +000091
Linus Walleij1b91ca62008-10-17 07:07:56 +000092
93The Examples
94------------
95
96In the subdirectory "examples" you find a number of
97command-line tools, illustrating the use of libmtp in very
98simple terms.
99
100Please do not complain about the usability or documentation
101of these examples, they look like they do for two reasons:
102
1031. They are examples, not tools. If they were intended for
104 day-to-day usage by commandline freaks, I would have
105 called them "tools" not "examples".
106
1072. The MTP usage paradigm is that a daemon should hook
108 the device upon connection, and that it should be
109 released by unplugging. GUI tools utilizing HAL (hald)
110 and D-Bus do this much better than any commandline
111 program ever can. (See below on bugs.) Specificationwise
112 this is a bug, however it is present in many, many
113 devices.
114
115That said, if you want to pick up and maintain the examples,
116please volunteer.
117
118
Linus Walleija1b66f22007-05-10 20:02:16 +0000119New Devices
120-----------
121
Linus Walleijfcf88912006-06-05 13:23:33 +0000122If you happen upon a device which libmtp claims it cannot
123autodetect, please submit the vendor ID and device ID
Linus Walleij9ee29402007-10-31 20:24:48 +0000124(these can be obtained from the "lsusb" and "lsusb -n"
125commands run as root) as a bug, patch or feature request
126on the Sourceforge bug tracker at our homepage. If it
127gives a sensible output from "mtp-detect" then please attach
128the result as well as it teach us some stuff about your
129device. If you've done some additional hacking, join our
130mailinglist and post your experiences there.
Linus Walleijda558be2007-03-10 21:42:25 +0000131
Linus Walleija1b66f22007-05-10 20:02:16 +0000132If you want to be able to hack some more and you're not
133afraid of C hacking, add an entry for your device's
134vendor/product ID and a descriptive string to the database
Linus Walleij6dc01682007-11-15 21:23:46 +0000135in the file src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000136
137If you want to poke around to see if your device has some
138special pecularities, you can test some special device
Linus Walleij6dc01682007-11-15 21:23:46 +0000139flags (defined in src/device-flags.h) by inserting them
140together with your device entry in src/music-players.h.
Linus Walleija1b66f22007-05-10 20:02:16 +0000141Flags can be tested in isolation or catenated with "|"
142(binary OR). If relatives to your device use a certain
143flag, chances are high that a new device will need it
144too, typically from the same manufacturer.
145
146The most common flag that needs to be set is the
147DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel
148drivers that may have attached to the device making
Linus Walleij94f23d52007-08-04 19:37:28 +0000149MTP access impossible. This is however not expected to
150really work: this is a problem being tracked as of
151now (2007-08-04). See the "last resort" solutions below
152if you really need to get your dual-mode device to work
153with MTP.
Linus Walleija1b66f22007-05-10 20:02:16 +0000154
Linus Walleijcc2cf972007-11-22 20:23:43 +0000155Another flag which is easy to identify is the
156DEVICE_FLAG_NO_ZERO_READS, which remedies connection
157timeouts when getting files, and some timeouts on e.g.
158successive "mtp-connect" calls.
159
Linus Walleij91fb0282007-09-03 21:16:08 +0000160If you are a device vendor, please consider assigning one
161of your employees as a contact person for libmtp, have them
162sign up to the libmtp development list and answer questions
163and post new device ID:s as they are released to our
164mailing list. By the way: do you have spare devices you
165can give us? Send them to Richard (Mac support) or Linus
166(Linux support). (So far nobody did that except for Microsoft
167who sent us a Zune by proxy!)
168
Linus Walleija1b66f22007-05-10 20:02:16 +0000169If your device is very problematic we are curious of how it
Linus Walleijda558be2007-03-10 21:42:25 +0000170works under Windows, so we enjoy reading USB packet sniffs
171that reveal the low-level traffic carried out between
172Windows Media Player and your device. This can be done
Linus Walleij61c25682007-09-04 14:46:21 +0000173using e.g.:
174
175* USBsnoop:
176 http://benoit.papillault.free.fr/usbsnoop/
177
178* The trial version of HHD Softwares software-only
179 USB monitor. You need to get a copy of version 2.37 since
180 the newer trial versions won't let you carry out the
181 needed packet sniffs. (As of 2007-03-10 a copy can be found
182 at: http://www.cobbleware.com/files/usb-monitor-237.exe)
183
Linus Walleijda558be2007-03-10 21:42:25 +0000184There are other USB monitors as well, some more expensive
185alternatives use hardware and even measure electronic
186characteristics of the traffic (which is far too much
187detail for us).
188
Linus Walleij91fb0282007-09-03 21:16:08 +0000189Device sniffs are an easy read since the PTP/MTP protocol
190is nicely structured. All commands will have a structure such
191as this in the log, we examplify with a object list request:
192
193PTP REQEUST:
194000120: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:25.9843750 +0.0
195Pipe Handle: 0x863ce234 (Endpoint Address: 0x2)
196Send 0x20 bytes to the device:
197 20 00 00 00 01 00 05 98 23 00 00 00 27 03 00 10 ......?#...'...
198 Length TYPE CMD Trans# Param1
199
200 00 00 00 00 02 DC 00 00 00 00 00 00 00 00 00 00 .....Ü..........
201 Param2 Param3 Param4 Param5
202
203[OPTIONAL] DATA PHASE:
204000121: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0156250
205Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
206Get 0x1a bytes from the device:
207 1A 00 00 00 02 00 05 98 23 00 00 00 01 00 00 00 .......?#.......
208 Length TYPE CMD Trans# DATA
209
210 27 03 00 10 02 DC 04 00 00 30 '....Ü...0
211
212RESPONSE:
213000122: Bulk or Interrupt Transfer (UP), 03.09.2007 12:49:26.0 +0.0
214Pipe Handle: 0x863ce214 (Endpoint Address: 0x81)
215Get 0xc bytes from the device:
216 0C 00 00 00 03 00 01 20 23 00 00 00 ....... #...
217 Length TYPE CODE Trans#
218
219* One send (OUT to the device), two reads (IN from the device).
220
221* All three byte chunks commands are
222 sent/recieved/recieeved by the function ptp_transaction()
223 in the file ptp.c.
224
225* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()
226 or ptp_usb_getdata() and finally ptp_usb_getresp() in the file
227 libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()
228 are ALWAYS called. The TYPE field correspond to this, so the
229 TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),
230 and "RESPONSE" (0x0003).
231
232* Notice that the byte order is little endian, so you need to read
233 each field from right to left.
234
235* This COMMAND has:
236 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
237 Transaction# 0x00000023.
238 REQUEST parameters 0x10000327, 0x00000000, 0x0000DC02, 0x00000000
239 0x00000000, in this case it means "get props for object 0x10000327",
240 "any format", "property 0xDC02" (PTP_OPC_ObjectFormat), then two
241 parameters that are always zero (no idea what they mean or their
242 use).
243
244* The DATA has:
245 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
246 Transaction# 0x00000023.
247 Then comes data 0x00000001, 0x10000327, 0xDC02, 0x0004, 0x3000
248 Which means in this case, (and this is the tricky part) "here
249 you have 1 property", "for object 0x10000327", "it is property
250 0xDC02" (PTP_OPC_ObjectFormat), "which is of type 0x0004"
251 (PTP_DTC_UINT16), "and set to 0x3000" (PTP_OFC_Undefined, it
252 is perfectly valid to have undefined object formats, since it
253 is a legal value defining this).
254
255* This RESPONSE has:
256 CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.
257 Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.
258 Transaction# 0x00000023.
Linus Walleijfcf88912006-06-05 13:23:33 +0000259
Linus Walleijd05fce62007-09-29 20:17:23 +0000260If you want to compare the Windows behaviour with a similar
Linus Walleij6dc01682007-11-15 21:23:46 +0000261operation using libmtp you can go into the src/libusb-glue.c
262file and uncomment the row that reads:
Linus Walleijd05fce62007-09-29 20:17:23 +0000263
264//#define ENABLE_USB_BULK_DEBUG
265
266(I.e. remove the two //.)
267
268This will make libmtp print out a hex dump of every bulk USB
269transaction. The bulk transactions contain all the PTP/MTP layer
270data, which is usually where the problems appear.
271
Linus Walleij6fd2f082006-03-28 07:19:22 +0000272
Linus Walleijbd7624c2007-05-28 10:48:54 +0000273Devices does not work - last resort:
274------------------------------------
275
276Some devices that are dual-mode are simply impossible to get
277to work under Linux because the usb-storage(.ko) kernel
278module hook them first, and refuse to release them, even
Linus Walleij94f23d52007-08-04 19:37:28 +0000279when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe
280it DOES release it but the device will immediately be probed
281at the USB mass storage interface AGAIN because it
282enumerates.)
Linus Walleijbd7624c2007-05-28 10:48:54 +0000283
Linus Walleije20abaf2007-12-10 11:20:34 +0000284Linux: Try this, if you have a recent 2.6.x Linux kernel,
Linus Walleij584eb8d2007-09-05 19:51:27 +0000285run (as root) something like:
286
287> rmmod usb_storage ; mtp-detect
288
289You can run most any command or a client like gnomad2 or
290Amarok immediately after the rmmod command. This works
291sometimes. Another way:
Linus Walleijbd7624c2007-05-28 10:48:54 +0000292
Linus Walleij94f23d52007-08-04 19:37:28 +0000293* Edit /etc/modprobe.d/blacklist
Linus Walleijbd7624c2007-05-28 10:48:54 +0000294
295* Add the line "blacklist usb-storage"
296
297* Reboot.
298
299Now none of you USB disks, flash memory sticks etc will be
300working (you just disabled them all). However you *can* try
301your device, and it might have started working because there
302is no longer a USB mass storage driver that tries to hook onto
303the mass storage interface of your device.
304
Linus Walleij94f23d52007-08-04 19:37:28 +0000305If not even blacklisting works (check with
306"lsmod | grep usb-storage"), there is some problem with
307something else and you may need to remove or rename the file
308/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko
309manually.
310
Linus Walleijbd7624c2007-05-28 10:48:54 +0000311If you find the PerfectSolution(TM) to this dilemma, so you
312can properly switch for individual devices whether to use it
313as USB mass storage or not, please tell us how you did it. We
314know we cannot use udev, because udev is called after-the-fact:
315the device is already configured for USB mass storage when
316udev is called.
317
Linus Walleije20abaf2007-12-10 11:20:34 +0000318On Mac OS there is another ugly hack:
319
3201. Open up a terminal window
3212. Type:
322sudo mv /System/Library/Extensions/IOUSBMassStorageClass.kext
323/System/Library/Extensions/IOUSBMassStorageClass.kext.disabled
324
325and when prompted enter your password.
326
3273. Restart.
328
329To reverse this change, just reverse the filenames:
330
331sudo mv /System/Library/Extensions/
332IOUSBMassStorageClass.kext.disabled /System/Library/Extensions/
333IOUSBMassStorageClass.kext
334
335and restart.
336
Linus Walleijbd7624c2007-05-28 10:48:54 +0000337
Linus Walleij15def332006-09-19 14:27:02 +0000338Calendar and contact support:
339-----------------------------
Linus Walleijd3bdf762006-02-20 22:21:56 +0000340
Linus Walleij3c16fe42006-04-30 07:53:41 +0000341The Creative Zen series can read VCALENDAR2 (.ics) files
Linus Walleij15def332006-09-19 14:27:02 +0000342and VCard (.vcf) files from programs like for example
343Evolution with the following limitations/conditions:
Linus Walleijd3bdf762006-02-20 22:21:56 +0000344
Linus Walleij3c16fe42006-04-30 07:53:41 +0000345- The file must be in DOS (CR/LF) format, use the unix2dos
346 program to convert if needed
Linus Walleij15def332006-09-19 14:27:02 +0000347
348- Repeat events in calendar files do not seem to be supported,
349 entries will only appear once.
350
351- Calendar (.ics) files should be stored in the folder "My Organizer"
352 when sent to the device (this directory should be autodetected
Linus Walleij80b2c722006-06-22 17:57:17 +0000353 for use with calendar files, otherwise use the option
Linus Walleij15def332006-09-19 14:27:02 +0000354 -f "My Organizer" to sendfile for this) Apparently this file can
355 also contain tasklists.
356
357- Contact (.vcf) files should be stored in the folder "My Contacts"
358 when sent to the device. (-f "My Contacts")
359
360- Some devices are picky about the name of the calendar and
361 contact files. For example the Zen Microphoto wants:
362
Linus Walleijb1318d12006-09-25 14:59:26 +0000363 Calendar: My Organizer/6651416.ics
364 Contacts: My Organizer/6651416.vcf
365
366
367Syncing in with Evolution and Creative Devices
368----------------------------------------------
369
370Evolution can easily export .ics an .vcf files, but you currently
371need some command-line hacking to get you stuff copied over in
372one direction host -> device. The examples/ directory contains a script
373created for the Creative Zen Microphoto by Nicolas Tetreault.
374
Linus Walleij6e8cef42006-12-03 20:45:04 +0000375
376It's Not Our Bug!
377-----------------
378
379Some MTP devices have strange pecularities. We try to work around
380these whenever we can, sometimes we cannot work around it or we
381cannot test your solution.
382
Linus Walleij67038b92008-04-16 15:01:40 +0000383* Generic MTP/PTP disconnect misbehaviour: we have noticed that
384 Windows Media Player apparently never close the session to an MTP
385 device. There is a daemon in Windows that "hooks" the device
386 by opening a PTP session to any MTP device, whenever it is
387 plugged in. This daemon proxies any subsequent transactions
388 to/from the device and will never close the session, thus
389 Windows simply does not close sessions at all.
390
Linus Walleije2f65662008-12-07 20:44:11 +0000391 Typical sign of this illness: broken pipes on closing sessions,
392 on the main transfer pipes(s) or the interrupt pipe:
393
394 Closing session
395 usb_clear_halt() on INTERRUPT endpoint: Broken pipe
396 OK.
397
Linus Walleij67038b92008-04-16 15:01:40 +0000398 This means that device manufacturers doesn't notice any problems
399 with devices that do not correctly handle closing PTP/MTP
400 sessions, since Windows never do it. The proper way of closing
401 a session in Windows is to unplug the device, simply put.
402
403 Since libmtp actually tries to close sessions, some devices
404 may fail since the close session functionality has never been
405 properly tested, and "it works with Windows" is sort of the
406 testing criteria at some companies.
407
408 You can get Windows-like behaviour on Linux by running a HAL-aware
409 libmtp GUI client like Rhythmbox or Gnomad2, which will "hook"
410 the device when you plug it in, and "release" it if you unplug
411 it.
412
413 If this bug in your device annoys you, contact your device
414 manufacturer and ask them to test their product with some libmtp
415 program.
416
Linus Walleijb715ba62008-02-12 23:41:49 +0000417* Generic USB misbehaviour: some devices behave badly under MTP
418 and USB mass storage alike, even down to the lowest layers
419 of USB. You can always discuss such issues at the linux-usb
420 mailing list if you're using Linux:
421 http://www.linux-usb.org/mailing.html
422
Linus Walleij76b185d2008-02-12 23:46:14 +0000423 If you have a problem specific to USB mass storage mode, there
424 is a list of strange behaving devices in the Linux kernel:
425 http://lxr.linux.no/linux/drivers/usb/storage/unusual_devs.h
Linus Walleijf7d8df12008-02-13 00:02:17 +0000426 You can discuss this too on the mentioned list, for understanding
427 the quirks, see:
428 http://www2.one-eyed-alien.net/~mdharm/linux-usb/target_offenses.txt
Linus Walleij76b185d2008-02-12 23:46:14 +0000429
Linus Walleijdeddc342008-08-16 23:52:06 +0000430* Kernel bug on Linux. Linux 2.6.16 is generally speaking required
431 to use any MTP device under USB 2.0. This is because the EHCI
432 driver previously did not support zero-length writes to endpoints.
433 It should work in most cases however, or if you connect it
434 to an UHCI/OHCI port instead (yielding lower speed). But
435 please just use a recent kernel.
436
Linus Walleij07bb5382008-07-31 20:21:09 +0000437* Zen models AVI file seeking problem: the Zens cannot parse the
438 files for the runlength metadata. Do not transfer file with e.g.
439 mtp-sendfile, use mtp-sendtr and set the length of the track to
440 the apropriate number of seconds and it will work. In graphical
441 clients, use a "track transfer" function to send these AVI files,
442 the Zens need the metadata associated with tracks to play back
443 movies properly. Movies are considered "tracks" in the MTP world.
444
Linus Walleij64e2e982008-08-01 21:51:13 +0000445* Some devices that disregard the metadata sent with the MTP
446 commands will parse the files for e.g. ID3 metadata. Some still
447 of these devices expect only ID3v2.3 metadata and will fail with
448 a modern ID3v2,4 tag writer, like many of those found in Linux
449 applications. Windows Media Player use ID3v2.3 only, so many
450 manufacturers only test this version.
451
Linus Walleij6e8cef42006-12-03 20:45:04 +0000452* The Zen Vision:M (possibly more Creative Zens) has a firmware bug
453 that makes it drop the last two characters off a playlist name.
454 It is fixed in later firmware.
455
Linus Walleijc41f2e82007-03-12 22:26:00 +0000456* For Creative Technology devices, there are hard limits on how
457 many files can be put onto the device. For a 30 GiB device (like
458 the Zen Xtra) the limit is 6000, for a 60 GiB device the limit
459 is 15000 files. For further Creative pecularities, see the
460 FAQ sections at www.nomadness.net.
461
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000462* Sandisk sansa c150 and probably several other Sandisk devices
463 (and possibly devices from other manufacturers) have a dual
464 mode with MTP and USB mass storage. The device will initially
465 claim to be mass storage so udev will capture is and make the
Linus Walleijda558be2007-03-10 21:42:25 +0000466 use of MTP mode impossible. One way of avoiding it could be to
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000467 be to blacklist the "usb-storage" module in
468 /etc/modprobe.c/blacklist with a row like this:
Linus Walleijda558be2007-03-10 21:42:25 +0000469 "blacklist usb-storage". Some have even removed the
470 "usb-storage.ko" (kernel module file) to avoid loading.
Linus Walleijd24a7ab2007-03-07 21:48:43 +0000471
Linus Walleij2242b022009-01-02 01:44:00 +0000472* Sandisk Sansa Fuze has three modes: auto, MTP or mass storage
473 (MSC). Please set it to MTP to avoid problems with libmtp.
474
Linus Walleijda558be2007-03-10 21:42:25 +0000475* The iriver devices (possibly all of them) cannot handle the
Linus Walleij6e8cef42006-12-03 20:45:04 +0000476 enhanced GetObjectPropList MTP command (0x9805) properly. So
477 they have been banned from using it.
478
Linus Walleijda558be2007-03-10 21:42:25 +0000479* iriver devices have problems with older versions of libmtp and
Linus Walleij82265222007-03-04 19:47:08 +0000480 with new devices libmtp does not know of as of yet, since it
481 has an oldstyle USB device controller that cannot handle zero
Linus Walleijda558be2007-03-10 21:42:25 +0000482 writes. (Register your device with us!) All their devices are
483 likely to need a special device flag in the src/libusb-glue.c
484 database.
Linus Walleij82265222007-03-04 19:47:08 +0000485
Linus Walleij6e8cef42006-12-03 20:45:04 +0000486* The Samsung Yepp T9 has several strange characteristics, some
487 that we've managed to work around. (For example it will return
488 multiple PTP packages in a single transaction.)
489
Linus Walleijf2711b32007-02-26 20:18:40 +0000490* The early firmware for Philips HDD players is known to be
491 problematic. Please upgrade to as new firmware as you can get.
492 (Yes this requires some kind of Windows Installation I think.)
493
Linus Walleijb5a4f922008-05-11 20:15:00 +0000494* Philips HDD 1630/16 or 1630/17 etc may lock themselves up,
495 turning inresponsive due to internal corruption. This typically
496 gives an error in opening the PTP session. Apparently you can
497 do a "repair" with the firmware utility (Windows only) which
498 will often fix this problem and make the device responsive
499 again.
500
Linus Walleij9340aac2007-10-01 10:02:05 +0000501* Some devices that implement GetObjectPropList (0x9805) will
502 not return the entire object list if you request a list for object
503 0xffffffffu. (But they should.) So they may need the special
504 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.
505
506* Some (smaller) subset of devices cannot even get all the
507 properties for a single object in one go, these need the
508 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the
509 iriver devices seem to have this bug.
510
511* The Toshiba Gigabeat S (and probably its sibling the
512 Microsoft Zune and other Toshiba devices) will only display
513 album information tags for a song in case there is also
514 an abstract album (created with the album interface) with
515 the exact same name.
Linus Walleijd132d8e2007-04-03 23:24:54 +0000516
Linus Walleij265b9d62007-11-25 20:08:15 +0000517* The Zen Vision:M has an older firmware which is very corrupt,
518 it is incompatible with the Linux USB stack altogether. The
519 kernel dmesg will look something like this, and you have to
520 upgrade the firmware using Windows:
521 usb 4-5: new high speed USB device using ehci_hcd and address 5
522 usb 4-5: configuration #1 chosen from 1 choice
523 usb 4-5: can't set config #1, error -110
Linus Walleijd132d8e2007-04-03 23:24:54 +0000524
Linus Walleij103a78e2008-08-25 20:48:52 +0000525* The Sirus Stiletto does not seem to allow you to copy any files
526 off the device. This may be someone's idea of copy protection.
Linus Walleijb715ba62008-02-12 23:41:49 +0000527
Linus Walleij1b91ca62008-10-17 07:07:56 +0000528
Linus Walleijd132d8e2007-04-03 23:24:54 +0000529Lost symbols
530------------
531
532Shared libraries can be troublesome to users not experienced with
533them. The following is a condensed version of a generic question
534that has appeared on the libmtp mailing list from time to time.
535
536> PTP: Opening session
537> Queried Creative Zen Vision:M
538> gnomad2: relocation error: gnomad2: undefined symbol:
539> LIBMTP_Get_Storageinfo
540> (...)
541> Are these type of errors related to libmtp or something else?
542
543The problem is of a generic nature, and related to dynamic library
544loading. It is colloquially known as "dependency hell".
545(http://en.wikipedia.org/wiki/Dependency_hell)
546
547The gnomad2 application calls upon the dynamic linker in Linux to
548resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol
549(ELF symbol, or link point or whatever you want to call them, a
550symbol is a label on a memory address that the linker shall
551resolve from label to actual address.)
552For generic information on this subject see the INSTALL file and
553this Wikipedia page:
554
555http://en.wikipedia.org/wiki/Library_(computing)
556
557When Linux /lib/ld-linux.so.X is called to link the symbols compiled
558into gnomad2 (or any other executable using libmtp), it examines the
559ELF file for the libmtp.so.X file it finds first and cannot resolve
560the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a
561problem witj) from it, since it's probably not there. There are many
562possible causes of this symbol breakage:
563
5641) You installed precompiled libmtp and gnomad2 packages (RPMs, debs
565 whatever) that do not match up. Typical cause: your gnomad2 package was
566 built against a newer version of libmtp than what's installed on your
567 machine. Another typical cause: you installed a package you found on
568 the web, somewhere, the dependency resolution system did not protest
569 properly (as it should) or you forced it to install anyway, ignoring
570 some warnings.
571
5722) You compiled libmtp and/or gnomad2 from source, installing both or
573 either in /usr/local/lib and /usr/local/bin. This means at compile-time
574 gnomad2 finds the libmtp library in /usr/local/lib but at runtime, it
575 depends on the Linux system wide library loader (/lib/ld-linux.so.X) in
576 order to resolve the symbols. This loader will look into the file
577 /etc/ld.so.conf and/or the folder /etc/ld.so.conf.d in order to find
578 paths to libraries to be used for resolving the symbols. If you have
579 some older version of libmtp in e.g. /usr/lib (typically installed by a
580 package manager) it will take precedence over the new version you just
581 installed in /usr/local/lib and the newly compiled library in
582 /usr/local/lib will *not* be used, resulting in this error message.
583
5843) You really did install the very latest versions (as of writing libmtp
585 0.1.5 and gnomad2 2.8.11) from source and there really is no
586 pre-installed package of either on your machine. In that case I'm
587 totally lost, I have no idea what's causing this.
588
589Typical remedies:
590
5911) If you don't want to mess around with your system and risk these
592 situations, only use pre-packaged software that came with the
593 distribution or its official support channels. If it still breaks,
594 blame your distribution, they're not packaging correctly. Relying on
595 properly packaged software and not installing things yourself *is* the
596 Linux solution to the "dependency hell" problem.
597
5982) Read about dynamically linked library handling until the stuff I wrote
599 about in the previous list sounds like music to your ears, inspect
600 your /lib, /usr/lib, /usr/local/lib, /etc/ld.so.conf and the
601 /etc/ld.so.conf.d, remove all pre-packed versions using RPM, APT,
602 YaST or whatever your distribution uses, compile libmtp and gnomad2
603 (or whatever) from source only and you will be enlighted.
604
605I don't know if this helps you, it's the best answer we can give.
Linus Walleij387e37a2008-10-29 17:22:22 +0000606
607
608API is obscure - I want plain files!
609------------------------------------
610
611PTP/MTP devices does not actually contain "files", they contain
612objects. These objects have file names, but that is actually
613just a name tag on the object.
614
615Folders/directories aren't really such entities: they are just
616objects too, albeit objects that can act as parent to other
Linus Walleij8aba06d2008-12-28 08:26:57 +0000617objects. They are called "associations" and are created in atomic
Linus Walleij387e37a2008-10-29 17:22:22 +0000618fashion and even though there is an MTP command to get all the
Linus Walleij8aba06d2008-12-28 08:26:57 +0000619associations of a certain association, this command is optional
620so it is perfectly possible (and most common, actually) to create
621devices where the "folders" (which are actually associations) have
622no idea whatsoever of what files they are associated as parents to
Linus Walleij387e37a2008-10-29 17:22:22 +0000623(i.e. which files they contain). This is very easy for device
Linus Walleij8aba06d2008-12-28 08:26:57 +0000624manufacturers to implement, all the association (i.e. finding out
625which files are in a certain folder) has to be done by the MTP
626Initiator / host computer.
Linus Walleij387e37a2008-10-29 17:22:22 +0000627
628Moving a file to a new folder is for example very simple in a
629"real" file system. In PTP/MTP devices it is often not even possible,
630some devices *may* be able to do that. But actually the only
631reliable way of doing that is to upload the file to the host,
Linus Walleij8aba06d2008-12-28 08:26:57 +0000632download it with the new parent, then delete the old file.
Linus Walleij387e37a2008-10-29 17:22:22 +0000633We have played with the idea of implementing this time consuming
634function, perhaps we will.
635
Linus Walleij8aba06d2008-12-28 08:26:57 +0000636Then the issue that in PTP/MTP it is legal for two files to have
637exactly the same path as long as their object IDs differ. A
638folder/association can contain two files with the exact same name.
639(And on the Creative devices this even works, too, though most devices
640implicitly fail at this.) Perhaps one could add some custom hook for
641handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something
642similar, but it's really a bit kludgy.
643
Linus Walleij387e37a2008-10-29 17:22:22 +0000644Playlists and albums aren't really files, thinking about
645them as files like the hacks in libgphoto2 is really backwards. They are
646called associations and are more like a symbolic link that links in a
647star-shaped pattern to all the files that are part of the album/playlist.
648Some devices (Samsung) thought that was too complicated and have a
649different way of storing playlists in an UTF-16 encoded .spl-like file
650instead! This is why playlists/albums must have their own structs and
651functions.
652
Linus Walleij8aba06d2008-12-28 08:26:57 +0000653Plain file access also assumes to be able to write files of an
654undetermined size, which is simply not possible in a transactional
655file system like PTP/MTP. (See further below.)
656
Linus Walleij387e37a2008-10-29 17:22:22 +0000657
658I Want Streaming!
659-----------------
660
661Streaming reads is easy. Just connect the output file descriptor from
662LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)
663wherever you want.
664
665People have connected this to TCP sockets for streaming web servers
666etc, works like a charm. Some devices will even survive if the callback
667functions return non-zero and cancel the download. Some devices will
668lock up and even require a reset if you do that. Devices are poorly
669implemented so that's life. If you want to stream off a device, the
670best idea is always to stream the entire file and discard the stuff
671at the end you don't want. It will incur a delay if you e.g. want to
672skip between tracks, sadly.
673
674Then we get to the complicated things: streaming WRITES...
675
676There is a function:
677LIBMTP_Send_File_From_File_Descriptor() (and similar for tracks)
678which will write a file to a device from a file descriptor, which may
679be a socket or whatever.
680
681HOWEVER: this requires a piece of metadata with the .filesize properly
682set first.
683
684This is not because we think it is funny to require that, the protocol
685requires it. The reason is that PTP/MTP is a transactional file system
686and it wants to be able to deny file transfer if the file won't fit on
687the device, so the transaction never even starts, it's impossible to
688start a transaction without giving file length.
689
690People really want streaming so I tried a lot of hacks to see if they
691would work, such as setting file size to 0xffffffffU or something other
692unnaturally big and then aborting the file transfer when the stream ends.
693It doesn't work: either the device crashes or the file simply disappears
694since the device rolls back all failed transactions.
695
696So this is an inherent limitation of the PTP/MTP protocol.