Working with iPods

This chapter describes:


Note: For information about how to get configuration values from an iPod device, see Getting and setting external device options in the chapter External Devices, CD Changers and Streamed Media.

Installing MME components for external media players

If you want use an external media player, such as an iPod or a PlaysForSure-enabled device, you need to:

  1. Install the runtime files that support these devices. These installations may require special licenses.
  2. Use iofs-ipod or iofs-pfs, depending on the type of media player.

For more detailed instructions, see the QNX® Aviage Multimedia Suite Installation Note.

Connecting to and using iPods

This section describes how to connect to iPod devices, and how to use the MME to interface to and manage iPods, where the behavior of iPods requires an approach different from that used for other devices.

Required components

The table below lists the non-standard components you need to connect to and use iPod devices from a QNX system:

Component Serial USB Description
Licenses Yes Yes See Licenses below.
Authentication chip Recommended Yes See Authenticating iPods below.
deva-ctrl-ipod.so Depends on configuration Yes The iPod audio driver.
io-fs-media Yes Yes The media filesystem.
iofs-ipod.so Yes Yes The iPod driver.
iofs-ser-ipod.so Yes No The serial transport.
iofs-usb-ipod.so No Yes The USB transport.
iofs-i2c-ipod.so If using chip. Yes The i2c interface to the Apple authentication chip.

See also the MME Utilities Reference for detailed information about the relevant drivers and transports.

Licenses

Special licenses are required to access and use iPod devices. Please contact Apple to obtain the licenses needed for your environment.

Authenticating iPods

Two methods are available for authenticating iPod devices:

Apple authentication chip

An Apple authentication IC chip is required for USB transport connections, and is highly recommended for serial transport connections. An Apple authentication IC chip ensures:

The QNX iofs-i2c-ipod.so module allows the QNX iPod driver to access the authentication chip using a standard i2c driver. If you do not install the authentication chip as a standard i2c device, you must write a custom module that gives the QNX iPod driver access to the chip. For more information, see Link kit for iPod authentication below.

To instruct the iPod driver to use this authentication method, start iofs-ipod.so with the the acp option set to i2c and its options:

# io-fs-media -dipod,transport=usb,acp=i2c[:options]

Cross transport authentication

A cross transport authentication chip can be built into the cable connection iPods to your system. This authentication method is available for USB transport connections only; it authenticates iPods over the serial pins and tell the iPods to grant authenticated privileges to the USB transport.

As well as offering the same advantages as an authentication chip built in to your system, a cross transport authentication chip in a cable:

Please contact Apple for more information about licenses and specifications for a cross transport authentication chip.

To instruct the iPod driver to use this authentication method, start iofs-ipod.so with the the acp option set to cta:

# io-fs-media -dipod,transport=usb,acp=cta

Note: The following iPod devices support cross transport authentication, provided they have the latest firmware:
  • all iPod touches
  • all iPhones
  • all iPod nano 4G

Connecting to iPods

You can connect from a QNX system to any iPod device (including an iPhone) with an Apple 30-pin connector. You can connect to these devices through a QNX serial device (“2-wire” connection) or a QNX USB device (“1-wire” connection).

You can connect to newer iPods (Generation 5 and more recent) either through a serial connection or, with an Apple authentication chip, through a USB connection. Older iPods (Generation 4 and older) support only the serial connection.

Before designing your client application, you should contact:


Note: iPod nano 2G devices: use a high speed port for connections to these iPods; do not use a full speed port.

The iPod nano 2G refuses to connect if the upstream port reports full speed; this device can not complete a control transfer if the interrupt endpoint is polled before the status phase of the control transfer is complete.


Accessing iPods as USB devices

Some iPods support USB connections as mass storage devices; when accessed in this way they look like hard drives. Older iPods and iPod Shuffles can be accessed only as USB storage devices:

Apple devices that support digital audio

At time of this MME release, the following Apple devices supported digital audio:

Model Firmware*
iPod nano 1G 1.2.0
iPod nano 2G 1.1.2
iPod nano 3G 1.0
iPod 5G 1.2
iPod classic 1.0
iPod touch 1.1
iPhone 1.1

