Descriptor.pm

filter: Statementstmt 64.7% 11 / 17 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 60.0% 3 / 5 Podpod 100% 2 / 2 totaltotal 66.6% 16 / 24 CC 1 SCAR 3.4
CC
1
Cov
65%
composite
2.0
device
2.0
BEGIN
1.0
CRAP 1.4
« HID/Descriptor/Interface.pm ↑ Summary
1 package USB::Descriptor;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use USB::Descriptor::Device;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 our $VERSION = '2';
8  
9 =head1 NAME
10  
11 USB::Descriptor - USB Device Descriptor generation tools
12  
13 =head1 SYNOPSIS
14  
15 A set of classes and methods for generating USB descriptor sets.
16  
17 use USB::Descriptor;
18  
19 my $device = USB::Descriptor::device( product => 'My First Device' );
20 $device->vendorID(0x1234);
21 $device->productID(0x5678);
22 $device->configurations( [ USB::Descriptor::Configuration->new() ] );
23 ...
24  
25 =head1 DESCRIPTION
26  
27 L<USB::Descriptor> provides a means of specifying a device's USB descriptors
28 and then generating descriptor structures suitable for use in the device's
29 firmware. However, L<USB::Descriptor> only generates the bytes that comprise the
30 structures, it does not handle generation of valid source code.
31  
32 Any strings used in the descriptor set are automatically assigned indexes and
33 collected into a set of string descriptors by the top level
34 L<USB::Descriptor::Device> object.
35  
36 The easiest way to create a new descriptor set is to use the
37 L<USB::Descriptor::device()> factory method. It accepts a hash of arguments that
38 happens to be the same hash expected by L<USB::Descriptor::Device> and returns
39 a reference to a new L<USB::Descriptor::Device> object.
40  
41 use USB::Descriptor;
42  
43 my $device = USB::Descriptor::device(
44 'usb_version' => '2.0.0', # Default
45 'max_packet_size' => 64, # Full speed device
46 'vendorID' => 0x1234,
47 'productID' => 0x5678,
48 'manufacturer' => 'Acme, Inc.',
49 'product' => 'Giant Catapult',
50 'serial_number' => '007',
51 'configurations' => [{
52 'description' => 'Configuration 0',
53 'remote_wakeup' => 1,
54 'max_current' => 100, # mA
55 'interfaces' => [{
56 'description' => 'Interface 0',
57 'endpoints' => [{
58 'direction' => 'in',
59 'number' => 1,
60 'max_packet_size' => 42,
61 }],
62 }],
63 },
64 );
65  
66 The code above generates a L<USB::Descriptor::Device> object as well as a
67 L<USB::Descriptor::Configuration>, a L<USB::Descriptor::Interface> and a single
68 L<USB::Descriptor::Endpoint>. Each descriptor object is configured using the
69 provided arguments and added to the descriptor tree.
70  
71 Values for the device descriptor structure can be obtained by calling
72 C<< $device->bytes >>, or by using arrayification ( C<@{$device}> ).
73  
74 my @bytes = $device->bytes
75  
76 or
77  
78 my @bytes = @{$device};
79  
80 A simple script can then be written to emit the device descriptor structure in
81 whatever language is appropriate to the device's project. For example, to store
82 the descriptor as an array of bytes for a B<C> language project...
83  
84 print "uint8_t device_descriptor[] = {", join(', ', @bytes), "};\n";
85  
86 Calling C<bytes> on a L<USB::Descriptor::Configuration> object, or arrayifying
87 it, produces a similar result. However, the configuration object returns more
88 than a configuration descriptor worth of values. It returns the concatenated set
89 of configuration, interface and endpoint descriptors that is requested by a USB
90 host during device enumeration. Generating suitable B<C> source might be
91 accomplished with:
92  
93 my @configurations = @{$device->configurations};
94 foreach my $configuration ( @configurations )
95 {
96 print 'uint8_t configuration[] = {',
97 join(', ', @{$configuration->bytes} ), "}\n";
98 }
99  
100 When calling C<bytes>, or arrayifying a L<USB::Descriptor::Device>, all of the
101 child objects are queried for their strings. The resulting strings are
102 automatically assigned string indexes and assembled into a string descriptor set.
103 The set of assembled strings can be retrieved as an array, in index order, by
104 calling C<< $device->strings >>. The first string in the array is the string that
105 should be returned by the device in response to a request for string ID 1.
106  
107 my @strings = $device->strings
108  
109 Suitable language-specific code can then be generated from the resulting array
110 of strings.
111  
112 =head1 CLASS METHODS
113  
114 =over
115  
116 =item $device = USB::Descriptor::composite(vendorID=>$vendorID, ...);
117  
118 Convience method for creating descriptors for Composite devices.
119  
120 Constructs and returns a new L<USB::Descriptor::Device> object using the
121 passed options and sets C<class>, C<subclass>, and C<protocol> to zero. Each
122 option key is the name of an accessor method of L<USB::Descriptor::Device>.
123  
124 =item $device = USB::Descriptor::device(vendorID=>$vendorID, ...);
125  
126 Constructs and returns a new L<USB::Descriptor::Device> object using the
127 passed options. Each option key is the name of an accessor method of
128 L<USB::Descriptor::Device>.
129  
130 =back
131  
132 =cut
133  
134 sub composite
135 0 ▶{
Subroutine composite: not called CC=1 SCAR=6.9
Pod documented
136 0 my %options = @_; # Hijack the passed options
137  
138 0 $options{'class'} = 0; # Forcefully configure for a composite device
139 0 $options{'subclass'} = 0;
140 0 $options{'protocol'} = 0;
141  
142 0 return device(%options);
143 }
144  
145 sub device
146 0 ▶{
Subroutine device: not called CC=1 SCAR=6.9
Pod documented
147 0 return USB::Descriptor::Device->new(@_);
148 }
149  
150 2 1;
151  
152 =head1 AUTHOR
153  
154 Brandon Fosdick, C<< <bfoz at bfoz.net> >>
155  
156  
157 =head1 BUGS
158  
159 Please report any bugs or feature requests to C<bug-usb-descriptor at rt.cpan.org>, or through
160 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=USB-Descriptor>. I will be notified, and then you'll
161 automatically be notified of progress on your bug as I make changes.
162  
163  
164 =head1 SUPPORT
165  
166 You can find documentation for this module with the perldoc command.
167  
168 perldoc USB::Descriptor
169  
170  
171 You can also look for information at:
172  
173 =over 4
174  
175 =item * RT: CPAN's request tracker (report bugs here)
176  
177 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=USB-Descriptor>
178  
179 =item * AnnoCPAN: Annotated CPAN documentation
180  
181 L<http://annocpan.org/dist/USB-Descriptor>
182  
183 =item * CPAN Ratings
184  
185 L<http://cpanratings.perl.org/d/USB-Descriptor>
186  
187 =item * Search CPAN
188  
189 L<http://search.cpan.org/dist/USB-Descriptor/>
190  
191 =back
192  
193  
194 =head1 ACKNOWLEDGEMENTS
195  
196  
197 =head1 LICENSE AND COPYRIGHT
198  
199 Copyright 2011 Brandon Fosdick.
200  
201 This program is released under the terms of the BSD License.
202  
203 =cut
« HID/Descriptor/Interface.pm ↑ Summary