AN1325
APPLICATION NOTE
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
by Microcontroller Division Applications
This application note descr ibes how to use th e ST 7 USB Low-Spee d Li brary 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 U SB requ est layers. Yo u will find the DF U 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 U SB L ow -S peed F irmw are Libra ry is wri tten in C l a nguage a nd is com pat ible w ith
both Cosmic and Metrowerks compilers.
This Library provides a complete USB protocol layer for the ST7 USB Low-Speed microcontrollers (such as the ST 7261, ST 7262, S T7263 and ST7263B) . The source co de is a vailable
free to STMicroelectronics customers.
This Library is supplied in a ZIP file. Star ting from version 4.10, t he 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.
AN1325/0203 1/15
1
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/15
2
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 DIRECTOR Y
This di rec tor y cont ain s a ll t he f ile s c ont ai nin g th e m a cro de fin iti on s s h are d be twe en the Li brary and the different projects. It contains also the U nicode tabl e used for the definition of the
String descriptors . For ex ample you will fi nd th e desc ription o f “Ena bleInterr upts” and “Disa bleInterrupts” mac ro. All these files are commo n for Cosmic and Metrowerks com pilers 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 t he ST726X micro controllers fam ily (ST 7261, ST 7262, ST72 63 and
ST7263B) . All these MAP files are common for Cosmic and M etrowerks comp ilers.
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 don’t 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
doesn’t 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 r eally what we call THE
Library.
3/15
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
File Description
USB.c Library core functions
USB.h Lib rary core prototypes
USB_Def.h
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
USB_Rc.c Hardware abstraction layer
USB_Rc.h Prototypes for Hardware abstraction layer
USB_Var.c Library variables declaration
USB_Var.h P rototy pes for Library variables
USB_JumpTable_Cosmic.a sm Contains Jump to USB functions (for DFU only)
USB_JumpTable_Hiware.asm Contains Jump to USB functions (for DFU only)
Description of all aliases and variables shared between
the Library and the Application layer
Prototypes of all the Library functions to be called by the
Application layer code
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 ORGANIZAT ION
Applica tion Co de
(main.c, Hid_layer.c, User_var.c, ...)
USB_Lib.h USB_Def.h
USB_Rc.c
USB.c
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.
4/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
Descript.c
Descript.h
Entry module. Calls the Initialization functions and contains the infinite loop.
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).
5/15
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
File Name Description
Int_726x.c
My_Init.c
My_Init.h
User_Var.c
User_Var.h
USB_App.c
USB_App.h
HIDlayer.c
HIDlayer.h
DFUlayer.c
DFUlayer.h
USB_Opts.h
User_Def.h Declaration of your compilation directives.
All the interrupt routines for your application have to be in one of these files (depends on the selected microcontroller).
Your initialisation routines (optional).
Declaration of all variables related to your application (optional).
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.
HID specific functions (like Handle_HID_Requests, Get_Output & Set_Feature).
DFU specific functions (like Handle_DFU_Requests).
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-specific parameters such as the lengths of Input and Output Reports (but not for descriptors - see Descript.c/.h).
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 Vecto r files . The content o f the se files is g iven as a n ex ample an d mus t 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 updated 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.
6/15
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
4 SHARED VARIABLES AND FUNCTIONS
As shown in Fi gure 1, the USB protoc ol firmwar e, ( which y ou d o no t have to mo dify) us es a
certain number of variables and functions which you can also use in your application source
files (Appli direct ory). These variables an d fu nctions a re al so us ed in the data trans fer functions and interrupt routines.
Figure 1: Interdependancy of USB Variables and Functions
User Software
Init
Shared Variables
USB polling
(USB protocol)
USB application
USB
Bus
Shared Functions
7/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
USBLibStatus
USBTransferStatus
USBbmRequestType
Declaration/
Aliases
USB_Var.c
USB_Def.h
USB_Var.c
USB_Var.h
USB_Var.c
USB_Var.h
Description
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 when 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_WAK EU P_ ENABL E (0x40) : set by Library
when host enables the remote wakeup
USB_CONFIGURED (0x80) : set by Library when host config-
ured the peripheral
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_I N (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
Contains the characteristic of the request sent by the host. Refer to USB spec ver 1.1, chap 9.3, page 183 for more informations. Possible values are :
RECIPIENT (0x03)
REDEVICE (0x00)
REINTERFACE (0x01)
REENDPOINT (0x02)
8/15
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
Variable
USBbRequest
USBwValue[2] USB_Var.c
USBwIndex USB_Var.c
USBwLength USB_Var.c
USBDataXferStatus
Declaration/
Aliases
USB_Var.c
USB_Def.h
USB_Var.c
USB_Def.h
4.2 SHARED FUNCTIONS
Description
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
Word-sized field that varies from request. It is used to pass a parameter to the device, specific to the request. Refer to USB spec
ver 1.1, chap 9.3, page 183.
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.
Number of bytes to transfer if there is a data stage. Refer to USB
spec ver 1.1, chap 9.3, page 183
Used to send and receive more than 8 bytes for HID requests
(i.e. SetFeature, GetFeature, etc.)
The table below shows all the func tions 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 functio ns will allow also to build a report directly into the EndPoint buffer in case the RAM size is critical. The most important functions are described in detail below.
Function File Description
Init_USB_HW USB_Lib.c
Disable_USB_HW USB_Lib.c
Handle_USB_Events USB_Lib.c
Enable_STATUS_St age USB_Lib.c
Switch ON the USB cell (connect the peripheral to
the bus) and initialize Library variables.
Switch OFF the USB cell (disconnect the peripheral
from the bus) and reset Library variables.
Manage USB flow (interrupts) on EndPoint0 and
process standard requests only. Manage also all requests for HID class descriptors (HID, Report or
Physical). It’s also responsible for STALLing all unsupported and invalid USB requests.
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_Requests function.
9/15
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
Function File Description
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”
Test_EP_Ready USB_Lib.c
Set_EP_Ready USB_Li b.c
Write_EP_Buffer USB_Lib.c
Read_EP_Buffer USB_Lib.c
Do_USB_RemoteWU USB_Rwu.c
Start_USB_RemoteWU USB_Rwu.c
Stop_USB_RemoteWU USB_Rwu.c
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.
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 direction (Host to ST7) set the EPRx to VALID and ignore
the data length passed as argument.
Write the data (pointer passed as argument) into the
USB DMA RAM transmit buffer of the selected EndPoint.
Read data from the USB DMA RAM receive buffer
into the data (pointer passed as argument).
Send a complete Remote WakeUp signaling sequence 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 maintain). If you don’t want all interrupts to be masked for
10ms, when exiting suspend, use the
“Start_USB_RemoteWU” and
“Stop_USB_RemoteWU” functions instead (see below).
Start a Remote WakeUp signaling to the Host. Take
care that Application code must call the
“Stop_USB_RemoteWU” function after a 10ms delay.
End the Remote WakeUp signaling initiated by the
“Start_USB_RemoteWU” function. Reset also the
USB_SUSPEND flag.
10/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 requests 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 (nondescriptor HID requests and all Vendor-specific requests). These requests are addressed in
the Application function “Do_App_Requests”.
Figure 2: Handle_USB_Events architecture
void Handle_USB_Events (void)
Cor rect IT transfer
by H/W detected
on EP0
?
NO
YES
[SETUP or IN or OUT]
Process the Correct IT Transfer
on EndPoint0
Re- e nable transmission /Reception
on EndPoint0
Return
11/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)
YES
EP0 ? IN ? Data sent?
NO
NO
YES
EP1 ? IN ? Data sent?
NO
NO
YES
EP2 ? IN ? Data sent?
YES YES
NO
Data
received?
YES YES
Data
received?
YES YES
YES
NO
NO
YES
NO
IN = ST7 to Host
OUT = Host to ST7
Data sent or received ? = status NAK ?
Return Tr u e
Return Fa lse
Return Tr u e
Return False
Return Tr u e
Return Fa lse
Return Tr u e
Return False
Return Tr u e
12/15
NO
Return False
NO
Data
received?
NO
NO
Return Fa lse
YES
Return Tr u e
Return False
4.2.3 . Set_EP_Ready
Figure 4: Set_EP_Ready architecture
Void Set_EP_Ready (EndPoint, Direction, Length)
USING THE ST7 USB LOW-SPEED LIBRARY V4.2x
EP0 ? IN ?
YES
NO
YES
EP1 ? IN ?
NO
YES
EP2 ? IN ?
NO
Return
NO
NO
NO
YES
YES
YES
Enable EP0 for next IN toke n :
set number of data to send
set EP0 V ALID for trans mission
Enable EP0 for next OUT token :
set EP0 VALID for reception
Enable EP1 for next IN toke n :
set number of data to send
set EP1 V ALID for trans mission
Enable EP1 for next OUT token :
set EP1 VALID for reception
Enable EP2 for next IN toke n :
set number of data to send
set EP2 V ALID for trans mission
Enable EP2 for next OUT token :
set EP2 VALID for reception
4.3 FUNCTIONS ALREADY AVAILABLE FOR HID CLASS
You will find the following functions in the file “HIDlayer.c” (in “Appli” directory) :
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.
Note: They are given as example only and are not part of the USB core Library.
13/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 par ts that concern the Ev alKit appl ic ation (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, LK F etc ...).
5. Mod ify th e fi le “U SB _ Op ts. h” (i n “A pp li/I ncl ud es” di re cto ry ) a c cord i ng to y ou r ap plic at ion
needs.
6. Modify the files “Descript.c” and “ Descript.h” (i n “Appli ” directory) with y our own descriptors.
Don’t 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 managemen t section ”. Build y our re port_IN a nd send da ta or rec eive da ta and p rocess the
report_OUT). You can also create new files.
8. Process the non-stand ard requests (Vendor and Cla ss) in the fi le “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
“App lis” di recto ry).
6 OTHER DO CUMENTS
For further information on the DFU please refer to the following documents :
- AN1577 “Device Firmware Upgrade (DFU) for ST7 USB devices”
14/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 THE IR PRO DUCT S IN OR DER FO R THEM TO SAV E TIME . AS A RES ULT, STMIC ROEL ECTR ONI CS
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 consequences
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 implic ation or otherwise under any patent or patent r i ght s of STMi croelectr oni cs. Spec i fications mentione d i n this publicatio n are subj ect
to change without notice. This publication supersedes and replaces all information previously supplied. STMicroelectronics product s are not
authorized for use as cri tical comp onents in lif e support devi ces or systems without the express written appr oval of STMic roelectronics.
The ST logo is a registered trademark of STMicroelectronics
2003 STMicroelectronics - All Rights Reserved.
STMicroelectronics Grou p of Companies
http://www.s t. com
Purchase of I
2
C Components by STMicroelectronics conveys a license under the Philips I2C Patent. Rights to use the se components in an
2
C system i s granted pro vi ded that the sy stem conforms to the I2C Standard Specification as defined by Philips.
I
Australi a - Brazil - Canada - China - Fi nl and - Franc e - Germany - Hong Kong - Ind i a - Is rael - Ital y - J apan
Malaysi a - M al ta - Morocco - Singapore - Spain - Sweden - Sw itzerland - Uni t ed Kingdo m - U.S.A.
15/15
Loading...