Chapter 2 - USBX Device Class Considerations

USB Device Classes :

USB Device RNDIS Class
USB Device DFU Class
USB Device PIMA Class
USB Device AUDIO Class
USB Device PRINTER Class

usb_device_rndis_class

The USB device RNDIS class allows for a USB host system to communicate with the device as a ethernet device. This class is based on the Microsoft implementation and is specific to Windows platforms.

RNDIS Class Initialize
RNDIS Class Configuration Options

rndis_class_initialize

A RNDIS compliant device framework needs to be declared by the device stack. An example is found below.

unsigned char device_framework_full_speed[] = {
    /* VID: 0x04b4
    PID: 0x1127
    */

    /* Device Descriptor */
    0x12, /* bLength */
    0x01, /* bDescriptorType */
    0x10, 0x01, /* bcdUSB */
    0x02, /* bDeviceClass - CDC */
    0x00, /* bDeviceSubClass */
    0x00, /* bDeviceProtocol */
    0x40, /* bMaxPacketSize0 */
    0xb4, 0x04, /* idVendor */
    0x27, 0x11, /* idProduct */
    0x00, 0x01, /* bcdDevice */
    0x01, /* iManufacturer */
    0x02, /* iProduct */
    0x03, /* iSerialNumber */
    0x01, /* bNumConfigurations */

    /* Configuration Descriptor */
    0x09, /* bLength */
    0x02, /* bDescriptorType */
    0x38, 0x00, /* wTotalLength */
    0x02, /* bNumInterfaces */
    0x01, /* bConfigurationValue */
    0x00, /* iConfiguration */
    0x40, /* bmAttributes - Self-powered */
    0x00, /* bMaxPower */

    /* Interface Association Descriptor */
    0x08, /* bLength */
    0x0b, /* bDescriptorType */
    0x00, /* bFirstInterface */
    0x02, /* bInterfaceCount */
    0x02, /* bFunctionClass - CDC - Communication */
    0xff, /* bFunctionSubClass - Vendor Defined – In this case, RNDIS */
    0x00, /* bFunctionProtocol - No class specific protocol required */
    0x00, /* iFunction */

    /* Interface Descriptor */
    0x09, /* bLength */
    0x04, /* bDescriptorType */
    0x00, /* bInterfaceNumber */
    0x00, /* bAlternateSetting */
    0x01, /* bNumEndpoints */
    0x02, /* bInterfaceClass - CDC - Communication */
    0xff, /* bInterfaceSubClass - Vendor Defined – In this case, RNDIS */
    0x00, /* bInterfaceProtocol - No class specific protocol required */
    0x00, /* iInterface */

    /* Endpoint Descriptor */
    0x07, /* bLength */
    0x05, /* bDescriptorType */
    0x83, /* bEndpointAddress */
    0x03, /* bmAttributes - Interrupt */
    0x08, 0x00, /* wMaxPacketSize */
    0xff, /* bInterval */

    /* Interface Descriptor */
    0x09, /* bLength */
    0x04, /* bDescriptorType */
    0x01, /* bInterfaceNumber */
    0x00, /* bAlternateSetting */
    0x02, /* bNumEndpoints */
    0x0a, /* bInterfaceClass - CDC - Data */
    0x00, /* bInterfaceSubClass - Should be 0x00 */
    0x00, /* bInterfaceProtocol - No class specific protocol required */
    0x00, /* iInterface */

    /* Endpoint Descriptor */
    0x07, /* bLength */
    0x05, /* bDescriptorType */
    0x02, /* bEndpointAddress */
    0x02, /* bmAttributes - Bulk */
    0x40, 0x00, /* wMaxPacketSize */
    0x00, /* bInterval */

    /* Endpoint Descriptor */
    0x07, /* bLength */
    0x05, /* bDescriptorType */
    0x81, /* bEndpointAddress */
    0x02, /* bmAttributes - Bulk */
    0x40, 0x00, /* wMaxPacketSize */
    0x00, /* bInterval */
};

The RNDIS class uses a very similar device descriptor approach to the CDC-ACM and CDC-ECM and also requires a IAD descriptor. See the CDC-ACM class for definition and requirements for the device descriptor.

The activation of the RNDIS class is as follows.

UX_SLAVE_CLASS_RNDIS_PARAMETER       rndis_parameter;

