View AN1325_8128086.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

AN1325 / 0203 1/15 AN1325 application note using the st7 usb low-speed library v4.2x by microcontroller division applications this application note describes how to use the st7 usb low-speed library v4.2x. starting from version 4.20 the library supports the dfu class layer. caution: the dfu class and the hid class layers are not included in the library. the library contains only the standard usb request layers. you will find the dfu and hid layers in the st7 usb low-speed dfu evalkit firmware. note: in this document the names hiware and metrowerks refer to the same compiler manufacturer. 1 overview the st7 usb low-speed firmware library is written in c language and is compatible with both cosmic and metrowerks compilers. this library provides a complete usb protocol layer for the st7 usb low-speed microcon- trollers (such as the st7261, st7262, st7263 and st7263b). the source code is available free to stmicroelectronics customers. this library is supplied in a zip file. starting from version 4.10, the library contains only the files that are common for all the projects. this new architecture has been choosen in order to better separate what is really the library and what is related to a project. this architecture will also facilitate the upgrade of different projects with new library versions in the future. 1
2/15 using the st7 usb low-speed library v4.2x 2 library 2.1 directories architecture the files which compose the library are placed into 4 distinct directories : docs , macro , micro , and usb : st7usbls-library-v4.2x/ |--- docs/ |--- macro/ |--- micro/ |--- usb/ the files inside these directories cannot be used alone. you have to use them within a project. to do so, you have to include in your project setting files the path of these directories (mak file for cosmic and default.env for metrowerks). this way you will be able to use easily the same library for different projects. example in a mak file for cosmic : macro_path = d:\st7usbls-library-v4.2x\macro micro_path = d:\st7usbls-library-v4.2x\micro usb_path = d:\st7usbls-library-v4.2x\usb example in default.env file for metrowerks : genpath=\ d:\st7usbls-library-v4.2x\macro;\ d:\st7usbls-library-v4.2x\micro;\ d:\st7usbls-library-v4.2x\usb ; normally there is no need to change any of the files present in these directories. all the changes must be done inside your project files. the following chapters will explain in detail the content of all this directories. 2
3/15 using the st7 usb low-speed library v4.2x 2.2 docs directory this directory contains all documentations related to the library: releasenote.txt, flowchart, etc... 2.3 macro directory this directory contains all the files containing the macro definitions shared between the li- brary and the different projects. it contains also the unicode table used for the definition of the string descriptors. for example you will find the description of enableinterrupts and disa- bleinterrupts macro. all these files are common for cosmic and metrowerks compilers with the exception of the hidef.h file wich is used only for metrowerks. 2.4 micro directory this directory contains all the files which are related to the microcontrollers. you will find here all the map files for the st726x microcontrollers family (st7261, st7262, st7263 and st7263b) . all these map files are common for cosmic and metrowerks compilers. important note : for metrowerks, all the h/w registers addresses are written inside the prm files of each project. for cosmic, all these informations are written directly inside the map files. 2.5 usb directory this directory contains the usb library core files for cosmic and metrowerks compilers. these file dont need to be changed by the customer. this usb library can be seen as a toolbox where the application picks up the tools it needs (calls the functions it needs). note that there is no callback functions from the library (the user doesnt need to create specific functions that could be called by the library). 2.6 usb core files all the following files are placed inside usb directory. these files are really what we call the library.
4/15 using the st7 usb low-speed library v4.2x the 2 assembly files (usb_jumptable_xxx.asm) contain a jump table used by the application to access the library functions. these files are only used for dfu. 2.7 files organization as you can see on this chart : usb_lib.h and usb_def.h are the only files from the library that your project needs to refer to. file description usb.c library core functions usb.h library core prototypes usb_def.h description of all aliases and variables shared between the library and the application layer usb_rwu.c remote wake-up functions usb_rwu.h prototypes for remote wake-up functions usb_lib.c library functions to be called by application layer code usb_lib.h prototypes of all the library functions to be called by the application layer code usb_rc.c hardware abstraction layer usb_rc.h prototypes for hardware abstraction layer usb_var.c library variables declaration usb_var.h prototypes for library variables usb_jumptable_cosmic.asm contains jump to usb functions (for dfu only) usb_jumptable_hiware.asm contains jump to usb functions (for dfu only) application code (main.c, hid_layer.c, user_var.c, ...) usb_lib.h usb_def.h usb_rc.c usb.c
5/15 using the st7 usb low-speed library v4.2x 3 project this chapter describes an example of a project architecture. you are not obliged to follow this architecture to use the usb low-speed library. 3.1 directories architecture the project directories architecture has been simplified. you will now have only the following directories : projectname/ |--- docs/ |--- appli/ |--- config/ |--- cosmic/ |--- hiware/ |--- objects/ |--- cosmic/ |--- hiware/ |--- st7usbls-library-v4.2x / 3.2 docs directory this directory contains all documentations related to the project. you can use this directory to put all your project documents. 3.3 appli directory all the application-specific files have to be located inside this directory. here is a description of the files that are in this directory initially: file name description main.c main.h entry module. calls the initialization functions and contains the infinite loop. descript.c descript.h usb descriptor files for the application: you have to modify them according to your application (the initial values filled in apply to the library firmware).
6/15 using the st7 usb low-speed library v4.2x 3.4 config/cosmic directory in this directory are placed all files that are used for the cosmic compiler only. you will find all the mak and lkf files for all the st7 usb low-speed microcontrollers. you will find also and the interrupt vector files. the content of these files is given as an example and must be up- dated according to your project. 3.5 config/hiware directory same as the previous directory excepted that it is for metrowerks compiler only. you will find the mak and prm files for all the st7 usb low-speed microcontrollers. you will find also the default.env file which contains all the paths description, and the burner.cmd file used to create a s19 file. same as above, the content of these files is given as an example and must be up- dated according to your project. 3.6 objects/cosmic and objects/hiware directories in this directory you will find all the output files coming from the different tools (compiler, linker, etc...). 3.7 st7usbls-library-v4.2x directory this directory contains the library files described in the beginning of this document. int_726x.c all the interrupt routines for your application have to be in one of these files (de- pends on the selected microcontroller). my_init.c my_init.h your initialisation routines (optional). user_var.c user_var.h declaration of all variables related to your application (optional). usb_app.c usb_app.h contains non standard usb requests. for example you will find the function handle_app_requests which interacts with the library to handle requests that are directed at the application. hidlayer.c hidlayer.h hid specific functions (like handle_hid_requests, get_output & set_feature). dfulayer.c dfulayer.h dfu specific functions (like handle_dfu_requests). usb_opts.h it is the means by which optional usb library code and functionality is selected for compilation and use by the application. it is also the place for application-spe- cific parameters such as the lengths of input and output reports (but not for de- scriptors - see descript.c/.h). user_def.h declaration of your compilation directives. file name description
7/15 using the st7 usb low-speed library v4.2x 4 shared variables and functions as shown in figure 1, the usb protocol firmware, (which you do not have to modify) uses a certain number of variables and functions which you can also use in your application source files (appli directory). these variables and functions are also used in the data transfer func- tions and interrupt routines. figure 1: interdependancy of usb variables and functions shared variables shared functions usb bus user software init usb polling (usb protocol) usb application
8/15 using the st7 usb low-speed library v4.2x 4.1 shared variables here is a description of the variables shared between the usb library and the application code layer :. variable declaration/ aliases description usblibstatus usb_var.c usb_def.h used to exchange usb status information between the library and the application. possible values are : product1 (0x01) : always defined product2 (0x02) : alternate product dfu_mode (0x40) : dfu code loader device app_request (0x08) : set by library w hen a non standard re- quest has been received on ep0 usb_stall (0x10) : set by application to stall a non standard request usb_suspend (0x20) : set by library when suspended mode is requested usb_remote_wakeup_enable (0x40) : set by library when host enables the remote wakeup usb_configured (0x80) : set by library when host config- ured the peripheral usbtransferstatus usb_var.c usb_var.h specifies the current control transfer transaction stages. pos- sible values are : no_data_stage (0x01) : an in status will follow the setup to- ken data_stage_in (0x02) : transfer with in data phase data_stage_out (0x04) : transfer with out data phase one_more (0x08) : last data in transfer before status out address2set (0x10) : device address set_tx0_valid (0x20) : request to set ep0 tx buffer to valid set_rx0_valid (0x40) : request to set ep0 rx buffer to valid usbbmrequesttype usb_var.c usb_var.h contains the characteristic of the request sent by the host. re- fer to usb spec ver 1.1, chap 9.3, page 183 for more informa- tions. possible values are : recipient (0x03) redevice (0x00) reinterface (0x01) reendpoint (0x02)
9/15 using the st7 usb low-speed library v4.2x 4.2 shared functions the table below shows all the functions shared between the library and the application. some functions have been written especially to transfer data over the usb. in order to improve the flexibility and control over the usb flow some functions have been changed compared to the library version 3. these new functions will allow also to build a report directly into the end- point buffer in case the ram size is critical. the most important functions are described in de- tail below. usbbrequest usb_var.c usb_def.h specific request. refer to usb spec ver 1.1, chap 9.3, page 183. possible values are : get_status, clear_feature_stall, set_feature_stall, set_address, get_descriptor, set_descriptor, get_configuration, set_configuration, get_interface, set_interface usbwvalue[2] usb_var.c word-sized field that varies from request. it is used to pass a pa- rameter to the device, specific to the request. refer to usb spec ver 1.1, chap 9.3, page 183. usbwindex usb_var.c word-sized field that varies from request. typically used to pass an index or offset. refer to usb spec ver 1.1, chap 9.3, page 183. usbwlength usb_var.c number of bytes to transfer if there is a data stage. refer to usb spec ver 1.1, chap 9.3, page 183 usbdataxferstatus usb_var.c usb_def.h used to send and receive more than 8 bytes for hid requests (i.e. setfeature, getfeature, etc.) function file description init_usb_hw usb_lib.c switch on the usb cell (connect the peripheral to the bus) and initialize library variables. disable_usb_hw usb_lib.c switch off the usb cell (disconnect the peripheral from the bus) and reset library variables. handle_usb_events usb_lib.c manage usb flow (interrupts) on endpoint0 and process standard requests only. manage also all re- quests for hid class descriptors (hid, report or physical). its also responsible for stalling all un- supported and invalid usb requests. enable_status_stage usb_lib.c allow st7 to ack or stall incoming status stage after completion of a non standard request. this function is called by application once the app_requests processing is done in the handle_app_r equests function. variable declaration/ aliases description
10/15 using the st7 usb low-speed library v4.2x test_ep_ready usb_lib.c check if the endpoint buffer (passed as argument) is ready to be written or read. return true if the end- point is ready. for in direction (st7 to host) ready means the buffer has been sent and is available for sending new data. for out direction (host to st7) ready means the buffer contains new data to be read. set_ep_ready usb_lib.c this function informs the library that there is data in the epxinbuffer ready to be sent (in direction) or that the application has read/consumed the data in the epxoutbuffer (out direction). for in direction (st7 to host) update the transmit byte counter and set eptx to valid. for out direc- tion (host to st7) set the eprx to valid and ignore the data length passed as argument. write_ep_buffer usb_lib.c write the data (pointer passed as argument) into the usb dma ram transmit buffer of the selected end- point. read_ep_buffer usb_lib.c read data from the usb dma ram receive buffer into the data (pointer passed as argument). do_usb_remotewu usb_rwu.c send a complete remote wakeup signaling se- quence to the host (reset usb_suspend flag). while sending the resume signaling, all interrupts are disable for 10ms (due to k state that must be main- tain). if you dont want all interrupts to be masked for 10ms, when exiting suspend, use the start_usb_remotewu and stop_usb_remotewu functions instead (see be- low). start_usb_remotewu usb_rwu.c start a remote wakeup signaling to the host. take care that application code must call the stop_usb_remotewu function after a 10ms de- lay. stop_usb_remotewu usb_rwu.c end the remote wakeup signaling initiated by the start_usb_remotewu function. reset also the usb_suspend flag. function file description
11/15 using the st7 usb low-speed library v4.2x 4.2.1 handle_usb_events function most of the work of the usb library is performed by this function and the private usb library functions that it calls. the events to be handled are the assorted usb interrupts that may occur as a result of usb transaction or changes in the state of the bus. the interrupt service routine (int_usb) copies the event information to a variable (usbctrflag) where the handle_usb_events function can access it. the event processing occurs when this function is called from the main loop of the application. this function is responsible for handling all standard (chapter 9) requests as well as all re- quests for hid class descriptors (hid, report or physical). it is also responsible for stalling all unsupported (as indicated via the switches in usb_opts.h) and invalid usb requests. note: some usb requests will require attention from the application side of the code (non- descriptor hid requests and all vendor-specific requests). these requests are addressed in the application function do_app_requests. figure 2: handle_usb_events architecture ? return yes no void handle_usb_events (void) correct it transfer by h/w detected on ep0 [setup or in or out] process the correct it transfer re-enable transmission/reception on endpoint0 on endpoint0
12/15 using the st7 usb low-speed library v4.2x 4.2.2 test_ep_ready function figure 3: test_ep_ready architecture bool test_ep_ready (endpoint, direction) ep0 ? in ? data sent? data received? yes yes yes yes no return true return false no return true return false no ep1 ? in ? data sent? data received? yes yes yes yes no return true return false no return true return false no ep2 ? in ? data sent? data received? yes yes yes yes no return true return false no return true return false no return false no no no in = st7 to host out = host to st7 data sent or received ? = status nak ?
13/15 using the st7 usb low-speed library v4.2x 4.2.3 . set_ep_ready figure 4: set_ep_ready architecture 4.3 functions already available for hid class you will find the following functions in the file hidlayer.c (in appli directory) : note: they are given as example only and are not part of the usb core library. function description handle_hid_requests decode human interface device requests. get_output build output report (mandatory if output usage is defined). get_input build input report (mandatory if input usage is defined). get_feature build feature report (mandatory if feature usage is defined). set_feature process feature report. set_output process output report. void set_ep_ready (endpoint, direction, length) ep0 ? in ? yes yes no enable ep0 for next in token : set number of data to send set ep0 valid for transmission enable ep0 for next out token : set ep0 valid for reception ep2 ? in ? yes yes no ep1 ? in ? yes yes no return no no no enable ep1 for next in token : set number of data to send set ep1 valid for transmission enable ep1 for next out token : set ep1 valid for reception enable ep2 for next in token : set number of data to send set ep2 valid for transmission enable ep2 for next out token : set ep2 valid for reception
14/15 using the st7 usb low-speed library v4.2x 5 how to start a new application 1. make a copy of the complete evaluationkit project. give an appropriate name to this new directory. 2. remove all the parts that concern the evalkit application (modification in applet.c, main.c, hidlayer.c, int_xxx, ...). 3. create a new workspace and select the mak file corresponding to the device you are using. 4. modify the toolchain configuration files (mak, prm, lkf etc...). 5. modify the file usb_opts.h (in appli/includes directory) according to your application needs. 6. modify the files descript.c and descript.h (in appli directory) with your own descriptors. dont forget to put your own vendor id (assigned by the usb-if). 7. add your application in the file main.c (in appli directory) inside the endpoint 1 & 2 man- agement section. build your report_in and send data or receive data and process the report_out). you can also create new files. 8. process the non-standard requests (vendor and class) in the file usb_app.c (in appli directory). 9. for hid class requests, use the hidlayer.c and hidlayer.h files (in appli directory). 10. you might want to use as well the predefined modules user_var.h and user_def.h (in applis directory). 6 other documents for further information on the dfu please refer to the following documents : - an1577 device firmware upgrade (dfu) for st7 usb devices
15/15 using the st7 usb low-speed library v4.2x the present note which is for guidance only aims at providing customers with information regarding their products in order for them to save time. as a result, stmicroelectronics shall not be held liable for any direct, indirect or consequential damages with respect to any claims arising from the content of such a note and/or the use made by customers of the information contained herein in connection with their products. information furnished is believed to be accurate and reliable. however, stmicroelectronics assumes no responsibility for the co nsequences of use of such information nor for any infringement of patents or other rights of third parties which may result from its use. no license is granted by implication or otherwise under any patent or patent rights of stmicroelectronics. specifications mentioned in this publicati on are subject to change without notice. this publication supersedes and replaces all information previously supplied. stmicroelectronics prod ucts are not authorized for use as critical components in life support devices or systems without the express written approval of stmicroele ctronics. the st logo is a registered trademark of stmicroelectronics ? 2003 stmicroelectronics - all rights reserved. purchase of i 2 c components by stmicroelectronics conveys a license under the philips i 2 c patent. rights to use these components in an i 2 c system is granted provided that the system conforms to the i 2 c standard specification as defined by philips. stmicroelectronics group of companies australia - brazil - canada - china - finland - france - germany - hong kong - india - israel - italy - japan malaysia - malta - morocco - singapore - spain - sweden - switzerland - united kingdom - u.s.a. http://www.st.com

▲Up To Search▲

Price & Availability of AN1325

	To Download AN1325 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .