share/man/man9f/usb_parse_data.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USB_PARSE_DATA 9F "Oct 30, 2016"
   7 .SH NAME
   8 usb_parse_data \- Tokenize and align the bytes of raw variable-format data
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13
  14
  15
  16 \fBsize_t\fR \fBusb_parse_data\fR(\fBchar *\fR\fIformat\fR, \fBuchar_t *\fR\fIdata\fR,
  17      \fBsize_t\fR \fIdatalen\fR, \fBvoid *\fR\fIstructure\fR, \fBsize_t\fR \fIstructlen\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .LP
  22 Solaris DDI specific (Solaris DDI)
  23 .SH PARAMETERS
  24 .ne 2
  25 .na
  26 \fB\fIformat\fR\fR
  27 .ad
  28 .RS 13n
  29 Null terminated string describing the format of the data structure for
  30 general-purpose byte swapping. The letters "c," "s," "l," and "L" represent 1,
  31 2, 4 and 8 byte quantities, respectively. A descriptor that consists of a short
  32 and two bytes would be described by "scc." A number preceding a letter serves
  33 as a multiplier of that letter. A format equivalent to "scc" is "s2c."
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIdata\fR\fR
  40 .ad
  41 .RS 13n
  42 Raw descriptor data to parse.
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIdatalen\fR\fR
  49 .ad
  50 .RS 13n
  51 Length, in bytes, of the raw descriptor data buffer.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIstructure\fR\fR
  58 .ad
  59 .RS 13n
  60 Destination data buffer where parsed data is returned.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIstructlen\fR\fR
  67 .ad
  68 .RS 13n
  69 Length, in bytes, of the destination data buffer. Parsed result length will not
  70 exceed this value.
  71 .RE
  72
  73 .SH DESCRIPTION
  74 .LP
  75 The \fBusb_parse_data\fR function parses data such as a variable-format class-
  76 or vendor-specific descriptor. The function also tokenizes and aligns the bytes
  77 of raw descriptor data into fields of a variable-format descriptor.
  78 .sp
  79 .LP
  80 While the USBA framework can parse the endpoint, interface, configuration, and
  81 string descriptors defined by the \fIUSB 3.0\fR specification, the format of
  82 class- or vendor-specific descriptors cannot be explicitly defined by the
  83 specification and will be unique for each. The \fIformat\fR argument defines
  84 how to parse such a descriptor.
  85 .sp
  86 .LP
  87 While the USB specification defines bit ordering as little-endian, this routine
  88 (like the entire API), converts the data to the endianness of the host.
  89 .sp
  90 .LP
  91 The \fIstructlen\fR parameter defines the size of the destination data buffer.
  92 Data is truncated to this size if the destination data buffer is too small.
  93 .SH RETURN VALUES
  94 .LP
  95 On success: Returns the size (in bytes) of the parsed data result.
  96 .sp
  97 .LP
  98 On failure: Returns 0. (Same as USB_PARSE_ERROR).
  99 .SH CONTEXT
 100 .LP
 101 May be called from user, kernel or interrupt context.
 102 .SH EXAMPLES
 103 .in +2
 104 .nf
 105   /*
 106    * Parse raw descriptor data in buf, putting result into ret_descr.
 107    * ret_buf_len holds the size of ret_descr buf;  routine returns
 108    * number of resulting bytes.
 109    *
 110    * Descriptor being parsed has 2 chars, followed by one short,
 111    * 3 chars and one more short.
 112    */
 113   size_t size_of_returned_descr;
 114   xxx_descr_t ret_descr;
 115
 116    size_of_returned_descr = usb_parse_data("ccscccs",
 117       buf, sizeof(buf), (void *)ret_descr, (sizeof)xxx_descr_t));
 118   if (size_of_returned_descr < (sizeof (xxx_descr_t))) {
 119            /* Data truncated. */
 120   }
 121
 122   or:
 123
 124   size_of_returned_descr = usb_parse_data("2cs3cs",
 125       buf, sizeof(buf), (void *)ret_descr, (sizeof)xxx_descr_t));
 126   if (size_of_returned_descr < (sizeof (xxx_descr_t))) {
 127           /* Data truncated. */
 128   }
 129 .fi
 130 .in -2
 131
 132 .SH ATTRIBUTES
 133 .LP
 134 See \fBattributes\fR(5) for descriptions of the following attributes:
 135 .sp
 136
 137 .sp
 138 .TS
 139 box;
 140 c | c
 141 l | l .
 142 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 143 _
 144 Architecture    PCI-based systems
 145 _
 146 Interface stability     Committed
 147 .TE
 148
 149 .SH SEE ALSO
 150 .LP
 151 \fBattributes\fR(5), \fBusb_get_dev_data\fR(9F),
 152 \fBusb_get_string_descr\fR(9F), \fBusb_get_cfg\fR(9F)