/* Set the parameters for callback when insertion/extraction of a CDC device. */
rndis_parameter.ux_slave_class_rndis_instance_activate   =  demo_rndis_instance_activate;
rndis_parameter.ux_slave_class_rndis_instance_deactivate =  demo_rndis_instance_deactivate;
    
/* Define a local NODE ID.  */
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[0] = 0x00;
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[1] = 0x1e;
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[2] = 0x58;
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[3] = 0x41;
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[4] = 0xb8;
rndis_parameter.ux_slave_class_rndis_parameter_local_node_id[5] = 0x78;

/* Define a remote NODE ID.  */
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[0] = 0x00;
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[1] = 0x1e;
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[2] = 0x58;
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[3] = 0x41;
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[4] = 0xb8;
rndis_parameter.ux_slave_class_rndis_parameter_remote_node_id[5] = 0x79;

/* Set extra parameters used by the RNDIS query command with certain OIDs.  */
rndis_parameter.ux_slave_class_rndis_parameter_vendor_id          =  0x04b4 ;
rndis_parameter.ux_slave_class_rndis_parameter_driver_version     =  0x1127;
ux_utility_memory_copy(rndis_parameter.ux_slave_class_rndis_parameter_vendor_description, "ELOGIC RNDIS", 12);

/* Initialize the device rndis class. This class owns both interfaces. */
status = ux_device_stack_class_register(_ux_system_slave_class_rndis_name, ux_device_class_rndis_entry, 1,0, &parameter);

As for the CDC-ECM, the RNDIS class requires 2 nodes, one local and one remote but there is no requirement to have a string descriptor describing the remote node.

However due to the Microsoft messaging mechanism, some extra parameters are required. First the vendor ID has to be passed. Likewise, the driver version of the RNDIS. A vendor string must also be given.

The RNDIS class has built-in APIs for transferring data both ways but they are hidden to the application as the user application will communicate with the USB Ethernet device through NetX Duo.

The USBX RNDIS class is closely tied to the NetX Duo Network stack. An application using both NetX Duo and USBX RNDIS class will activate the NetX Duo network stack in its usual way but in addition needs to activate the USB network stack as follows.

/* Initialize the NetX Duo system. */

nx_system_initialize();

/* Perform the initialization of the network driver. This will initialize the USBX network layer.*/
ux_network_driver_init();

The USB network stack needs to be activated only once and is not specific to RNDIS but is required by any USB class that requires NetX services.

The RNDIS class will not be recognized by MAC OS and Linux hosts as it is specific to Microsoft operating systems. On Windows platforms a .inf file needs to be present on the host that matches the device descriptor. Microsoft supplies a template for the RNDIS class and it can be found in the usbx_windows_host_files directory. For more recent version of Windows the file RNDIS_Template.inf should be used. This file needs to be modified to reflect the PID/VID used by the device. The PID/VID will be specific to the final customer when the company and the product are registered with the USB-IF. In the inf file, the fields to modify are located here.

[DeviceList]
%DeviceName%=DriverInstall, USB\\VID_xxxx&PID_yyyy&MI_00

[DeviceList.NTamd64]
%DeviceName%=DriverInstall, USB\\VID_xxxx&PID_yyyy&MI_00

In the device framework of the RNDIS device, the PID/VID are stored in the device descriptor (see the device descriptor declared above)

When a USB host systems discovers the USB RNDIS device, it will mount a network interface and the device can be used with network protocol stack. See the host Operating System for reference.

rndis_class_configuration_options

There are several configuration options for building USB Device RNDIS Class. All options are located in the ux_user.h.

Configuration Option	Description
UX_DEVICE_CLASS_RNDIS_ZERO_COPY	This macro enables device RNDIS zero copy support (works if RNDIS owns endpoint buffer). Enabled, it requires that the NX IP default packet pool is in cache safe area, and buffer max size is larger than UX_DEVICE_CLASS_RNDIS_MAX_PACKET_TRANSFER_SIZE (1600).

usb_device_dfu_class

The USB device DFU class allows for a USB host system to update the device firmware based on a host application. The DFU class is a USB-IF standard class.

USBX DFU class is relatively simple. It device descriptor does not require anything but a control endpoint. Most of the time, this class will be embedded into a USB composite device. The device can be anything such as a storage device or a comm device and the added DFU interface can inform the host that the device can have its firmware updated on the fly.