*Firmware listed is the minimum required.


Note: A very small number of iPods with outdated firmware may present themselves as supporting digital audio, when in fact they do not support it.

If an iPod falsely presents itself as supporting digital audio, the launcher has no way of telling that the presentation is false. It will launch the digital audio driver, not the driver for a USB storage device, and the MME will be unable to play media or do anything with the iPod.

You should therefore design your client application to detect this sort of situation and alert the user so he or she can intervene and mount the iPod as a USB mass storage device.


Connecting through a serial device

When you connect to iPod devices through a serial device, the connection uses an iPod-specific protocol.

The iPod-specific protocol is used regardless of the type of physical layer used for the connection. A serial device can be a serial port (such as a 16550), a USB-to-serial class driver, or any other interface that presents a serial device.

For this type of connection, you can manufacture a serial to USB iPod cable to easily connect iPods into any USB port on an existing system. This cable should have an iPod 30-pin connector at one end, a USB connector at the other end, and a USB to serial chip inside the cable.

The iPod driver iofs-ipod.so and the serial transport iofs-ser-ipod.so together support the serial protocol required to communicate with iPods.


Note:
  • Serial connections to iPods are sometimes referred to as “2-wire” connections.
  • When you connect to an iPod through a serial device you must route the audio to the appropriate location in the system.

Two-wire connections

Serial connections to iPods use two wires:

If you choose to bring the analog audio into io-audio and have the MME manage it, you need to:

If you do not bring the audio into io-audio, the MME can receive time position updates and track changes from the iPod through the control lines, but it cannot control volume, mute or other functionality on the iPod.

Hardware requirements for serial connections to iPods

When designing a system that will use a serial interface to iPod devices you must ensure that the hardware on your system:

Connecting through a USB device

When you connect to iPod devices on a USB bus, the connection uses an iPod-specific USB protocol.

To connect to iPod devices and communicate with them through a USB connection, you need:


Note:
  • USB connections to iPods are sometimes referred to as “1-wire” connections.
  • To support USB transport connections to iPods, you need the following patch: deva-ctrl-ipod.so sound driver for iPod digital audio devices (Patch ID 1154).
  • When you connect to an iPod through a USB device you must also launch a USB audio driver for the iPod.

One-wire connections

USB connections to iPods use one wire:

Starting the drivers

To use iPod devices, after you obtained the required licenses, cable and authentication chip, follow the instructions in the Installation Note provided with your QNX Aviage Multimedia Suite package, and install the following software components onto your system:

After you have installed the required components, to connect from a QNX system to an iPod device:

  1. Start io-usb, specifying the -c option and the driver.
  2. Start io-fs-media, specifying the device, the transport (serial or USB, as required) with either the path to the device or the device name, the authentication chip interface with the address, path and speed for the connection to the chip, other options as required. For example, to connect to an iPod on the default serial port and using the authentication chip, start io-fs-media as follows:
    # io-fs-media -dipod,transport=ser,acp=i2c
    	
  3. If your system is configured to use io-audio, start it. See Starting io-audio below.
  4. Physically connect an iPod device to your system.

Below is a sample startup:

# io-usb -c -duhci -dehci
# io-audio -dipod busno=0,devno=1,cap_name=ipod-0-1
# io-fs-media -dipod,transport=usb:devno=1:busno=0:sconfig:audio=/dev/snd/ipod-0-1,darates=+8000:11025:12000:16000:22050:24000,playback,acp=i2c

Note:
  • The io-usb may use the EHCI, OHCI or UHCI driver, as required.
  • The io-usb -c option is needed to instruct io-usb not to select the iPod configuration.
  • The io-fs-media iPod transport's sconfig option selects the USB configuration. You can omit it if you use a launcher that selects the USB configuration.

See the MME Utilities Reference for more information about the iPod driver options and default values, and io-usb in the Neutrino Utilities Reference for more information about io-usb.


Note: io-fs-media is single threaded, so you need to start a separate instance of the filesystem for each device to which you want to connect.

Starting io-audio

