diff --git a/endpoint.go b/endpoint.go index 116a876..b6794f2 100644 --- a/endpoint.go +++ b/endpoint.go @@ -111,7 +111,7 @@ func (e *endpoint) transfer(ctx context.Context, buf []byte) (int, error) { // InEndpoint represents an IN endpoint open for transfer. // InEndpoint implements the io.Reader interface. -// For high-throughput transfers, consider creating a bufffered read stream +// For high-throughput transfers, consider creating a buffered read stream // through InEndpoint.ReadStream. type InEndpoint struct { *endpoint @@ -120,6 +120,13 @@ type InEndpoint struct { // Read reads data from an IN endpoint. Read returns number of bytes obtained // from the endpoint. Read may return non-zero length even if // the returned error is not nil (partial read). +// It's recommended to use buffer sizes that are multiples of +// EndpointDesc.MaxPacketSize to avoid overflows. +// When a USB device receives a read request, it doesn't know the size of the +// buffer and may send too much data in one packet to fit in the buffer. +// If that happens, Read will return an error signaling an overflow. +// See http://libusb.sourceforge.net/api-1.0/libusb_packetoverflow.html +// for more details. func (e *InEndpoint) Read(buf []byte) (int, error) { return e.transfer(context.Background(), buf) } @@ -130,6 +137,13 @@ func (e *InEndpoint) Read(buf []byte) (int, error) { // The passed context can be used to control the cancellation of the read. If // the context is cancelled, ReadContext will cancel the underlying transfers, // resulting in TransferCancelled error. +// It's recommended to use buffer sizes that are multiples of +// EndpointDesc.MaxPacketSize to avoid overflows. +// When a USB device receives a read request, it doesn't know the size of the +// buffer and may send too much data in one packet to fit in the buffer. +// If that happens, Read will return an error signaling an overflow. +// See http://libusb.sourceforge.net/api-1.0/libusb_packetoverflow.html +// for more details. func (e *InEndpoint) ReadContext(ctx context.Context, buf []byte) (int, error) { return e.transfer(ctx, buf) } diff --git a/endpoint_stream.go b/endpoint_stream.go index b4f2780..9a0117a 100644 --- a/endpoint_stream.go +++ b/endpoint_stream.go @@ -35,6 +35,9 @@ func (e *endpoint) newStream(size, count int) (*stream, error) { // defines how many transactions should be active at any time. // By keeping multiple transfers active at the same time, a Stream reduces // the latency between subsequent transfers and increases reading throughput. +// Similarly to InEndpoint.Read, the size of the buffer should be a multiple +// of EndpointDesc.MaxPacketSize to avoid overflows, see documentation +// in InEndpoint.Read for more details. func (e *InEndpoint) NewStream(size, count int) (*ReadStream, error) { s, err := e.newStream(size, count) if err != nil {