USB Basic Mini Host and Peripheral Driver (USB Mini Firmware) Using Firmware Integration Technology

Transcription

1 USB Basic Mini Host and Peripheral Driver (USB Mini Firmware) Using Firmware Integration Technology Introduction APPLICATION NOTE This application note describes the USB Basic Mini Firmware, which utilizes Firmware Integration Technology (FIT). This module performs hardware control of USB communication. It is referred to below as the USBBASICF/W FIT module. Target Device RX111, RX113, RX231 When using this application note with other Renesas MCUs, careful evaluation is recommended after making modifications to comply with the alternate MCU. Related Documents 1. Universal Serial Bus Revision 2.0 specification http// 2. RX111 User s Manual Hardware (Document number No. R01UH0365EJ) 3. RX113 User s Manual Hardware (Document number No. R01UH0448EJ) 4. RX231 User s Manual Hardware (Document number No. R01UH0496EJ) Renesas Electronics Website http// USB Devices Page http// R01AN2166EJ0102 Rev.1.02 Cotents 1. Overview How to Register Class Driver Task ID and Priority Setting Peripheral Host Scheduler How to register in USBBASICF/W DTC Transfer R01AN2166EJ0102 Rev.1.02 Page 1 of 94

2 1. Overview The USBBASICF/W FIT module performs USB hardware control. The USBBASICF/W FIT module operates in combination with sample device class drivers provided by Renesas or device class drivers created by the user. The This module supports the following functions. <Overall> Capable of running at FullSpeed and LowSpeed (USB2.0). Can operate in either host or peripheral mode. Device connect/disconnect, suspend/resume, and USB bus reset processing. Control transfer on pipe 0. Data transfer on pipes 1 to 9. (bulk or interrupt transfer CPU access/dtc access) <Host mode> In host mode, enumeration as lowspeed/fullspeed device (However, operating speed is different by devices ability.) A sample program for CDP operation or DCP operation is provided. <Peripheral mode> In peripheral mode, enumeration as USB Host of USB1.1/2.0/3.0. A sample program for CDP operation is provided. Limitations This module is subject to the following restrictions. The following functions must be provided by the customer to match the system under development. Overcurrent detection processing when connecting USB cables (Host mode). Descriptor analysis (Host mode). The pipe usage methods are limited by the pipe information setting functions. The receive pipe uses the transaction counter with the SHTNAK function. The structures contain members of different types. (Depending on the compiler, the address alignment of the structure members may be shifted.) In host mode, USBBASICF/W FIT module does not support suspend/resume of the connected hub and devices connected to the hub s down ports. USBBASICF/W FIT module does not support suspend during data transfer. Execute suspend after confirming the data transfer was completed. Terms and Abbreviations API Application Program Interface APL Application program cstd Prefix of function and file for Peripheral & Host Common Basic F/W CS+ Renesas integration development environment CDP Charging Downstream Port DCP Dedicated Charging Port HBC Host Battery Charging control Data Transfer Generic name of Bulk transfer and Interrupt transfer (When the host function is selected, the Control transfer is contained.) e 2 studio Eclipse embedded studio HCD Host control driver of USBBASICF/W HDCD Host device class driver (device driver and USB class driver) HEW Highperformance Embedded Workshop HM Hardware Manual hstd Prefix for host function of USBBASICF/W H/W Renesas USB device MGR Sequencer of HCD to manage the state of the peripheral device PBC Peripheral Battery Charging control PCD Peripheral control driver of USBBASICF/W PDCD Peripheral device class driver (device driver and USB class driver) psmpl Peripheral Sample (code) PP Preprocessed definition R01AN2166EJ0102 Rev.1.02 Page 2 of 94

3 pstd Prefix for peripheral function of USBBASICF/W RSK Renesas Starter Kits STD Standard Downstream Port UPL User Programming Layer (Upper layer of USBBASICF/WHDCD, PDCD, APL or etc) USB Universal Serial Bus USBBASICF/W USB Basic Host and Peripheral Mini Firmware Scheduler Used to schedule functions, like a simplified OS. Scheduler Macro Used to call a scheduler function Task Processing unit R01AN2166EJ0102 Rev.1.02 Page 3 of 94

4 1.1 USBBASICF/W FIT module User needs to integrate this module to the project using r_bsp. User can control USB H/W by using this module API after integrating to the project. Please refer to the chapter 4.2.8Adding the Module or 5.2.8Adding the Module about how to add the module. 1.2 Software Configuration In peripheral mode, USBBASICF/W comprises the peripheral driver (PCD), and the application (APL). PDCD is the class driver and not part of the USBBASICF/W. See Figure 1.1. In host mode, USBBASICF/W comprises the host driver (HCD), the manager (MGR) and the application (APL). HDD and HDCD are not part of the USBBASICF/W, see Table 1.1 PCD operates H/W control and data transfers upon demand from UPL. It also notifies the application task when H/W control ends, of results of data transfers, and of requests of the USB interrupt handler (status change etc). HCD likewise operates H/W control and data transfer upon demand from the MGR task. It executes data transfers on demand from UPL, and notifies MGR and UPL of the result of these data transfers. HCD also notifies MGR when H/W control ends, and of requests of the USB interrupt handler (status change etc). MGR manages the USB state of the connected device and processes sequences such as enumeration. Moreover, the USB state of the connected device changes according to demands of UPL via API functions. To do this, MGR sends requests to HCD to achieve this sequence processing necessary for USB state transition. (HCD then does the H/W control and data transfers.) The result of the USB state transition is notified to UPL via callbacks. The customer will need to make a variety of customizations, for example designating classes, issuing vendorspecific requests, making settings with regard to the communication speed or program capacity, or making individual settings that affect the user interface. Peripheral Mode Application (APL) User Programming Layer Host Mode Application (APL) Device driver (HDD) Device class driver (PDCD) Device class driver (HDCD) Scheduler Function (nonos) Manager Task (MGR) Peripheral Driver Task (PCD) Host Driver Task (HCD) 1 USB Interrupt Handler USB BASIC F/W Hardware Figure 1.1 Task Configuration of USBBASICF/W R01AN2166EJ0102 Rev.1.02 Page 4 of 94

5 Table 1.1 Software function overview No Module Name Function 1 USB Interrupt Handler USB interrupt handler (USB packet transmit/receive end and special signal detection) 2 Peripheral Control Driver (PCD) Hardware control in peripheral mode Peripheral transaction management 3 Host control driver (HCD) Hardware control in host mode Host transaction management 4 Host Manager (MGR) Device state management Enumeration HCD control message determination 5 Device Class Driver Provided by the customer as appropriate for the system. 6 Device Driver Provided by the customer as appropriate for the system. 7 Application Provided by the customer as appropriate for the system. 1.3 Scheduler Function and Tasks The USBBASICF/W FIT module uses the scheduler function to manage tasks and hardware requests according to the task priority. It is structured such that the completion of requests is reported to tasks by means of callback functions. Even if additions or changes are made to the UPL, there is no need to change the scheduler function. This means it is possible to implement a UPL optimized to the user system without modifying the scheduler itself. Please refer to PCD Callback functions or 5.4.1Host callback functions. 1.4 Note 1. USBBASICF/W FIT module is not guaranteed to provide USB communication operation. The customer should verify operation when utilizing it in a system and confirm the ability to connect to a variety of different types of devices. 2. The USBBASICF/W FIT module can be combined with the DTC FIT module and used to provide DTC transfer functionality. R01AN2166EJ0102 Rev.1.02 Page 5 of 94

6 2. How to Register Class Driver The class driver which the user created functions as the USB class driver by registering with USBBASICF/W FIT module. 2.1 How to register Peripheral Class Driver User needs to register the various information for the peripheral class driver which User has developed to usb_pcdreg_t structure. Please refer to usb_pcdreg_t structure about usb_pcdreg_t structure. The following describes how to register userdeveloped class drivers and applications in the USBBASICF/W FIT module. USB_STATIC void usb_psmpl_driver_registration(void) usb_pcdreg_t driver; /* Driver registration */ driver.pipetbl = g_usb_psmpl_eptbl1; /* Pipe define table */ driver.devicetbl = g_usb_psmpl_devicedescriptor; driver.configtbl = g_usb_psmpl_configurationf_1; driver.stringtbl = g_usb_psmpl_stringptr; driver.statediagram = &usb_psmpl_device_state; /* Change device state */ driver.ctrltrans = &usb_psmpl_control_transfer; /* Control transfer */ R_usb_pstd_DriverRegistration(&driver); 2.2 How to register Host Class Driver User needs to register the various information for the host class driver which User has developed to usb_hcdreg_t structure. Please refer to usb_hcdrequest_t structure about usb_hcdreg_t structure. The following describes how to register usercreated class drivers and applications in the USBBASICF/W FIT module. USB_STATIC void usb_hsmpl_driver_registration(void) usb_hcdreg_t driver; usb_pipe_t i; for( i = USB_MIN_PIPE_NO; i <= USB_MAX_PIPE_NO; i++ ) g_usb_hsmpl_usepipe[i] = USB_NO; /* Driver registration */ driver.ifclass = USB_IFCLS_VEN; /* Vendor class */ driver.classcheck = &usb_hsmpl_class_check; /* Operation judgment */ driver.statediagram = &usb_hsmpl_device_state; /* Change device state */ R_usb_hstd_DriverRegistration(&driver); R01AN2166EJ0102 Rev.1.02 Page 6 of 94

7 3. Task ID and Priority Setting Set task IDs and its maximum value. Do not set the same values for the task ID. Set the maximum value to one more (+ 1) than the highest task ID to be used. Set the UPL task ID to be used depending on the number to be used. The task priority level is the same as the task ID. The highest priority level becomes 0. In host mode, set the task priorities as"hcd task < MGR task < HCDC task". In peripheral mode, set the task priorities as "PCD task < PDCD task". Task ID 2 to (USB_IDMAX 1) Mailbox ID Set the same value as Task ID [Note] 1. USB_IDMAX is the defined by User in r_usb_basic_mini_config.h file. 2. Task IDs 0 and 1 are already defined. When setting task IDs, use values other than 0 and Define ID numbers for user tasks, etc., in the application files. R01AN2166EJ0102 Rev.1.02 Page 7 of 94

8 4. Peripheral 4.1 Peripheral Control Driver (PCD) Basic functions PCD is a program for controlling the hardware. PCD analyzes requests from PDCD (not part of the USBBASICF/W FIT module) and controls the hardware accordingly. It also sends notification of control results using a user provided callback function. PCD also analyzes requests from hardware and notifies PDCD accordingly. PCD accomplishes the following 1. Detection of USB state change with the connected host, and notification ofthe result. 2. Enumeration with the host. 3. Notification of USB requests. 4. Data transfer and notification of transfer result. 5. Charging Port Detection which was defined in USB Battery Charging Specification Revision Issuing requests to PCD API functions are used when hardware control requests are issued to the PCD and when performing data transfers. API functions and library functions can be used to obtain information for managing PCD. In response to a request from an upper layer task, PCD sends a result notification by means of a callback function. PCD has no API functions for class/vendor requests Notification of USB State Change To notify UPL of a USB state transition etc, the USBBASICF/W executes USB state transition callback function (*g_usb_pcddriver.statediagram) that the user previously registered with USBBASICF/W. The USBBASICF/W notifies the information below to the UPL using the second argument of the callback function. Analyze the USB state and perform suitable processing to the system. < USB state transition > #define USB_STS_DETACH #define USB_STS_ATTACH #define USB_STS_DEFAULT #define USB_STS_ADDRESS #define USB_STS_CONFIGURED #define USB_STS_SUSPEND #define USB_STS_RESUME Detach detection Attach detection Default state transition (USB bus reset detection) Address state transition (Set_Address request reception) Configured state transition (Set_Configuration request reception) Suspend state transition (suspend detection) Suspend state cancellation (resume detection) Control Transfer Notification The USBBASICF/W automatically returns standard requests when enumerating to a USB host. When a device class (a vendor class) request is received, the control transfer callback function (*g_usb_pstd_driver.ctrltrans), registered in the USBBASICF/W, is executed. The USBBASICF/W notifies the UPL of the information the first argument of the callback function. The UPL must analyze a USB request and perform appropriate processing. < Standard request > USB_CLEARSTALL USB_CLEARREMOTE USB_SETREMOTE USB_SETSTALL USB_RECIPIENT Receive Clear_Feature request (Clear STALL) Receive Clear_Feature request (Disable remote wakeup) Receive Set_Feature request (Enable remote wakeup) Receive Set_Feature request (Set STALL) Receive Get_Descriptor request and brecipient is an interface R01AN2166EJ0102 Rev.1.02 Page 8 of 94

