Kernel Functions for Drivers                   usbparsedata(9F)



NAME
     usbparsedata  -  Tokenize  and  align  the  bytes  of  raw
     variable-format data

SYNOPSIS
     #include 



     sizet usbparsedata(char *format, uchart *data,
          sizet datalen, void *structure, sizet structlen);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     format       Null terminated string describing the format of
                  the  data  structure  for  general-purpose byte
                  swapping. The letters "c," "s,"  "l,"  and  "L"
                  represent  1,  2,  4  and  8  byte  quantities,
                  respectively. A descriptor that consists  of  a
                  short  and  two  bytes  would  be  described by
                  "scc." A number preceding a letter serves as  a
                  multiplier  of that letter. A format equivalent
                  to "scc" is "s2c."


     data         Raw descriptor data to parse.


     datalen      Length, in bytes, of the  raw  descriptor  data
                  buffer.


     structure    Destination data buffer where  parsed  data  is
                  returned.


     structlen    Length,  in  bytes,  of  the  destination  data
                  buffer.  Parsed  result  length will not exceed
                  this value.


DESCRIPTION
     The usbparsedata function parses data such as a  variable-
     format  class-  or  vendor-specific descriptor. The function
     also tokenizes and aligns the bytes of raw  descriptor  data
     into fields of a variable-format descriptor.






SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers                   usbparsedata(9F)



     While the USBA framework can parse the endpoint,  interface,
     configuration, and string descriptors defined by the USB 2.0
     specification,  the  format  of  class-  or  vendor-specific
     descriptors  cannot  be explicitly defined by the specifica-
     tion and will  be  unique  for  each.  The  format  argument
     defines how to parse such a descriptor.


     While the USB specification defines bit ordering as  little-
     endian,  this  routine  (like  the entire API), converts the
     data to the endianness of the host.


     The structlen parameter defines the size of the  destination
     data  buffer. Data is truncated to this size if the destina-
     tion data buffer is too small.

RETURN VALUES
     On success: Returns the size (in bytes) of the  parsed  data
     result.


     On failure: Returns 0. (Same as USBPARSEROR).

CONTEXT
     May be called from user, kernel or interrupt context.

EXAMPLES
         /*
          * Parse raw descriptor data in buf, putting result into retdescr.
          * retbuflen holds the size of retdescr buf;  routine returns
          * number of resulting bytes.
          *
          * Descriptor being parsed has 2 chars, followed by one short,
          * 3 chars and one more short.
          */
         sizet sizeofreturneddescr;
         xxxdescrt retdescr;

          sizeofreturneddescr = usbparsedata("ccscccs",
             buf, sizeof(buf), (void *)retdescr, (sizeof)xxxdescrt));
         if (sizeofreturneddescr < (sizeof (xxxdescrt))) {
                  /* Data truncated. */
         }

         or:

         sizeofreturneddescr = usbparsedata("2cs3cs",
             buf, sizeof(buf), (void *)retdescr, (sizeof)xxxdescrt));
         if (sizeofreturneddescr < (sizeof (xxxdescrt))) {
                 /* Data truncated. */
         }



SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers                   usbparsedata(9F)



ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 PCI-based systems           
    
     Interface stability          Committed                   
    
     Availability                 SUNWusb                     
    


SEE ALSO
     attributes(5),                         usbgetdevdata(9F),
     usbgetstringdescr(9F), usbgetcfg(9F)



































SunOS 5.11           Last change: 5 Jan 2004                    3