The DFU class works in 3 steps. First the device mounts as normal using the class exported. An application on the host (Windows or Linux) will exercise the DFU class and send a request to reset the device into DFU mode. The device will disappear from the bus for a short time (enough for the host and the device to detect a RESET sequence) and upon restarting, the device will be exclusively in DFU mode, waiting for the host application to send a firmware upgrade. When the firmware upgrade has been completed, the host application resets the device and upon re-enumeration the device will revert to its normal operation with the new firmware.

DFU Class Initialize
DFU Class Configuration Options

dfu_class_initialize

A DFU device framework will look like this.

UCHAR device_framework_full_speed[] = {

    /* Device descriptor */
    0x12, 0x01, 0x10, 0x01, 0x00, 0x00, 0x00, 0x40,
    0x99, 0x99, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02,
    0x03, 0x01,

    /* Configuration descriptor */
    0x09, 0x02, 0x1b, 0x00, 0x01, 0x01, 0x00, 0xc0,
    0x32,

    /* Interface descriptor for DFU. */
    0x09, 0x04, 0x00, 0x00, 0x00, 0xFE, 0x01, 0x01, 0x00,

    /* Functional descriptor for DFU. */
    0x09, 0x21, 0x0f, 0xE8, 0x03, 0x40, 0x00, 0x00,
    0x01,

};

In this example, the DFU descriptor is not associated with any other classes. It has a simple interface descriptor and no other endpoints attached to it. There is a Functional descriptor that describes the specifics of the DFU capabilities of the device.

The description of the DFU capabilities are as follows.

Name	Offset	Size	type	Description
bmAttributes	2	1	Bit field	Bit 3: device will perform a bus detach-attach sequence when it receives a DFU_DETACH request. The host must not issue a USB Reset. (bitWillDetach) 0 = no 1 = yes Bit 2: device is able to communicate via USB after Manifestation phase. (bitManifestationTolerant) 0 = no, must see bus reset 1 = yes Bit 1: upload capable (bitCanUpload) 0 = no 1 = yes Bit 0: download capable (bitCanDnload) 0 = no 1 = yes
wDetachTimeOut	3	2	number	Time, in milliseconds, that the device will wait after receipt of the DFU_DETACH request. If this time elapses without a USB reset, then the device will terminate the Reconfiguration phase and revert back to normal operation. This represents the maximum time that the device can wait (depending on its timers, etc.). USBX sets this value to 1000 ms.
wTransferSize	5	2	number	Maximum number of bytes that the device can accept per control-write operation. USBX sets this value to 64 bytes.

The declaration of the DFU class is as follows:

UX_SLAVE_CLASS_DFU_PARAMETER        dfu_parameter;

/* Store the DFU parameters.   */
dfu_parameter.ux_slave_class_dfu_parameter_instance_activate               =  demo_dfu_activate;
dfu_parameter.ux_slave_class_dfu_parameter_instance_deactivate             =  demo_dfu_deactivate;
dfu_parameter.ux_slave_class_dfu_parameter_read                            =  demo_dfu_read;
dfu_parameter.ux_slave_class_dfu_parameter_write                           =  demo_dfu_write; 
dfu_parameter.ux_slave_class_dfu_parameter_get_status                      =  demo_dfu_get_status;
dfu_parameter.ux_slave_class_dfu_parameter_notify                          =  demo_dfu_notify;
#ifdef UX_DEVICE_CLASS_DFU_CUSTOM_REQUEST_ENABLE
dfu_parameter.ux_device_class_dfu_parameter_custom_request                 =  demo_dfu_custom_request;
#endif
dfu_parameter.ux_slave_class_dfu_parameter_framework                       =  device_framework_dfu;
dfu_parameter.ux_slave_class_dfu_parameter_framework_length                =  DEVICE_FRAMEWORK_LENGTH_DFU;

/* Initialize the device dfu class. The class is connected with interface 1 on configuration 1. */
status = ux_device_stack_class_register(_ux_system_slave_class_dfu_name, ux_device_class_dfu_entry, 1, 0, (VOID *)&dfu_parameter);

if (status != UX_SUCCESS) 
    return;

The DFU class needs to work with a device firmware application specific to the target. Therefore it defines several call back to read and write blocks of firmware and to get status from the firmware update application. The DFU class also has a notify callback function to inform the application when a begin and end of transfer of the firmware occur.