9 4.1.5 USB requests The following standard requests are supported by PCD. GET_STATUS GET_DESCRIPTOR GET_CONFIGURATION GET_INTERFACE CLEAR_FEATURE SET_FEATURE SET_ADDRESS SET_CONFIGURATION SET_INTERFACE PCD answers requests other than the above with a STALL response. When the PCD receives one of the above standard requests, it executes the functions listed in Table4.1 according to the control transfer stage. Note that, if the received USB request is a device class request or a vender class request, the user needs to create a program to judge these requests and register the program in the driver. The following shows the peripheral processes available for the control transfer stage, based on the standard request received from a host. ControlRead When a valid request is received, data for transmission to the host is generated, and written to the FIFO ControlWrite When a valid request is received, enables data reception from the host. NoDataControl When a valid request is received, returns the status. ControlReadStatus Receives the status from the host. ControlWriteStatus Returns the status to the host. Control transfer end Sends notification to PDCD of a request received from host. Table4.1 Peripheral Function Used Control Transfer Stage Device Class Response to Host ControlRead usb_pstd_standreq1() Transmit data ControlWrite usb_pstd_standreq2() Receive data NoDataControl usb_pstd_standreq3() Return status ControlRead Status usb_pstd_standreq4() Receive status ControlWrite Status usb_pstd_standreq5() Return status Control transfer end usb_pstd_standreq0() None Peripheral Battery Charging (PBC) PBC is the H/W control program for the target device that operates the Charging Port Detection (CPD) defined by the USB Battery Charging Specification (Revision 1.2). CPD immediately executes after the USBBASICF/W notifies of USB state transition USB_STS_ATTACH to UPL via the callback function (*g_usb_pcddriver.statediagram). USBBASICF/W also notifies the result of the CPD action to UPL by the callback function, at the USB state transition USB_PORTENABLE, using the first argument. The result of the callback notified to UPL is one of the following 0 Standard Downstream Port (SDP) Detection 1 Charging Downstream Port (CDP) Detection 2 Dedicated Charging Port (DCP) Detection R01AN2166EJ0102 Rev.1.02 Page 9 of 94

10 The processing flow of PBC is shown in Table 1.1 Figure 4.1 PBC processing flow R01AN2166EJ0102 Rev.1.02 Page 10 of 94

11 4.2 API Information This Driver API follows the Renesas API naming standards Hardware Requirements This driver requires your MCU support the following features USB Software Requirements This driver is dependent upon the following packages r_bsp r_usb_dtc (using DTC transfer) Supported Toolchains This driver is tested and working with the following toolchains Renesas RX Toolchain v Header Files All API calls and their supporting interface definitions are located in r_usb_basic_mini_if.h Integer Types This project uses ANSI C99 Exact width integer types in order to make the code clearer and more portable. These types are defined in stdint.h Compile Setting The configuration option settings for this module are specified in r_usb_basic_mini_config.h. The option names and setting values are described below. USB_DTC_ENABLE USB_FUNCSEL_PP USB_LSPERI_PP USB_FSPERI_PP USB_DEBUG_HOOK_USE USB_PERI_BC_ENABLE USB_CPUBYTE_PP USB_BCDNUM USB_RELEASE USB_DCPMAXP USB_VENDORID Configuration options in r_usb_basic_mini_config.h Selects whether or not the DTC FIT module is used. = Enabled DTC FIT module is used. = Disabled DTC FIT module is not used. Specifies the operating mode of the USB module (USB0). = USB_HOST_PP USB module operates as a host. = USB_PERI_PP USB module operates as a peripheral. Specifies data transfer rate. Transfer speed is set by fullspeed or lowspeed. = USB_LSPERI_PPLowSpeed is used. = USB_FSPERI_PPFullSpeed is used. Specifies the function to use the fook function when the error is generated. = Enabled Fook function is used. = Disabled Fook function is not used. Specifies whether or not battery charging functionality is enabled in Peripheral mode. = Enabled Battery charging functionality is used. = Disabled Battery charging functionality is not used. Specifies the endian mode for USB FIFO register access. The setting of this item should match the endian mode of the CPU. = USB_BYTE_LITTLE_PP Littleendian = USB_BYTE_BIG_PP Bigendian Specifies the value of the bcdusb device descriptor in Peripheral mode. (This item may be used for a device descriptor created by the user.) Specifies the value of the bcddevice device descriptor in Peripheral mode. (This item may be used for a device descriptor created by the user.) Specifies the value of the bmaxpacketsize device descriptor in Peripheral mode. (This item may be used for a device descriptor created by the user.) Specifies the value of the idvendor device descriptor in Peripheral mode. R01AN2166EJ0102 Rev.1.02 Page 11 of 94

12 USB_PRODUCTID USB_IDMAX USB_BLKMAX USB_TABLEMAX USB_D0FIFO0_PRI USB_D1FIFO0_PRI USB_USBI0_PRI USB_USBR0_PRI (This item may be used for a device descriptor created by the user.) Specifies the value of the idproduct device descriptor in Peripheral mode. (This item may be used for a device descriptor created by the user.) Specifies the maximum number of task IDs that can be registered in the scheduler. Specifies the maximum number of memory pools that can be set in the scheduler. Specifies the maximum number of messages that can be set for each priority in the scheduler. Specifies the interrupt priority level for the D0FIFO interrupt. Specifies the value 0(Priority Low) to 15(Priority High). Specifies the interrupt priority level for the D1FIFO interrupt. Specifies the value 0(Priority Low) to 15(Priority High). Specifies the interrupt priority level for the USBI interrupt. Specifies the value 0(Priority Low) to 15(Priority High). Specifies the interrupt priority level for the USBR interrupt. Specifies the value 0(Priority Low) to 15(Priority High) Argument The structure for the arguments of the API functions is shown below. For details, please refer to4.7.3(the USB Communication Structure (usb_utr_t)). struct usb_utr_t usb_strct_t msginfo; /* Message information */ usb_strct_t pipenum ; /* Sub information(port No/Pipe No etc) */ usb_strct_t status; /* USB status */ usb_strct_t flag; /* Flag */ usb_cb_t complete; /* Pointer to the callback function */ usb8_t *tranadr; /* Pointer to USB transfer buffer */ uint16_t *setup; /* Pointer to Setup packet data */ uint16_t pipectr; /* PIPECTR register */ usb_leng_t tranlen; /* USB data length*/ uint8_t dummy; /* Adjustment of the byte border */ Adding the Module This module must be added to an existing e 2 studio project. By using the e 2 studio plugin, it is possible to update the include file path automatically. It is therefore recommended that this plugin be used to add the project. For instructions when using e 2 studio, refer to RX Family Adding Firmware Integration Technology Modules to Projects (document No. R01AN1723EU). For instructions when using CS+, refer to RX Family Integration into CS+, Firmware Integration Technology (document No. R01AN1826EJ). R01AN2166EJ0102 Rev.1.02 Page 12 of 94

