/devstat
For example:
/dev/usb/472.b0b0/0/devstat
When ugen is bound to a single device interface, the follow-
ing logical device nodes are created:
Endpoint 0 (default endpoint):
/dev/usb/.//ifcntrl0
/dev/usb/.//ifcntrl0stat
For example:
/dev/usb/472.b0b0/0/if0cntrl0
/dev/usb/472.b0b0/0/if0cntrl0stat
Device status:
/dev/usb/.//ifdevstat
For example:
/dev/usb/472.b0b0/0/if0devstat
SunOS 5.11 Last change: 3 Dec 2008 5
Devices ugen(7D)
The format for all other logical device names is identical
to the format used when ugen is bound to the entire device.
Opening the endpoint of a different configuration or dif-
ferent alternate interface will cause an implicit change of
configuration or a switch to an alternate interface. A con-
figuration change is prohibited when any non-zero endpoint
device nodes are open. An alternate interface switch is
prohibited if any endpoint in the same interface is open.
HOT-PLUGGING
A device may be hot-removed at any time. Following hot-
removal, the device status changes to
USB_DEV_STAT_DISCONNECTED, the status of open endpoints
change to USB_LC_STAT_DISCONNECTED upon their access, and
all subsequent transfer requests fail. Endpoints are reac-
tivated by first reinserting the device and then closing and
reopening all endpoints that were open when the device was
disconnected.
CPR (CHECKPOINT/RESUME)
CPR (Checkpoint/Resume) may be initiated at any time and is
treated similarly to a hot-removal. Upon successful suspend
and resume, all subsequent transfer requests fail as an
indication to the application to reinitialize. Applications
should close and reopen all endpoints to reinstate them. All
endpoint and device status on Resume (before close and reo-
pen) is USB_LC_STAT_SUSPENDED. A system suspend will fail
while ugen is performing a transfer.
DEVICE POWER MANAGEMENT
Devices which support remote wakeup can be power managed
when they have no open logical device nodes. When an appli-
cation opens the first logical device node of a device, that
application should assume that a reinitialization of device
state is required.
DEVICE STATUS MANAGEMENT
Applications can monitor device status changes by reading
the device status from the device status logical name. When
opened without O_NONBLOCK and O_NDELAY, all reads from that
file descriptor (with the exception of the the intial read
that follows the open) block until a device status change
occurs. Calls to read will always return immediately if
opened with O_NONBLOCK or O_NDELAY. Nonblocking calls to
read which have no data to return, return no error and zero
bytes read.
Device statuses are:
SunOS 5.11 Last change: 3 Dec 2008 6
Devices ugen(7D)
USB_DEV_STAT_ONLINE Device is available.
USB_DEV_STAT_DISCONNECTED Device has been disconnected.
USB_DEV_STAT_RESUMED Device has been resumed, how-
ever, endpoints which were open
on suspend have not yet been
closed and reopened.
USB_DEV_STAT_UNAVAILABLE Device has been reconnected,
however, endpoints which were
open on disconnect have not yet
been closed and reopened.
The following code reads the device status device logical
name:
int fd;
int status;
if ((fd = open("/dev/usb/472.b0b0/0/devstat",
O_RDONLY)) < 0) {
/* handle error */
}
if (read(fd, &status, sizeof(status)) != sizeof(status)) {
/* handle error */
}
switch (status) {
case USB_DEV_STAT_DISCONNECTED:
printf ("Terminating as device has been disconnected.\n");
exit (0);
case USB_DEV_STAT_RESUMED:
case USB_DEV_STAT_UNAVAILABLE:
/*
* Close and reopen endpoints to reestablish device access,
* then reset device.
*/
break;
case USB_DEV_STAT_ONLINE:
default:
break;
}
SunOS 5.11 Last change: 3 Dec 2008 7
Devices ugen(7D)
Use poll(2) to block on several logical names simultane-
ously, including device status logical names. Poll indi-
cates when reading a logical name would return data. See
poll(2) for details. Calls to read may be done whether or
not they follow calls to poll.
ENDPOINT STATUS MANAGEMENT
Each data endpoint has a corresponding status logical name.
Use the status logical name to retrieve the state of the
data endpoint, including detail on how its most recent
transfer failed. Reads of the status file descriptors always
return immediately. See the ERRORS section for more informa-
tion on endpoint status values. All logical device name
files created for returning status must be opened with
O_RDONLY.
The following code illustrates reading the status file
descriptor of an endpoint which just failed a data transfer
in order to get more information on the failure.
int data_xfered, status;
int ep1_data_fd, ep1_stat_fd;
uchar_t request[8];
ep1_data_fd = open ("/dev/usb/472.b0b0/0/if0out1", O_WRONLY);
if (ep1_data_fd < 0) {
/* Handle open error. */
}
ep1_stat_fd = open ("/dev/usb/472.b0b0/0/if0out1stat",
O_RDONLY);
if (ep1_stat_fd < 0) {
/* Handle open error. */
}
data_xfered = write(ep1_data_fd, request, sizeof (request));
/* An error occured during the data transfer. */
if (data_xfered != sizeof (request)) {
/* Read status file descriptor for details on failure. */
if (read(ep1_stat_fd, (int *)&status, sizeof (status)) !=
sizeof (status)) {
status = USB_LC_STAT_UNSPECIFIED_ERR;
}
/* Take appropriate action. */
switch (status) {
case USB_LC_STAT_STALL:
printf ("Endpoint stalled.\n");
SunOS 5.11 Last change: 3 Dec 2008 8
Devices ugen(7D)
break;
case ...
...
}
}
CONTROL TRANSFERS
The control endpoint is typically used to set up the device
and to query device status or configuration.
Applications requiring I/O on a control endpoint should open
the corresponding logical device name and use regular UNIX
I/O system calls. For example: read(2), write(2),
aioread(3C) and aiowrite(3C). poll(2) is not supported on
control endpoints.
A control endpoint must be opened with O_RDWR since it is
bidirectional. It cannot be opened with O_NONBLOCK or
O_NDELAY.
For example:
fd = open("/dev/usb/472.b0b0/0/cntrl0", O_RDWR);
fdstat = open("/dev/usb/472.b0b0/0/cntrl0stat", O_RDONLY);
Control endpoints can be read and written. A read operation
receives data from the device and a write operation sends
data to the device.
To perform a control-IN transfer, perform a write(2) of USB
setup data (see section 9.3 of the USB 1.1 or 2.0 specifica-
tions) followed by a read(2) on the same control endpoint to
fetch the desired data. For example:
void init_cntrl_req(
uchar_t *req, uchar_t bmRequestType, uchar_t bRequest,
ushort_t wValue, ushort_t wIndex, ushort_t wLength) {
req[0] = bmRequestType;
req[1] = bRequest;
req[2] = 0xFF & wValue;
req[3] = 0xFF & (wValue >> 8);
SunOS 5.11 Last change: 3 Dec 2008 9
Devices ugen(7D)
req[4] = 0xFF & wIndex;
req[5] = 0xFF & (wIndex >> 8);
req[6] = 0xFF & wLength;
req[7] = 0xFF & (wLength >> 8);
}
....
uchar_t dev_descr_req[8];
usb_dev_descr_t descr;
init_cntrl_req(dev_descr_req,
USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
USB_DESCR_TYPE_SETUP_DEV, 0, sizeof (descr));
count = write(fd, dev_descr_req, sizeof (dev_descr_req));
if (count != sizeof (dev_descr_req)) {
/* do some error recovery */
...
}
count = read(fd, &descr, sizeof (descr));
if (count != sizeof (descr)) {
/* do some error recovery */
}
The application can issue any number of reads to read data
received on a control endpoint. ugen successfully completes
all reads, returning the number of bytes transferred. Zero
is returned when there is no data to transfer.
If the read/write fails and returns -1, you can access the
endpoint's status device logical name for precise error
information:
int status;
count = read(fdstat, &status, sizeof (status));
if (count == sizeof (status)) {
switch (status) {
case USB_LC_STAT_SUSPENDED:
case USB_LC_STAT_DISCONNECTED:
/* close all endpoints */
...
break;
default:
...
break;
SunOS 5.11 Last change: 3 Dec 2008 10
Devices ugen(7D)
}
}
Refer to the ERRORS section for all possible error values.
To perform a control-OUT transfer, send in a single
transfer, the USB setup data followed by any accompanying
data bytes.
/* 1st 8 bytes of wbuf are setup. */
init_cntrl_req(wbuf, .......);
/* Data bytes begin at byte 8 of wbuf. */
bcopy(data, &wuf[8], sizeof (data));
/* Send it all in a single transfer. */
count = write(fd, wbuf, sizeof (wbuf));
A write(2) returns the number of bytes (both setup and data)
actually transferred, (whether or not the write is com-
pletely successful), provided that some data is actually
transferred. When no data is transferred, write(2) returns
-1. Applications can read the corresponding endpoint status
to retrieve detailed error information. Note that it is an
error to specify a size different than:
(number of data bytes + number of setup bytes).
Here is a more extensive example which gets all descriptors
of a device configuration. For sake of brevity, uninterest-
ing parts are omitted.
#include
#include
uchar_t *config_cloud;
uchar_t *curr_descr;
uchar_t *bytes;
int curr_descr_len;
int curr_descr_type;
usb_cfg_descr_t cfg_descr;
usb_if_descr_t if_descr;
SunOS 5.11 Last change: 3 Dec 2008 11
Devices ugen(7D)
usb_ep_descr_t ep_descr;
/* See 9.13 of USB 2.0 spec for ordering. */
static char *pipetypes[] = {
"Control", "Isochronous", "Bulk", "Interrupt"
};
/*
* Setup to send a request to read just the config descriptor. The
* size of the whole cloud, containing all cfg, interface, endpoint,
* class and vendor-specific descriptors, will be returned as part of
* the config descriptor.
*/
init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
USB_DESCR_TYPE_SETUP_CFG, 0, USB_CFG_DESCR_SIZE);
/*
* Write setup data. USB device will prepare to return the whole
* config cloud as a response to this. We will read this separately.
*/
count = write(ctrl_fd, &setup_data, sizeof (setup_data));
if (count != sizeof (setup_data)) {
/* Error recovery. */
} else {
count = read(ctrl_fd, &cfg_descr, USB_CFG_DESCR_SIZE);
if (count != USB_CFG_DESCR_SIZE) {
/* Error recovery. */
}
}
/* USB data is little endian. */
bytes = (uchar_t *)(&cfg_descr.wTotalLength);
totalLength = bytes[0] + (bytes[1] << 8);
/*
* The size of the whole cloud is in the bLength field. Set up
* to read this amount of data, to get the whole cloud.
*/
config_cloud = malloc(totalLength);
init_cntrl_req(&setup_data, USB_DEV_REQ_DEV_TO_HOST, USB_REQ_GET_DESCR,
USB_DESCR_TYPE_SETUP_CFG, 0, totalLength);
count = write(ctrl_fd, &setup_data, sizeof (setup_data));
if (count != sizeof (setup_data)) {
/* Error recovery. */
} else {
count = read(ctrl_fd, config_cloud, totalLength);
if (count != totalLength) {
/* Error recovery. */
}
}
SunOS 5.11 Last change: 3 Dec 2008 12
Devices ugen(7D)
/* Got the data. Now loop, dumping out the descriptors found. */
curr_descr = config_cloud;
offset = 0;
while (offset < totalLength) {
/* All descr have length and type at offset 0 and 1 */
curr_descr_len = curr_descr[0];
curr_descr_type = curr_descr[1];
switch (curr_descr_type) {
case USB_DESCR_TYPE_CFG:
/*
* Copy data into separate structure, needed for
* proper alignment of all non char fields. Note:
* non-char fields of all descriptors begin on aligned
* boundaries. The issue is that some structures may
* be adjacent to others which have an odd-numbered
* byte size, and may thus start on an odd-numbered
* boundary. */
bcopy(curr_descr, &cfg_descr, curr_descr_len);
/* Remember to read any words in endian-neutral way. */
(void) printf("\nConfig %d found.\n",
cfg_descr.bConfigurationValue);
break;
case USB_DESCR_TYPE_IF:
bcopy(curr_descr, &if_descr, curr_descr_len);
(void) printf("\n\tInterface %d, Alt %d found.\n",
if_descr.bInterfaceNumber,
if_descr.bAlternateSetting);
break;
case USB_DESCR_TYPE_EP:
bcopy(curr_descr, &ep_descr, curr_descr_len);
(void) printf("\n\t\tEndpoint %d (%s-%s) found.\n",
(ep_descr.bEndpointAddress & USB_EP_NUM_MASK),
(pipetypes[
ep_descr.bmAttributes & USB_EP_ATTR_MASK]),
((ep_descr.bEndpointAddress &
USB_EP_DIR_IN) ? "IN" : "OUT"));
break;
default:
(void) printf(
"\n\t\t\tOther descriptor found. Type:%d\n",
curr_descr_type);
break;
SunOS 5.11 Last change: 3 Dec 2008 13
Devices ugen(7D)
}
offset += curr_descr_len;
curr_descr = &config_cloud[offset];
}
INTERRUPT-IN TRANSFERS
Applications requiring data from an interrupt-IN endpoint
should open the corresponding logical device name and use
read(2), aioread(3C) and poll(2) system calls.
An interrupt-IN endpoint must be opened with O_RDONLY. It
can also be opened using O_NONBLOCK or O_NDELAY if desired.
fd = open("/dev/usb/472.b0b0/0/if0in1", O_RDONLY);
fdstat = open("/dev/usb/472.b0b0/0/if0in1stat", O_RDONLY);
ugen starts polling interrupt-IN endpoints immediately upon
opening them and stops polling them upon closure. (Polling
refers to interrogation of the device by the driver and
should not be confused with poll(2), which is an interroga-
tion of the driver by the application.)
A read(2) of an endpoint opened with the O_NONBLOCK or
O_NDELAY flags set will not block when there is insufficient
data available to satisfy the request. The read simply
returns what it can without signifying any error.
Applications should continuously check for and consume
interrupt data. ugen enables buffering of up to one second
of incoming data. In case of buffer overflow, ugen stops
polling the interrupt-IN endpoint until the application con-
sumes all the data. In this case, a read(2) of an empty
buffer returns -1, sets the endpoint status to
USB_LC_STAT_INTR_BUF_FULL (to indicate that the buffer had
been full and polling had been stopped) and causes ugen to
start polling the endpoint again. To retrieve the status,
the application can open and read the corresponding
endpoint's status device logical name.
for (;;) {
count = read(fd, buf, sizeof(buf));
if (count == -1) {
SunOS 5.11 Last change: 3 Dec 2008 14
Devices ugen(7D)
int cnt, status;
cnt = read(fdstat, &status, sizeof (status));
if (cnt == -1) {
/* more error recovery here */
} else {
switch (status) {
case USB_LC_STAT_INTR_BUF_FULL:
...
break;
default:
...
break;
}
}
}
/* process the data */
....
}
ugen will never drop data. However, the device may drop data
if the application cannot read it at the rate that it is
produced.
Applications requiring unbuffered data from an interrupt-IN
endpoint should open the associated status endpoint with
O_RDWR before opening the associated interrupt-IN endpoint
and write a control byte with USB_EP_INTR_ONE_XFER set. All
other bits are reserved and should be 0.
"One transfer" mode will persist until disabled explicitly
after the associated interrupt-IN endpoint has been closed
by writing a control byte with USB_EP_INTR_ONE_XFER cleared.
"One transfer" mode is implicitly disabled when the
status/control endpoint is closed.
Attempts to change the "one transfer" mode while the end-
point is open will result in EINVAL.
An application can open multiple interrupt-IN endpoints and
can call poll(2) to monitor the availability of new data.
(Note: poll works with interrupt-IN data endpoints, not
their status endpoints.)
SunOS 5.11 Last change: 3 Dec 2008 15
Devices ugen(7D)
struct pollfd pfd[2];
bzero(pfd, sizeof (pfd));
pfd[0].fd = fd1; /* fd1 is one interrupt-IN endpoint. */
pfd[0].events = POLLIN;
pfd[1].fd = fd2; /* fd2 is another interrupt-IN endpoint. */
pfd[1].events = POLLIN;
for (;;) {
poll(pfd, 2, -1);
if (pfd[0].revents & POLLIN) {
count = read(fd1, buf, sizeof (buf));
....
}
if (pfd[1].revents & POLLIN) {
count = read(fd2, buf, sizeof (buf));
....
}
}
You can monitor the device status endpoint via poll(2) con-
currently with the multiple interrupt-IN endpoints. Simply
add another pollfd element to the pfd array in the previous
code example, and initialize the new element's fd field with
the file descriptor of the device status endpoint (opened
without O_NONBLOCK or O_NDELAY). Set the new element's
event field to POLLIN like the other elements. Note that
only interrupt-IN endpoints and the device status endpoint
can be monitored using poll(2).
INTERRUPT-OUT TRANSFERS
Applications requiring output on an interrupt-OUT endpoint
can open the corresponding logical device name and perform
regular UNIX I/O system calls such as write(2) and
aiowrite(3C).
An interrupt-OUT endpoint must be opened with O_WRONLY.
fd = open("/dev/usb/472.b0b0/0/if0out3", O_WRONLY);
fdstat = open("/dev/usb/472.b0b0/0/if0out3stat", O_RDONLY);
Data can be written to an interrupt-OUT endpoint as follows:
SunOS 5.11 Last change: 3 Dec 2008 16
Devices ugen(7D)
count = write(fd, buf, sizeof (buf)):
if (count == -1) {
/* error recovery */
}
BULK TRANSFERS
Applications requiring I/O on a bulk endpoint can open the
corresponding logical device name and perform regular UNIX
I/O system calls. For example: read(2), write(2),
aioread(3C) and aiowrite(3C). poll(2) is not supported on
bulk endpoints.
A bulk endpoint must be opened with O_RDONLY or O_WRONLY and
cannot be opened with O_NONBLOCK or O_NDELAY:
fd = open("/dev/usb/472.b0b0/0/if0in2", O_RDONLY);
fdstat = open("/dev/usb/472.b0b0/0/if0in2stat", O_RDONLY);
Data can be read from a bulk-IN endpoint as follows:
count = read(fd, buf, sizeof (buf)):
if (count == -1) {
/* error recovery */
}
Data can be written to a bulk-OUT endpoint as follows:
count = write(fd, buf, sizeof (buf)):
if (count == -1) {
/* error recovery */
}
ISOCHRONOUS TRANSFERS
Applications requiring I/O on an isochronous endpoint can
open the corresponding logical device name and perform regu-
lar UNIX I/O system calls such as read(2), write(2),
poll(2), aioread(3C) and aiowrite(3C). An isochronous end-
point must be opened with O_RDWR.
fd = open("/dev/usb/472.b0b0/0/if0.3in2", O_RDWR);
fdstat = open("/dev/usb/472.b0b0/0/if0.3in2stat", O_RDONLY);
SunOS 5.11 Last change: 3 Dec 2008 17
Devices ugen(7D)
Applications can use the status logical name to retrieve the
state of the isochronous data endpoint, including details on
why the most recent transfer failed.
Applications have the flexibility to specify the number of
isochronous packets and the size of individual packets they
want to transfer. Applications should use the following data
structures to exchange isochronous packet information with
the ugen driver:
typedef struct ugen_isoc_pkt_descr {
/*
* Set by the application, for all isochro.
* requests, to the num. of bytes to xfer
* in a packet.
*/
ushort_t dsc_isoc_pkt_len;
/*
* Set by ugen to actual num. of bytes sent/received
* in a packet.
*/
ushort_t dsc_isoc_pkt_actual_len;
/*
* Per pkt. status set by ugen driver both for the
* isochronous IN and OUT requests. Application can
* use USB_LC_STAT_* to parse the status.
*/
int dsc_isoc_pkt_status;
} ugen_isoc_pkt_descr_t;
typedef struct ugen_isoc_req_head {
/* pkt count of the isoc request */
int req_isoc_pkts_count;
/* pkt descriptors */
ugen_isoc_pkt_descr_t req_isoc_pkt_descrs[1];
} ugen_isoc_req_head_t;
req_isoc_pkts_count is limited by the capability of the USB
host controller driver. The current upper bound for the uhci
and ohci drivers is 512. The upper bound for the ehci driver
is 1024.
For an isochronous-IN endpoint, applications must first use
the ugen_isoc_req_head_t structure followed by
ugen_isoc_pkt_descr_t to write packet request information to
SunOS 5.11 Last change: 3 Dec 2008 18
Devices ugen(7D)
the ugen node. The ugen driver then checks the validity of
the request. If it is valid, the driver immediately begins
isochronous polling on the IN endpoint and applications can
proceed with read(2) of the data on the isochronous-IN end-
point. Upon successful return of read(2), isochronous packet
descriptors (whose dsc_isoc_pkt_actual_len and
dsc_isoc_pkt_status fields were filled by the driver) are
returned, followed by the request's device payload data.
Applications should continuously check for and consume iso-
chronous data. The ugen driver enables buffering of up to
eight seconds of incoming data for full-speed isochronous
endpoint, one second of data for high-speed isochronous end-
points who request one transaction per microframe and 1/3 of
a second of incoming data for high-speed high-bandwidth iso-
chronous endpoints who request three transactions per
microframe. In case of buffer overflow, ugen discards the
oldest data.
The isochronous-IN polling can only be stopped by a close(2)
associated file descriptor. If applications want to change
packet information, they must first close(2) the endpoint to
stop the isochronous-IN polling, then open(2) the endpoint
and write(2) new packets request.
The following example shows how to read an isochronous-IN
endpoint:
#include
char *buf, *p;
ushort_t pktlen;
int pktcnt, i;
int len;
ugen_isoc_req_head_t *req;
ugen_isoc_pkt_descr_t *pktdesc;
char rdbuf[5000];
pktcnt = 4; /* 4 packets in this request */
len = sizeof(int) +
sizeof(ugen_isoc_pkt_descr_t) * pktcount;
buf = malloc(len);
if (!buf) {
/* Error recovery. */
}
req = (ugen_isoc_req_head_t *)buf;
SunOS 5.11 Last change: 3 Dec 2008 19
Devices ugen(7D)
req->req_isoc_pkts_count = pktcnt;
pktdesc = (ugen_isoc_pkt_descr_t *)
(req->req_isoc_pkt_descrs);
for (i = 0; i < pktcnt; i++) {
/*
* pktlen should not exceed xfer
* capability of an endpoint
*/
pktdesc[i].dsc_isoc_pkt_len = pktlen;
pktdesc[i].dsc_isoc_pkt_actual_len = 0;
pktdesc[i].dsc_isoc_pkt_status = 0;
}
/*
* write request info to driver and len must
* be exactly the sum of
* sizeof(int) + sizeof(ugen_isoc_pkt_descr_t) * pktcnt.
* Otherwise, an error is returned.
*/
if (write(fd, buf, len) < 0) {
/* Error recovery. */
}
/*
* Read length should be sum of all pkt descriptors
* length + payload data length of all pkts
* (sizeof(ugen_isoc_pkt_descr_t) + pktlen) * pktcnt
*/
if (read(fd, rdbuf, (sizeof(ugen_isoc_pkt_descr_t) +
pktlen) * pktcnt) < 0) {
/* Error recovery. */
}
pktdesc = (ugen_isoc_pkt_descr_t *) rdbuf;
/* points to payload beginning */
p = rdbuf + pktcnt * sizeof(ugen_isoc_pkt_descr_t);
for (i = 0; i < pktcnt; i++) {
printf("packet %d len = %d,"
" actual_len = %d, status = 0x%x0,
i, pktdesc->dsc_isoc_pkt_len,
pktdesc->dsc_isoc_pkt_actual_len,
pktdesc->dsc_isoc_pkt_status);
/* Processing data */
/*
* next packet data payload, do NOT use
SunOS 5.11 Last change: 3 Dec 2008 20
Devices ugen(7D)
* dsc_isoc_pkt_actual_len
*/
p += pktdesc->dsc_isoc_pkt_len;
pktdesc++;
}
For an isochronous-OUT endpoint, applications use the same
packet descriptor and request structures to write request
information to the ugen node. Following the packet request
head information is the packet payload data. Upon successful
return of write(2), applications can read(2) the same ugen
file immediately to retrieve the individual packet transfer
status of the last request. If the application isn't con-
cerned about the status, it can omit it.
In the following example, an application transfers data on
an isochronous-OUT endpoint:
#include
char *buf, *p;
ushort_t i, pktlen;
int len, pktcnt;
ugen_isoc_req_head_t *req;
ugen_isoc_pkt_descr_t *pktdesc;
char rdbuf[4096];
pktcnt = 4;
/*
* set packet length to a proper value, don't
* exceed endpoint's capability
*/
pktlen = 1024;
len = sizeof(int) +
sizeof(ugen_isoc_pkt_descr_t) * pktcount;
len += pktlen * pktcnt;
buf = malloc(len);
if (!buf) {
/* Error recovery. */
}
req = (ugen_isoc_req_head_t *)buf;
req->req_isoc_pkts_count = pktcnt;
pktdesc =
SunOS 5.11 Last change: 3 Dec 2008 21
Devices ugen(7D)
(ugen_isoc_pkt_descr_t *)(req->req_isoc_pkt_descrs);
for (i = 0; i < pktcnt; i++) {
pktdesc[i].dsc_isoc_pkt_len = pktlen;
pktdesc[i].dsc_isoc_pkt_actual_len = 0;
pktdesc[i].dsc_isoc_pkt_status = 0;
}
/* moving to beginning of payload data */
p = buf + sizeof(int) + sizeof(*pktdesc) * pktcnt;
for (i = 0; i < pktcnt; i++) {
/* fill in the data buffer */
p += pktlen;
}
/*
* write packet request information and data to ugen driver
*
* len should be the exact value of sizeof(int) +
* sizeof(ugen_isoc_pkt_descr_t) * pktcnt + payload length
*/
if (write(fd, buf, len) < 0) {
/* Error recovery. */
}
/* read packet status */
if (read(fd, rdbuf, sizeof(*pktdesc) * pktcnt) < 0) {
/* Error recovery. */
} else {
/* Parse every packet's transfer status */
}
ERRORS
The following statuses are returned by endpoint status dev-
ice logical names:
USB_LC_STAT_NOERROR
No error.
USB_LC_STAT_CRC
CRC error detected.
SunOS 5.11 Last change: 3 Dec 2008 22
Devices ugen(7D)
USB_LC_STAT_BITSTUFFING
Bit stuffing error.
USB_LC_STAT_DATA_TOGGLE_MM
Data toggle did not match.
USB_LC_STAT_STALL
Endpoint returned stall.
USB_LC_STAT_DEV_NOT_RESP
Device not responding.
USB_LC_STAT_UNEXP_PID
Unexpected Packet Identifier (PID).
USB_LC_STAT_PID_CHECKFAILURE
Check bits on PID failed.
USB_LC_STAT_DATA_OVERRUN
Data overrun.
USB_LC_STAT_DATA_UNDERRUN
Data underrun.
USB_LC_STAT_BUFFER_OVERRUN
Buffer overrun.
USB_LC_STAT_BUFFER_UNDERRUN
Buffer underrun.
USB_LC_STAT_TIMEOUT
SunOS 5.11 Last change: 3 Dec 2008 23
Devices ugen(7D)
Command timed out.
USB_LC_STAT_NOT_ACCESSED
Not accessed by the hardware.
USB_LC_STAT_UNSPECIFIED_ERR
Unspecified USBA or HCD error.
USB_LC_STAT_NO_BANDWIDTH
No bandwidth available.
USB_LC_STAT_HW_ERR
Host Controller h/w error.
USB_LC_STAT_SUSPENDED
Device was suspended.
USB_LC_STAT_DISCONNECTED
Device was disconnected.
USB_LC_STAT_INTR_BUF_FULL
Polling was stopped as the interrupt-IN data buffer was
full. Buffer is now empty and polling has been resumed.
USB_LC_STAT_INTERRUPTED
Request was interrupted.
USB_LC_STAT_NO_RESOURCES
No resources available for request.
USB_LC_STAT_INTR_POLLING_FAILED
Failed to restart polling.
SunOS 5.11 Last change: 3 Dec 2008 24
Devices ugen(7D)
USB_LC_STAT_ISOC_POLLING_FAILED
Failed to start isochronous polling.
USB_LC_STAT_ISOC_UNINITIALIZED
Isochronous packet information not initialized.
USB_LC_STAT_ISOC_PKT_ERROR
All packets in this isochronous request have errors. The
polling on this isochronous-IN endpoint is suspended and
can be resumed on next read(2).
The following system call errno values are returned:
EINVAL An attempt was made to enable or disable "one
transfer" mode while the associated endpoint was
open.
EBUSY The endpoint has been opened and another open is
attempted.
EACCES An endpoint open was attempted with incorrect
flags.
ENOTSUP Operation not supported.
ENXIO Device associated with the file descriptor does
not exist.
ENODEV Device has been hot-removed or a suspend/resume
happened before this command.
EIO An I/O error occurred. Send a read on the end-
point status minor node to get the exact error
information.
EINTR Interrupted system call.
SunOS 5.11 Last change: 3 Dec 2008 25
Devices ugen(7D)
ENOMEM No memory for the allocation of internal struc-
tures.
FILES
/kernel/drv/ugen 32 bit ELF kernel module (x86 platform only)
/kernel/drv/sparcv9/ugen 64 bit ELF kernel module
/dev/usb/.//cntrl0
/dev/usb/.//cntrl0stat
/dev/usb/.//if
/dev/usb/.//if
stat
/dev/usb/.//if.
/dev/usb/.//if.
stat
/dev/usb/.//cfgif
/dev/usb/.//cfgif
/dev/usb/.//cfgif.
/dev/usb/.//cfgif.
stat
/dev/usb/.//devstat
/dev/usb/.//ifcntrl0
/dev/usb/.//ifcntrl0stat
where N is an integer representing the instance number of
this type of device. (All logical device names for a single
device share the same N.)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 3 Dec 2008 26
Devices ugen(7D)
_________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|__________________________________|
| Architecture | PCI-based SPARC |
|_____________________________|__________________________________|
| Availability | driver/usb/ugen, driver/usb/ugenu|
|_____________________________|__________________________________|
SEE ALSO
libusb(3LIB), close(2), poll(2), read(2), write(2),
aioread(3C), aiowrite(3C), usba(7D), usb_dev_descr(9S).
DIAGNOSTICS
In addition to being logged, the following messages may
appear on the system console. All messages are formatted in
the following manner:
Warning: (ugen): Error Message...
Too many minor nodes.
Device has too many minor nodes. Not all are available.
Instance number too high ().
Too many devices are using this driver.
Cannot access . Please reconnect.
This device has been disconnected because a device other
than the original one has been inserted. The driver
informs you of this fact by displaying the name of the
original device.
Device is not identical to the previous one on this port.
Please disconnect and reconnect.
Same condition as described above; however in this case,
the driver is unable to identify the original device
with a name string.
NOTES
ugen returns -1 for all commands and sets errno to ENODEV
when device has been hot-removed or resumed from a suspend.
The application must close and reopen all open minor nodes
SunOS 5.11 Last change: 3 Dec 2008 27
Devices ugen(7D)
to reinstate successful communication.
SunOS 5.11 Last change: 3 Dec 2008 28