Following is the description of a typical DFU application flow.

DFU application flow

The major challenge of the DFU class is getting the right application on the host to perform the download the firmware. There is no application supplied by Microsoft or the USB-IF. Some shareware exist and they work reasonably well on Linux and to a lesser extent on Windows.

On Linux, one can use dfu-utils to be found here: https://wiki.openmoko.org/wiki/Dfu-util A lot of information on dfu utils can also be found on this link: https://github.com/libusb/libusb/wiki

The Linux implementation of DFU performs correctly the reset sequence between the host and the device and therefore the device does not need to do it. Linux can accept for the bmAttributes bitWillDetach to be 0. Windows on the other side requires the device to perform the reset.

On Windows, the USB registry must be able to associate the USB device with its PID/VID and the USB library which will in turn be used by the DFU application. This can be easily done with the free utility Zadig which can be found here: https://sourceforge.net/projects/libwdi/files/zadig/.

Running Zadig for the first time will show this screen:

Running Zadig for the first time

From the device list, find your device and associate it with the libusb windows driver. This will bind the PID/VID of the device with the Windows USB library used by the DFU utilities.

To operate the DFU command, simply unpack the zipped dfu utilities into a directory, making sure the libusb dll is also present in the same directory. The DFU utilities must be run from a DOS box at the command line.

First, type the command dfu-util –l to determine whether the device is listed. If not, run Zadig to make sure the device is listed and associated with the USB library. You should see a screen as follows:

C:\usb specs\DFU\dfu-util-0.6&gt;dfu-util -l dfu-util 0.6

Copyright 2005-2008 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2012 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Found Runtime: [0a5c:21bc] devnum=0, cfg=1, intf=3, alt=0, name="UNDEFINED"

The next step will be to prepare the file to be downloaded. The USBX DFU class does not perform any verification on this file and is agnostic of its internal format. This firmware file is very specific to the target but not to DFU nor to USBX.

Then the dfu-util can be instructed to send the file by typing the following command:

dfu-util –R –t 64 -D file_to_download.hex

The dfu-util should display the file download process until the firmware has been completely downloaded.

dfu_class_configuration_options

There are several configuration options for building USB Device DFU Class. All options are located in the ux_user.h.

Configuration Option	Description
UX_DEVICE_CLASS_DFU_UPLOAD_DISABLE	This macro will disable DFU_UPLOAD support.
UX_DEVICE_CLASS_DFU_ERROR_GET_ENABLE	This macro will enable DFU_GETSTATUS and DFU_GETSTATE in dfuERROR.
UX_DEVICE_CLASS_DFU_STATUS_MODE	This macro will change status mode. 0 - simple mode, status is queried from application in dfuDNLOAD-SYNC and dfuMANIFEST-SYNC state, no bwPollTimeout. 1 - status is queried from application once requested, b0-3 : media status, b4-7 : bStatus, b8-31: bwPollTimeout, bwPollTimeout supported
UX_DEVICE_CLASS_DFU_STATUS_POLLTIMEOUT	This value represents the default DFU status bwPollTimeout. The value is 3 bytes long (max 0xFFFFFFu). By default the bwPollTimeout is 1 (means 1ms).
UX_DEVICE_CLASS_DFU_CUSTOM_REQUEST_ENABLE	This macro will enable custom request process callback.

usb_device_pima_class

The USB device PIMA class allows for a USB host system (Initiator) to connect to a

PIMA Class Initialize
PIMA Class Configuration Options
PIMA Class APIs

PIMA device (Responder) to transfer media files. USBX Pima Class is conforming to the USB-IF PIMA 15740 class also known as PTP class (for Picture Transfer Protocol).

pima_class_initialize

USBX device side PIMA class supports the following operations.

