PHDC Class Instance Communication

Now that the class instance has been correctly initialized, it’s time to exchange data. PHDC offers 4 functions to do so. Table - PHDC Communication API Summary summarizes the communication functions provided by the PHDC implementation. See the PHDC API Reference for a complete API reference.

Table - PHDC Communication API Summary

Function name	Operation
`USBD_PHDC_PreambleRd()`	Reads metadata preamble.
`USBD_PHDC_Rd()`	Reads PHDC data.
`USBD_PHDC_PreambleWr()`	Writes metadata preamble.
`USBD_PHDC_Wr()`	Writes PHDC data.

With Metadata Preamble

Via the preamble enabled callback, the application will be notified once the host enables the metadata preamble. If metadata preambles are enabled, you should use the following procedure to perform a read:

Call USBD_PHDC_PreambleRd(). Device expects metadata preamble from the host. This function will return opaque data and the number of incoming transfers that the host specified. Note that if the host disables preamble while the application is pending on that function, it will immediately return with error “USBD_ERR_OS_ABORT”.
Call USBD_PHDC_Rd() a number of times corresponding to the number of incoming transfers returned by USBD_PHDC_PreambleRd(). The application must ensure that the buffer provided to the function is large enough to accommodate all the data. Otherwise, synchronization issues might happen. Note that if the host enables preamble while the application is pending on that function, it will immediately return with error “USBD_ERR_OS_ABORT”.

Listing - PHDC Read Procedure

CPU_INT16U  App_USBD_PHDC_Rd(CPU_INT08U   class_nbr,
                             CPU_INT08U  *p_data_opaque_buf
                             CPU_INT08U  *p_data_opaque_len,
                             CPU_INT08U  *p_buf,
                             USBD_ERR    *p_err) 
{
    CPU_INT08U  nbr_xfer;
    CPU_INT16U  xfer_len;
    CPU_INT08U  i;


   *p_data_opaque_len = USBD_PHDC_PreambleRd(        class_nbr,               (1)
                                             (void *)p_data_opaque_buf,       (2)
                                                     USBD_PHDC_CFG_DATA_OPAQUE_MAX_LEN,
                                                    &nbr_xfer,                (3)
                                                     0,                       (4)
                                                     p_err);

    for (i = 0u; i < nbr_xfer; i++) {                                         (5)
        xfer_len = USBD_PHDC_Rd(        class_nbr,
                                (void *)p_buf,                                (6)
                                        APP_USBD_PHDC_ITEM_DATA_LEN_MAX,
                                        0,                                    (4)
                                        p_err);

        /* Handle received data. */
    }

    return (xfer_len);
}

(1) The class instance number obtained with USBD_PHDC_Add() will serve internally to the PHDC class to route the data to the proper endpoints.

(2) Buffer that will contain opaque data. The application must ensure that the buffer provided is large enough to accommodate all the data. Otherwise, synchronization issues might happen.

(3) Variable that will contain the number of following transfers to which this preamble applies.

(4) In order to avoid an infinite blocking situation, a timeout expressed in milliseconds can be specified. A value of ‘0’ makes the application task wait forever.

(5) Read all the USB transfers to which the preamble applies.

(6) Buffer that will contain the data. The application must ensure that the buffer provided is large enough to accommodate all the data. Otherwise, synchronization issues might happen.

You should use the following procedure to perform a write:

Call USBD_PHDC_PreambleWr(). The host expects metadata preamble from the device. The application will have to specify opaque data, transfer’s QoS (see Table - Listing of QoS Bins), and a number of following transfers to which the selected QoS applies.
Call USBD_PHDC_Wr() a number of times corresponding to the number of transfers following the preamble.

Listing - PHDC Write Procedure

CPU_INT16U  App_USBD_PHDC_Wr(CPU_INT08U           class_nbr,
                             LATENCY_RELY_FLAGS   latency_rely,
                             CPU_INT08U           nbr_xfer,
                             CPU_INT08U          *p_data_opaque_buf
                             CPU_INT08U           data_opaque_buf_len,
                             CPU_INT08U          *p_buf,
                             CPU_INT08U           buf_len,
                             USBD_ERR            *p_err) 
{
    CPU_INT08U  i;


    (void)USBD_PHDC_PreambleWr(        class_nbr,                             (1)
                               (void *)p_data_opaque_buf,                     (2)
                                       data_opaque_buf_len,
                                       latency_rely,                          (3)
                                       nbr_xfer,                              (4)
                                       0,                                     (5)
                                       p_err);

    for (i = 0u; i < nbr_xfer; i++) {                                         (6)
        /* Prepare data to send. */

        xfer_len = USBD_PHDC_Wr(        class_nbr,                            (1)
                                (void *)p_buf,                                (7)
                                        buf_len,
                                        latency_rely,                         (3)
                                        0,
                                        p_err);
    }
}

(1) The class instance number obtained with USBD_PHDC_Add() will serve internally to the PHDC class to route the data to the proper endpoints.

(2) Buffer that contains opaque data.

(3) Latency / reliability (QoS) of the following transfer(s).

(4) Variable that contains the number of following transfers to which this preamble will apply.

(5) In order to avoid an infinite blocking situation, a timeout expressed in milliseconds can be specified. A value of ‘0’ makes the application task wait forever.

(6) Write all the USB transfers to which the preamble will apply.

(7) Buffer that contains the data.

Without Metadata Preamble

If the device does not support metadata preamble or if it supports them but it has not been enabled by the host, you should not call USBD_PHDC_PreambleRd() and USBD_PHDC_PreambleWr().