MIDI.h 10.1 KB
 Dean Camera committed May 08, 2010 1 2 3 /* LUFA Library Copyright (C) Dean Camera, 2010.  4   Dean Camera committed May 08, 2010 5  dean [at] fourwalledcubicle [dot] com  Dean Camera committed Oct 28, 2010 6  www.lufa-lib.org  Dean Camera committed May 08, 2010 7 8 9 10 11 */ /* Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)  12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 15  all copies and that both that the copyright notice and this  16 17 18  permission notice and warranty disclaimer appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the  Dean Camera committed May 08, 2010 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35  software without specific, written prior permission. The author disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. */ /** \file * \brief Host mode driver for the library USB MIDI Class driver. * * Host mode driver for the library USB MIDI Class driver. *  Dean Camera committed Oct 24, 2010 36 37  * \note This file should not be included directly. It is automatically included as needed by the USB module driver * dispatch header located in LUFA/Drivers/USB.h.  Dean Camera committed May 08, 2010 38 39 40 41 42 43 44  */ /** \ingroup Group_USBClassMIDI * @defgroup Group_USBClassMIDIHost MIDI Class Host Mode Driver * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module:  Dean Camera committed Jul 19, 2010 45  * - LUFA/Drivers/USB/Class/Host/MIDI.c (Makefile source module name: LUFA_SRC_USBCLASS)  Dean Camera committed May 08, 2010 46 47 48 49 50 51 52 53 54 55 56 57 58  * * \section Module Description * Host Mode USB Class driver framework interface, for the MIDI USB Class driver. * * @{ */ #ifndef __MIDI_CLASS_HOST_H__ #define __MIDI_CLASS_HOST_H__ /* Includes: */ #include "../../USB.h" #include "../Common/MIDI.h"  59   Dean Camera committed May 08, 2010 60 61 62 63 64 65 66  /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks: */ #if !defined(__INCLUDE_FROM_MIDI_DRIVER)  Dean Camera committed Oct 24, 2010 67 68 69 70 71  #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. #endif #if defined(__INCLUDE_FROM_MIDI_HOST_C) && defined(NO_STREAM_CALLBACKS) #error The NO_STREAM_CALLBACKS compile time option cannot be used in projects using the library Class drivers.  Dean Camera committed May 08, 2010 72  #endif  73   Dean Camera committed May 08, 2010 74 75 76 77 78 79 80 81 82 83 84 85  /* Public Interface - May be used in end-application: */ /* Type Defines: */ /** \brief MIDI Class Host Mode Configuration and State Structure. * * Class state structure. An instance of this structure should be made within the user application, * and passed to each of the MIDI class driver functions as the MIDIInterfaceInfo parameter. This * stores each MIDI interface's configuration and state information. */ typedef struct { const struct {  Dean Camera committed Jun 17, 2010 86 87  uint8_t DataINPipeNumber; /**< Pipe number of the MIDI interface's streaming IN data pipe. */ bool DataINPipeDoubleBank; /**< Indicates if the MIDI interface's IN data pipe should use double banking. */  88   Dean Camera committed Jun 17, 2010 89 90  uint8_t DataOUTPipeNumber; /**< Pipe number of the MIDI interface's streaming OUT data pipe. */ bool DataOUTPipeDoubleBank; /**< Indicates if the MIDI interface's OUT data pipe should use double banking. */  Dean Camera committed May 08, 2010 91 92 93 94 95  } Config; /**< Config data for the USB class interface within the device. All elements in this section * must be set or the interface will fail to enumerate and operate correctly. */ struct {  Dean Camera committed Sep 30, 2010 96 97 98 99 100  bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid * after \ref MIDI_Host_ConfigurePipes() is called and the Host state machine is in the * Configured state. */ uint8_t InterfaceNumber; /**< Interface index of the MIDI interface within the attached device. */  Dean Camera committed May 08, 2010 101   Dean Camera committed Jun 17, 2010 102 103  uint16_t DataINPipeSize; /**< Size in bytes of the MIDI Streaming Data interface's IN data pipe. */ uint16_t DataOUTPipeSize; /**< Size in bytes of the MIDI Streaming Data interface's OUT data pipe. */  Dean Camera committed May 08, 2010 104 105 106 107 108  } State; /**< State data for the USB class interface within the device. All elements in this section * may be set to initial values, but may also be ignored to default to sane values when * the interface is enumerated. */ } USB_ClassInfo_MIDI_Host_t;  109   Dean Camera committed May 08, 2010 110 111  /* Enums: */ /** Enum for the possible error codes returned by the \ref MIDI_Host_ConfigurePipes() function. */  Dean Camera committed Sep 28, 2010 112  enum MIDI_Host_EnumerationFailure_ErrorCodes_t  Dean Camera committed May 08, 2010 113  {  Dean Camera committed Jun 17, 2010 114 115  MIDI_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */ MIDI_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */  Dean Camera committed Sep 30, 2010 116  MIDI_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible MIDI interface was not found in the device's Configuration Descriptor. */  Dean Camera committed Dec 02, 2010 117  MIDI_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */  Dean Camera committed May 08, 2010 118  };  119   Dean Camera committed May 08, 2010 120 121 122 123 124 125 126  /* Function Prototypes: */ /** Host interface configuration routine, to configure a given MIDI host interface instance using the Configuration * Descriptor read from an attached USB device. This function automatically updates the given MIDI Host instance's * state values and configures the pipes required to communicate with the interface if it is found within the device. * This should be called once after the stack has enumerated the attached device, while the host state machine is in * the Addressed state. *  Dean Camera committed Sep 30, 2010 127 128 129 130  * \note The pipe index numbers as given in the interface's configuration structure must not overlap with any other * interface, or pipe bank corruption will occur. Gaps in the allocated pipe numbers or non-sequential indexes * within a single interface is allowed, but no two interfaces of any type have have interleaved pipe indexes. *  Dean Camera committed Jun 17, 2010 131 132 133  * \param[in,out] MIDIInterfaceInfo Pointer to a structure containing an MIDI Class host configuration and state. * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor. * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor.  Dean Camera committed May 08, 2010 134  *  Dean Camera committed Sep 28, 2010 135  * \return A value from the \ref MIDI_Host_EnumerationFailure_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 136  */  Dean Camera committed Jul 21, 2010 137 138  uint8_t MIDI_Host_ConfigurePipes(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo, uint16_t ConfigDescriptorSize,  Dean Camera committed May 08, 2010 139 140  void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);  Dean Camera committed Oct 27, 2010 141 142 143 144 145 146 147  /** General management task for a given MIDI host class interface, required for the correct operation of the interface. This should * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask(). * * \param[in,out] MIDIInterfaceInfo Pointer to a structure containing an MIDI Class host configuration and state. */ void MIDI_Host_USBTask(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed May 08, 2010 148 149  /** Sends a MIDI event packet to the device. If no device is connected, the event packet is discarded. *  Dean Camera committed Oct 12, 2010 150  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  Dean Camera committed Jun 15, 2010 151  * call will fail.  Dean Camera committed May 08, 2010 152  *  Dean Camera committed Jun 17, 2010 153 154  * \param[in,out] MIDIInterfaceInfo Pointer to a structure containing a MIDI Class configuration and state. * \param[in] Event Pointer to a populated USB_MIDI_EventPacket_t structure containing the MIDI event to send.  Dean Camera committed May 08, 2010 155  *  Dean Camera committed Jun 17, 2010 156  * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 157 158 159 160 161  */ uint8_t MIDI_Host_SendEventPacket(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo, MIDI_EventPacket_t* const Event) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /** Flushes the MIDI send buffer, sending any queued MIDI events to the device. This should be called to override the  Dean Camera committed Jul 30, 2010 162  * \ref MIDI_Host_SendEventPacket() function's packing behaviour, to flush queued events. Events are queued into the  Dean Camera committed May 08, 2010 163 164 165  * pipe bank until either the pipe bank is full, or \ref MIDI_Host_Flush() is called. This allows for multiple MIDI * events to be packed into a single pipe packet, increasing data throughput. *  Dean Camera committed Jun 17, 2010 166  * \param[in,out] MIDIInterfaceInfo Pointer to a structure containing a MIDI Class configuration and state.  Dean Camera committed May 08, 2010 167  *  Dean Camera committed Jun 17, 2010 168  * \return A value from the \ref Pipe_WaitUntilReady_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 169  */  170  uint8_t MIDI_Host_Flush(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);  171   Dean Camera committed May 08, 2010 172 173  /** Receives a MIDI event packet from the device. *  Dean Camera committed Oct 12, 2010 174  * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the  Dean Camera committed Jun 15, 2010 175  * call will fail.  Dean Camera committed May 08, 2010 176  *  Dean Camera committed Jun 17, 2010 177 178  * \param[in,out] MIDIInterfaceInfo Pointer to a structure containing a MIDI Class configuration and state. * \param[out] Event Pointer to a USB_MIDI_EventPacket_t structure where the received MIDI event is to be placed.  Dean Camera committed May 08, 2010 179  *  Dean Camera committed Jun 17, 2010 180  * \return Boolean true if a MIDI event packet was received, false otherwise.  Dean Camera committed May 08, 2010 181 182 183 184 185 186 187  */ bool MIDI_Host_ReceiveEventPacket(USB_ClassInfo_MIDI_Host_t* const MIDIInterfaceInfo, MIDI_EventPacket_t* const Event) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Function Prototypes: */  Dean Camera committed Oct 24, 2010 188  #if defined(__INCLUDE_FROM_MIDI_HOST_C)  Dean Camera committed May 09, 2010 189 190  static uint8_t DCOMP_MIDI_Host_NextMIDIStreamingInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1); static uint8_t DCOMP_MIDI_Host_NextMIDIStreamingDataEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1);  191  #endif  Dean Camera committed May 08, 2010 192  #endif  193   Dean Camera committed May 08, 2010 194 195 196 197 198 199 200 201  /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif #endif /** @} */  202