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