13 4.3 API (Application Programming Interface) A PDCD module (USB class driver) implements hardware control requests by using the PCD API. The return values of each API function are scheduler macro error codes. A list of PCD API functions is shown in Table4.2. Table4.2 Function R_USB_Open() R_USB_Close() R_USB_GetVersion() R_usb_pstd_PcdOpen() R_usb_pstd_PcdTask() R_usb_pstd_TransferStart() R_usb_pstd_TransferEnd() R_usb_pstd_ChangeDeviceState() R_usb_pstd_DeviceInformation() R_usb_pstd_DriverRegistration() R_usb_pstd_ControlRead() R_usb_pstd_ControlWrite() R_usb_pstd_ControlEnd() R_usb_pstd_SetStallPipe0() R_usb_pstd_SetPipeStall() R_usb_pstd_SetPipeRegister() List of PCD API Functions Description Start the USB module Stop the USB module Return the driver version Start the PCD task The PCD Task Data transfer execution request Data transfer forced end request USB device state change request Get USB device state information Register the PDCD FIFO access execution request for control read transfer FIFO access execution request for control write transfer Control transfer end request Set PID of pipe 0 to STALL Set PID of pipe other than pip 0 to STALL Set pipe information R01AN2166EJ0102 Rev.1.02 Page 13 of 94

14 4.3.1 R_USB_Open Power on USB module. Format usb_err_t Arguments Return Value USB_SUCCESS USB_ERR_BUSY USB_ERR_OPENED Description Note R_USB_Open(void) This function applies power to the USB module. Success Locked USB module by other S/W module USB module currently in operation 1. Call this API once only at the initializing 2. Don t call this API after powering on USB module. Example void usb_smp_task() usb_er_t err; err = R_USB_Open(); /* Start USB module */ if(err!= USB_SUCCESS) /* error */ R01AN2166EJ0102 Rev.1.02 Page 14 of 94

15 4.3.2 R_USB_Close Power off USB module. Format usb_err_t Arguments Return Value R_USB_Close(void) USB_SUCCESS USB_ERR_BUSY USB_ERR_NOT_OPEN Description Note This function removes power to the USB module. Success Locked USB module by other S/W module. USB module is not opened. 1. Call this API once only to shut down the USB module. Example void usb_smp_task() usb_er_t err; err = R_USB_Close(); /* Stop USB module */ if(err!= USB_SUCCESS) /* error */ R01AN2166EJ0102 Rev.1.02 Page 15 of 94

16 4.3.3 R_USB_ GetVersion Return the driver version number Format uint32_t Arguments Return Value Version number Description Note R_USB_GetVersion(void) This function returns the driver version number at runtime Example void usb_smp_task() uint32_t version; version = R_USB_GetVersion(); R01AN2166EJ0102 Rev.1.02 Page 16 of 94

17 4.3.4 R_usb_pstd_PcdOpen Start PCD task Format void R_usb_pstd_PcdOpen(void) Arguments Return Value Description This function initializes the global variables used by the PCD. Note 1. The user application should register the PDCD in the PCD and then call this function during initialization. Please register the PDCD by using the function R_usb_pstd_DriverRegistration. 2. Please do not call this function after starting the PCD task Example void usb_psmpl_main_init(void) /* Target board initialize */ usb_cpu_target_init(); /* USBIP initialized */ R_usb_pstd_ChangeDeviceState(USB_DO_INITHWFUNCTION); /* PCD driver open & registratuion */ R_usb_pstd_PcdOpen(); /* PCD task open */ usb_psmpl_driver_registration(); /* Sample driver registration */ /* Scheduler initialized */ R_usb_pstd_ChangeDeviceState(USB_DO_SETHWFUNCTION); R01AN2166EJ0102 Rev.1.02 Page 17 of 94

18 4.3.5 R_usb_pstd_PcdTask End PCD task Format void Arguments Return Value Description Note R_usb_pstd_PcdTask(void) This function provides hardware control when selecting peripheral functions. usb_pstd_pcd_task() Responds to USB standard requests. Calls the control transfer callback function registered by the UPL when a class request or vendor request is detected. Calls the USB state transition callback function registered by the UPL when a USB state transition is detected. usb_pstd_pcd_task() performs the data transfer requested via the API function. Calls the callback function specified by the API function when data transfer finishes. 1. Call this function in a loop using the scheduler mechanism. 2. When an invalid message is received, the hook function (R_usb_cstd_debug_hook()) is called. For information on the hook function, see 6.3, Commnon Library Functions. Example void usb_smp_mainloop(void) while(1) /* Scheduler */ if(r_usb_cstd_scheduler() == USB_FLGSET) R_usb_pstd_PcdTask(); usb_psmpl_apl_task(); R01AN2166EJ0102 Rev.1.02 Page 18 of 94

