#include <cyg/io/usb/usbs.h> |
cyg_bool usbs_rx_endpoint_halted(usbs_rx_endpoint* ep);
void usbs_set_rx_endpoint_halted(usbs_rx_endpoint* ep, cyg_bool new_state);
void usbs_start_rx_endpoint_wait(usbs_rx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);
cyg_bool
+usbs_tx_endpoint_halted(usbs_tx_endpoint* ep);
void usbs_set_tx_endpoint_halted(usbs_tx_endpoint* ep, cyg_bool new_state);
void usbs_start_tx_endpoint_wait(usbs_tx_endpoint* ep, void (*)(void*, int) complete_fn, void * complete_data);
Normal USB traffic involves straightforward handshakes, with either an +ACK to indicate that a packet was transferred +without errors, or a NAK if an error occurred, or +if a peripheral is currently unable to process another packet from the +host, or has no packet to send to the host. There is a third form of +handshake, a STALL, which indicates that the +endpoint is currently halted.
When an endpoint is halted it means that the host-side code needs to +take some sort of recovery action before communication over that +endpoint can resume. The exact circumstances under which this can +happen are not defined by the USB specification, but one example would +be a protocol violation if say the peripheral attempted to transmit +more data to the host than was permitted by the protocol in use. The +host can use the standard control messages get-status, set-feature and +clear-feature to examine and manipulate the halted status of a given +endpoint. There are USB-specific functions which can be used inside +the peripheral to achieve the same effect. Once an endpoint has been +halted the host can then interact with the peripheral using class or +vendor control messages to perform appropriate recovery, and then the +halted condition can be cleared.
Halting an endpoint does not constitute a device state change, and +there is no mechanism by which higher-level code can be informed +immediately. However, any ongoing receive or transmit operations will +be aborted with an -EAGAIN error, and any new +receives or transmits will fail immediately with the same error.
There are six functions to support halted endpoints, one set for +receive endpoints and another for transmit endpoints, with both sets +behaving in essentially the same way. The first, +usbs_rx_endpoint_halted, can be used to determine +whether or not an endpoint is currently halted: it takes a single +argument that identifies the endpoint of interest. The second +function, usbs_set_rx_endpoint_halted, can be +used to change the halted condition of an endpoint: it takes two +arguments; one to identify the endpoint and another to specify the new +state. The last function +usbs_start_rx_endpoint_wait operates in much the +same way as usbs_start_rx_buffer: when the +endpoint is no longer halted the device driver will invoke the +supplied completion function with a status of 0. The completion +function has the same signature as that for a transfer operation. +Often it will be possible to use a single completion function and have +the foreground code invoke either +usbs_start_rx_buffer or +usbs_start_rx_endpoint_wait depending on the +current state of the endpoint.