All USB connections and serial connections that route audio through the MME require io-audio. If you system configuration requires io-audio, you should start it before physically connecting an iPod device.

When you start io-audio, you need to specify:

For example:

# io-audio -dipod busno=0,devno=1,cap_name=ipod-0-1 &

For more information about io-audio and its options, see io-audio in the Neutrino Utilities Reference.

iPod one-wire: from connection to playback

The figure below shows the sequence of activities from the insertion of an iPod through a USB connection to playback:


Sequence of activities after iPod connection through USB transport.


Activities sequence after iPod connection through USB transport.

  1. The launcher (enum-usb) sees the iPod, then sends the device information, such as vendor ID and device ID, to enum-devices, which uses this information to determine the driver it must launch.
  2. enum-devices launches io-fs-media ipod and an io-audio instance.
  3. io-fs-media ipod places the iPod in the filesystem: /fs/ipod0.
  4. mcd notices the appearance of /fs/ipod0 in the filesystem, and notifies mme.
  5. mme writes iPod information in its database through qdb, and notifies the HMI that the iPod is present.
  6. The HMI explores the iPod, then asks mme for playback of some tracks on the iPod.
  7. mme tells io-media to start playback on the iPod.
  8. io-media tells the iPod to start playback, and routes the digital audio from the iPod to the speakers through a second io-audio instance.

Checking for optimal connections

To check it an iPod is using the optimal available connections, you can examine the capabilities field for the device in the mediastores table:


Note: The MME_MSCAP_*_NONOPTIMAL flags apply only to iPods that are capable of playback and control via USB connections as well as serial and analog connections. For early iPods models, which only support serial and analog connections, a 2-wire connection is “optimal”, as it is the only one possible.

For a full list of possible mediastore capabilities values, see MME_MSCAP_* in the MME API Library Reference.

Detecting iPods

When the MME detects an iPod, it updates the mediastores table just as it does with other types of mediastores. It sets the storage_type column in the mediastores table to the mediastore type, MME_STORAGETYPE_IPOD, and it updates the folders table with the root folder information for the iPod.

After receiving an MME_EVENT_MS_STATECHANGE event with mme_ms_state_t indicating a newly inserted mediastore, to check if the mediastore you are working with is an iPod, you can check this column in the mediastores table for the presence of an iPod. The SELECT statement below shows how to check for an iPod:

qdb_statement( db, "SELECT 1 FROM mediastores
                    WHERE msid = %lld AND storage_type = %d;",
                    event.data.msid, MME_STORAGETYPE_IPOD );

Removing iPods

When you have finished playing media from an iPod, you do not need to disconnect it from the MME. Just physically remove it from the system. Note, however, that when an iPod is removed from the system, the MME removes the iPod content from its database — it maintains an entry for the iPod in the mediastores table and an entry for the iPod root folder in the folders table, but the content of the iPod “disappears” from the system.

This MME behavior is specific to iPod devices and is implemented because it isn't possible to quickly determine if any changes were made to an iPod device between its removal from the MME system and its re-insertion: the MME needs to resynchronize the iPod to ensure the accuracy of its data.

Synchronizing iPods

The MME supports synchronization of media on iPod devices. The design of iPod devices imposes some constraints on how the MME performs synchronizations on iPods. If the default configurations for iPod synchronizations are used:

To improve the browsing of iPods, the MME updates the title field during the first synchronization pass. This behavior is unique to iPod synchronizations.

To synchronize an iPod, you should use the directed synchronization function mme_sync_directed(), specifying the path where you want to begin synchronization. For more information, see Directed synchronization in the chapter Synchronizing Media.

We don't recommend that you use the standard synchronization function mme_resync_mediastore() to perform a full, recursive synchronization of all media on an iPod device, due to the size of iPod databases, duplicate files on iPods, and the slow interface between the MME and these devices.

Configuring MME iPod synchronizations

You can configure:

For more information, see Configuring MME iPod synchronization in the MME Configuration Guide.

Playing media on iPods

An iPod manages its own:

These characteristics place some constraints on what the MME can do with these devices, and they determine client application behavior when working with these devices. Specifically, iPods require special consideration when working with track sessions, when resuming playback, and when using random and repeat modes.