19 4.3.6 R_usb_pstd_TransferStart Data transfer request Format usb_er_t Arguments *utr_table Return Value USB_E_OK USB_E_ERROR USB_E_QOVR Description R_usb_pstd_TransferStart(usb_utr_t * utr_table) Pointer to a USB Transfer Structure Success Failure Overlap. (The pipe is in use.) Request the data transfer of the pipe specified in the transfer structure. When either the specified data size is satisfied, a short packet is received, or an error occurs, the data transfer ends. When data transfer ends, the callback function of the argument in the structure member is called. Remaining data length of transmission and reception, status, and information of transfer end are set in the argument of this callback function (utr_table). When a data transfer is restarted with the same pipe, it is necessary to put the pipe status (data toggle previous pipe status) for the next transfer. Structure member (utr_table.pipectr) of the argument must be set to the pipe status. When a USB reset or clear STALL etc. occur, the pipe status should be initialized to DATA0". When a transfer start request is issued to a pipe during a data transfer, USB_E_QOVR is returned. Note 1. Call this function from the user application or class driver. 2. The structure members indicated by the argument include pipe number, transfer data start address, transfer data length, status, callback function at end, etc. 3. When the received data is n times of the maximum packet size and less than the specified data size, it is considered that the data transfer is not ended and a callback function is not generated. Example usb_utr_t usb_pvndr_trnmsg[usb_max_pipe_no+1]; usb_er_t usb_pvndr_data_transfer(usb_pipe_t pipe) usb_er_t err; /* PIPE Transfer set */ usb_pvndr_trnmsg[pipe].pipenum = pipe; usb_pvndr_trnmsg[pipe].tranadr = usb_pvndr_trnptr[pipe]; usb_pvndr_trnmsg[pipe].tranlen = usb_pvndr_trnsize[pipe]; usb_pvndr_trnmsg[pipe].pipectr = usb_pvndr_pipectr[pipe]; usb_pvndr_trnmsg[pipe].setup = 0; usb_pvndr_trnmsg[pipe].complete = (usb_cb_t)&usb_pvndr_transfer_result; err = R_usb_pstd_TransferStart((usb_utr_t *)&usb_pvndr_trnmsg[pipe]); return err; R01AN2166EJ0102 Rev.1.02 Page 19 of 94

20 4.3.7 R_usb_pstd_TransferEnd Data transfer forced end request Format usb_er_t Arguments pipe msginfo Return Value USB_E_OK USB_E_ERROR USB_E_QOVR R_usb_pstd_TransferEnd(usb_pipe_t pipe, usb_strct_t_t msginfo) Pipe number USB communication status Success Failure Overlap. (The pipe is in use.) Description Set the following values to the argument msginfo. Note USB_DO_TRANSFER_STP USB_DO_TRANSFER_TMO Data transfer forced end Data transfer timeout (The PCD does not call back.) The transfer end is notified to UPL using the callback function set when the data transfer was requested with R_usb_pstd_TransferStart The callback will signal forced end with msginfo=usb_do_transfer_stp. The remaining data length of transmission and reception, pipe control register value, and transfer status = USB_DATA_STOP are available in the argument of the callback (usb_utr_t). When a forced end request is issued to a pipe is not executing any data transfer, USB_E_QOVR is returned. 1. When data transmission is suspended, the FIFO buffer of the SIE is not cleared. When the FIFO buffer is transmitted using double buffer, the data that has not been transmitted yet may remain in the FIFO buffer. 2. Call this function from the user application or class driver. Example void usb_smp_task(void) err = R_usb_pstd_TransferEnd(USB_PIPE4, USB_DO_TRANSFER_STP); return err; R01AN2166EJ0102 Rev.1.02 Page 20 of 94

21 4.3.8 R_usb_pstd_ ChangeDeviceState USB peripheral device state change request Format usb_er_t Arguments msginfo Return Value USB_E_OK USB_E_ERROR R_usb_pstd_ChangeDeviceState(usb_strct_t msginfo) Desired USB state Success Failure Description This function sends a request to the PCD to change the USB device state by setting one of the following values of argument state, and then call the complete callback function. USB_DO_REMOTEWAKEUP Remote wakeup execution request to PCD USB_DP_ENABLE D+ line pullup request to PCD USB_DP_DISABLE D+ line pullup cancel request to PCD USB_DO_INITHWFUNCTION Start the USBIP and perform a software reset. Execute this function before USBBASICF/W starts. USB_DO_SETHWFUNCTION Set the the USBIP as a USB peripheral (device). Execute this function after registering UPL. Note 1. Call this function from the user application or class driver. 2. If connected/disconnected interrupt is detected, a D+ line pullup cancel is executed automatically by firmware. 3. This is executed without the PCD task being involved. Example void usb_smp_task(void) R_usb_pstd_ChangeDeviceState(USB_DO_INITHWFUNCTION); R_usb_pstd_PcdOpen(); /* PCD task open */ usb_psmpl_driver_registration(); /* Sample driver registration */ R_usb_pstd_ChangeDeviceState(USB_DO_SETHWFUNCTION); R01AN2166EJ0102 Rev.1.02 Page 21 of 94

22 4.3.9 R_usb_pstd_DeviceInformation Get a USB peripheral s device state information Format void Arguments *table R_usb_pstd_DeviceInformation ( uint16_t *table) Pointer to the buffer that the device information is stored. Return Value Description This function gets USB peripherals device state information. It stores the following information at the address designated by the argument table. [0]USB device state *1 DVSQ and VBSTS bit value in he interrupt status register (INTSTS0)is stored. [1]Configuration number used Configuration number (wvalue of SET_CONFIGURATION request) [2]Interface number (g_usb_pcddriver.configtbl[usb_con_num_interface]) [3]Remote Wakeup Flag (Enable USB_YES, disable USB_NO) *1 For details, see the description of Interrupt Status Register 0 (INTSTS0) in the user s manual (hardware). Note 1. Call this function from the user application or class driver. 2. Provide 4 word area for the argument *table. Example void usb_smp_task(usb_utr_t *ptr) uint16_t res[4]; /* Get USB Device Information */ R_usb_pstd_DeviceInformation( res ); R01AN2166EJ0102 Rev.1.02 Page 22 of 94