Operation code	Value	Description
UX_DEVICE_CLASS_PIMA_OC_GET_DEVICE_INFO	0x1001	Obtain the device supported operations and events
UX_DEVICE_CLASS_PIMA_OC_OPEN_SESSION	0x1002	Open a session between the host and the device
UX_DEVICE_CLASS_PIMA_OC_CLOSE_SESSION	0x1003	Close a session between the host and the device
UX_DEVICE_CLASS_PIMA_OC_GET_STORAGE_IDS	0x1004	Returns the storage ID for the device. USBX PIMA uses one storage ID only
UX_DEVICE_CLASS_PIMA_OC_GET_STORAGE_INFO	0x1005	Return information about the storage object such as max capacity and free space
UX_DEVICE_CLASS_PIMA_OC_GET_NUM_OBJECTS	0x1006	Return the number of objects contained in the storage device
UX_DEVICE_CLASS_PIMA_OC_GET_OBJECT_HANDLES	0x1007	Return an array of handles of the objects on the storage device
UX_DEVICE_CLASS_PIMA_OC_GET_OBJECT_INFO	0x1008	Return information about an object such as the name of the object, its creation date, modification date
UX_DEVICE_CLASS_PIMA_OC_GET_OBJECT	0x1009	Return the data pertaining to a specific object
UX_DEVICE_CLASS_PIMA_OC_GET_THUMB	0x100A	Send the thumbnail if available about an object
UX_DEVICE_CLASS_PIMA_OC_DELETE_OBJECT	0x100B	Delete an object on the media
UX_DEVICE_CLASS_PIMA_OC_SEND_OBJECT_INFO	0x100C	Send to the device information about an object for its creation on the media
UX_DEVICE_CLASS_PIMA_OC_SEND_OBJECT	0x100D	Send data for an object to the device
UX_DEVICE_CLASS_PIMA_OC_FORMAT_STORE	0x100F	Clean the device media
UX_DEVICE_CLASS_PIMA_OC_RESET_DEVICE	0x0110	Reset the target device

Operation Code	Value	Description
UX_DEVICE_CLASS_PIMA_EC_CANCEL_TRANSACTION	0x4001	Cancels the current transaction
UX_DEVICE_CLASS_PIMA_EC_OBJECT_ADDED	0x4002	An object has been added to the device media and can be retrieved by the host.
UX_DEVICE_CLASS_PIMA_EC_OBJECT_REMOVED	0x4003	An object has been deleted from the device media
UX_DEVICE_CLASS_PIMA_EC_STORE_ADDED	0x4004	A media has been added to the device
UX_DEVICE_CLASS_PIMA_EC_STORE_REMOVED	0x4005	A media has been deleted from the device
UX_DEVICE_CLASS_PIMA_EC_DEVICE_PROP_CHANGED	0x4006	Device properties have changed
UX_DEVICE_CLASS_PIMA_EC_OBJECT_INFO_CHANGED	0x4007	An object information has changed
UX_DEVICE_CLASS_PIMA_EC_DEVICE_INFO_CHANGE	0x4008	A device has changed
UX_DEVICE_CLASS_PIMA_EC_REQUEST_OBJECT_TRANSFER	0x4009	The device requests the transfer of an object from the host
UX_DEVICE_CLASS_PIMA_EC_STORE_FULL	0x400A	Device reports the media is full
UX_DEVICE_CLASS_PIMA_EC_DEVICE_RESET	0x400B	Device reports it was reset
UX_DEVICE_CLASS_PIMA_EC_STORAGE_INFO_CHANGED	0x400C	Storage information has changed on the device
UX_DEVICE_CLASS_PIMA_EC_CAPTURE_COMPLETE	0x400D	Capture is completed

The USBX PIMA device class uses a TX Thread to listen to PIMA commands from the host.

A PIMA command is composed of a command block, a data block and a status phase.

The function ux_device_class_pima_thread posts a request to the stack to receive a PIMA command from the host side. The PIMA command is decoded and verified for content. If the command block is valid, it branches to the appropriate command handler.

Most PIMA commands can only be executed when a session has been opened by the host. The only exception is the command UX_DEVICE_CLASS_PIMA_OC_GET_DEVICE_INFO. With USBX PIMA implementation, only one session can be opened between an Initiator and Responder at any time. All transactions within the single session are blocking and no new transaction can begin before the previous one completed.

PIMA transactions are composed of 3 phases, a command phase, an optional data phase and a response phase. If a data phase is present, it can only be in one direction.

The Initiator always determines the flow of the PIMA operations but the Responder can initiate events back to the Initiator to inform status changes that happened during a session.

The following diagram shows the transfer of a data object between the host and the PIMA device class.

PIMA transactions

Initialization of the PIMA device class

The PIMA device class needs some parameters supplied by the application during the initialization.

The following parameters describe the device and storage information.

