Bus/USBtmc.pm untested

filter: Statementstmt 0.0% 0 / 271 Branchbran 0.0% 0 / 120 Conditioncond 0.0% 0 / 68 MC/DCmcdc 0.0% 0 / 43 Subroutinesub 0.0% 0 / 26 Podpod 0.0% 0 / 15 totaltotal 0.0% 0 / 543 CC 60 SCAR 62.6
CC
60
Cov
0%
connection_new
1190.0
connection_read
240.0
get_stb
20.0
CRAP 521.8
1 package Lab::Bus::USBtmc;
2 #ABSTRACT: USBtmc (Test & Measurement) Linux kernel driver bus
3 $Lab::Bus::USBtmc::VERSION = '3.899';
4 use v5.20;
5 use Config;
6  
7 # the ioctl includes need to have 'sizeof' definitions, which
8 # h2ph *does*not*provide* So we roll our own
9 our (%sizeof);
10  
11 {
12 # sizes needed for ioctl calls
13  
14 no warnings qw(redefine misc);
15  
16 %sizeof = (
17 'char' => (1 * 1),
18 'double' => ($Config{doublesize} * 1),
19 'int' => ($Config{intsize} * 1),
20 'long' => ($Config{longsize} * 1),
21 'short' => ($Config{shortsize} * 1),
22 'long double' => ($Config{longdblsize} * 1),
23 'long long' => ($Config{longlongsize} * 1),
24 'ptr' => ($Config{ptrsize} * 1),
25 '__uint8_t' => (1 * 1),
26 '__uint16_t' => (2 * 1),
27 '__uint32_t' => (4 * 1),
28 '__uint64_t' => (8 * 1),
29 'int8_t' => (1 * 1),
30 'int16_t' => (2 * 1),
31 'int32_t' => (4 * 1),
32 'int64_t' => (8 * 1),
33 'pid_t' => (4 * 1),
34 'caddr_t' => (4 * 1),
35 'sa_family_t' => (1 * 1),
36 'void' => (1 * 1),
37 );
38
39 %sizeof = (
40 (%sizeof),
41 'unsigned int' => $sizeof{int},
42 'unsigned char' => $sizeof{char},
43 'unsigned long' => $sizeof{long},
44 'unsigned short' => $sizeof{short},
45 );
46 }
47  
48 # "sys/ioctl.ph" throws a warning about FORTIFY_SOURCE, but
49 # this alternate is (perhaps?) not present on all systems,
50 # so do a workaround
51 if ( !defined( eval('require "linux/ioctl.ph";') ) ) {
52 require "sys/ioctl.ph";
53 }
54 require "linux/usb/tmc.ph";
55  
56 #
57 # please note: with the usbtmc kernel module on Linux
58 # kernel 4.7.4 (and some prior versions) the module has a
59 # built-in unchangable timeout of 5 seconds. So the only
60 # way to deal with timeouts is "try the read N times, and see
61 # if there is a response". It also makes no sense to "sleep between
62 # the write and read" of a query, since one might as well do
63 # the read and get a (potentially) faster result.
64  
65 # So:
66 # wait_query is ignored
67 # brutal only has the effect of not throwing errors on read timeouts
68 # timeout is rounded to 5 second interval, to give the number of reads
69 # that are tried
70  
71 # kernel <4.20 the default buffer size was 2048; later
72 # kernel versions have a default buffer size of 4096, but
73 # for some reason, tests with a TDS2024B show that the
74 # buffering is 1024. It might be at the 'device' end.
75  
76 # the reason this matters is in how one determines that a usbtmc
77 # 'read' is complete, because many of the queries do not return
78 # a completely deterministic number of bytes; so you have to request
79 # with a larger number, and you get less. Is that because the read
80 # is split up in multiple buffers (with more remaining to be read),
81 # or did you reach the end? Reading data that isn't there will give
82 # a timeout error, or hang the interface.
83  
84 # there are four hints for 'reached the end':
85 # the bytes returned is less than a full buffer
86 # the last byte of the returned buffer is '\n' (LF)
87 # the EOM bit is set in bmTransferAttributes (bit 0) (4.20+ only)
88 # the device has MAV bit set in STB when 'more data available'.
89 #
90  
91 # the STB can be read by ioctl USBTMC488_IOCTL_READ_STB (>=4.6)
92 # but it's only really useful if there is a USB 'interrupt'
93 # endpoint for retrieving STB in a side-channel from the main
94 # BULK-in data channel, otherwise it just gets queued to the end
95 # of the other data. (>=4.6 has this)
96  
97 # all of this stuff is relevant when binary data is read from the
98 # device, because you can't really trust that a \n at the end of
99 # a block of data means that it's the end, or just an unfortunate
100 # coincidence.
101  
102 # the EOM bit is faster to deal with, no extra USB i/o is
103 # requred, but it does need the requested buffer to be >=
104 # the internal buffer, to make sure that that one is getting
105 # the full buffer for which the EOM bit applies (instead of the
106 # first part of a buffer that is being transfered to user in
107 # smaller parts).
108  
109 # so, going to ignore the user read_length for performing
110 # the usb i/o, and only apply it when deciding what to
111 # store for transfer to user.
112  
113 # going with the ioctl "*STB?" version for now, since it
114 # seems more likely to work without weird failure modes.
115  
116 use strict;
117 use Scalar::Util qw(weaken);
118 use Carp;
119 use Lab::Bus;
120 use Data::Dumper;
121 use File::Which qw(which);
122  
123 our @ISA = ("Lab::Bus");
124  
125 our $DRIVER_TIMEOUT = 5; # sec, built into module
126 our $DRIVER_BUFFER = 4096; # module default? but devices may have smaller buffer
127  
128 our %fields = (
129 type => 'USBtmc',
130 brutal => 0, # ignore read timeout
131 read_length => -1, # bytes (if <= 0, no limit on returned size string)
132 wait_query => 10e-6, # ignored
133 timeout => 10, # sec,
134 read_buffer => $DRIVER_BUFFER,
135 no_LF => 0, # true if no \n at end of data
136 debug => 0, # debug print
137 );
138  
139  
140 sub new {
141 my $proto = shift;
142 my $class = ref($proto) || $proto;
143 my $twin = undef;
144 my $self = $class->SUPER::new(@_)
145 ; # getting fields and _permitted from parent class
146 $self->${ \( __PACKAGE__ . '::_construct' ) }(__PACKAGE__);
147  
148 # search for twin in %Lab::Bus::BusList. If there's none, place $self there and weaken it.
149 if ( $class eq __PACKAGE__ )
150 { # careful - do only if this is not a parent class constructor
151 if ( $twin = $self->_search_twin() ) {
152 undef $self;
153 return $twin; # ...and that's it.
154 }
155 else {
156 $Lab::Bus::BusList{ $self->type() }->{'default'} = $self;
157 weaken( $Lab::Bus::BusList{ $self->type() }->{'default'} );
158 }
159 }
160  
161 return $self;
162 }
163  
164 sub connection_new { # { tmc_address => primary address }
165 my $self = shift;
166 my $args = undef;
167 if ( ref $_[0] eq 'HASH' ) {
168 $args = shift;
169 } # try to be flexible about options as hash/hashref
170 else { $args = {@_} }
171  
172 my $fn;
173 my $usb_vendor;
174 my $usb_product;
175 my $usb_serial = '*';
176  
177 if ( defined $args->{'tmc_address'}
178 && $args->{'tmc_address'} =~ /^[0-9]*$/ ) {
179 $fn = "/dev/usbtmc" . $args->{'tmc_address'};
180 }
181 else {
182 # want the vendor/product as strings, hex values
183 if (
184 defined $args->{'visa_name'}
185 && ( $args->{'visa_name'}
186 =~ /USB::0x([0-9A-Fa-f]{4})::0x([0-9A-Fa-f]{4})::[^:]*::INSTR/
187 )
188 ) {
189 $usb_vendor = $1;
190 $usb_product = $2;
191 $usb_serial = $3;
192 }
193 else {
194 $usb_vendor = $args->{'usb_vendor'};
195 if ( $usb_vendor =~ /^\s*0x([\da-f]{4})/i ) {
196 $usb_vendor = $1;
197 }
198 else {
199 $usb_vendor = sprintf( '%04x', $usb_vendor );
200 }
201 $usb_product = $args->{'usb_product'};
202 if ( $usb_product =~ /^\s*0x([\da-f]{4})/i ) {
203 $usb_product = $1;
204 }
205 else {
206 $usb_product = sprintf( '%04x', $usb_product );
207 }
208 $usb_serial = $args->{'usb_serial'};
209 }
210 }
211  
212 if ( !defined $fn && ( !defined $usb_vendor || !defined $usb_product ) ) {
213 Lab::Exception::CorruptParameter->throw(
214 error => "No valid USB TMC address given to "
215 . __PACKAGE__
216 . "::connection_new()\n", );
217 }
218  
219 $self->{debug} = $self->{config}->{debug} || $self->{ins_debug};
220 $Data::Dumper::Useqq = 1 if $self->{debug};
221 $self->{read_buffer} = $self->{config}->{read_buffer};
222
223 # try to find device
224 # options: lsusb, /proc/bus/usb/ /sys/kernel/debug/usb/devices
225 # select matching serial; if usb_serial = '*' select first match.
226  
227 if ( !defined($fn) ) {
228 my $got = 0;
229  
230 if (
231 open( LSUSB_HANDLE,
232 "/usr/bin/lsusb -d ${usb_vendor}:${usb_product} -v 2>/dev/null |"
233 )
234 ) {
235 # sometimes lsusb doesn't have serial, not sure why
236 while (<LSUSB_HANDLE>) {
237 if ( !$got && /^\s*iSerial\s+\d+\s+([^\s]+)?/i ) {
238 $got = 1 if $usb_serial eq '*';
239 $self->{config}->{usb_serial} = $1;
240 next;
241 }
242 if ( $got && /^\s*iInterface\s+(\d+)\s/i ) {
243 $fn = "/dev/usbtmc$1";
244 last;
245 }
246 }
247 close(LSUSB_HANDLE);
248 }
249  
250 if ( !$got
251 && which("usb-devices")
252 && open( LSUSB_HANDLE, "usb-devices |" ) ) {
253 my $okdev = 0;
254 while (<LSUSB_HANDLE>) {
255 $okdev = 0 if /^\s*$/;
256 $okdev = 1
257 if /Vendor=${usb_vendor}\s+ProdID=${usb_product}\s/i;
258 next unless $okdev;
259 if (/SerialNumber=([^\s]+)/i) {
260 $got = 1 if $usb_serial eq '*' || $usb_serial eq $1;
261 $self->{config}->{usb_serial} = $1;
262 }
263 next unless $got;
264 if (/\sIf#=\s*(\d+|0x[\da-f]+)/i) {
265 my $devnum = $1 + 0;
266 $fn = "/dev/usbtmc$devnum";
267 last;
268 }
269 }
270 close(LSUSB_HANDLE);
271 }
272  
273 # modern /sys/ stuff, but maybe not user readable, or
274 # obsolete usbfs stuff, same format
275 if (
276 !$got
277 && ( open( LSUSB_HANDLE, "</sys/kernel/debug/usb/devices" )
278 || open( LSUSB_HANDLE, "</proc/bus/usb/devices" ) )
279 ) {
280 my $okdev = 0;
281 while (<LSUSB_HANDLE>) {
282 $okdev = 0 if /^\s*$/;
283 $okdev = 1
284 if /Vendor=${usb_vendor}\s+ProdID=${usb_product}\s/i;
285 next unless $okdev;
286 if (/SerialNumber=([^\s]+)/i) {
287 $got = 1 if $usb_serial eq '*' || $usb_serial eq $1;
288 $self->{config}->{usb_serial} = $1;
289 }
290 next unless $got;
291 if (/\sIf#=\s*(\d+)/i) {
292 $fn = "/dev/usbtmc$1";
293 last;
294 }
295 }
296 close(LSUSB_HANDLE);
297 }
298  
299 }
300  
301 if ( !defined $fn ) {
302 Lab::Exception::CorruptParameter->throw(
303 error => sprintf(
304 "Could not find specified device 0x%s/0x%s/%s in "
305 . __PACKAGE__
306 . "::connection_new()\n",
307 $usb_vendor, $usb_product, $usb_serial
308 ),
309 );
310 }
311  
312 # get some driver info, if it is available
313 # this is sysfs, not sure about older varieties,
314 # but you wouldn't have an up-to-date module for them, would you?
315  
316 if (open(TMCMOD,"</sys/module/usbtmc/parameters/io_buffer_size")) {
317 my $nbuf = <TMCMOD>;
318 $nbuf =~ s/\s$//g;
319 $DRIVER_BUFFER = $nbuf;
320 close(TMCMOD);
321 print STDERR "driver buf $nbuf\n" if $self->debug;
322 }
323  
324 if (open(TMCMOD,"</sys/module/usbtmc/parameters/usb_timeout")) {
325 my $timeout = <TMCMOD>;
326 $timeout =~ s/\s$//g;
327 $DRIVER_TIMEOUT = $timeout/1000; # module value in ms
328 close(TMCMOD);
329 print STDERR "driver timeout $timeout ms\n" if $self->debug;
330 }
331
332 my $connection_handle = undef;
333 my $tmc_handle = undef;
334  
335 open( $tmc_handle, "+<", $fn )
336 || Lab::Exception::CorruptParameter->throw(
337 error => $! . ": '$fn'\n" );
338 binmode($tmc_handle);
339 $tmc_handle->autoflush;
340  
341 $connection_handle
342 = { valid => 1, type => "USBtmc", tmc_handle => $tmc_handle };
343 return $connection_handle;
344 }
345  
346 # if read returns 'undef', that's an EOF/error/Timeout, see $!
347 # return a zero length string if brutal=1 and timeout
348 # READ_BUFFER is the max read buffer size, instrument/driver defines
349 # no_LF if we don't expect a \n at end of returned data.
350  
351 sub connection_read
352 { # @_ = ( $connection_handle, $args = { read_length, brutal }
353 my $self = shift;
354 my $connection_handle = shift;
355 my $args = undef;
356 if ( ref $_[0] eq 'HASH' ) {
357 $args = shift;
358 } # try to be flexible about options as hash/hashref
359 else { $args = {@_} }
360  
361 my $brutal = $args->{'brutal'} || $self->brutal();
362 my $read_length = $args->{'read_length'} || $self->read_length();
363 my $timeout = $args->{'timeout'} || $self->{'timeout'};
364 my $read_buffer = $args->{'read_buffer'} || $self->{'read_buffer'};
365 my $no_LF = $args->{'no_LF'} || $self->{'no_LF'};
366  
367 my $result = '';
368  
369 my $tmc_handle = $connection_handle->{'tmc_handle'};
370 my $iss;
371 my $tries = 0;
372  
373 while (1) {
374 my $buf;
375 $iss = sysread( $tmc_handle, $buf, $read_buffer );
376 if ( !defined($iss) ) {
377 if ( $! =~ /timed?\s*out/i ) {
378 $tries++;
379 next if $timeout <= 0;
380 next if $timeout >= $tries * $DRIVER_TIMEOUT;
381 if ( !$brutal ) {
382 Lab::Exception::Timeout->throw(
383 error => "USBtmc read time out\n",
384 );
385 }
386  
387 return '';
388 }
389 else {
390 Lab::Exception::DriverError->throw(
391 error => "USBtmc read error $!\n",
392 );
393 }
394 }
395 print STDERR "read: ",Dumper($buf),"\n" if $self->{debug};
396  
397  
398 if ($read_length > 0) {
399 my $totlength = length($result)+length($buf);
400 $totlength-- unless $no_LF;
401
402 $result .= substr($buf,0,$read_length-length($result))
403 if length($result) < $read_length;
404  
405 if ($totlength > $read_length) {
406 Lab::Exception::DriverError->throw(
407 error => "USBtmc data returned ($totlength) > read_length ($read_length)",
408 );
409 }
410 } else {
411 $result .= $buf;
412 }
413 if ($iss < $read_buffer ||
414 $no_LF || substr($buf,-1,1) eq "\n" ) {
415 last unless $self->get_stb($connection_handle,0x10);
416 }
417 }
418  
419 # strip \n at end
420 $result =~ s/\n$// unless $no_LF;
421 return $result;
422 }
423  
424  
425  
426 # read the status register via ioctl/usb interrupt endpoint
427  
428 # can select a single bit for true/false return:
429 # ex: get_stb($conn, STB_MAV);
430 #
431 sub get_stb {
432 my $self = shift;
433 my $connection_handle = shift;
434 my $tmc_handle = $connection_handle->{'tmc_handle'};
435 my $bitmask = shift;
436
437 my $stb = ' ';
438 my $iss = ioctl($tmc_handle,USBTMC488_IOCTL_READ_STB(), $stb);
439 if (!$iss) {
440 Lab::Exception::DriverError->throw(
441 error => "USBtmc read_stb ioctl error $!\n",
442 );
443 return 0;
444 }
445 $stb = unpack('C',$stb);
446 printf STDERR ("STB=0b%08b\n",$stb) if $self->debug;
447 return ($stb & $bitmask) != 0 if defined $bitmask;
448 return $stb;
449 }
450  
451  
452  
453 # write then read
454 sub connection_query
455 { # @_ = ( $connection_handle, $args = { command, read_length, wait_status, wait_query, brutal }
456 my $self = shift;
457 my $connection_handle = shift;
458 my $args = undef;
459 if ( ref $_[0] eq 'HASH' ) {
460 $args = shift;
461 } # try to be flexible about options as hash/hashref
462 else { $args = {@_} }
463  
464 # my $wait_query = $args->{'wait_query'} || $self->wait_query();
465 # just use regular 'timeout' for the wait time
466 my $result = undef;
467  
468 $self->connection_write($connection_handle, $args);
469 $result = $self->connection_read($connection_handle, $args);
470 return $result;
471 }
472  
473 sub connection_write
474 { # @_ = ( $connection_handle, $args = { command, wait_status }
475 my $self = shift;
476 my $connection_handle = shift;
477 my $args = undef;
478 if ( ref $_[0] eq 'HASH' ) {
479 $args = shift;
480 } # try to be flexible about options as hash/hashref
481 else { $args = {@_} }
482  
483 my $command = $args->{'command'} || undef;
484  
485 if ( !defined $command ) {
486 Lab::Exception::CorruptParameter->throw(
487 error => "No command given to "
488 . __PACKAGE__
489 . "::connection_write().\n", );
490 }
491  
492 # use syswrite, since 'print' and 'sysread' should not be mixed
493 my $iss = syswrite( $connection_handle->{'tmc_handle'}, $command );
494  
495 if ( !defined($iss) ) {
496 Lab::Exception::DriverError->throw(
497 error => "USBtmc write error $!\n",
498 );
499 return 0;
500 }
501  
502 return 1;
503 }
504  
505 sub connection_settermchar { # @_ = ( $connection_handle, $termchar
506  
507 # my $self = shift;
508 # my $connection_handle=shift;
509 # my $termchar =shift; # string termination character as string
510 #
511  
512 # useless for USBtmc, return success
513  
514 return 1;
515 }
516  
517 sub connection_enabletermchar { # @_ = ( $connection_handle, 0/1 off/on
518  
519 # my $self = shift;
520 # my $connection_handle=shift;
521 # my $arg=shift;
522 #
523 # useless for USBtmc, return success
524  
525 return 1;
526 }
527  
528 sub serial_poll {
529 my $self = shift;
530 my $connection_handle = shift;
531 my $sbyte = undef;
532  
533 # useless for USBtmc return undef
534 return $sbyte;
535 }
536  
537 sub connection_clear {
538 my $self = shift;
539 my $connection_handle = shift;
540  
541 close( $connection_handle->{'tmc_handle'} );
542 }
543  
544 sub connection_device_clear {
545 my $self = shift;
546 my $connection_handle = shift;
547  
548 my $unused = 0;
549  
550 ioctl(
551 $connection_handle->{'tmc_handle'},
552 USBTMC_IOCTL_ABORT_BULK_OUT(), $unused
553 );
554 ioctl(
555 $connection_handle->{'tmc_handle'},
556 USBTMC_IOCTL_ABORT_BULK_IN(), $unused
557 );
558 ioctl(
559 $connection_handle->{'tmc_handle'},
560 USBTMC_IOCTL_CLEAR_OUT_HALT(), $unused
561 );
562 ioctl(
563 $connection_handle->{'tmc_handle'},
564 USBTMC_IOCTL_CLEAR_IN_HALT(), $unused
565 );
566 ioctl(
567 $connection_handle->{'tmc_handle'}, USBTMC_IOCTL_CLEAR(),
568 $unused
569 );
570 }
571  
572 sub timeout {
573 my $self = shift;
574 my $connection_handle = shift;
575 my $timo = shift;
576  
577 my $t;
578  
579 if ( $timo !~ /^\s*(\+|\-)?(\d+\.\d*|\d+|\d*\.\d+)\s*$/ ) {
580 Lab::Exception::CorruptParameter->throw(
581 error => "Bad timeout value '$timo'\n" );
582 return;
583 }
584  
585 $timo = $timo + 0;
586  
587 if ( $timo <= 0 ) {
588 $t = -1; # infinite
589 }
590 else {
591 $t = ( int( $timo / $DRIVER_TIMEOUT ) + 1 ) * $DRIVER_TIMEOUT;
592 }
593 $self->{timeout} = $t;
594 }
595  
596 sub ParseIbstatus
597 { # Ibstatus
598 # https://linux-gpib.sourceforge.io/doc_html/reference-globals-ibsta.html
599 my $self = shift;
600 my $ibstatus = shift; # stb byte from device
601
602 carp("ParseIbstatus not supported");
603 }
604  
605 sub VerboseIbstatus {
606 my $self = shift;
607 my $ibstatus = shift;
608  
609 carp("VerboseIbstatus not supported");
610 }
611  
612 #
613 # search and return an instance of the same type in %Lab::Bus::BusList
614 #
615 sub _search_twin {
616 my $self = shift;
617  
618 if ( !$self->ignore_twins() ) {
619 for my $conn ( values %{ $Lab::Bus::BusList{ $self->type() } } ) {
620 return $conn; # if $conn->gpib_board() == $self->gpib_board();
621 }
622 }
623 return undef;
624 }
625  
626 1;
627  
628  
629 1;
630  
631 __END__