23 R_usb_pstd_ DriverRegistration Register a PDCD Format void Arguments *registinfo Return Value Description Note R_usb_pstd_DriverRegistration(usb_pcdreg_t *registinfo) Pointer to class driver structure This function registers the PDCD information, which is registered in the class driver structure, in the PCD. After registration is complete, the initialization callback function is executed. 1. The user must call this function from the user s program during initialization. 2. Only one device can be registered. Please refer to Table4.6 Member of usb_pcdreg_t structure about the registration information. Example void usb_psmpl_driver_registration(void) usb_pcdreg_t driver; /* Driver registration */ driver.pipetbl = g_usb_psmpl_eptbl1; driver.devicetbl = g_usb_psmpl_devicedescriptor; driver.configtbl = g_usb_psmpl_configurationf_1; driver.stringtbl = g_usb_psmpl_stringptr; driver.statediagram = &usb_apl_change_device_state; driver.ctrltrans = &usb_psmpl_control_transfer; R_usb_pstd_DriverRegistration(&driver); R01AN2166EJ0102 Rev.1.02 Page 23 of 94

24 R_usb_pstd_ControlRead FIFO access request for control read transfer Format uint16_t Arguments bsize *table Return Value USB_WRITESHRT USB_WRITING USB_FIFOERROR Description Note R_usb_pstd_ControlRead(usb_leng_t bsize, uint8_t *table) Transmit data buffer size Pointer to transmit data buffer address Data write end (short packet data write) Data write in progress (additional data present) FIFO access error During a control IN transfer, this function issues a FIFO access execution request to PCD during the data stage. The address of the read data to send to host is given by the argument (*table), and will be written to the FIFO buffer. USBBASICF/W discontinues the data stage if a short packet or OUT token is received from host. 1. If USBBASICF/W is also use on the host side, note that if when the specified data size is equal to the size of the max packet, the NULL packet is transmitted by the IN token after the specified data is transmitted. 2. Please call this function at the control IN transfer data stage. Please refer to4.6 eripheral Control Transfer. Example uint8_t g_usb_smp_buff[16]; void usb_smpl_vendore_reques1(usb_request_t *data1, uint16_t data2) if (data1>typerecip == USB_INTERFACE ) R_usb_pstd_ControlRead(10,(uint8_t*)&g_usb_smp_buff); else R_usb_pstd_SetStallPipe0(); R01AN2166EJ0102 Rev.1.02 Page 24 of 94

25 R_usb_pstd_ControlWrite FIFO access request for control write transfer Format void Argument bsize *table R_usb_pstd_ControlWrite(usb_leng_t bsize, uint8_t *table) Receive data buffer size for control write transfer Receive data buffer address for control write transfer Return Value Description Note Example Call this API at the control OUT transfer data stage to request FIFO access to the PCD. The PCD reads data from the hardware FIFO buffer and writes it to the area specified by the argument (*table). 1. The data will be read up to the specified length. 2. If received data is less than the data length, reading ends when a short packet is received. 3. Please call this function at the control OUT transfer data stage. Please refer to 4.6 eripheral Control Transfer. uint8_t g_usb_smp_buf[16]; void usb_smpl_vendore_reques2(usb_request_t *data1, uint16_t data2) if(data1>typerecip == USB_INTERFACE ) R_usb_pstd_ControlWrite(10, (uint8_t*)(& usb_smp_buf)); R01AN2166EJ0102 Rev.1.02 Page 25 of 94

26 R_usb_pstd_ControlEnd Control transfer end request Format void Argument status Return Value Description R_usb_pstd_ControlEnd(uint16_t status) Status This function issues a request for control transfer status stage execution to PCD. It is called at the control transfer status stage. Besides above arguments, also set the following value for the status argument. USB_CTRL_END Status stage normal end. USB_DATA_STOP Return NAK to host at status stage. USB_DATA_OVR Return STALL to host at status stage. Note 1. Please call this function at the control transfer status stage. Refer to 4.6 eripheral Control Transfer. 2. When specifying USB_CTRL_END to the argument (status) while PID is STALL, STALL is returned. 3. Refer to MCU hardware manual about PID, BUF and CCPL. Example uint8_t g_usb_smp_buff[16]; void usb_smpl_vendore_reques3(usb_request_t *data1, uint16_t data2) if (data1>typerecip == USB_INTERFACE ) R_usb_pstd_ControlEnd(USB_CTRL_END); else R_usb_pstd_ControlEnd(USB_DATA_ERR); R01AN2166EJ0102 Rev.1.02 Page 26 of 94

27 R_usb_pstd_SetStallPipe0 Set STALL for pipe x PID (for data transfers) Format void Argument Return Value R_usb_pstd_SetStallPipe0 (void) Description Note Set STALL to the PID of PIPE0. 1. Call this function when the response to a class request or vendor request is to be STALL. When R_usb_ControlEnd(USB_CTRL_END) is called after this API is executed, A STALL is responped. 2. Call this function from the user application, or the class driver. Example void usb_psmpl_control_transfer(usb_request_t *data1, uint16_t data2) if (data1>typerecip == USB_INTERFACE ) R_usb_pstd_SetStallPipe0(); else usb_smpl_vendore_request(data1); ; R01AN2166EJ0102 Rev.1.02 Page 27 of 94

28 R_usb_pstd_SetPipeStall Set STALL for pipe x PID (for data transfers) Format void R_usb_pstd_SetPipeStall ( uint16_t pipe ) Argument pipe Return Value USB_E_OK USB_E_ERROR Description Note Pipe number Success Failure, argument error Set STALL as PID of the pipe number specified by the argument. The callback function that is specified by argument complete will be called when a stall packet has been sent. 1. Pipe 0 as argument is an error. Use the R_usb_pstd_SetStallPipe0() function. 2. Call this function from the user application, or the class driver. Example void usb_smp_task(usb_utr_t *ptr) R_usb_pstd_SetPipeStall(USB_PIPE4); R01AN2166EJ0102 Rev.1.02 Page 28 of 94