ux_device_class_pima_manufacturer
ux_device_class_pima_model
ux_device_class_pima_device_version
ux_device_class_pima_serial_number
ux_device_class_pima_storage_id
ux_device_class_pima_storage_type
ux_device_class_pima_storage_file_system_type
ux_device_class_pima_storage_access_capability
ux_device_class_pima_storage_max_capacity_low
ux_device_class_pima_storage_max_capacity_high
ux_device_class_pima_storage_free_space_low
ux_device_class_pima_storage_free_space_high
ux_device_class_pima_storage_free_space_image
ux_device_class_pima_storage_description
ux_device_class_pima_storage_volume_label

The PIMA class also requires the registration of callback into the application to inform the application of certain events or retrieve/store data from/to the local media. The callbacks are as follows.

ux_device_class_pima_object_number_get
ux_device_class_pima_object_handles_get
ux_device_class_pima_object_info_get
ux_device_class_pima_object_data_get
ux_device_class_pima_object_info_send
ux_device_class_pima_object_data_send
ux_device_class_pima_object_delete

The following example shows how to initialize the client side of PIMA. This example uses Pictbridge as a client for PIMA.

/* Initialize the first XML object valid in the pictbridge instance.

Initialize the handle, type and file name.

The storage handle and the object handle have a fixed value of 1 in our implementation. */

object_info = pictbridge -> ux_pictbridge_object_client;

object_info -> ux_device_class_pima_object_format = UX_DEVICE_CLASS_PIMA_OFC_SCRIPT;
object_info -> ux_device_class_pima_object_storage_id = 1;
object_info -> ux_device_class_pima_object_handle_id = 2;

ux_utility_string_to_unicode(_ux_pictbridge_ddiscovery_name, object_info -> ux_device_class_pima_object_filename);

/* Initialize the head and tail of the notification round robin buffers.
   At first, the head and tail are pointing to the beginning of the array.
*/

pictbridge -> ux_pictbridge_event_array_head = pictbridge -> ux_pictbridge_event_array;
pictbridge -> ux_pictbridge_event_array_tail = pictbridge -> ux_pictbridge_event_array;
pictbridge -> ux_pictbridge_event_array_end = pictbridge -> ux_pictbridge_event_array + UX_PICTBRIDGE_MAX_EVENT_NUMBER;

/* Initialize the pima device parameter. */
pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_manufacturer =
    pictbridge -> ux_pictbridge_dpslocal.ux_pictbridge_devinfo_vendor_name;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_model =
    pictbridge -> ux_pictbridge_dpslocal.ux_pictbridge_devinfo_product_name;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_serial_number =
    pictbridge -> ux_pictbridge_dpslocal.ux_pictbridge_devinfo_serial_no;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_id = 1;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_type =
    UX_DEVICE_CLASS_PIMA_STC_FIXED_RAM;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_file_system_type =
    UX_DEVICE_CLASS_PIMA_FSTC_GENERIC_FLAT;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_access_capability =
    UX_DEVICE_CLASS_PIMA_AC_READ_WRITE;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_max_capacity_low =
    pictbridge -> ux_pictbridge_dpslocal.ux_pictbridge_devinfo_storage_size;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_max_capacity_high = 0;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_free_space_low =
    pictbridge -> ux_pictbridge_dpslocal.ux_pictbridge_devinfo_storage_size;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_free_space_high = 0;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_free_space_image = 0;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_description =
    _ux_pictbridge_volume_description;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_storage_volume_label =
    _ux_pictbridge_volume_label;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_number_get =
    ux_pictbridge_dpsclient_object_number_get;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_handles_get =
    ux_pictbridge_dpsclient_object_handles_get;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_info_get =
    ux_pictbridge_dpsclient_object_info_get;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_data_get =
    ux_pictbridge_dpsclient_object_data_get;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_info_send =
    ux_pictbridge_dpsclient_object_info_send;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_data_send =
    ux_pictbridge_dpsclient_object_data_send;

pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_object_delete =
    ux_pictbridge_dpsclient_object_delete;

/* Store the instance owner. */
pictbridge -> ux_pictbridge_pima_parameter.ux_device_class_pima_parameter_application =
    (VOID *) pictbridge;

/* Initialize the device pima class. The class is connected with interface 0 */

