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 Opendev
 221 creates a
 222 .B Dev
 223 for the endpoint with directory
 224 .IR fn .
 225 Usually, the endpoint is a setup endpoint representing a device. The endpoint
 226 control file is open, but the data file is not. The USB description is void.
 227 In most cases drivers call
 228 .I startdevs
 229 and
 230 .I openep
 231 and do not call this function directly.
 232 .PP
 233 .I Configdev
 234 opens the data file for the device supplied and
 235 loads and parses its configuration information.
 236 After calling it, the device is ready for I/O and the USB description in
 237 .B Dev.usb
 238 is valid.
 239 .PP
 240 Control requests for an endpoint may be written by calling
 241 .I devctl
 242 in the style of
 243 .IR print (2).
 244 It is better not to call
 245 .I print
 246 directly because the control request should be issued as a single
 247 .I write
 248 system call.
 249 See
 250 .IR usb (3)
 251 for a list of available control requests (not to be confused with
 252 USB control transfers performed on a control endpoint).
 253 .SS Input/Output
 254 .I Opendevdata
 255 opens the data file for the device according to the given
 256 .IR mode .
 257 The mode must match that of the endpoint, doing otherwise is considered
 258 an error.
 259 Actual I/O is performed by reading/writing the descriptor kept in the
 260 .B dfd
 261 field of
 262 .BR Dev .
 263 .PP
 264 For control endpoints,
 265 it is not necessary to call
 266 .I read
 267 and
 268 .I write
 269 directly.
 270 Instead,
 271 .I usbcmd
 272 issues a USB control request to the device
 273 .I d
 274 (not to be confused with a
 275 .IR usb (3)
 276 control request sent to its control file).
 277 .I Usbcmd
 278 retries the control request several times upon failure because some devices
 279 require it.
 280 The format of requests is fixed per the USB standard:
 281 .I type
 282 is the type of request and
 283 .I req
 284 identifies the request. Arguments
 285 .I value
 286 and
 287 .I index
 288 are parameters to the request and the last two arguments,
 289 .I data
 290 and
 291 .IR count ,
 292 are similar to
 293 .I read
 294 and
 295 .I write
 296 arguments.
 297 However,
 298 .I data
 299 may be
 300 .B nil
 301 if no transfer (other than the control request) has to take place.
 302 The library header file includes numerous symbols defined to help writing
 303 the type and arguments for a request.
 304 .PP
 305 The return value from
 306 .I usbcmd
 307 is the number of bytes transferred, zero to indicate a stall and -1
 308 to indicate an error.
 309 .PP
 310 A common request is to unstall an endpoint that has been stalled
 311 due to some reason by the device (eg., when read or write indicate
 312 a count of zero bytes read or written on the endpoint). The function
 313 .I unstall
 314 does this.
 315 It is given the device that stalled the endpoint,
 316 .IR dev ,
 317 the
 318 stalled endpoint,
 319 .IR ep ,
 320 and the direction of the stall (one of
 321 .B Ein
 322 or
 323 .BR Eout ).
 324 The function takes care of notifying the device of the unstall as well
 325 as notifying the kernel.
 326 .SS Tools
 327 .I Class
 328 returns the class part of the number given, representing a CSP.
 329 .I Subclass
 330 does the same for the device subclass and
 331 .I Proto
 332 for the protocol.
 333 The counterpart is
 334 .IR CSP ,
 335 which builds a CSP from the device class, subclass, and protocol.
 336 For some classes,
 337 .I classname
 338 knows the name (for those with constants in the library header file).
 339 .PP
 340 The macros
 341 .I GET2
 342 and
 343 .I PUT2
 344 get and put a (little-endian) two-byte value and are useful to
 345 parse descriptors and replies for control requests.
 346 .PP
 347 Functions
 348 .I emallocz
 349 and
 350 .I estrdup
 351 are similar to
 352 .I mallocz
 353 and
 354 .I strdup
 355 but abort program operation upon failure.
 356 .PP
 357 The function
 358 .I Ufmt
 359 is a format routine suitable for
 360 .IR fmtinstall (2)
 361 to print a
 362 .B Dev
 363 data structure.
 364 The auxiliary
 365 .I hexstr
 366 returns a string representing a dump (in hexadecimal) of
 367 .I n
 368 bytes starting at
 369 .IR a .
 370 The string is allocated using
 371 .IR malloc (2)
 372 and memory must be released by the caller.
 373 .PP
 374 .I Loaddevstr
 375 returns the string obtained by reading the device string descriptor number
 376 .IR sid .
 377 .SH SOURCE
 378 .B /sys/src/cmd/nusb/lib
 379 .SH "SEE ALSO"
 380 .IR usb (3),
 381 .IR nusb (4).
 382 .SH BUGS
 383 Not heavily exercised yet.