Vendor Class Configuration

General Configuration

Some constants are available to customize the class. These constants are located in the USB device configuration file, usbd_cfg.h. Table - General Configuration Constants Summary shows their description.

Table - General Configuration Constants Summary

Constant Description Possible Values

USBD_VENDOR_CFG_MAX_NBR_DEV Configures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to 1. From 1 to 254. Default value is 1.

USBD_VENDOR_CFG_MAX_NBR_CFG Configures the maximum number of configuration in which Vendor class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2.

USBD_VENDOR_CFG_MAX_NBR_MS_EXT_PROPERTY

Configures the maximum number of Microsoft extended properties that can be defined per Vendor class instance.

For more information on Microsoft OS descriptors and extended properties, refer to the Microsoft Hardware Dev Center .

From 1 to 255. Default value is 1.

Class Instance Configuration

Before starting the communication phase, your application needs to initialize and configure the class to suit its needs. Table - Vendor Class Initialization API Summary summarizes the initialization functions provided by the Vendor class. For more details about the functions parameters, refer to the Vendor Class Functions reference.

Table - Vendor Class Initialization API Summary

Function name	Operation
`USBD_Vendor_Init()`	Initializes Vendor class internal structures and variables.
`USBD_Vendor_Add()`	Creates a new instance of Vendor class.
`USBD_Vendor_CfgAdd()`	Adds Vendor instance to the specified device configuration.
`USBD_Vendor_MS_ExtPropertyAdd()`	Adds a Microsoft extended property to the Vendor class instance. Calling this function is not mandatory. You must set `USBD_CFG_MS_DESC_EN` to `DEF_ENABLED` before using this function.

You need to call these functions in the order shown below to successfully initialize the Vendor class:

Call USBD_Vendor_Init()
This is the first function you should call and you should do it only once even if you use multiple class instances. This function initializes all internal structures and variables that the class needs.
Call USBD_Vendor_Add()
This function allocates a Vendor class instance. This function allows you to include a pair of interrupt endpoints for the considered class instance. If the interrupt endpoints are included, the polling interval can also be indicated. The polling interval will be the same for interrupt IN and OUT endpoints. Moreover, another parameter lets you specify a callback function used when receiving vendor requests. This callback allows the decoding of vendor-specific requests utilized by a proprietary protocol.
Call USBD_Vendor_CfgAdd()
Once the Vendor class instance has been created, you must add it to a specific configuration.
Optional: Call USBD_Vendor_MS_ExtPropertyAdd()
If you plan to use the Microsoft OS descriptors in your design, you can call this function to add Microsoft extended properties to your Vendor class instance. However, calling this function is not mandatory. You must set USBD_CFG_MS_DESC_EN to DEF_ENABLED before using this function.

Listing - Vendor Class Initialization Example illustrates the use of the previous functions for initializing the Vendor class.

Listing - Vendor Class Initialization Example

                                                                              (1)
static  CPU_BOOLEAN  App_USBD_Vendor_VendorReq (      CPU_INT08U       class_nbr,
                                                const USBD_SETUP_REQ  *p_setup_req);

CPU_BOOLEAN  App_USBD_Vendor_Init (CPU_INT08U  dev_nbr,
                                   CPU_INT08U  cfg_hs,
                                   CPU_INT08U  cfg_fs)
{
    USBD_ERR    err;
    CPU_INT08U  class_nbr;


    USBD_Vendor_Init(&err);                                                   (2)
    if (err != USBD_ERR_NONE) {
        /* $$$$ Handle the error. */
    }

    class_nbr = USBD_Vendor_Add(DEF_FALSE,                                    (3)
                                0u, 
                                App_USBD_Vendor_VendorReq,                    (1)
                               &err);
    if (err != USBD_ERR_NONE) {
        /* $$$$ Handle the error. */
    }
 
    if (cfg_hs != USBD_CFG_NBR_NONE) {
        USBD_Vendor_CfgAdd(class_nbr, dev_nbr, cfg_hs, &err);                 (4)
        if (err != USBD_ERR_NONE) {
            /* $$$$ Handle the error. */
        }
    }
    if (cfg_fs != USBD_CFG_NBR_NONE) {
        USBD_Vendor_CfgAdd(class_nbr, dev_nbr, cfg_fs, &err);                 (5)
        if (err != USBD_ERR_NONE) {
            /* $$$$ Handle the error. */
        }
    }

#if (USBD_CFG_MS_DESC_EN == DEF_ENABLED)
    USBD_Vendor_MS_ExtPropertyAdd(class_nbr,                                  (6)
                                  USBD_MS_PROPERTY_TYPE_REG_SZ,
                                  App_USBD_Vendor_MS_PropertyNameGUID,
                                  sizeof(App_USBD_Vendor_MS_PropertyNameGUID),
                                  App_USBD_Vendor_MS_GUID,
                                  sizeof(App_USBD_Vendor_MS_GUID),
                                 &err);
    if (err != USBD_ERR_NONE) {
        /* $$$$ Handle the error. */
    }
#endif
}

(1) Provide an application callback for vendor requests decoding.

(2) Initialize Vendor internal structures, variables.

(3) Create a new Vendor class instance. In this example, DEF_FALSE indicates that no interrupt endpoints are used. Thus, the polling interval is set to 0. The callback App_USBD_Vendor_VendorReq() is passed to the function.

(4) Check if the high-speed configuration is active and proceed to add the Vendor instance previously created to this configuration.

(5) Check if the full-speed configuration is active and proceed to add the Vendor instance to this configuration.

(6) Adds a Microsoft GUID as a Microsoft extended property of the vendor class instance.

Listing - Vendor Class Initialization Example also illustrates an example of multiple configurations. The functions USBD_Vendor_Add() and USBD_Vendor_CfgAdd() allow you to create multiple configurations and multiples instances architecture. Refer to the Class Instance Concept page for more details about multiple class instances.