status = ux_device_stack_class_register(_ux_system_slave_class_pima_name, ux_device_class_pima_entry, 1, 0, (VOID *)&pictbridge -> ux_pictbridge_pima_parameter);

/* Check status. */
if (status != UX_SUCCESS)
{
    return;
}

The following example shows how to initialize the client side of PIMA. This example uses PIMA.

UX_SLAVE_CLASS_PIMA_PARAMETER       pima_device_parameter;

/* Set the parameters for PIMA device.  */
pima_device_parameter.ux_device_class_pima_instance_activate   =  test_pima_instance_activate;
pima_device_parameter.ux_device_class_pima_instance_deactivate =  test_pima_instance_deactivate;

/* Initialize the pima device parameter.  */
pima_device_parameter.ux_device_class_pima_parameter_manufacturer                  = pima_device_info_vendor_name;
pima_device_parameter.ux_device_class_pima_parameter_model                         = pima_device_info_product_name;
pima_device_parameter.ux_device_class_pima_parameter_device_version                = pima_device_info_version;
pima_device_parameter.ux_device_class_pima_parameter_serial_number                 = pima_device_info_serial_no;
pima_device_parameter.ux_device_class_pima_parameter_storage_id                    = UX_TEST_PIMA_STORAGE_ID;
pima_device_parameter.ux_device_class_pima_parameter_storage_type                  = UX_DEVICE_CLASS_PIMA_STC_FIXED_RAM;
pima_device_parameter.ux_device_class_pima_parameter_storage_file_system_type      = UX_DEVICE_CLASS_PIMA_FSTC_GENERIC_FLAT;
pima_device_parameter.ux_device_class_pima_parameter_storage_access_capability     = UX_DEVICE_CLASS_PIMA_AC_READ_WRITE;
pima_device_parameter.ux_device_class_pima_parameter_storage_max_capacity_low      = ram_disk.fx_media_total_clusters * ram_disk.fx_media_sectors_per_cluster * ram_disk.fx_media_bytes_per_sector;
pima_device_parameter.ux_device_class_pima_parameter_storage_max_capacity_high     = 0;
pima_device_parameter.ux_device_class_pima_parameter_storage_free_space_low        = ram_disk.fx_media_available_clusters * ram_disk.fx_media_sectors_per_cluster * ram_disk.fx_media_bytes_per_sector;
pima_device_parameter.ux_device_class_pima_parameter_storage_free_space_high       = 0;
pima_device_parameter.ux_device_class_pima_parameter_storage_free_space_image      = 0xFFFFFFFF;
pima_device_parameter.ux_device_class_pima_parameter_storage_description           = pima_parameter_volume_description;
pima_device_parameter.ux_device_class_pima_parameter_storage_volume_label          = pima_parameter_volume_label;
pima_device_parameter.ux_device_class_pima_parameter_device_properties_list        = pima_device_prop_supported;
pima_device_parameter.ux_device_class_pima_parameter_supported_capture_formats_list= pima_device_supported_capture_formats;
pima_device_parameter.ux_device_class_pima_parameter_supported_image_formats_list  = pima_device_supported_image_formats;
pima_device_parameter.ux_device_class_pima_parameter_object_properties_list        = pima_device_object_prop_supported;

/* Define the callbacks.  */
pima_device_parameter.ux_device_class_pima_parameter_device_reset                  = pima_device_device_reset;
pima_device_parameter.ux_device_class_pima_parameter_device_prop_desc_get          = pima_device_device_prop_desc_get;
pima_device_parameter.ux_device_class_pima_parameter_device_prop_value_get         = pima_device_device_prop_value_get;
pima_device_parameter.ux_device_class_pima_parameter_device_prop_value_set         = pima_device_device_prop_value_set;
pima_device_parameter.ux_device_class_pima_parameter_storage_format                = pima_device_storage_format;
pima_device_parameter.ux_device_class_pima_parameter_storage_info_get              = pima_device_storage_info_get;
pima_device_parameter.ux_device_class_pima_parameter_object_number_get             = pima_device_object_number_get;
pima_device_parameter.ux_device_class_pima_parameter_object_handles_get            = pima_device_object_handles_get;
pima_device_parameter.ux_device_class_pima_parameter_object_info_get               = pima_device_object_info_get;
pima_device_parameter.ux_device_class_pima_parameter_object_data_get               = pima_device_object_data_get;
pima_device_parameter.ux_device_class_pima_parameter_object_info_send              = pima_device_object_info_send;
pima_device_parameter.ux_device_class_pima_parameter_object_data_send              = pima_device_object_data_send;
pima_device_parameter.ux_device_class_pima_parameter_object_delete                 = pima_device_object_delete;
pima_device_parameter.ux_device_class_pima_parameter_object_prop_desc_get          = pima_device_object_prop_desc_get;
pima_device_parameter.ux_device_class_pima_parameter_object_prop_value_get         = pima_device_object_prop_value_get;
pima_device_parameter.ux_device_class_pima_parameter_object_prop_value_set         = pima_device_object_prop_value_set;
pima_device_parameter.ux_device_class_pima_parameter_object_references_get         = pima_device_object_references_get;
pima_device_parameter.ux_device_class_pima_parameter_object_references_set         = pima_device_object_references_set;

