Lemz_SwCtrlStmProj/App/usb/usb_hooks.h

// -----------------------------------------------------------------------------
// USB Library "usblib"
// Target:  for lpc17xx
// Author:  Sychov A.
// Date:    12/10/2018
// Version: 1.0
// -----------------------------------------------------------------------------
// File:    USB-hooks header
// Version: 1.0
// -----------------------------------------------------------------------------

#ifndef USB_HOOKS_H
#define USB_HOOKS_H
    
    #include "usb/usb_transfers.h"
    #include "usb/usb_spec.h"

    // USB-Callbacks (Hooks)

    // fUsbEpIrqHandler_t:
    // Callback-type function is called on each interrupt of any endpoint.    
    // @EndpointStatus - 32-bit word of flags, where each bit represents
    // each physical endpoint.
    // Bit 0 - EP0RX
    // Bit 1 - EP0TX
    // Bit 2 - EP1RX
    // Bit 3 - EP1TX, and etc.
    // The value 1 in the bit means an interrupt occurred on apropriate endpoint.
    // The notification type function code must clear the interrupt in hardware itself.
    typedef void (* fUsbEpIrqHandler_t )( uint32_t EndpointStatus );

    // fUsbBusReset_t:
    // The notification type function is called on USB-bus reset event
    typedef void (* fUsbBusReset_t)(); 

    // fUsbSetIface_t:
    // The notification type function is called to inform the application of interface activating
    // The function must return 'true' if application able to activate specified interface, and 'false' otherwise.
    // In case of 'false', the USB-request causes request error.
    // The callee should take account the bAlternateSetting of specified @iface, active bAlternateSetting value can be requested by @fUsbGetIface_t
    typedef bool (* fUsbSetIface_t)( uint8_t cfgidx, uint8_t ifidx, const sUSBInterfaceDescriptor_t * ifdesc );    

    // fUsbClrIface_t:
    // The notification type function is called to inform the application of interface de-activating
    // The callee should take account the bAlternateSetting of specified @iface, active bAlternateSetting value can be requested by @fUsbGetIface_t
    typedef void (* fUsbClrIface_t)( uint8_t cfgidx, uint8_t ifidx, const sUSBInterfaceDescriptor_t * ifdesc );

    // fUsbGetIface_t:
    // The request-type function is called to query the interface active alternate setting
    // If this callback is not specified, the alternate setting = 0 will be reported in GET_INTERFACE request
    typedef bool (* fUsbGetIface_t)( uint8_t cfgidx, uint8_t ifidx, uint8_t * pAltSetting );

    // fUsbSuspendEvent_t:
    // The notification type function is called on USB suspending/resuming event
    // @suspend - suspend state, true - USB-Controller is suspended, false - USB-Controller is resumed
    typedef void (* fUsbSuspendEvent_t)( bool suspend );

    // The data arrival event
    // This hook is called to process the portion of data by application
    // @pSetup - the setup packet caused the callback call
    // @rx - the transfer to read data from
    // @idx - the data index, equals to the number of bytes already sent in request
    // @bytesRemaining - the whole amount of bytes needed to receive more.
    // For control transfers (EP0) this number depends on the @wLength.
    // Note: @tx refers to the Transfer-object with small buffer with the size 
    // less than @bytesRemaining. The user must read the bytes from transfer @tx
    // and return the read bytes count. This value is provided by usb_read_transfer().
    // The @bytesRemaining is amount of remaining bytes to receive incliding the bytes
    // queued into @rx transfer.
    typedef size_t (* fUsbCtlEpRx_t) ( const tUSBSetupPacket_t * pSetup, sUSBTransfer_t * rx, size_t idx, size_t bytesRemaining );

    // The data requesting event
    // This hook is called to provide the portion of data for the usb-core
    // @pSetup - the setup packet caused the callback call
    // @tx - the transfer to write data into
    // @idx - the data index, equals to the number of bytes already received in request
    // @bytesRemaining - the whole amount of bytes needed to send more.
    // For control transfers (EP0) this number depends on the @wLength.
    // Note: @rx refers to the Transfer-object with small buffer with the size 
    // less than @bytesRemaining. The user must write not more than @bytesRemaining
    // in each callback call until the Transfer-buffer is full. Since the transfer
    // buffer fulls, the usb_write_transfer() returns 0.
    // The function must return the written bytes count into the transfer @tx
    // This value is provided by usb_write_transfer().    
    typedef size_t (* fUsbCtlEpTx_t) ( const tUSBSetupPacket_t * pSetup, sUSBTransfer_t * tx, size_t idx, size_t bytesRemaining );

    // fUsbSetupRx_t:
    // The callback type function is called on each received SETUP packet in Control Endpoint.
    // The function is called twice: firstly before the packet processing in the kernel,
    // secondly afther the processing.
    // In case the callback function code processes the SETUP packet itself and wants to
    // intercept it and make the packet aren't processed in the kernel, the function must
    // return 'false' at first stage. Otherwise, in case the function returns 'true', it 
    // should not process the packet, but can use the event as notification.
    // The second stage does not appear in case the first stage function returns 'false'.
    // Otherwise, the second stage function is called after the packet is processed in 
    // kernel. It does not matter what value the function returns in this stage.
    // @bFirstStage - stage flag. For first stage - 'true', for second - 'false'
    // @success - the indicator whether the setup packet is processed correcly at second stage. 
    // For first stage @success is always false.
    typedef bool (* fUsbSetupRx_t) ( const tUSBSetupPacket_t * pSetup, bool bFirstStage, bool success );
   
    typedef bool (* fUsbDataRx_t)(   uint8_t bEpLogAddress,
                                     sUSBTransfer_t * rx );

    typedef bool (* fUsbDataTx_t)(   uint8_t bEpLogAddress,
                                     sUSBTransfer_t * tx );

    // fUsbDataErr_t
    // Notify-type callback is called when a USB error occurred
    // @bConfValue - active configuration value
    // @bIntNumber - active interface number
    // @bEpLogAddress - active endpoint address
    // @error - error mask, see USB Error flags below.
    // To proceed, the function must return true.
    // Otherwise, if function returns false, the library may interrupt current operation
    typedef bool (* fUsbDataErr_t)(  uint8_t bEpLogAddress,
                                               uint32_t error );

    typedef int8_t (* fUsbInit_t )(void);
    typedef int8_t (* fUsbDeInit_t )(void);

    typedef bool   (* fUsbDataInit_t )( uint8_t epnum );
    typedef void   (* fUsbDataDeInit_t )( uint8_t epnum );
                   
    // Enumeration-Level hooks:
    typedef struct
    {
        fUsbSetupRx_t       fUsbSetup;        // optional
        fUsbCtlEpRx_t       fUsbCtlEpRx;      // optional
        fUsbCtlEpTx_t       fUsbCtlEpTx;      // optional
        fUsbEpIrqHandler_t  fIrqHandler;      // optional        
        fUsbBusReset_t      fResetEvent;      // optional
        fUsbSuspendEvent_t  fSuspendEvent;    // optional
        fUsbSetIface_t      fSetIface;        // optional SetInterface/SetConfiguration request handler
        fUsbClrIface_t      fClrIface;        // optional SetInterface/SetConfiguration request handler
        fUsbGetIface_t      fGetIface;        // optional (GET_INTERFACE request)
        fUsbDataRx_t        fDataRxHandler;   // optional ( endpoints I/O )
        fUsbDataTx_t        fDataTxHandler;   // optional ( endpoints I/O )
        fUsbDataErr_t       fDataErrHandler;  // optional ( endpoints I/O )
    }
    sUSBHooks_t;

    typedef struct
    {
       fUsbInit_t          fUsbInit;
       fUsbDeInit_t        fUsbDeInit;
       fUsbSetupRx_t       fUsbSetup;  
       fUsbCtlEpRx_t       fUsbCtlEpRx;
       fUsbCtlEpTx_t       fUsbCtlEpTx;
       fUsbBusReset_t      fResetEvent; 
    }
    sUSBAppEntry_Control_t;

    typedef struct
    {
       fUsbDataInit_t      fDataInitHandler;   // optional
       fUsbDataRx_t        fDataRxHandler;     // optional
       fUsbDataTx_t        fDataTxHandler;     // optional
       fUsbDataErr_t       fDataErrHandler;    // optional
       fUsbDataDeInit_t    fDataDeInitHandler; // optional
    }
    sUSBAppEntry_Data_t;

    // USB Error flags for @fUsbDataErr_t:
    #define USB_ERR_NOERR       0 
    #define USB_ERR_RX          (1<<0)   // common receive error       
    #define USB_ERR_TX          (1<<1)   // common transmit error       
    #define USB_ERR_TX_NODATA   (1<<2)   // no data available to transmit
    #define USB_ERR_STALL       (1<<3)   // endpoint is stalled
#endif