usb endpoint module documentation

module usb_serial_ctrl_ep (
  input clk,
  input reset,
  output [6:0] dev_addr,

  // For terminology, see https://www.beyondlogic.org/usbnutshell/usb4.shtml.
  //
  // An output control transfer has three stages:
  // 1. Setup (the request from the host)
  // 2. Data (zero or more out packets containing data from the host)
  // 3. Status (a zero-length in packet requesting the endpoint's status of the overall transfer:
  //    done ["ack"], still processing ["nak"], or error ["stall"])
  //
  // An input control transfer has three stages:
  // 1. Setup (the request from the host)
  // 2. Data (zero or more in packets containing data from the endpoint)
  // 3. Status (a zero-length out packet requesting the endpoint's status of the overall transfer:
  //    ready to receive another input request ["ack"], still processing ["nak"], or error
  //    ["stall"])

  ////////////////////
  // out endpoint interface
  ////////////////////

  // To get data from the out endpoint, the following handshake happens:
  //
  // 1. out_ep_data_avail gets set.  // You've got data!
  // 2. Set out_ep_req.              // Can I have it now?
  // 3. out_ep_grant gets set.       // Yes!
  // 4. Set out_ep_data_get.         // Give me the data.
  // 5. Reset out_ep_data_get.
  // 6. Read out_ep_data.            // Here is the data.
  // (repeat 4-6 while out_ep_data_avail is set)
  //
  // TODO: Is 4-6 the right sequence? In other words, is out_ep_data guaranteed to be valid
  // after out_ep_data_get is reset? And I'm assuming the clocking of out_ep_data_get has a maximum
  // frequency, probably that of clk.

  // Set this when data is available (out_ep_data_avail set) in order to request the data.
  output out_ep_req,
  // Set after out_ep_req is set to indicate that the request is granted, and you are now free to
  // get the data by setting out_ep_data_get.
  input out_ep_grant,
  // Set after a DATA0 or DATA1 packet is received for this device and endpoint. If
  // out_ep_setup is high, then this is the data for a setup packet, otherwise this is
  // the data for an out packet.
  input out_ep_data_avail,
  // Set after a SETUP token is received, which indicates that host wants to
  // get a descriptor. Remains high until an OUT token is received. Not applicable to
  // endpoints that are not the control endpoint.
  input out_ep_setup,
  // Set this when the data request has been granted (out_ep_grant set) in order to get the data.
  // A positive transition clocks the next byte into out_ep_data. Continue clocking the data until
  // out_ep_data_avail gets reset.
  output out_ep_data_get,
  // A byte of output data. Only valid if out_ep_grant and out_ep_data_get are set.
  input [7:0] out_ep_data,
  // Set this after receiving the data for an out packet on an output stall condition. During the
  // data stage of a control transfer, a stall happens when the endpoint has had an error and the
  // halt bit is set (TODO: explain this). During the status stage of an output control transfer, a
  // stall happens when the endpoint had an error processing the previous host command (sent via an
  // IN token).
  output out_ep_stall,
  // Set after the host successfully received the input control transfer data.
  //
  // TODO: Is this the out packet for the status stage of an in transfer, or the in packet for
  // the status stage of an out tranfer?
  input out_ep_acked,


  ////////////////////
  // in endpoint interface
  ////////////////////

  // To send data via the in endpoint, the following handshake happens:
  //
  // 1. in_ep_data_free gets set.    // Ready to send.
  // 2. Set in_ep_req.               // I have data to send. Can I send it?
  // 3. in_ep_grant gets set.        // Yes!
  // 4. Set in_ep_data_put.          // This is the data.
  // 5. Set in_ep_data.              //
  // 6. Reset in_ep_data_put.        // Go ahead and send it.
  // (repeat 4-6 until no more data)
  // 7. Set in_ep_data_done.         // I have no more data to send.
  // 8. out_ep_acked gets set.       // Host received the data.
  //
  // TODO: Is 4-6 the right sequence? In other words, is in_ep_data required to be stable
  // when in_ep_data_put is reset? And I'm assuming the clocking of in_ep_data_put has a maximum
  // frequency, probably that of clk.
  //
  // TODO: Does setting in_ep_data_done imply that the endpoint is ready for another input request?
  // If so, does that mean it needs to set in_ep_stall instead of in_ep_data_done?

  // Set this when data is ready to send and the line is free (in_ep_data_free set) in order to
  // request permission to send.
  output in_ep_req,
  // Set after in_ep_req is set to indicate that the request is granted, and you are now free to
  // send the data by setting in_ep_data_put.
  input in_ep_grant,
  // Set when the controller is ready to accept a request to send data.
  input in_ep_data_free,
  // Set this when the data send request has been granted (in_ep_grant set) in order to send the
  // data that is in in_ep_data. A negative transition clocks the byte in in_ep_data_put onto the
  // bus. Continue clocking the data until no more data, then set in_ep_data_done.
  output in_ep_data_put,
  // The data to send.
  output reg [7:0] in_ep_data = 0,
  // Set this after final byte is sent.
  output in_ep_data_done,
  // Set this after sending the data for an in packet on an input stall condition. During the
  // data stage of a control transfer, a stall happens when the endpoint has had an error and the
  // halt bit is set (TODO: explain this). During the status stage of an input control transfer, a
  // stall happens when the endpoint had an error processing the previous host data (sent via an OUT
  // token).
  output reg in_ep_stall,
  // Set by the host to acknowledge our completion of processing of the output data sent by the
  // host.
  //
  // TODO: Is this the out packet for the status stage of an in transfer, or the in packet for
  // the status stage of an out tranfer?
  input in_ep_acked
);