For information about how to check mediastore and device capabilities, see Mediastore and device capabilities in the chapter Working with Mediastores.


Note: The MME supports concurrent playback and synchronization or exploration on an iPod device. That is, you can explore or synchronize the device's folders and files during playback. You can not, however, start more than one playback session at a time; attempting to initiate a second playback session will fail and return the event MME_PLAY_ERROR_MEDIABUSY.

Rules for playing media on iPods

To avoid unexpected behavior, follow the rules listed below when playing media on iPods. For more detailed information, see the relevant sections below.


Caution: Do not set autopause (mme_setautopause()) for control contexts with an iPod. Because iPods control their own playback, if you set autopause for a control context with an iPod:
  • playback from the iPod may produce unexpected behavior
  • metadata and other track information requested from the iPod may be invalid

Working with track sessions when using iPod devices

To play media on an iPod, call the same functions as for other devices:

However, because iPods manage their own track sessions, when you use the MME to play media on these devices, you in fact have two layers of track session:

These two layers of track sessions mean that, once the MME has started playback on an iPod, unlike devices that do not manage their own track sessions, the iPod continues playback on its own. When it reaches the end of a track, the iPod starts playback of the next entry in the iPod track session, and continues until it either comes to the end of its track session, or the client application tells it to stop by calling mme_stop().

This behavior means that if you place multiple file IDs (fids) from an iPod in an MME track session, playback will:

  1. Start at the fid on the iPod.
  2. Continue playback through every track in the iPod's track session before returning to the MME track session.
  3. Start at the next fid in the MME's track session.
  4. If this fid is on the iPod, continue from this fid through every trackin the iPod's track session, and so on.

For example, if an iPod folder has five files, and you create a track session for an iPod using a SELECT statement, such as SELECT fid FROM library WHERE folderid=x, that is appropriate for other devices, you would place all five tracks from the folder (A, B, C, D, E) in the MME track session. Assuming that the iPod repeat and random modes are off, this MME track session would, in fact, play 15 tracks on the iPod, as follows:

A, B, C, D, E
B, C, D, E
C, D, E
D, E
E

To prevent the situation described above and to avoid unintentional repetition of iPod track sessions, when using iPods, place only one fid from the iPod in the MME track session.

The tables below describe playback behavior of two MME track sessions. The first table shows an MME track session with multiple fids from an iPod (not recommended). The second table shows an MME track session with one fid per iPod (recommended). The sequentialid is from the trksessionview table; it is the fid for playback in sequential mode. Both examples assume that random and repeat modes are off.

Not recommended: more than 1 fid per iPod

Mediastore sequentialid nowplaying
fid
Behavior
HDD 12 12 1. Play fid 12.
2. Move to the next sequentialid entry in the trksessionview table.
iPod 1 16 0 1. Play fid 16 on iPod 1.
2. Play all other tracks after fid 16 in the iPod track session.
3. Move to the next sequentialid entry in the trksessionview table.
iPod 1 17 0 1. Play fid 17 on iPod 1.
2. Play all other tracks after fid 17 in the iPod track session.
3. Move to the next sequentialid entry in the trksessionview table.
USB 1 23 23 1. Play fid on USB 1.
2. Move to the next sequentialid entry in the trksessionview table.

Recommended: 1 fid per iPod

Mediastore sequentialid nowplaying
fid
Behavior
HDD 12 12 1. Play fid 12.
2. Move to the next sequentialid entry in the trksessionview table.
iPod 1 17 0 1. Play fid 17 on iPod 1.
2. Play all other tracks after fid 17 in the iPod track session.
3. Move to the next sequentialid entry in the trksessionview table.
iPod 2 96 0 1. Play fid 96 on iPod 2.
2. Play all other tracks after fid 96 in the iPod track session.
3. Move to the next sequentialid entry in the trksessionview table.
USB 1 23 23 1. Play fid on USB 1.
2. Move to the next sequentialid entry in the trksessionview table.

