sys/man/2/nusb

   1 .TH NUSB 2
   2 .SH NAME
   3 usbcmd,
   4 classname,
   5 closedev,
   6 configdev,
   7 devctl,
   8 getdev,
   9 loaddevstr,
  10 opendev,
  11 opendevdata,
  12 openep,
  13 unstall - USB device driver library
  14 .SH SYNOPSIS
  15 .EX
  16 .ta 8n +8n +8n +8n +8n +8n +8n
  17 #include <u.h>
  18 #include <libc.h>
  19 #include "../lib/usb.h"
  20 .sp 0.3v
  21 struct Dev {
  22         Ref;
  23         char*   dir;            /* path for the endpoint dir */
  24         int     id;             /* usb id for device or ep. number */
  25         int     dfd;            /* descriptor for the data file */
  26         int     cfd;            /* descriptor for the control file */
  27         int     maxpkt;         /* cached from usb description */
  28         Usbdev* usb;            /* USB description */
  29         void*   aux;            /* for the device driver */
  30         void    (*free)(void*); /* idem. to release aux */
  31 };
  32 .sp 0.3v
  33 struct Usbdev {
  34         ulong   csp;            /* USB class/subclass/proto */
  35         int     vid;            /* vendor id */
  36         int     did;            /* product (device) id */
  37         int     dno;            /* device release number */
  38         char*   vendor;
  39         char*   product;
  40         char*   serial;
  41         int     ls;             /* low speed */
  42         int     class;          /* from descriptor */
  43         int     nconf;          /* from descriptor */
  44         Conf*   conf[Nconf];    /* configurations */
  45         Ep*     ep[Nep];        /* all endpoints in device */
  46         Desc*   ddesc[Nddesc];  /* (raw) device specific descriptors */
  47 };
  48 .sp 0.3v
  49 struct Ep {
  50         uchar   addr;           /* endpt address */
  51         uchar   dir;            /* direction, Ein/Eout */
  52         uchar   type;           /* Econtrol, Eiso, Ebulk, Eintr */
  53         uchar   isotype;        /* Eunknown, Easync, Eadapt, Esync */
  54         int     id;
  55         int     maxpkt;         /* max. packet size */
  56         Conf*   conf;           /* the endpoint belongs to */
  57         Iface*  iface;          /* the endpoint belongs to */
  58 };
  59 .sp 0.3v
  60 struct Altc {
  61         int     attrib;
  62         int     interval;
  63         void*   aux;            /* for the driver program */
  64 };
  65 .sp 0.3v
  66 struct Iface {
  67         int     id;             /* interface number */
  68         ulong   csp;            /* USB class/subclass/proto */
  69         Altc*   altc[Naltc];
  70         Ep*     ep[Nep];
  71         void*   aux;            /* for the driver program */
  72 };
  73 .sp 0.3v
  74 struct Conf {
  75         int     cval;           /* value for set configuration */
  76         int     attrib;
  77         int     milliamps;      /* maximum power in this config. */
  78         Iface*  iface[Niface];  /* up to 16 interfaces */
  79 };
  80 .sp 0.3v
  81 struct Desc {
  82         Conf*   conf;           /* where this descriptor was read */
  83         Iface*  iface;          /* last iface before desc in conf. */
  84         Ep*     ep;             /* last endpt before desc in conf. */
  85         Altc*   altc;           /* last alt.c. before desc in conf. */
  86         DDesc   data;           /* unparsed standard USB descriptor */
  87 };
  88 .sp 0.3v
  89 struct DDesc {
  90         uchar   bLength;
  91         uchar   bDescriptorType;
  92         uchar   bbytes[1];
  93         /* extra bytes allocated here to keep the rest of it */
  94 };
  95 .sp 0.3v
  96 #define Class(csp)      ((csp)&0xff)
  97 #define Subclass(csp)   (((csp)>>8)&0xff)
  98 #define Proto(csp)      (((csp)>>16)&0xff)
  99 #define CSP(c, s, p)    ((c) | ((s)<<8) | ((p)<<16))
 100 #define GET2(p)         ...
 101 #define PUT2(p,v)       ...
 102 #define GET4(p)         ...
 103 #define PUT4(p,v)       ...
 104 #define dprint   if(usbdebug)fprint
 105 #define ddprint if(usbdebug > 1)fprint
 106 .sp 0.3v
 107 int     Ufmt(Fmt *f);
 108 char*   classname(int c);
 109 void    closedev(Dev *d);
 110 int     configdev(Dev *d);
 111 int     devctl(Dev *dev, char *fmt, ...);
 112 void*   emallocz(ulong size, int zero);
 113 char*   estrdup(char *s);
 114 char*   hexstr(void *a, int n);
 115 char*   loaddevstr(Dev *d, int sid);
 116 Dev*    opendev(char *fn);
 117 int     opendevdata(Dev *d, int mode);
 118 Dev*    openep(Dev *d, int id);
 119 int     unstall(Dev *dev, Dev *ep, int dir);
 120 int     usbcmd(Dev *d, int type, int req,
 121                 int value, int index, uchar *data, int count);
 122 Dev*    getdev(int id);
 123 .sp 0.3v
 124 extern int usbdebug;    /* more messages for bigger values */
 125 .EE
 126 .SH DESCRIPTION
 127 This library provides convenience structures and functions to write
 128 USB device drivers.
 129 It is not intended for user programs using USB devices.
 130 See
 131 .IR usb (3)
 132 for a description of the interfaces provided for that purpose.
 133 .PP
 134 Usb drivers rely on
 135 .IR usb (3)
 136 to perform I/O through USB as well as on
 137 .IR usbd
 138 to perform the initial configuration for the device's setup endpoint.
 139 The rest of the work is up to the driver and is where this library may help.
 140 .PP
 141 An endpoint as provided by
 142 .IR usb (3)
 143 is represented by a
 144 .B Dev
 145 data structure.
 146 The setup endpoint for a
 147 device represents the USB device, because it is the means to
 148 configure and operate the device.
 149 This structure is reference counted.
 150 Functions creating
 151 .B Devs
 152 adjust the number of references to one, initially.
 153 The driver is free to call
 154 .IR incref
 155 (in
 156 .IR lock (2))
 157 to add references and
 158 .I closedev
 159 to drop references (and release resources when the last one vanishes).
 160 As an aid to the driver, the field
 161 .B aux
 162 may keep driver-specific data and the function
 163 .B free
 164 will be called (if not null) to release the
 165 .B aux
 166 structure when the reference count goes down to zero.
 167 .PP
 168 .I Dev.dir
 169 holds the path for the endpoint's directory.
 170 .PP
 171 The field
 172 .B id
 173 keeps the device number for setup endpoints and the endpoint number
 174 for all other endpoints.
 175 For example, it would be
 176 .B 3
 177 for
 178 .B /dev/usb/ep3.0
 179 and
 180 .B 1
 181 for
 182 .BR /dev/usb/ep3.1 .
 183 It is easy to remember this because the former is created to operate
 184 on the device, while the later has been created as a particular endpoint
 185 to perform I/O.
 186 .PP
 187 Fields
 188 .B dfd
 189 and
 190 .B cfd
 191 keep the data and
 192 control file descriptors, respectively.
 193 When a
 194 .B Dev
 195 is created the control file is open, initially.
 196 Opening the data
 197 file requires calling
 198 .I opendevdata
 199 with the appropriate mode.
 200 .PP
 201 When the device configuration information has been loaded (see below),
 202 .B maxpkt
 203 holds the maximum packet size (in bytes) for the endpoint and
 204 .B usb
 205 keeps the rest of the USB information.
 206 .PP
 207 Most of the information in
 208 .B usb
 209 comes from parsing
 210 various device and configuration descriptors provided by the device,
 211 by calling one of the functions described later.
 212 Only descriptors unknown
 213 to the library are kept unparsed at
 214 .B usb.ddesc
 215 as an aid for the driver
 216 (which should know how to parse them and what to do with the information).
 217 .SS Configuration
 218 .PP
 219 .I Opendev
 220 creates a
 221 .B Dev
 222 for the endpoint with directory
 223 .IR fn .
 224 Usually, the endpoint is a setup endpoint representing a device. The endpoint
 225 control file is open, but the data file is not. The USB description is void.
 226 In most cases drivers call
 227 .I startdevs
 228 and
 229 .I openep
 230 and do not call this function directly.
 231 .PP
 232 .I Configdev
 233 opens the data file for the device supplied and
 234 loads and parses its configuration information.
 235 After calling it, the device is ready for I/O and the USB description in
 236 .B Dev.usb
 237 is valid.
 238 .PP
 239 Control requests for an endpoint may be written by calling
 240 .I devctl
 241 in the style of
 242 .IR print (2).
 243 It is better not to call
 244 .I print
 245 directly because the control request should be issued as a single
 246 .I write
 247 system call.
 248 See
 249 .IR usb (3)
 250 for a list of available control requests (not to be confused with
 251 USB control transfers performed on a control endpoint).
 252 .SS Input/Output
 253 .I Opendevdata
 254 opens the data file for the device according to the given
 255 .IR mode .
 256 The mode must match that of the endpoint, doing otherwise is considered
 257 an error.
 258 Actual I/O is performed by reading/writing the descriptor kept in the
 259 .B dfd
 260 field of
 261 .BR Dev .
 262 .PP
 263 For control endpoints,
 264 it is not necessary to call
 265 .I read
 266 and
 267 .I write
 268 directly.
 269 Instead,
 270 .I usbcmd
 271 issues a USB control request to the device
 272 .I d
 273 (not to be confused with a
 274 .IR usb (3)
 275 control request sent to its control file).
 276 .I Usbcmd
 277 retries the control request several times upon failure because some devices
 278 require it.
 279 The format of requests is fixed per the USB standard:
 280 .I type
 281 is the type of request and
 282 .I req
 283 identifies the request. Arguments
 284 .I value
 285 and
 286 .I index
 287 are parameters to the request and the last two arguments,
 288 .I data
 289 and
 290 .IR count ,
 291 are similar to
 292 .I read
 293 and
 294 .I write
 295 arguments.
 296 However,
 297 .I data
 298 may be
 299 .B nil
 300 if no transfer (other than the control request) has to take place.
 301 The library header file includes numerous symbols defined to help writing
 302 the type and arguments for a request.
 303 .PP
 304 The return value from
 305 .I usbcmd
 306 is the number of bytes transferred, zero to indicate a stall and -1
 307 to indicate an error.
 308 .PP
 309 A common request is to unstall an endpoint that has been stalled
 310 due to some reason by the device (eg., when read or write indicate
 311 a count of zero bytes read or written on the endpoint). The function
 312 .I unstall
 313 does this.
 314 It is given the device that stalled the endpoint,
 315 .IR dev ,
 316 the
 317 stalled endpoint,
 318 .IR ep ,
 319 and the direction of the stall (one of
 320 .B Ein
 321 or
 322 .BR Eout ).
 323 The function takes care of notifying the device of the unstall as well
 324 as notifying the kernel.
 325 .SS Tools
 326 .I Class
 327 returns the class part of the number given, representing a CSP.
 328 .I Subclass
 329 does the same for the device subclass and
 330 .I Proto
 331 for the protocol.
 332 The counterpart is
 333 .IR CSP ,
 334 which builds a CSP from the device class, subclass, and protocol.
 335 For some classes,
 336 .I classname
 337 knows the name (for those with constants in the library header file).
 338 .PP
 339 The macros
 340 .I GET2
 341 and
 342 .I PUT2
 343 get and put a (little-endian) two-byte value and are useful to
 344 parse descriptors and replies for control requests.
 345 .PP
 346 Functions
 347 .I emallocz
 348 and
 349 .I estrdup
 350 are similar to
 351 .I mallocz
 352 and
 353 .I strdup
 354 but abort program operation upon failure.
 355 .PP
 356 The function
 357 .I Ufmt
 358 is a format routine suitable for
 359 .IR fmtinstall (2)
 360 to print a
 361 .B Dev
 362 data structure.
 363 The auxiliary
 364 .I hexstr
 365 returns a string representing a dump (in hexadecimal) of
 366 .I n
 367 bytes starting at
 368 .IR a .
 369 The string is allocated using
 370 .IR malloc (2)
 371 and memory must be released by the caller.
 372 .PP
 373 .I Loaddevstr
 374 returns the string obtained by reading the device string descriptor number
 375 .IR sid .
 376 .SH SOURCE
 377 .B /sys/src/cmd/nusb/lib
 378 .SH "SEE ALSO"
 379 .IR usb (3),
 380 .IR nusb (4).
 381 .SH BUGS
 382 Not heavily exercised yet.