/* Store the instance owner.  */
pima_device_parameter.ux_device_class_pima_parameter_application                   = (VOID *) 0;

/* Initialize the device PIMA class.  */
status = ux_device_stack_class_register(_ux_system_slave_class_pima_name, ux_device_class_pima_entry, 1, 0, &pima_device_parameter);

if (status != UX_SUCCESS)
{
    return;
}

pima_class_configuration_options

There are several configuration options for building USB Device PIMA Class. All options are located in the ux_user.h.

Configuration Option	Description
UX_PIMA_WITH_MTP_SUPPORT	This macro enables device/host PIMA MTP support.

pima_class_apis

The PIMA class API functions are defined below.

ux_device_class_pima_object_add
ux_device_class_pima_object_number_get
ux_device_class_pima_object_handles_get
ux_device_class_pima_object_info_get
ux_device_class_pima_object_data_get
ux_device_class_pima_object_info_send
ux_device_class_pima_object_data_send
ux_device_class_pima_object_delete

ux_device_class_pima_object_add

Adding an object and sending the event to the host

Configuration Option	Description
UX_DEVICE_CLASS_AUDIO_FEEDBACK_SUPPORT	This macro enables device audio feedback endpoint support
UX_DEVICE_CLASS_AUDIO_FEEDBACK_ENDPOINT_BUFFER_SIZE	Works if UX_DEVICE_ENDPOINT_BUFFER_OWNER is 1. Defined, it represents feedback endpoint buffer size. It should be larger than feedback endpoint max packet size in framework.
UX_DEVICE_CLASS_AUDIO_INTERRUPT_SUPPORT	This macro enables device audio interrupt endpoint support.

Command name	Value	Description
GET_DEVICE_ID	0x00	Get the device ID, the device id array is assigned by initialization parameter
GET_PORT_STATUS	0x01	Get the printer port status, the port status can be set by UX_DEVICE_CLASS_PRINTER_IOCTL_PORT_STATUS_SET
SOFT_RESET	0x02	Request to execute soft reset, the reset callback function is assigned by initialization parameter

Configuration Option	Description
UX_DEVICE_CLASS_PRINTER_ZERO_COPY	This macro enables zero copy support (works if PRINTER owns endpoint buffer). Defined, it enables zero copy for bulk in/out endpoints (write/read). In this case, the endpoint buffer is not allocated in class, application must provide the buffer for read/write, and the buffer must meet device controller driver (DCD) buffer requirements (e.g., aligned and cache safe if buffer is for DMA).
UX_DEVICE_CLASS_PRINTER_WRITE_AUTO_ZLP	class _write is pending ZLP automatically (complete transfer) after buffer is sent.

Function	Value
UX_DEVICE_CLASS_PRINTER_IOCTL_PORT_STATUS_SET	1
UX_DEVICE_CLASS_PRINTER_IOCTL_READ_TIMEOUT_SET	2
UX_DEVICE_CLASS_PRINTER_IOCTL_WRITE_TIMEOUT_SET	3

Name	Offset	Size	type	Description
Reserved	0	3	Bit field	Reserved for future use; should be 0
Not Error	3	1	Bit field	1 = No Error, 0 = Error
Selected	4	1	Bit field	1 = Selected, 0 = Not Selected
Paper Empty	5	1	Bit field	1 = Paper Empty, 0 = Paper Not Empty
Reserved	6	2	Bit field	Reserved for future use; should be 0