Note:
  • If you created your MME track session to play tracks exclusively from the iPod, it should have only one fid and you can start playback by calling mme_play() with the fid argument set to 0 (zero).
  • If your MME track session includes tracks from iPods and from other devices and mediastores (CDs, USB sticks, etc.):
    • If you want to play only the tracks on the iPod, you must call mme_play() with the fid argument set to the fid for the track in the iPod track session where you want to start playback.
    • If you want to play all tracks (from the iPod, and from other devices and mediastores) in the track session, you can call mme_play() with the fid argument set to 0 (zero) to start playback from the first track in the MME track session.

Getting track information when playing media on iPods

An iPod sends back to the MME metadata such as track title and artist, which the client application can display to the end-user. However, because iPods manage their own track sessions, the MME has no way of knowing information that the iPod doesn't report, such as the filename or the file ID of the currently playing track in the iPod track session. These constraints mean that if playback is on an iPod:

If you want to know if a track is playing on the iPod track session, you can:

Getting the time position when playing media on iPods

When playback is on an iPod, the MME reports the playback time position just as it does when playback is on other devices. Note, however, that iPods usually deliver events every 500 milliseconds. If the MME notification interval is less than 500 milliseconds (the default setting is 100 milliseconds), client applications that rely on delivery of time events from an iPod may see jitter in time-position reporting. For more detailed information, see mme_set_notification_interval() in the chapter MME API.

Moving through an iPod track session

To move to the next or previous track in an iPod track session, call the mme_button() function with the button argument set to MM_BUTTON_NEXT or MM_BUTTON_PREV, as required.

Manage trick play behavior and modes in the same manner as for other devices, with calls to functions such as mme_play_set_speed() to fast forward, reverse, pause, etc.


Note: MM_BUTTON_NEXT and MM_BUTTON_PREV are the only mme_button() settings supported by iPods.

Fast forward and reverse on iPods

Fast forward and reverse, and reporting of the current speed is implemented differently on iPods than on most other media devices:


Note: The damping_audio_writer filter has no effect on iPods because these devices control their own trick play behavior.

Resuming playback on iPods

The MME doesn't have access to detailed track session information on devices, such as iPods, that manage their own track sessions. This limitation means that when the MME creates a track session for media one of these devices, it simply:

If you want to stop, then resume playback of a track session on an iPod, you must:

  1. Do whatever action the user requests: pause playback, switch to another activity, note that the device has been disconnected from the system, etc. The device is responsible for saving the state of track session.
  2. Call mme_play_resume_msid() to resume playback of the track session. This function creates a new MME track session, and the device is responsible for resuming playback from the point where it was stopped.

    Note: Calling mme_play_resume_msid() when the iPod device itself is in a stopped state will not resume playback, because a stopped iPod has no active track session that can be resumed.


Stopping and resuming an iPod track session.


Stopping and resuming a device-controled track session.


Caution: A call to mme_play() stops playback after mme_play_resume_msid() has been called, because mme_play() finds no playable tracks in the MME track session.

The only exception to this behavior occurs when the user has browsed the iPod and requests playback of a specific folder's contents: Artist, Genre, etc. In this case, the client application should create a new MME track session with the fid requested by the user, and use mme_play() to start playback on that track session.

Using random and repeat modes on iPods

An iPod maintains its own random and repeat modes. The MME works with this characteristic and behaves as follows with iPod devices:

Remember that:


Note: With all versions (up to 1.1 as of this writing) of the iPhone and iPod touch, the following behavior has been observed:
  • A request to set the repeat mode to repeat single takes effect on the next track, not on the currently playing track.
  • When repeat single mode is set, it is not possible to turn repeat mode off: the MME repeat mode is turned off as expected, but the iPhone remains in repeat single mode.

To correct this behavior, remove the iPhone or iPod touch, then re-insert it into the system.


Seeking chapters on iPods

To seek to a chapter on an iPod, simply call mme_seek_title_chapter() as you would to seek to a chapter on a DVD-video. When the chapter changes, the MME will deliver the event MME_EVENT_MEDIA_STATUS.

Similarly, to get the number of titles and chapters in the current track, and the currently playing title and chapter numbers, use mme_get_title_chapter().

