?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /******************************************************************************
2  
3 USB Host Audio v1.0 Client Driver Header File
4  
5 Description:
6 This is the header file for a USB Embedded Host that is using the Audio
7 Class v1.0
8  
9 This file should be included with usb_host.h to provide the USB hardware
10 interface. It must be included after the application-specific usb_config.h
11 file and after the USB Embedded Host header file usb_host.h, as definitions
12 in those files are required for proper compilation.
13  
14 To interface with usb_host.c, the routine USBHostAudioV1Initialize() should
15 be specified as the Initialize() function, and USBHostAudioV1EventHandler()
16 should be specified as the EventHandler() function in the
17 usbClientDrvTable[] array declared in usb_config.h.
18  
19 This driver can be configured to use transfer events from usb_host.c.
20 Transfer events require more RAM and ROM than polling, but it cuts down or
21 even eliminates the required polling of the various USBxxxTasks functions.
22 For this class, USBHostMSDTasks() is compiled out if transfer events from
23 usb_host.c are used. However, USBHostTasks() still must be called to
24 provide attach, enumeration, and detach services. If transfer events from
25 usb_host.c are going to be used, USB_ENABLE_TRANSFER_EVENT should be
26 defined. If transfer status is going to be polled,
27 USB_ENABLE_TRANSFER_EVENT should not be defined.
28  
29 This driver can also be configured to provide mass storage transfer events
30 to the next layer. Generating these events requires a small amount of
31 extra ROM, but no extra RAM. The layer above this driver must be
32 configured to receive and respond to the events. If mass storage transfer
33 events are going to be sent to the next layer,
34 USB_MSD_ENABLE_TRANSFER_EVENT should be defined. If mass storage transfer
35 status is going to be polled, USB_MSD_ENABLE_TRANSFER_EVENT should not be
36 defined.
37  
38 Since audio support is performed with both isochronous and interrupt
39 transfers, USB_SUPPORT_INTERRUPT_TRANSFERS and
40 USB_SUPPORT_ISOCHRONOUS_TRANSFERS must be defined.
41  
42 Summary:
43 This is the header file for a USB Embedded Host that is using the Audio
44 Class v1.0.
45  
46 *******************************************************************************/
47 //DOM-IGNORE-BEGIN
48 /*******************************************************************************
49  
50 * FileName: usb_host_audio_v1.h
51 * Dependencies: None
52 * Processor: PIC24/dsPIC30/dsPIC33/PIC32MX
53 * Compiler: C30 v3.12/C32 v1.05
54 * Company: Microchip Technology, Inc.
55  
56 Software License Agreement
57  
58 The software supplied herewith by Microchip Technology Incorporated
59 (the “Company”) for its PICmicro® Microcontroller is intended and
60 supplied to you, the Company’s customer, for use solely and
61 exclusively on Microchip PICmicro Microcontroller products. The
62 software is owned by the Company and/or its supplier, and is
63 protected under applicable copyright laws. All rights are reserved.
64 Any use in violation of the foregoing restrictions may subject the
65 user to criminal sanctions under applicable laws, as well as to
66 civil liability for the breach of the terms and conditions of this
67 license.
68  
69 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
70 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
71 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
72 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
73 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
74 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
75  
76 Change History:
77 Rev Description
78 ---- -----------
79 2.7 Initial Release
80  
81 2.7a added USBHostAudioV1DataEventHandler()
82 renamed EVENT_AUDIO_RECEIVE_STREAM to EVENT_AUDIO_STREAM_RECEIVED
83 *******************************************************************************/
84 //DOM-IGNORE-END
85  
86 //DOM-IGNORE-BEGIN
87 #ifndef _USBHOSTAUDIOV1_H_
88 #define _USBHOSTAUDIOV1_H_
89 //DOM-IGNORE-END
90  
91 // *****************************************************************************
92 // *****************************************************************************
93 // Section: Constants
94 // *****************************************************************************
95 // *****************************************************************************
96  
97 // *****************************************************************************
98 // Section: Initialization Handler Flags
99 // *****************************************************************************
100  
101 #define USB_AUDIO_IPOD_CHECK 1
102  
103 // *****************************************************************************
104 // Section: Class Error Codes
105 // *****************************************************************************
106  
107 #define AUDIO_COMMAND_PASSED 0x00 // Transfer was successful. Returned in dCSWStatus.
108 #define AUDIO_COMMAND_FAILED 0x01 // Transfer failed. Returned in dCSWStatus.
109  
110 #define USB_AUDIO_ERROR USB_ERROR_CLASS_DEFINED // Error code offset.
111  
112 #define USB_AUDIO_COMMAND_PASSED USB_SUCCESS // Command was successful.
113 #define USB_AUDIO_COMMAND_FAILED (USB_AUDIO_ERROR | 0x01) // Command failed at the device.
114 #define USB_AUDIO_OUT_OF_MEMORY (USB_AUDIO_ERROR | 0x02) // No dynamic memory is available.
115 #define USB_AUDIO_DEVICE_NOT_FOUND (USB_AUDIO_ERROR | 0x03) // Device with the specified address is not available.
116 #define USB_AUDIO_DEVICE_BUSY (USB_AUDIO_ERROR | 0x04) // A transfer is currently in progress.
117 #define USB_AUDIO_ILLEGAL_REQUEST (USB_AUDIO_ERROR | 0x05) // Cannot perform requested operation.
118  
119 // *****************************************************************************
120 // Section: Additional return values for USBHostMSDDeviceStatus (see USBHostDeviceStatus also)
121 // *****************************************************************************
122  
123 #define USB_MSD_DEVICE_DETACHED 0x50 // Device is detached.
124 #define USB_MSD_INITIALIZING 0x51 // Device is initializing.
125 #define USB_MSD_NORMAL_RUNNING 0x52 // Device is running and available for data transfers.
126 #define USB_MSD_RESETTING_DEVICE 0x53 // Device is being reset.
127 #define USB_MSD_ERROR_STATE 0x55 // Device is holding due to a MSD error.
128  
129 // *****************************************************************************
130 // Section: Interface and Protocol Constants
131 // *****************************************************************************
132  
133 #define DEVICE_CLASS_MASS_STORAGE 0x08 // Class code for Mass Storage.
134  
135 #define DEVICE_SUBCLASS_RBC 0x01 // SubClass code for Reduced Block Commands (not supported).
136 #define DEVICE_SUBCLASS_CD_DVD 0x02 // SubClass code for a CD/DVD drive (not supported).
137 #define DEVICE_SUBCLASS_TAPE_DRIVE 0x03 // SubClass code for a tape drive (not supported).
138 #define DEVICE_SUBCLASS_FLOPPY_INTERFACE 0x04 // SubClass code for a floppy disk interface (not supported).
139 #define DEVICE_SUBCLASS_REMOVABLE 0x05 // SubClass code for removable media (not supported).
140 #define DEVICE_SUBCLASS_SCSI 0x06 // SubClass code for a SCSI interface device (supported).
141  
142 #define DEVICE_INTERFACE_PROTOCOL_BULK_ONLY 0x50 // Protocol code for Bulk-only mass storage.
143  
144 // *****************************************************************************
145 // Section: Audio Event Definition
146 // *****************************************************************************
147  
148 // If the application has not defined an offset for audio events, set it to 0.
149 #ifndef EVENT_AUDIO_OFFSET
150 #define EVENT_AUDIO_OFFSET 0
151 #endif
152  
153 // No event occured (NULL event).
154 #define EVENT_AUDIO_NONE EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 0
155 // An audio device has attached. The returned data pointer points to a
156 // USB_AUDIO_V1_DEVICE_ID structure.
157 #define EVENT_AUDIO_ATTACH EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 1
158 // An audio device has detached. The returned data pointer points to a
159 // byte with the previous address of the detached device.
160 #define EVENT_AUDIO_DETACH EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 2
161 // An audio stream data packet has been received. The returned data
162 // pointer points to a HOST_TRANSFER_DATA structure, with information about
163 // the most recent transfer. One event will be returned for each transfer,
164 // so the application will know how much data was actually received in
165 // each transfer. If there was a bus error, both the returned data pointer
166 // and the size will be zero.
167 #define EVENT_AUDIO_STREAM_RECEIVED EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 3
168 // This event is returned after the sampling frequency is set via
169 // USBHostAudioV1SetSamplingFrequency(). The returned data pointer points
170 // to a HOST_TRANSFER_DATA structure, with the error code for this request.
171 #define EVENT_AUDIO_FREQUENCY_SET EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 4
172 // This event is returned after the full or zero bandwidth interface has
173 // been set. The returned data pointer is NULL, but the size is the
174 // error code from the transfer.
175 #define EVENT_AUDIO_INTERFACE_SET EVENT_AUDIO_BASE + EVENT_AUDIO_OFFSET + 5
176  
177 // *****************************************************************************
178 // *****************************************************************************
179 // Section: Data Structures
180 // *****************************************************************************
181 // *****************************************************************************
182  
183 // *****************************************************************************
184 /* Audio Device ID Information
185  
186 This structure contains identification information about an attached device.
187 */
188 typedef struct _USB_AUDIO_V1_DEVICE_ID
189 {
190 WORD vid; // Vendor ID of the device
191 WORD pid; // Product ID of the device
192 WORD audioDataPacketSize; // Bytes transferred in one isochronous transfer.
193 BYTE deviceAddress; // Address of the device on the USB
194 BYTE clientDriverID; // Client driver ID for device requests.
195 } USB_AUDIO_V1_DEVICE_ID;
196  
197  
198 // *****************************************************************************
199 // *****************************************************************************
200 // Section: Function Prototypes and Macro Functions
201 // *****************************************************************************
202 // *****************************************************************************
203  
204  
205 /****************************************************************************
206 Function:
207 BYTE USBHostAudioV1ReceiveAudioData( BYTE deviceAddress,
208 ISOCHRONOUS_DATA *pIsochronousData )
209  
210 Summary:
211 This function starts the reception of streaming, isochronous audio data.
212  
213 Description:
214 This function starts the reception of streaming, isochronous audio data.
215  
216 Precondition:
217 USBHostAudioV1SetInterfaceFullBandwidth() must be called to set the
218 device to its full bandwidth interface.
219  
220 Parameters:
221 BYTE deviceAddress - Device address
222 ISOCHRONOUS_DATA *pIsochronousData - Pointer to an ISOCHRONOUS_DATA
223 structure, containing information for the
224 application and the host driver for the
225 isochronous transfer.
226  
227 Return Values:
228 USB_SUCCESS - Request started successfully
229 USB_AUDIO_DEVICE_NOT_FOUND - No device with specified address
230 USB_AUDIO_DEVICE_BUSY - Device is already receiving audio data or
231 setting an interface.
232 Others - See USBHostIssueDeviceRequest() errors.
233  
234 Remarks:
235 Some devices require other operations between setting the full bandwidth
236 interface and starting the streaming audio data. Therefore, these two
237 functions are broken out separately.
238 ***************************************************************************/
239  
240 BYTE USBHostAudioV1ReceiveAudioData( BYTE deviceAddress,
241 ISOCHRONOUS_DATA *pIsochronousData );
242  
243  
244 /****************************************************************************
245 Function:
246 BYTE USBHostAudioV1SetInterfaceFullBandwidth( BYTE deviceAddress )
247  
248 Summary:
249 This function sets the full bandwidth interface.
250  
251 Description:
252 This function sets the full bandwidth interface. This function should
253 be called before calling USBHostAudioV1ReceiveAudioData() to receive the
254 audio stream. Upon completion, the event EVENT_AUDIO_INTERFACE_SET will
255 be generated.
256  
257 Precondition:
258 None
259  
260 Parameters:
261 BYTE deviceAddress - Device address
262  
263 Return Values:
264 USB_SUCCESS - Request started successfully
265 USB_AUDIO_DEVICE_NOT_FOUND - No device with specified address
266 USB_AUDIO_DEVICE_BUSY - Device is already receiving audio data or
267 setting an interface.
268 Others - See USBHostIssueDeviceRequest() errors.
269  
270 Remarks:
271 None
272 ***************************************************************************/
273  
274 BYTE USBHostAudioV1SetInterfaceFullBandwidth( BYTE deviceAddress );
275  
276  
277 /****************************************************************************
278 Function:
279 BYTE USBHostAudioV1SetInterfaceZeroBandwidth( BYTE deviceAddress )
280  
281 Summary:
282 This function sets the zero bandwidth interface.
283  
284 Description:
285 This function sets the full bandwidth interface. This function can
286 be called after calling USBHostAudioV1TerminateTransfer() to terminate the
287 audio stream. Upon completion, the event EVENT_AUDIO_INTERFACE_SET will
288 be generated.
289  
290 Precondition:
291 None
292  
293 Parameters:
294 BYTE deviceAddress - Device address
295  
296 Return Values:
297 USB_SUCCESS - Request started successfully
298 USB_AUDIO_DEVICE_NOT_FOUND - No device with the specified address.
299 Others - See USBHostIssueDeviceRequest()
300  
301 Remarks:
302 None
303 ***************************************************************************/
304  
305 BYTE USBHostAudioV1SetInterfaceZeroBandwidth( BYTE deviceAddress );
306  
307  
308 /****************************************************************************
309 Function:
310 BYTE USBHostAudioV1SetSamplingFrequency( BYTE deviceAddress, BYTE *frequency )
311  
312 Summary:
313 This function sets the sampling frequency for the device.
314  
315 Description:
316 This function sets the sampling frequency for the device. If the exact
317 frequency is not supported by the device, the device will round it to the
318 closest supported value.
319  
320 IMPORTANT: If the request is initiated successfully, the frequency value
321 must remain valid until the EVENT_AUDIO_FREQUENCY_SET event is received.
322 Therefore, this value cannot be a local (stack) variable. The application
323 can either use a global variable for this value, or it can use the
324 function USBHostAudioV1SupportedFrequencies() to obtain a pointer to the
325 number and list of supported frequencies, and pass a pointer to the desired
326 frequency in this list.
327  
328 Precondition:
329 None
330  
331 Parameters:
332 BYTE deviceAddress - Device address
333 BYTE *frequency - Pointer to three bytes that specify the desired
334 sampling frequency. NOTE: If the request is
335 initiated successfully, this location must
336 remain valid until the EVENT_AUDIO_FREQUENCY_SET
337 event is received.
338  
339 Return Values:
340 USB_SUCCESS - Request started successfully
341 Others - See USBHostIssueDeviceRequest() errors.
342  
343 Example:
344 <code>
345 BYTE numFrequencies;
346 BYTE *ptr;
347  
348 ptr = USBHostAudioV1SupportedFrequencies( deviceAddress );
349 if (ptr)
350 {
351 numFrequencies = *ptr;
352 ptr++;
353 if (numFrequencies == 0)
354 {
355 // Continuous sampling, minimum and maximum are specified.
356 DWORD minFrequency;
357 DWORD maxFrequency;
358  
359 minFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
360 ptr += 3;
361 maxFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
362 if ((minFrequency <= desiredFrequency) && (desiredFrequency <= maxFrequency))
363 {
364 rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, &desiredFrequency );
365 }
366 else
367 {
368 // Desired frequency out of range
369 }
370 }
371 else
372 {
373 // Discrete sampling frequencies are specified.
374 DWORD frequency;
375  
376 while (numFrequencies)
377 {
378 frequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
379 if (frequency == desiredFrequency)
380 {
381 rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, ptr );
382 continue;
383 }
384 numFrequencies--;
385 ptr += 3;
386 }
387 if (numFrequencies == 0)
388 {
389 // Desired frequency not found.
390 }
391 }
392 }
393 </code>
394  
395 Remarks:
396 If a global variable is used to old the frequency, it can be declared as
397 a DWORD. Since PIC Microcontrollers are little endian machines, a
398 pointer to the DWORD can be used as the frequency parameter:
399 <code>
400 DWORD desiredFrequency = 44100; // Hertz
401  
402 rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, (BYTE *)(&desiredFrequency) );
403 </code>
404  
405 ***************************************************************************/
406  
407 BYTE USBHostAudioV1SetSamplingFrequency( BYTE deviceAddress, BYTE *frequency );
408  
409  
410 /****************************************************************************
411 Function:
412 BYTE * USBHostAudioV1SupportedFrequencies( BYTE deviceAddress )
413  
414 Summary:
415 This function returns a pointer to the list of supported frequencies.
416  
417 Description:
418 This function returns a pointer to the list of supported frequencies. It
419 is intended to be used with the function USBHostAudioV1SetSamplingFrequency()
420 to set the device's sampling frequency.
421  
422 Precondition:
423 None
424  
425 Parameters:
426 BYTE deviceAddress - Device address
427  
428 Returns:
429 This function returns a BYTE pointer to the list of supported frequencies.
430 The first byte of this list is the number of supported frequencies. Each
431 supported frequency is then listed, with three bytes for each frequency.
432  
433 Example:
434 <code>
435 BYTE numFrequencies;
436 BYTE *ptr;
437  
438 ptr = USBHostAudioV1SupportedFrequencies( deviceAddress );
439 if (ptr)
440 {
441 numFrequencies = *ptr;
442 ptr++;
443 if (numFrequencies == 0)
444 {
445 // Continuous sampling, minimum and maximum are specified.
446 DWORD minFrequency;
447 DWORD maxFrequency;
448  
449 minFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
450 ptr += 3;
451 maxFrequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
452 if ((minFrequency <= desiredFrequency) && (desiredFrequency <= maxFrequency))
453 {
454 rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, &desiredFrequency );
455 }
456 else
457 {
458 // Desired frequency out of range
459 }
460 }
461 else
462 {
463 // Discrete sampling frequencies are specified.
464 DWORD frequency;
465  
466 while (numFrequencies)
467 {
468 frequency = *ptr + (*(ptr+1) << 8) + (*(ptr+2) << 16);
469 if (frequency == desiredFrequency)
470 {
471 rc = USBHostAudioV1SetSamplingFrequency( deviceAddress, ptr );
472 continue;
473 }
474 numFrequencies--;
475 ptr += 3;
476 }
477 if (numFrequencies == 0)
478 {
479 // Desired frequency not found.
480 }
481 }
482 }
483 </code>
484  
485 Remarks:
486 None
487 ***************************************************************************/
488  
489 BYTE * USBHostAudioV1SupportedFrequencies( BYTE deviceAddress );
490  
491  
492 /****************************************************************************
493 Function:
494 void USBHostAudioV1TerminateTransfer( BYTE deviceAddress )
495  
496 Summary:
497 This function terminates an audio stream.
498  
499 Description:
500 This function terminates an audio stream. It does not change the device's
501 selected interface. The application may wish to call
502 USBHostAudioV1SetInterfaceZeroBandwidth() after this function to set
503 the device to the zero bandwidth interface.
504  
505 Between terminating one audio stream and starting another, the application
506 should call USBHostIsochronousBuffersReset() to reset the data buffers.
507 This is done from the application layer rather than from this function, so
508 the application can process all received audio data.
509  
510 Precondition:
511 None
512  
513 Parameters:
514 BYTE deviceAddress - Device address
515  
516 Returns:
517 None
518  
519 Remarks:
520 None
521 ***************************************************************************/
522  
523 void USBHostAudioV1TerminateTransfer( BYTE deviceAddress );
524  
525  
526  
527 // *****************************************************************************
528 // *****************************************************************************
529 // Section: Host Stack Interface Functions
530 // *****************************************************************************
531 // *****************************************************************************
532  
533 /****************************************************************************
534 Function:
535 BOOL USBHostAudioV1DataEventHandler( BYTE address, USB_EVENT event,
536 void *data, DWORD size )
537  
538 Summary:
539 This function is the data event handler for this client driver.
540  
541 Description:
542 This function is the data event handler for this client driver. It is called
543 by the host layer when isochronous data events occur.
544  
545 Precondition:
546 The device has been initialized.
547  
548 Parameters:
549 BYTE address - Address of the device
550 USB_EVENT event - Event that has occurred
551 void *data - Pointer to data pertinent to the event
552 WORD size - Size of the data
553  
554 Return Values:
555 TRUE - Event was handled
556 FALSE - Event was not handled
557  
558 Remarks:
559 The client driver does not need to process the data. Just pass the event
560 up to the application layer.
561 ***************************************************************************/
562  
563 BOOL USBHostAudioV1DataEventHandler( BYTE address, USB_EVENT event, void *data, DWORD size );
564  
565  
566 /****************************************************************************
567 Function:
568 BOOL USBHostAudioV1Initialize( BYTE address, DWORD flags, BYTE clientDriverID )
569  
570 Summary:
571 This function is the initialization routine for this client driver.
572  
573 Description:
574 This function is the initialization routine for this client driver. It
575 is called by the host layer when the USB device is being enumerated.
576  
577 Precondition:
578 None
579  
580 Parameters:
581 BYTE address - Address of the new device
582 DWORD flags - Initialization flags
583 BYTE clientDriverID - ID to send when issuing a Device Request via
584 USBHostIssueDeviceRequest() or USBHostSetDeviceConfiguration().
585  
586 Return Values:
587 TRUE - We can support the device.
588 FALSE - We cannot support the device.
589  
590 Remarks:
591 None
592 ***************************************************************************/
593  
594 BOOL USBHostAudioV1Initialize( BYTE address, DWORD flags, BYTE clientDriverID );
595  
596  
597 /****************************************************************************
598 Function:
599 BOOL USBHostAudioV1EventHandler( BYTE address, USB_EVENT event,
600 void *data, DWORD size )
601  
602 Summary:
603 This function is the event handler for this client driver.
604  
605 Description:
606 This function is the event handler for this client driver. It is called
607 by the host layer when various events occur.
608  
609 Precondition:
610 The device has been initialized.
611  
612 Parameters:
613 BYTE address - Address of the device
614 USB_EVENT event - Event that has occurred
615 void *data - Pointer to data pertinent to the event
616 WORD size - Size of the data
617  
618 Return Values:
619 TRUE - Event was handled
620 FALSE - Event was not handled
621  
622 Remarks:
623 None
624 ***************************************************************************/
625  
626 BOOL USBHostAudioV1EventHandler( BYTE address, USB_EVENT event, void *data, DWORD size );
627  
628  
629 #endif
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3