29 R_usb_pstd_SetPipeRegister Set pipe information to USB H/W Format void Argument table command Return Value R_usb_pstd_SetPipeRegister(uint16_t* table, uint16_t command) Pipe information table Command. See below Description (1). When the command is USB_NO". All pipes specified with the pipe information table are set to be unused. (2). When the command is USB_YES". All pipes specified with the pipe information table are set to be unused. After set to unused, all pipes are reinitiated based on the pipe information. Note 1. When the Set_Configuration request is received, USBBASICF/W executes this processing. Example void usb_pstd_set_configuration3(void) if( g_usb_pcdrequest.typerecip == USB_DEVICE ) if( g_usb_pcdconfignum!= (uint8_t)g_usb_pcdrequest.wvalue ) /* Configuration number set */ g_usb_pcdconfignum = (uint8_t)g_usb_pcdrequest.wvalue; R_usb_pstd_SetPipeRegister(g_usb_PcdDriver.pipetbl, USB_NO); if( g_usb_pcdconfignum > 0 ) R_usb_pstd_SetPipeRegister(g_usb_PcdDriver.pipetbl, USB_YES); return; R_usb_pstd_SetStallPipe0(); R01AN2166EJ0102 Rev.1.02 Page 29 of 94

30 PCD Callback functions Show PCD callback function in Table4.3 Table4.5. Table4.3 *g_usb_pcddriver.statediagram Callback Callback when detecting the USB state transition Call format (*usb_cbinfo_t)(uint16_t, uint16_t) Arguments Normally not used, configuration number for uint16_t Set_Configurationdevice_state USB state. Resume detection USB_STS_RESUME State transition interrupt detectionusb_sts_default USB_STS_ADDRESS uint16_t USB_STS_CONFIGURED USB_STS_SUSPEND Detach detection USB_STS_DETACH Attach detection USB_STS_ATTACH USB data line is set to pull up USB_STS_PORTENABLE Return values Description Notifies the PDCD when a USB state transition occurs. Resume detection (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_RESUME); State transition interrupt detection (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_DEFAULT); (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_ADDRESS); (*g_usb_pcddriver.statediagram)(g_usb_pcdconfignum, USB_STS_CONFIGURED); (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_SUSPEND); Detach detection (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_DETACH); Attach detection (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_STS_ATTACH); D+ set to pull up (*g_usb_pcddriver.statediagram)(usb_no_arg, USB_PORTENABLE); Notes The communication speed of the callback device is not reported when a USB reset is detected. When a Set_Configuration request is received, no callback occurs if the configuration number has not changed. If a Set_Configuration request is received and the configuration number = 0, the ADDRESS state is reported. R01AN2166EJ0102 Rev.1.02 Page 30 of 94

31 Table4.4 *g_usb_pcddriver.ctrltrans Callback Callback for control transfer Call format (*usb_cb_trn_t)(usb_request_t*, uint16_t) Arguments usb_request_t USB request uint16_t Stage of control transfer Return values Description Reports the occurrence of a reclass request or vendor class request to the UPL. The classifications of the transfer stages reported by the second argument are listed below. For details, refer to the hardware manual. USB_CS_IDST /* Idle or setup stage */ USB_CS_RDDS /* Control read data stage */ USB_CS_WRDS /* Control write data stage */ USB_CS_WRND /* Control write nodata status stage */ USB_CS_RDSS /* Control read status stage */ USB_CS_WRSS /* Control write status stage */ USB_CS_SQER /* Control sequence error */ (*g_usb_pcddriver.ctrltrans)((usb_request_t*)&g_usb_pcdrequest, (uint16_t)intseq); This UPL is also notified when any of the following standard requests are received. Remote wakeup canceled by Clear_Feature request. (*g_usb_pcddriver. ctrltrans)((usb_request_t*)&g_usb_pcdrequest, USB_CLEARREMOTE); Endpoint STALL setting canceled by Clear_Feature request. (*g_usb_pcddriver. ctrltrans)((usb_request_t*)&g_usb_pcdrequest, USB_ CLEARSTALL); brecipient response to Get_Descriptor request is USB_INTERFACE. (*g_usb_pcddriver. ctrltrans)((usb_request_t*)&g_usb_pcdrequest, USB_RECIPIENT); Remote wakeup enabled by Set_Feature request. (*g_usb_pcddriver. ctrltrans)((usb_request_t*)&g_usb_pcdrequest, USB_SETREMOTE); Endpoint set to STALL by Set_Feature request. (*g_usb_pcddriver. ctrltrans)((usb_request_t*)&g_usb_pcdrequest, USB_SETSTALL); Notes USBBASICF/W does not remember the pipe information when the UPL makes the STALL setting. When a Clear_Feature request is received successfully, this is reported to the UPL by the associated callback. Therefore, the UPL should determine whether or not pipes set to STALL have had the STALL setting canceled. When the Get_Interface request is used to request an alternate notification, the response is always 0. R01AN2166EJ0102 Rev.1.02 Page 31 of 94

32 Table4.5 *g_usb_libpipe [pipe]>complete Callback Callback at data transfer end Call format (*usb_cb_t)(usb_utr_t*) Arguments usb_utr_t* Pointer to a USB Transfer Structure Return values Description Reports to the UPL when a data transfer finishes or is interrupted. The structure members updated by USBBASICF/W are listed below. < members of structure usb_utr_t > tranlen Reports the remaining data length for the transfer request. status Reports the communication result. pipectr Set to the value of the pipe control register. Notes No members other than the above are updated. The details of the transfer request are retained. For details of the members of structure usb_utr_t, see Table4.8. There is no callback when a timeout interruption occurs (USB_DO_TRANSFER_TMO specified by R_usb_pstd_TransferEnd() function). R01AN2166EJ0102 Rev.1.02 Page 32 of 94

33 4.4 Structure Definitions The structures used in USB peripheral mode are described below. They are defined in file usb_ctypedef.h usb_pcdreg_t structure The usb_pcdreg_t structure is used to register PDCD information using the function R_usb_pstd_DriverRegsitration. The callback function registered in usb_pcdreg_t is executed when the device state changes, etc. Table4.6 lists the members of the usb_pcdreg_t structure. Table4.6 Member of usb_pcdreg_t structure Type Member Description uint16_t **pipetbl Register the address of the pipe information table. uint8_t *devicetbl Register the device descriptor address. uint8_t **configtbl Register the address of the configuration descriptor address table. uint8_t **stringtbl Register the address of the string descriptor address table. uint8_t **stringtbl Register the address of the String Descriptor address table. usb_cbinfo_t statediagram Register the function to start when the USB state transits. usb_cb_trn_t ctrltrans Register the function to start when a class request or vendor request is issued The usb_request_t structure Usb_request_t is the structure where the latest USB request other than the standard request is stored. This structure is used as the argument to the callback function that was registered in member ctrltrans of the usb_request_t structure. Table4.7 shows the member of usb_request_t structure. Table4.7 Member of usb_request_t structure Type Member Description uint16_t wrequest The value is brequest of request. (The value is BREQUEST of USBREQ register.) When this value is used, mask with USBC_BREQUEST(0xFF00u) uint16_t wvalue The value is wvalue of request. (The value is USBVAL register.) uint16_t windex The value is windex of request. (The value is USBINDEX register.) uint16_t wlength The value is wlength of request. (The value is USBLENG register.) R01AN2166EJ0102 Rev.1.02 Page 33 of 94

