ug_usb20hr_halapi_2.1

ug_usb20hr_halapi_2.1 - USB20HR Nios II HAL API User Guide...

Info iconThis preview shows page 1. Sign up to view the full content.

View Full Document Right Arrow Icon
This is the end of the preview. Sign up to access the rest of the document.

Unformatted text preview: USB20HR Nios II HAL API User Guide System Level Solutions, Inc. (USA) 14100 Murphy Avenue San Martin, CA 95046 (408) 852 - 0067 HAL API Version: http://www.slscorp.com Document Date: Document Version: 2.0.1 2.1 May 2009 IP Usage Note The Intellectual Property (IP) core is intended solely for our clients for physical integration into their own technical products after careful examination by experienced technical personnel for its suitability for the intended purpose. The IP was not developed for or intended for use in any specific customer application. The firmware/software of the device may have to be adapted to the specific intended modalities of use or even replaced by other firmware/software in order to ensure flawless function in the respective areas of application. Performance data may depend on the operating environment, the area of application, the configuration, and method of control, as well as on other conditions of use; these may deviate from the technical specifications, the Design Guide specifications, or other product documentation. The actual performance characteristics can be determined only by measurements subsequent to integration. The reference designs were tested in a reference environment for compliance with the legal requirements applicable to the reference environment. No representation is made regarding the compliance with legal, regulatory, or other requirements in other environments. No representation can be made and no warranty can be assumed regarding the suitability of the device for a specific purpose as defined by our customers. SLS reserves the right to make changes to the hardware or firmware or software or to the specifications without prior notice or to replace the IP with a successor model to improve performance or design of the IP. Of course, any changes to the hardware or firmware or software of any IP for which we have entered into an agreement with our customers will be made only if, and only to the extent that, such changes can reasonably be expected to be acceptable to our customers. Copyright©2005-2009, System Level Solutions, Inc. (SLS) All rights reserved. SLS, an Embedded systems company, the stylized SLS logo, specific device designations, and all other words and logos that are identified as trademarks and/or service marks are, unless noted otherwise, the trademarks and service marks of SLS in India and other countries. All other products or service names are the property of their respective holders. SLS products are protected under numerous U.S. and foreign patents and pending applications, mask working rights, and copyrights. SLS reserves the right to make changes to any products and services at any time without notice. SLS assumes no responsibility or liability arising out of the application or use of any information, products, or service described herein except as expressly agreed to in writing by SLS. SLS customers are advised to obtain the latest version of specifications before relying on any published information and before orders for products or services. ug_ipusb20hr_halapi_2.1 ii USB20HR Nios II HAL API User Guide System Level Solutions May 2009 About this Guide Introduction The document provides information on how to use USB20HR Nios II HAL driver API and steps to create application. Table below shows the revision history of this user guide. Version Date Description 2.1 • Updated document as per USB20HR API version 2.0.1. 2.0 January 2009 • Updated document as per USB20HR API version 2.0.0 1.4 March 2008 • Replaced USB 2.0 with USB20HR 1.3 September 2007 • Added code for the board, Modified version history & Document part no. Modified the API Function Example. 1.2 March 2007 Second publication of USB2.0 NIOS Programmer’s Guide 1.1 How to find Information May 2009 April 2006 First Publication of the USB2.0 Nios Programmer’s Guide The Adobe Acrobat Find feature allows you to search the contents of a PDF file. Use Ctrl + F to open the Find dialog box. Use Shift + Ctrl + N to open to the Go To Page dialog box. Bookmarks serve as an additional table of contents. • Thumbnail icons, which provide miniature preview of each page, provide a link to the pages. • System Level Solutions May 2009 • Numerous links shown in Navy Blue color allow you to jump to related information. iii USB20HR Nios II HAL API User Guide How to Contact SLS How to Contact SLS For the most up-to-date information about SLS products, go to the SLS worldwide website at http://www.slscorp.com. For additional information about SLS products, consult the source shown below. Information Type E-mail Product literature services, SLS liter- support@slscorp.com ature services, Non-technical customer services, Technical support. Typographic Conventions The user guide uses the typographic conventions as shown below: Visual Cue Meaning Bold Type with Initial Capital letters All headings and Sub headings Titles in a document are displayed in bold type with initial capital letters; Example: Creating a Project, Building and Managing Project. Bold Type with Italic Letters All Definitions, Figure and Example Headings are displayed in Italics. Examples: Example1-1. Read Byte from SLSUSB Device, Figure 2-1. Creating a New Project 1., 2. Numbered steps are used in a list of items, when the sequence of items is important. such as steps listed in procedure. • Bullets are used in a list of items when the sequence of items is not important. The hand points to special information that requires special attention The caution indicates required information that needs special consideration and understanding and should be read prior to starting or continuing with the procedure or process. iv USB20HR Nios II HAL API User Guide System Level Solutions May 2009 Visual Cue Meaning The warning indicates information that should be read prior to starting or continuing the procedure or processes. The feet direct you to more information on a particular topic. System Level Solutions May 2009 v USB20HR Nios II HAL API User Guide Contents About this Guide ................................................................................................................ iii Introduction ..............................................................................................................................................iii How to find Information ..........................................................................................................................iii How to Contact SLS ................................................................................................................................iii Typographic Conventions ........................................................................................................................ iv 1. HAL API Reference ................................................................................................................... 1 usb20hr_config() ...................................................................................................................................... 2 usb20hr_ep_config() ................................................................................................................................ 4 usb20hr_with_dma_read() ....................................................................................................................... 6 usb20_without_dma_read() ..................................................................................................................... 7 usb20hr_with_dma_write() ...................................................................................................................... 9 usb20hr_without_dma_write ................................................................................................................. 10 usb20hr_check_bo_ready ....................................................................................................................... 12 usb20hr_check_bi_ready ....................................................................................................................... 13 usb20hr_connect() .................................................................................................................................. 14 usb20hr_disconnect() ............................................................................................................................. 15 dma_used() ............................................................................................................................................. 16 System Level Solutions v 1. HAL API Reference The USB20HR device driver has implemented functions which are used to communicate with USB 2.0 device. It is implemented on Nios II platform. This driver is designed to support device configuration with INTERRUPT, BULK IN/OUT and CONROL endpoint. All calls for read and write operation are blocking calls for USB20HR device driver. Therefore, whenever read/write call will be made, check the status of particular end point whether it is ready or not and then got for read/write operation. Read function will not return until the requested data is available from USB 2.0 Device. Same for the write, whenever any write call will be issued, it will try to write the data until the hardware (USB2.0 device) buffer is empty. As soon as the hardware buffer gets full, the write function will wait until the buffer empty. Once requested data is written, it will return to the requester with no of bytes sent. Whatever data the user wants just make a pointer of that size in the application file on Nios side so that it will get the data from the IP's buffer up to the number of bytes that user defines. The section below explains the API functions. System Level Solutions May 2009 1 USB20HR Nios II HAL API User Guide HAL API Reference usb20hr_config() Protocol: int usb20hr_config(struct sls_avalon_usb20hr_dev* usbdev, volatile int usb_base, volatile int usb_irq, const char *usb_name, int dma_base, void *usb_event); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: Returns 1 on success otherwise 0. Description: The usb20hr_config function registers USB IRQ in to the system. It also initializes the USB Device name, USB Device base address, DMA address, USB IRQ, function pointer for USB events. It is required to pass a function pointer in this function for error notification at application level. Table 1-1. Parameter Description Parameter Description usbdev USB device Structure usb_base USB device base address usb_irq USB device IRQ value usb_name Name of USB device in to system dma_base Base address of DMA used in system with USB device usb_event Function pointer of USB event notification Example: struct sls_avalon_usb20hr_dev usbdev; if(usb20hr_config(&usbdev,USB20HR_0_BASE,USB20HR_0_IRQ, USB20HR_0_NAME,DMA_BASE,NULL)) { printf("\nCONFIG DONE SUCCESSFUL"); usb20hr_connect(&usbdev); } System Level Solutions May 2009 2 USB20HR Nios II HAL API User Guide if(usb20hr_config(&usbdev,USB20HR_0_BASE,USB20HR_0_IRQ, USB20HR_0_NAME, DMA_BASE,(int *)&(usb20hr_event))) { printf("\nCONFIG DONE SUCCESSFUL"); usb20hr_connect(&usbdev); } usb20hr_event is a callback function. If any event occurs on USB device, HAL driver calls this function to notify to the user. It only covers basic events. To know more about basic events, refer PortInterface.c file located at <USB20HR Installation path>\embedded\example\niosII\portinterface. Two separate DMA connection for Bulk-In and Bulk-Out is not supported in current version of HAL driver. For such requirement, please contact support@slscorp.com. 3 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference usb20hr_ep_config() Protocol: int usb20hr_ep_config (struct sls_avalon_usb20hr_dev* usbdev,char ep_no,char ep_type,int ep_buf_size_fs, int ep_buf_size_hs,char ep_direction); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: Status of end point configuration. Description: The usb20hr_ep_config() function configures the USB end points. Table 1-2. Parameter Description Parameter Description usbdev USB device Structure ep_no Endpoint number to which ep configuration happen ep_type Type of EndPoint ep_buf_size_fs Full speed endpoint buffer size ep_buf_size_hs High speed endpoint buffer size ep_direction Direction of endpoint (IN/OUT) The buffer size shouldn’t be exceed then the size of Bulk-IN or Bulk-Out parameters specified in SOPC builder. If user enters wrong buffer size, driver may not handle it properly due to un-sufficient data space. For example, if user takes 2048 bytes of memory for Bulk-in endpoint then the HAL driver will divide the memory in to two equal size to allocate to buffer 0 and buffer 1. The endpoint buffer size for High speed is recommended in multiple of maximum packet size. For full speed operation, 128 bytes of buffer size is recommended for endpoint. This function also takes ep_no and ep_type to configure the USB IP. User must has to pass exact end point number to configure endpoint. At present, the HAL driver supports only BULK, INT type of endpoint. System Level Solutions May 2009 4 USB20HR Nios II HAL API User Guide Example: struct sls_avalon_usb20hr_dev usbdev; usb20hr_ep_config (&usbdev,1,BULK,128,2048,IN);//pass this arguments to configure BULK IN endpoint. usb20hr_ep_config (&usbdev,2,BULK,128,2048,OUT);//pass this arguments to configure BULK OUT endpoint. 5 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference usb20hr_with_dma_read() Protocol: int usb20hr_with_dma_read(struct sls_avalon_usb20hr_dev *usbdev,unsigned char ep_no,unsigned char *ptr,int size); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: This function reads data fromUSB2.0 device and returns number of bytes read successfully. Description: The usb20_with_dma_read() function reads a block of data from Bulkout endpoint. This function internally use DMA for data copy and it will be blocked until requested size of data is not read. The input argument,ptr, is the location from where data will be copied from the device and size is the length of data to read in bytes. Table 1-3. Parameter Description Parameter Description usbdev ep_no Endpoint number of Bulk-out endpoint ptr Destination address at where data will be copied from Bulk-out endpoint’s buffers Size System Level Solutions May 2009 USB device Structure Number of byte to read 6 USB20HR Nios II HAL API User Guide usb20_without_dma_read() int usb20hr_without_dma_read(struct sls_avalon_usb20hr_ dev *usbdev,unsigned char ep_no,unsigned char *ptr,int size); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: This function reads data fromUSB2.0 device and returns number of bytes read successfully. Description: The usb20_without_dma_read() function reads a block of data from Bulk-out endpoint. The input argument,ptr, is the location from where data will be copied from the device and size is the length of data to read in bytes. Internally this function will be blocked until requested size of data is not read. Table 1-4. Parameter Description Parameter Description usbdev ep_no Endpoint number of Bulk-out endpoint ptr Destination address at where data will be copied from Bulk-out endpoint’s buffers Size Example: USB device Structure Number of byte to read An example of usb20_with_dma_read() function is given below: For usb20_without_dma_read(), use same method shown in example. 7 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference Example 1-1. Reads Data from USB 2.0 Device u n s i gn e d c h a r r e a d _ b uf f [ 7 0 0 ] ; / / a p p l i ca t i o n d at a s t o r ag e b u f f er . i n t co u n t = 7 0 0; / / n u m be r o f b yt e s t o b e r e a d . char ERROR=0; i n t re a d _ c o u nt = 0 ; s t r u ct s l s _ a va l o n _ u s b2 0 h r _ d e v u s b d e v ; S t r u c t u re o f U S B d e v i c e ER R O R = u s b2 0 h r _ e p _c o n f i g (& u s b d e v , 1, B U L K , 1 28 , 1 0 2 4 , IN ) ; ER R O R = u s b2 0 h r _ e p _c o n f i g (& u s b d e v , 2, B U L K , 1 28 , 1 0 2 4 , OU T ) ; i f ( u sb 2 0 h r _ c on f i g ( & u sb d e v , U S B2 0 H R _ 0 _ B AS E , U S B 2 0H R _ 0 _ I R Q, U S B 2 0 H R_ 0 _ N A M E ,D M A _ B A S E, ( i n t * )& ( u s b 2 0 hr _ e v e n t ) )) { / / p r in t f ( " \ n CO N F I G D ON E S U C C U SS F U L " ) ; u s b 2 0h r _ c o n n ec t ( & u s b de v ) ; } / * C al l R e a d A P I t o re a d d a t a f r o m s l su s b 2 . 0 de v i c e * / i f ( u sb 2 0 h r _ c he c k _ b o _ re a d y ( & u sb d e v , 2 ) > =0 ) r e ad _ c o u n t = u s b 2 0 hr _ w i t h _ d ma _ r e a d ( &u s b d e v , 2, b u f , D A TA ) ; p r i n tf ( " N o o f b y t e s re a d f r o m S L S U S B 2 .0 % d \ n " ,r e a d _ c o un t ) ; System Level Solutions May 2009 8 USB20HR Nios II HAL API User Guide usb20hr_with_dma_write() Protocol: int usb20hr_with_dma_write(struct sls_avalon_usb20hr_dev *usbdev,unsigned char ep_no,unsigned char *ptr,int size); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: This function writes data to USB2.0 device and returns number of bytes written successfully. Description: The usb20_with_dma_write() function writes a block of data to Bulk-in endpoint. The input argument,ptr, is the location from where data will be written in to device and size is the length of data to be written in bytes. Internally this function will use DMA to copy data and it will be blocked until requested size of data is not written. Table 1-5. Parameter Description Parameter Description usbdev USB device Structure ep_no Endpoint number of Bulk-in endpoint ptr Source address from where data will copy in to Bulk-in endpoint’s buffers Size Number of byte to write 9 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference usb20hr_without_dma_write Protocol: int usb20hr_without_dma_write(struct sls_avalon_usb20hr_ dev *usbdev,unsigned char ep_no,unsigned char *ptr,int size); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: This function writes data to USB2.0 device and returns number of bytes written successfully. Description: The usb20hr_without_dma_write() function writes a block of data to Bulk-in endpoint. The input argument,ptr, is the location from where data will be written in to device and size is the length of data to be written in bytes. Internally this function will be blocked until requested size of data is not written. Table 1-6. Parameter Description Parameter Description usbdev ep_no Source address from where data will copy in to Bulk-in endpoint’s buffers Size System Level Solutions May 2009 Endpoint number of Bulk-in endpoint ptr Example: USB device Structure Number of byte to write An example of usb20hr_with_dma_write() function is given below: For usb20_without_dma_write(), use same method shown in example 10 USB20HR Nios II HAL API User Guide Example 1-2. Write Data to the USB2.0 Device unsigned char write_buff[512]; //application data storage buffer. int count=512; //Stores number of bytes to write. int write_count=0; struct sls_avalon_usb20hr_dev usbdev; Structure of USB device ERROR=usb20hr_ep_config (&usbdev,1,BULK,128,2048,IN); ERROR=usb20hr_ep_config (&usbdev,2,BULK,128,2048,OUT); if(usb20hr_config(&usbdev,USB20HR_0_BASE,USB20HR_0_IRQ,USB 20HR_0_NAME,DMA_BASE,(int *)&(usb20hr_event))) { //printf("\nCONFIG DONE SUCCUSSFUL"); usb20hr_connect(&usbdev); } /* Call Read API to read data from slsusb2.0 device*/ if(usb20hr_check_bi_ready(&usbdev,1)>=0) write_count = usb20hr_with_dma_write(&usbdev,1,buf,DATA); printf("No of bytes read from SLSUSB2.0 %d\n", write_count); 11 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference usb20hr_check_bo_ready Protocol: int usb20hr_check_bo_ready (struct sls_avalon_usb20hr_dev* usbdev,char ep_no); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: Returns -1 when no data in bulk out end point, otherwise returns Number of Bytes that are stored in the end point buffer. Description: The usb20hr_check_bo_ready function checks whether HOST has sent any data to Bulk-out endpoint or not. If host has sent data to the device, this function returns no. of bytes. So that user can call usb20hr_with_dma_read/usb20hr_without_dma_read function. Table 1-7. Parameter Description Parameter Description usbdev ep_no Example: USB device Structure Endpoint number of Bulk-out endpoint read_count=usb20hr_check_bo_ready(&usbdev,2) read_bytes=usb20hr_with_dma_read(&usbdev,2,buf, read_count); System Level Solutions May 2009 12 USB20HR Nios II HAL API User Guide usb20hr_check_bi_ready Protocol: extern int usb20hr_check_bi_ready (struct sls_avalon_usb20hr_dev* dev, char ep_no); Commonly called by: C/C++ programs Include: <sls_avalon_usb20hr.h> Return: The return value is -1 if data is not available in bulk in end point and 1 otherwise. Description: The usb20hr_check_bi_ready function checks whether HOST has received any data from Bulk- in endpoint or not. If host has not received any data, this function returns -1 so user does not need to submit another write from the device side which indicates that there is data in bulk in endpoint. If it returns value 1, user can submit write routine. Table 1-8. Parameter Description Parameter Description usbdev ep_no Example: USB device Structure Endpoint number of Bulk-in endpoint if(usb20hr_check_bi_ready(&usbdev,1)>=0) { write_count=usb20hr_with_dma_write(&usbdev,1,buf,DATA); } 13 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference usb20hr_connect() Protocol: void usb20hr_connect(struct sls_avalon_usb20hr_dev* usbdev); Commonly called by: C/C++ Programs Include: <sls_avalon_usb20hr.h> Return: – Description: The usb20hr_connect() function is used for enumerating device to host. Without this function, enumeration of device is not possible. After enumerating the device, user can perform read/write on device. Table 1-9. Parameter Description Parameter usbdev Example: Description USB device Structure An example of usb20hr_connect() function is given below: usb20hr_connect(&usbdev); System Level Solutions May 2009 14 USB20HR Nios II HAL API User Guide usb20hr_disconnect() Protocol: void usb20hr_disconnect(struct sls_avalon_usb20hr_dev* usbdev); Commonly called by: C/C++ Programs Include: <sls_avalon_usb20hr.h> Return: – Description: The usb20hr_disconnect() function is used to disconnect device from host. If user wants to perform read/write, then they have to re- enumerate the device and for that user has to use usb20hr_connect() to start enumeration of device. Table 1-10.Parameter Description Parameter usbdev Example: Description USB device Structure An example of usb20hr_disconnect()function is given below: usb20hr_disconnect(&usbdev); 15 USB20HR Nios II HAL API User Guide System Level Solutions May 2009 HAL API Reference dma_used() Protocol: void dma_used(struct sls_avalon_usb20hr_dev* usbdev, unsigned int dma_base); Commonly called by: C/C++ Programs Include: <sls_avalon_usb20hr.h> Return: – Description: The dma_used() function enables DMA inside the API by passing the dma_base address, if DMA is defined inside SOPC system. If SOPC design includes more than one DMA then pass the address of the DMA that you want to use in the dma_base address for USB transcation. If DMA is used in SOPC design, set the macro, _DMA_USE, to 1 otherwise set to 0. for e.g. Make following changes in the sls_avalon_usb20hr.h. file. #define _DMA_USE 1 // If DMA is used #define _DMA_USE 0 // If DMA is not used Table 1-11. Parameter Description Parameter Description usbdev dma_base Example: USB device Structure DMA base address An example of usb20hr_disconnect()function is given below: dma_used(&usbdev, dma_base); System Level Solutions May 2009 16 USB20HR Nios II HAL API User Guide ...
View Full Document

Ask a homework question - tutors are online