For more information, see Starting playback from a specific DVD title and chapter in the chapter Playing and Managing Video and DVDs.

Setting subtitles on iPods

To set subtitles on iPods and to get subtitle information from iPods, use the mme_video_get_subtitle_info() and mme_video_set_subtitle() functions like you would for other devices that support video.

For more information, see Managing video attributes in the chapter Playing and Managing Video and DVDs.

Video support

The MME supports playback of video on iPod devices, using analog video and audio output.

To play video on iPods, you need:

For more information about playing and managing video, see the chapter Playing and Managing Video and DVDs. For information about video layers, see the Advanced Graphics Developer's Guide, in particular the chapter Working with Layers, Surfaces, and Contexts, and the “Layers” API.


Note: The MME supports analog video with digital audio from iPods, but this support requires an asynchronous sample rate converter (ASRC) to maintain video and audio synchronization.

Displaying information from an iPod

The iofs-ipod presentation alters filesystem names of folders and files. Characters are substituted to allow for leading “.” (periods), embedded spaces and so on. In addition, iofs-ipod adds an index number, prefixed by a “~”.

The MME corrects these names when it places them in database columns, such as title that are not filesystem names, and when it builds pseudo-metadata for the library_genres, library_artists, and library_albums tables.

Further corrections to how information from an iPod is displayed must be handled by the client application. An iPod uses URL encoding in name strings, so a string such as “Folk/Rock” will display as “Folk%2FRock” to the end user, unless the client application decodes it.

Common URL encoding strings that need to be decoded from their hexadecimal values before displaying them to the end user are:

Retrieving artwork from iPods

Retrieval of artwork from an iPod is limited to the artwork for the currently playing iPod track only.

To retrieve the artwork for the currently playing iPod track, use the MME's Load-on-Demand metadata extraction API as you would to retrieve metadata from any other device. That is:

  1. Call mme_mme_metadata_create_session() to create a metadata session.
  2. Use the mme_metadata_getinfo_current() function to get the artwork information.
  3. Call mme_metadata_image_load() to load the artwork.

Note:
  • The MME supports iPod artwork in color only; it does not support grayscale iPod artwork.
  • iPod images are BMP files.
  • Due to a hardware limitation of 3G iPods, the MME does not support splash screen loading for these devices.

For more information about metadata sessions for the Load-on-Demand metadata extraction API, see Getting artwork in the chapter Metadata and Artwork.

Uploading splash screens to iPods

You can upload color or greyscale splash screen images to iPod devices when you start the iPod driver iofs-ipod.so. For more information, see Splash screens on the MME Utilities Reference page for iofs-ipod.so.

HD radio tagging

Client applications that support HD radio tagging for iPods can do so when running the MME. To implement radio tagging:


Note: HD radio tagging requires authentication.

Below is an example of code that can be used to write HD radio tags to an iPod. Your client application should be designed to manage writing to more than one iPod (/ipod0, /ipod1, etc.).

#include <sys/dcmd_media.h>

...