34 4.5 Pipe Information Table In order for the PDCD to perform data communication on pipes 1 to 9, it must maintain information tables to define pipe settings. A pipe information table comprises the necessary register setting values for performing data transfers and a specification of the FIFO port transfer direction (CPU transfer or DTC transfer). The follow shows the sample of the pipe information table. uint16_t g_usb_psmpl_eptbl1[] = USB_PIPE4, Pipe definition item 1 USB_NULL USB_BFREOFF USB_DBLBOFF USB_SHTNAKOFF, Pipe definition item 2 USB_NULL, Pipe definition item 3 USB_NULL, Dummy data USB_PDTBEND, A pipe information table comprises the following six items (uint16_t 4). 1. Pipe Window Select register (address 0x64) 2. Pipe Configuration register (address 0x68) 3. Pipe Maximum Packet Size register (address 0x6C) 4. Pipe Period Control register (address 0x6E) R01AN2166EJ0102 Rev.1.02 Page 34 of 94

35 (1). Pipe definition item 1 Specify the value to be set in the pipe window select register. Pipe select Specify the selected pipe (USB_PIPE1 to USB_PIPE9) Restrictions (2). Pipe definition item 2 Specify the values to be set in the pipe configuration register. Transfer type Specify either USB_BULK or USB_INT BRDY operation designation Specify USB_BFREOFF Double buffer mode Specify either USB_DBLBON or USB_DBLBOFF SHTNAK operation designation Specify either USB_SHTNAKON or USB_SHTNAKOFF Transfer direction Specify either USB_DIR_H_OUT or USB_DIR_H_IN Endpoint number Specify the endpoint number (EP1 to EP15) Restrictions The values that can be set for the transfer type differ according to the selected pipe. For details, refer to the hardware manual of the corresponding device. For a pipe set to the receive direction, specify USB_SHTNAKON The same endpoint number may not be set for pipes with different direction settings (3). Pipe definition item 4 Specify the settings for the pipe maximum packet size register Maximum packet size Specify the maximum packet size for the pipe. Restrictions The Max packet size which can be specified changes with devices. For details, please refer to the hardware manual of each device (4). Other pipe setting notes Pipe information is necessary only for the number of endpoints for which simultaneous communication is possible. Make sure to write USB_PDTBLEND at the end of the pipe information table. Alternate interface settings are not supported. R01AN2166EJ0102 Rev.1.02 Page 35 of 94

36 4.6 Peripheral Control Transfer This section provides a transfer control sample program which uses the API provided by the USBBASICF/W. The sample illustrates a control transfer that occurs when a class request is made from PDCD. The following functions are required for control transfer processing. Setup stage class request function. (This function shall match the user system. Refer to Class request processing.) Data stage API functions (R_usb_pstd_ControlRead / R_usb_pstd_ControlWrite). Status stage API function (R_usb_pstd_ControlEnd/ R_usb_pstd_ SetStallPipe0) Class request processing When USBBASICF/W receives a class request, it stores the request details in the global variable g_usb_pcddriver, which is declared by the usb_pcdreg_t type, then cals the class request processing function registered in member ctrltrans of structure usb_pcdreg_t. The arguments of this function specify the USB communication structure (usb_utr_t), request information, and control transfer stage information. Note that the class request processing function is called at the data stage and the status stage. A sample class request processing function is shown below. <Example class request processing function > void usb_psmp_controltransfer(usb_request_t* request, uint16_t ctsq) g_usb_psmp_request = request; if ((g_usb_psmp_request.wrequest & USB_BMREQUESTTYPETYPE) == USB_CLASS) switch( ctsq ) /* Idle or setup stage */ case USB_CS_IDST usb_psmp_control_trans0(request); break; /* Control read data stage */ case USB_CS_RDDS usb_psmp_control_trans1(request); break; /* Control write data stage */ case USB_CS_WRDS usb_psmp_control_trans2(request); break; /* Control write nodata status stage */ case USB_CS_WRND usb_psmp_control_trans3(request); R_USB_pstd_ControlEnd((uint16_t)USB_CTRL_END); break; /* Control read status stage */ case USB_CS_RDSS usb_psmp_control_trans4(request); R_USB_pstd_ControlEnd((uint16_t)USB_CTRL_END); break; /* Control write status stage */ case USB_CS_WRSS usb_psmp_control_trans5(request); R_USB_pstd_ControlEnd((uint16_t)USB_CTRL_END); break; /* Control sequence error */ case USB_CS_SQER R_USB_pstd_ControlEnd((uint16_t)USB_DATA_ERR); break; /* Illegal */ default R_USB_pstd_ControlEnd((uint16_t)USB_DATA_ERR); break; else R_USB_pstd_SetStallPipe0(); R01AN2166EJ0102 Rev.1.02 Page 36 of 94

37 1. Data stage processing If the received request is supported, use the R_usb_pstd_ControlRead() and R_usb_pstd_ControlWrite() APIs to perform data transfer with the host. If the request is not supported, call the R_usb_pstd_SetStall() API to return a STALL response to the host. 2. Status stage processing If the data stage ends properly, call the API R_usb_pstd_ControlEnd() and specify USB_CTRL_END as the status argument. If the data stage does not end properly, specify instead SB_DATA_ERR. *USBBASICF/W accesses the user buffer up to the data size specified with API function R_usb_pstd_ControlRead()/R_usbh_pstd_ControlWrite(). Therefore, make sure that the capacity of the user buffer exceeds the transmit / receive data size specified in the control transfer data stage. R01AN2166EJ0102 Rev.1.02 Page 37 of 94