2 * @brief Host mode driver for the library USB MIDI Class driver
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\r
10 * Software that is described herein is for illustrative purposes only
\r
11 * which provides customers with programming information regarding the
\r
12 * LPC products. This software is supplied "AS IS" without any warranties of
\r
13 * any kind, and NXP Semiconductors and its licensor disclaim any and
\r
14 * all warranties, express or implied, including all implied warranties of
\r
15 * merchantability, fitness for a particular purpose and non-infringement of
\r
16 * intellectual property rights. NXP Semiconductors assumes no responsibility
\r
17 * or liability for the use of the software, conveys no license or rights under any
\r
18 * patent, copyright, mask work right, or any other intellectual property rights in
\r
19 * or to any products. NXP Semiconductors reserves the right to make changes
\r
20 * in the software without notification. NXP Semiconductors also makes no
\r
21 * representation or warranty that such application will be suitable for the
\r
22 * specified use without further testing or modification.
\r
25 * Permission to use, copy, modify, and distribute this software and its
\r
26 * documentation is hereby granted, under NXP Semiconductors' and its
\r
27 * licensor's relevant copyrights in the software, without fee, provided that it
\r
28 * is used in conjunction with NXP Semiconductors microcontrollers. This
\r
29 * copyright, permission, and disclaimer notice must appear in all copies of
\r
33 /** @ingroup Group_USBClassMIDI
\r
34 * @defgroup Group_USBClassMIDIHost MIDI Class Host Mode Driver
\r
36 * @section Sec_Dependencies Module Source Dependencies
\r
37 * The following files must be built with any user project that uses this module:
\r
38 * - LPCUSBlib/Drivers/USB/Class/Host/MIDI.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>
\r
40 * @section Sec_ModDescription Module Description
\r
41 * Host Mode USB Class driver framework interface, for the MIDI USB Class driver.
\r
46 #ifndef __MIDI_CLASS_HOST_H__
\r
47 #define __MIDI_CLASS_HOST_H__
\r
50 #include "../../USB.h"
\r
51 #include "../Common/MIDIClassCommon.h"
\r
53 /* Enable C linkage for C++ Compilers: */
\r
54 #if defined(__cplusplus)
\r
58 /* Preprocessor Checks: */
\r
59 #if !defined(__INCLUDE_FROM_MIDI_DRIVER)
\r
60 #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.
\r
63 /* Public Interface - May be used in end-application: */
\r
65 /** @brief MIDI Class Host Mode Configuration and State Structure.
\r
67 * Class state structure. An instance of this structure should be made within the user application,
\r
68 * and passed to each of the MIDI class driver functions as the \c MIDIInterfaceInfo parameter. This
\r
69 * stores each MIDI interface's configuration and state information.
\r
75 uint8_t DataINPipeNumber; /**< Pipe number of the MIDI interface's streaming IN data pipe. */
\r
76 bool DataINPipeDoubleBank; /**< Indicates if the MIDI interface's IN data pipe should use double banking. */
\r
78 uint8_t DataOUTPipeNumber; /**< Pipe number of the MIDI interface's streaming OUT data pipe. */
\r
79 bool DataOUTPipeDoubleBank; /**< Indicates if the MIDI interface's OUT data pipe should use double banking. */
\r
80 uint8_t PortNumber; /**< Port number that this interface is running.
\r
82 } Config; /**< Config data for the USB class interface within the device. All elements in this section
\r
83 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
\r
87 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
\r
88 * after @ref MIDI_Host_ConfigurePipes() is called and the Host state machine is in the
\r
91 uint8_t InterfaceNumber; /**< Interface index of the MIDI interface within the attached device. */
\r
93 uint16_t DataINPipeSize; /**< Size in bytes of the MIDI Streaming Data interface's IN data pipe. */
\r
94 uint16_t DataOUTPipeSize; /**< Size in bytes of the MIDI Streaming Data interface's OUT data pipe. */
\r
95 } State; /**< State data for the USB class interface within the device. All elements in this section
\r
96 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
\r
97 * the interface is enumerated.
\r
99 } USB_ClassInfo_MIDI_Host_t;
\r
102 /** Enum for the possible error codes returned by the @ref MIDI_Host_ConfigurePipes() function. */
\r
103 enum MIDI_Host_EnumerationFailure_ErrorCodes_t
\r
105 MIDI_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */
\r
106 MIDI_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */
\r
107 MIDI_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible MIDI interface was not found in the device's Configuration Descriptor. */
\r
108 MIDI_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
\r
111 /* Function Prototypes: */
\r
112 /** @brief Host interface configuration routine, to configure a given MIDI host interface instance using the Configuration
\r
113 * Descriptor read from an attached USB device. This function automatically updates the given MIDI Host instance's
\r
114 * state values and configures the pipes required to communicate with the interface if it is found within the device.
\r
115 * This should be called once after the stack has enumerated the attached device, while the host state machine is in
\r
116 * the Addressed state.
\r
118 * @param MIDIInterfaceInfo : Pointer to a structure containing an MIDI Class host configuration and state.
\r
119 * @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.
\r
120 * @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.
\r
122 * @return A value from the @ref MIDI_Host_EnumerationFailure_ErrorCodes_t enum.
\r
124 uint8_t MIDI_Host_ConfigurePipes(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo,
\r
125 uint16_t ConfigDescriptorSize,
\r
126 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
128 /** @brief General management task for a given MIDI host class interface, required for the correct operation of the interface. This should
\r
129 * be called frequently in the main program loop, before the master USB management task @ref USB_USBTask().
\r
131 * @param MIDIInterfaceInfo : Pointer to a structure containing an MIDI Class host configuration and state.
\r
134 void MIDI_Host_USBTask(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
136 /** @brief Sends a MIDI event packet to the device. If no device is connected, the event packet is discarded.
\r
138 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
141 * @param MIDIInterfaceInfo : Pointer to a structure containing a MIDI Class configuration and state.
\r
142 * @param Event : Pointer to a populated USB_MIDI_EventPacket_t structure containing the MIDI event to send.
\r
144 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
146 uint8_t MIDI_Host_SendEventPacket(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo,
\r
147 MIDI_EventPacket_t* const Event) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
149 /** @brief Flushes the MIDI send buffer, sending any queued MIDI events to the device. This should be called to override the
\r
150 * @ref MIDI_Host_SendEventPacket() function's packing behaviour, to flush queued events. Events are queued into the
\r
151 * pipe bank until either the pipe bank is full, or @ref MIDI_Host_Flush() is called. This allows for multiple MIDI
\r
152 * events to be packed into a single pipe packet, increasing data throughput.
\r
154 * @param MIDIInterfaceInfo : Pointer to a structure containing a MIDI Class configuration and state.
\r
156 * @return A value from the @ref Pipe_WaitUntilReady_ErrorCodes_t enum.
\r
158 uint8_t MIDI_Host_Flush(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
160 /** @brief Receives a MIDI event packet from the device.
\r
162 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
165 * @param MIDIInterfaceInfo : Pointer to a structure containing a MIDI Class configuration and state.
\r
166 * @param Event : Pointer to a USB_MIDI_EventPacket_t structure where the received MIDI event is to be placed.
\r
168 * @return Boolean \c true if a MIDI event packet was received, \c false otherwise.
\r
170 bool MIDI_Host_ReceiveEventPacket(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo,
\r
171 MIDI_EventPacket_t* const Event) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
173 /* Private Interface - For use in library only: */
\r
174 #if !defined(__DOXYGEN__)
\r
175 /* Function Prototypes: */
\r
176 #if defined(__INCLUDE_FROM_MIDI_HOST_C)
\r
177 static uint8_t DCOMP_MIDI_Host_NextMIDIStreamingInterface(void* const CurrentDescriptor)
\r
178 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
179 static uint8_t DCOMP_MIDI_Host_NextMIDIStreamingDataEndpoint(void* const CurrentDescriptor)
\r
180 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
184 /* Disable C linkage for C++ Compilers: */
\r
185 #if defined(__cplusplus)
\r
projects / freertos / blob