if((fd = open("/fs/ipod0/.FS_info./control, O_RDWR)) == -1) {
    printf("Failed to access ipod");
} else {
    rc = devctl(fd, DCMD_MEDIA_IPOD_TAG, plist_single, plist_single_len, &ret);
    if (rc == 0)
        printf("Items were written, only iTunes can confirm contents");
    else
        printf("Write of tag file to iPod failed err:%d (%s): ret:%d", rc, strerror(rc), ret);
}

Note:
  • plist_single is the pointer to the XML tag; see the Apple documentation.
  • The devctl() ret argument returns the number of bytes written to the iPod.

iPods that support HD radio tagging

At time of this MME release, the following iPod models supported HD radio tagging:

Model Firmware*
iPod nano 3G 1.0
iPod 5G 1.2.3
iPod classic 1.0

*Firmware listed is the minimum required.

Link kit for iPod authentication

This section describes the MME link kit for building a customized iPod ACP (Authetication CoProcess) module for use with Apple authentication chips.

About the iPod authentication link kit

The MME includes the iofs-i2c-ipod.so module that allows the QNX iPod driver to access the iPod authentication chip using a standard i2c driver. Due to the multitude of possible target board configurations, this module may require modification in order to give the QNX iPod driver access to the Apple authentication chip in your environment.

The MME link kit for iPod authentication is provided to assist you in developing any custom authentication coprocessor communication modules you require. It includes the source code for the sample iofs-i2c-ipod.so module, which you can use as an example and modify as needed.

The sample iPod ACP module

The iPod ACP module is a plugin to the iPod driver. It allows the higher-level driver to communicate with the Apple authentication chip without worrying about the hardware specifics of the board on which it is running.

The sample iPod ACP module provided is a generic i2c implementation, which can be modified and implemented with many, different custom transport mechanisms. It contains the complete framework required for iPod ACP modules. You only need to modify its hardware and transport sections to meet the specifications for the ACP you will use.


Note: Before compiling and using the sample iPod ACP module, you must:
  • have a board on which you can perform your tests
  • install the BSP package you will use (with hw/i2c.h and relevant drivers)

iPod ACP module functions

The sample functions provided with the authentication link kit are describe below.You can modify these functions to meet the needs of your environment, maintaining the specified behaviors and return values. For more detailed information about these functions, see the source file, acp_i2c.c.

Unless otherwise noted, on failure these functions return -1 and set errno.

ipod_i2c_addinfo()

The ipod_i2c_addinfo() is useful for debugging. It adds information, as instructed, to the debug/information XML file created when an iPod filesystem is mounted. This function adds any requested informatiom into the XML file's i2c section, or any other section of the file, as required.

ipod_i2c_cpready()

If the generic iPod driver needs to check the CP_READY signal, it can call the ipod_i2c_cpready() function.

This sample function returns the state of the CP_READY signal:

If this function is not implemented, it returns ENOSYS


Note: Checking for a CP_READY signal is not required for Apple 2.0 rev B authentication chips; new designs should use this chip or a newer chip.

ipod_i2c_init()

When io-fs-media with an iPod driver is started, the iPod ACP module's initialization function is called. This function should:

The initialization function, ipod_i2c_init(), provided with the sample module:

ipod_i2c_lock()

The ipod_i2c_lock() locks and unlocks access to an ACP chip so that multiple iPod drivers can run concurrently, sharing access to a single ACP chip. The generic iPod driver for i2c calls this function with a the lock parameter set to a value defined by acplock.

When ipod_i2c_lock() is called with its lock parameter set to ACP_UNLOCKED, it tells the ACP chip that it is not needed until further notice. This call can return ACP_PWROFF, which tells the generic ACP code to power down the ACP chip by writing the appropriate commands to the chip's registers. When the generic code finishes telling the ACP chip to power down, it calls ipod_i2c_lock() again, this time passing it ACP_PWROFF to indicate that the chip power down processing has completed.

acplock

The enumerated value acplock defines the lock settings used by the ACP module. These settings are:


Two iPods sharing an authenitication chip.


Two iPods sharing an authenitication chip.

ipod_i2c_read() and ipod_i2c_write()

The ipod_i2c_read() and ipod_i2c_write() functions read and write data from and to an Apple authentication chip. They return the number of bytes read or written.

The parameters for these functions include:

Using the iPod ACP module

After you have added all your device-specific code to your custom iPod ACP module, you can build it, then use io-fs-media to load it.

Building the module

You can build the iPod ACP module as follows:

  1. Copy the sample modules to your home directory:
    # cp -R $QNX_TARGET/examples ~/examples
  2. In your home directory, make and install the module:
    # cd ~/examples/io-fs/drvr/media/ipod/acp/i2c
    # make install

To build all sample modules, you can make them from the ~/examples/io-fs directory, as follows:

# cd ~/examples/io-fs
# make install

Starting the module

You can use io-fs-media and the iPod driver to load your module. For example:

# io-fs-media -dipod,transport=usb,acp=modulename

You can also pass options to the module, as follows:

# io-fs-media -dipod,transport=usb,acp=acp_modulename:path=/sample/path:option2=someoption

For a list of options available with the ACP sample module, see iofs-i2c-ipod.so.