File Coverage

blib/lib/Device/Chip/Adapter.pm
Criterion Covered Total %
statement 29 32 90.6
branch 4 10 40.0
condition 2 6 33.3
subroutine 7 7 100.0
pod 2 2 100.0
total 44 57 77.1


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2015-2020 -- leonerd@leonerd.org.uk
5              
6 8     15   57335 use v5.26;
  8         29  
7 8     8   493 use Object::Pad 0.35;
  8         8923  
  8         34  
8              
9             package Device::Chip::Adapter 0.24;
10             role Device::Chip::Adapter :repr(HASH) :compat(invokable);
11              
12 8     8   7637 use utf8;
  8         100  
  8         37  
13              
14 8     8   263 use Carp;
  8         15  
  8         458  
15              
16 8     8   3215 use Struct::Dumb qw( readonly_struct );
  8         18662  
  8         36  
17              
18             require Device::Chip;
19              
20             =encoding UTF-8
21              
22             =head1 NAME
23              
24             C - an abstraction of a hardware communication device
25              
26             =head1 DESCRIPTION
27              
28             This package describes an interfaces tha classes can use to implement a driver
29             to provide access to some means of connecting an electronic chip or hardware
30             module to a computer. An instance implementing this interface provides some
31             means to send electrical signals to a connected chip or module, and receive
32             replies back from it; this device is called the I. This is provided
33             as a service to some instance of the related interface, L.
34              
35             It is suggested that a driver for a particular adapter provides a concrete
36             class named within the C heirarchy, adding the basic
37             name of the product or means of communication as a suffix; for example the
38             driver for communication device based on the I range of devices would
39             be called:
40              
41             package Device::Chip::Adapter::FTDI;
42              
43             This package provides a base class that such a specific implementation class
44             could use as a superclass, but it is not required to. The important detail is
45             that it provides the interface described by this documentation.
46              
47             =cut
48              
49             =head1 UTILITY CONSTRUCTOR
50              
51             =cut
52              
53             =head2 new_from_description
54              
55             $adapter = Device::Chip::Adapter->new_from_description( $DESC );
56              
57             This utility method is provided to allow end-user programs a convenient way to
58             construct a useable C instance from a given single
59             string value. This string takes the form of a the main name of the adapter
60             class (minus the leading C prefix), optionally
61             followed by a single colon and some comma-separated options. Each option takes
62             the form of a name and value, separated by equals sign. For example:
63              
64             FTDI
65             FTDI:
66             FTDI:product=0x0601
67             BusPirate:serial=/dev/ttyUSB3,baud=57600
68              
69             This utility method splits off the base name from the optional suffix, and
70             splits the options into an even-sized name/value list. It loads the class
71             implied by the base name and invokes a method called C
72             on it. This is passed the even-sized name/value list obtained by splitting
73             the option string. Any option named without a value will be passed having the
74             value true, as a convenience for options that are simple boolean flags.
75              
76             If the class does not provide the C method (and of
77             course, simply inheriting the base class one from here does not count), then
78             if there are no other options given, the plain C constructor is invoked
79             instead. If this is not possible because there are user-specified options that
80             must be honoured, then an exception is thrown instead.
81              
82             Note for example that in the case above, the C option would be passed
83             to the C adapter class still as a string value; it is likely that this
84             class would want to implement a C method to parse that
85             using the C operator into a plain integer.
86              
87             It is intended that this method is used for creating an adapter that a
88             standalone program can use from a description string specified by the user;
89             likely in a commandline option or environment variable.
90              
91             If I<$DESC> is undefined, a default value is taken from the environment
92             variable C, if defined. If not, an exception is thrown.
93              
94             =cut
95              
96             sub new_from_description
97             {
98 4     4 1 1552 shift;
99 4         8 my ( $description ) = @_;
100              
101 4 50 33     11 defined( $description //= $ENV{DEVICE_CHIP_ADAPTER} ) or
102             croak "Undefined Device::Chip adapter description";
103              
104 4 50       26 my ( $basename, $opts ) = $description =~ m/^([^:]+)(?::(.*))?$/ or
105             croak "Malformed adapter description - $description";
106              
107             # Not a hash, in case the same option is given more than once
108 4         12 my @opts = Device::Chip->_parse_options( $opts );
109              
110 4         9 my $class = "Device::Chip::Adapter::$basename";
111 4         17 ( my $file = "$class.pm" ) =~ s{::}{/}g;
112              
113 4         16 require $file;
114              
115 4         21 my $code = $class->can( "new_from_description" );
116 4 50 33     17 if( $code and $code != \&new_from_description ) {
    0          
117 4         12 return $class->$code( @opts );
118             }
119             elsif( !@opts ) {
120             # Fall back on plain ->new
121 0         0 return $class->new();
122             }
123              
124 0         0 croak "$class does not provide a ->new_from_description and we cannot fallback on ->new with options";
125             }
126              
127             =head1 METHODS
128              
129             The following methods documented in an C expression return L
130             instances.
131              
132             =cut
133              
134             =head2 make_protocol
135              
136             $protocol = await $adapter->make_protocol( $pname );
137              
138             Returns an object that satisfies one of the interfaces documented below in
139             L, depending on the protocol name given by I<$pname>. This should
140             be one of the following values:
141              
142             GPIO
143             SPI
144             I2C
145             UART
146              
147             It is unspecified what class these objects should belong to. In particular, it
148             is permitted that an adapter could even return itself as the protocol
149             implementation, provided it has the methods to satisfy the interface for that
150             particular protocol. This is especially convenient in the case that the
151             adapter is only capable of one kind of protocol.
152              
153             =cut
154              
155             # A default implementation that uses some reflection to simplify
156             # implementations
157             method make_protocol
158 7     7 1 120 {
159 7         45 my ( $pname ) = @_;
160              
161 7 50       59 if( my $code = $self->can( "make_protocol_$pname" ) ) {
162 7         22 return $code->( $self );
163             }
164             else {
165 0           croak "Unrecognised protocol name $pname";
166             }
167             }
168              
169             =head2 shutdown
170              
171             $adapter->shutdown;
172              
173             Shuts down the adapter in whatever manner is appropriate at the end of the
174             lifetime of the containing program; or at least, at the point when the program
175             has finished using the connected device.
176              
177             This method is allowed to block; it does not yield a L. It is suitable
178             to call from a C method or C block.
179              
180             =cut
181              
182             =head1 PROTOCOLS
183              
184             The following methods are common to all protocol instances:
185              
186             =head2 sleep
187              
188             await $protocol->sleep( $secs );
189              
190             Causes a fixed delay, given in (fractional) seconds. Adapter module authors
191             should attempt to perform this delay concurrently, overlapping IO with other
192             operations where possible.
193              
194             =head2 configure
195              
196             await $protocol->configure( %args );
197              
198             Sets configuration options for the protocol. The actual set of options
199             available will depend on the type of the protocol.
200              
201             Chip drivers should attempt to bundle their changes together into as few
202             C calls as possible, because adapters may find it most efficient to
203             apply multiple changes in one go.
204              
205             =head2 power
206              
207             await $protocol->power( $on );
208              
209             Switches on or off the power to the actual chip or module, if such ability is
210             provided by the adapter.
211              
212             =head2 list_gpios
213              
214             @pin_names = $protocol->list_gpios;
215              
216             Returns a list of the names of GPIO pins that are available for the chip
217             driver to use. This list would depend on the pins available on the adapter
218             itself, minus any pins that are in use by the protocol itself.
219              
220             Adapters should name GPIO pins in a way that makes sense from the hardware;
221             for example C, C, C, C, etc...
222              
223             =head2 meta_gpios
224              
225             @pin_definitions = $protocol->meta_gpios;
226              
227             Returns a list of definition objects that define the behavior of the GPIO
228             pins. This should be returned in the same order as the L method.
229              
230             Each returned value will be an instance with the following methods:
231              
232             =over 4
233              
234             =item name
235              
236             $def->name = STR
237              
238             Gives the device's name for that GPIO pin - the name that would be returned
239             by L and recognised by the other methods.
240              
241             =item dir
242              
243             $def->dir = "r" | "w" | "rw"
244              
245             Gives the data directions that the GPIO pin supports. C for pins that are
246             read-only, C for pins that are write-only, and C for pins that are
247             bidirectional.
248              
249             =item invert
250              
251             $def->invert = BOOL
252              
253             If true, the hardware itself will invert the sense of reads or writes to this
254             pin - that is, a low voltage on the pin will be represented by a true value in
255             the L and L methods, and a high voltage represented
256             by a false value.
257              
258             =back
259              
260             Adapter implementations may wish to use a L definition provided
261             by this package, called L to implement
262             these.
263              
264             =cut
265              
266             readonly_struct GPIODefinition => [qw( name dir invert )];
267              
268             =head2 write_gpios
269              
270             await $protocol->write_gpios( \%pin_values );
271              
272             Sets the named GPIO pins as driven outputs, and gives their new values. Any
273             GPIO pins not named are left as they are; either driving outputs at the
274             current state, or high-impedence inputs.
275              
276             Pins are specified as a C reference, mapping pin names (as returned by
277             the L method) to boolean logic levels.
278              
279             =head2 read_gpios
280              
281             \%pin_values = await $protocol->read_gpios( \@pin_names );
282              
283             Sets the named GPIO pins as high-impedence inputs, and reads their current
284             state. Any GPIO pins not named here are left as they are; either driving
285             outputs at the current state, or other inputs.
286              
287             Pins are specified in an C reference giving the names of pins (as
288             returned by the L method); read values are given in the returned
289             C reference which maps pin names to boolean logic levels.
290              
291             =head2 tris_gpios
292              
293             await $protocol->tris_gpios( \@pin_names );
294              
295             Sets the named GPIO pins as high-impedence inputs ("tristate"). Any GPIO pins
296             not named here are left as they are.
297              
298             This method is similar to L except that it does not return the
299             current pin values to the caller. Adapter implementations may implement this
300             by simply calling L or they may have a more efficient variant
301             that does not have to transfer these extra readings back from the adapter
302             hardware.
303              
304             =cut
305              
306             =head1 GPIO PROTOCOL
307              
308             The GPIO protocol adds no new abilities or methods; it is the most basic form
309             of protocol that simply provides access to the generic GPIO pins of the
310             device.
311              
312             =head1 SPI PROTOCOL
313              
314             =head2 Configuration Options
315              
316             The following configuration options are recognised:
317              
318             =over 4
319              
320             =item mode => 0 | 1 | 2 | 3
321              
322             The numbered SPI mode used to communicate with the chip.
323              
324             =item max_bitrate => INT
325              
326             The highest speed, in bits per second, that the chip can accept. The adapter
327             must pick a rate that is no higher than this. Note specifically that not all
328             adapters are able to choose a rate arbitrarily, and so the actually
329             communication may happen at some rate slower than this.
330              
331             =item wordsize => INT
332              
333             The number of bits per word transferred. Many drivers will not be able to
334             accept a number other than 8.
335              
336             For values less than 8, the value should be taken from the least-significant
337             bits of each byte given to the C or C methods.
338              
339             For values greater than 8, use character strings with wide codepoints inside;
340             such as created by the C function.
341              
342             =back
343              
344             =head2 readwrite
345              
346             $words_in = await $spi->readwrite( $words_out );
347              
348             Performs a complete SPI transaction; assert the SS pin, synchronously clock
349             the data given by the I<$words_out> out of the MOSI pin of the adapter while
350             simultaneously capturing the data coming in to the MISO pin, then release the
351             SS pin again. The values clocked in are eventually returned as the result of
352             the returned future.
353              
354             =head2 write
355              
356             await $spi->write( $words );
357              
358             A variant of C where the caller does not intend to make use of the
359             data returned by the device, and so the adapter does not need to return it.
360             This may or may not make a material difference to the actual communication
361             with the adapter or device; it could be implemented simply by calling the
362             C method and ignoring the return value.
363              
364             =head2 read
365              
366             $words = await $spi->read( $len );
367              
368             A variant of C where the chip will not care what data is written
369             to it, so the caller does not need to supply it. This may or may not make a
370             material difference to the actual communication with the adapter or device;
371             it could be implemented simply by calling the C method and passing
372             in some constant string of appropriate length.
373              
374             =head2 write_then_read
375              
376             $words_in = await $spi->write_then_read( $words_out, $len_in );
377              
378             Performs a complete SPI transaction; assert the SS pin, synchronously clock
379             the data given by I<$words_out> out of the MOSI pin of the adapter, then clock
380             in more data from the MISO pin, finally releasing the SS pin again. These two
381             operations must be performed within a single assert-and-release SS cycle. It
382             is unspecified what values will be sent out during the read phase; adapters
383             should typically send all-bits-low or all-bits-high, but in general may not
384             allow configuration of what that will be.
385              
386             This differs from the C method in that it works sequentially;
387             sending out words while ignoring the result, then reading in words while
388             sending unspecified data.
389              
390             =head2 assert_ss
391              
392             =head2 release_ss
393              
394             await $spi->assert_ss;
395              
396             await $spi->release_ss;
397              
398             Lower-level access methods to directly assert or release the SS pin of the
399             adapter. These would typically be used in conjunction with L
400             or L.
401              
402             =head2 readwrite_no_ss
403              
404             =head2 write_no_ss
405              
406             =head2 read_no_ss
407              
408             $words_in = await $spi->readwrite_no_ss( $words_out );
409              
410             await $spi->write_no_ss( $words );
411              
412             $words = await $spi->read_no_ss( $len );
413              
414             Lower-level access methods to directly perform a data transfer across the
415             MOSI/MISO pins of the adapter, without touching the SS pin. A complete SPI
416             transaction can be performed in conjunction with the L and
417             L methods.
418              
419             $spi->assert_ss
420             ->then( sub {
421             $spi->readwrite_no_ss( $words_out );
422             })
423             ->then( sub {
424             ( $words_in ) = @_;
425             $spi->release_ss->then_done( $words_in );
426             });
427              
428             These methods are provided for situations where it is not possible to know in
429             advance all the data to be sent out in an SPI transaction; where the chip
430             driver code must inspect some of the incoming data before it can determine
431             what else needs to be sent, but when these must all be sent in one SS-asserted
432             transaction.
433              
434             Because they perform multiple independent operations on the underlying
435             adapter, these lower-level methods may be less efficient than using the single
436             higher-level methods of L and L. As such, they should only
437             be used when the combined higher-level method cannot be used.
438              
439             Note that many of these methods can be synthesized from other simpler ones. A
440             convenient abstract base class, L, can be
441             used to do this, providing wrappers for some methods implemented using others.
442             This reduces the number of distinct methods that need to be provided.
443             Implementations may still, and are encouraged to, provide "better" versions of
444             those methods if they can be provided more efficiently than simply wrapping
445             others.
446              
447             =cut
448              
449             =head1 I2C PROTOCOL
450              
451             =head2 Configuration Options
452              
453             The following configuration options are recognised:
454              
455             =over 4
456              
457             =item addr => INT
458              
459             The (7-bit) slave address for the chip this protocol is communicating with.
460              
461             =item max_bitrate => INT
462              
463             The highest speed, in bits per second, that the chip can accept. The adapter
464             must pick a rate that is no higher than this. Note specifically that not all
465             adapters are able to choose a rate arbitrarily, and so the actually
466             communication may happen at some rate slower than this.
467              
468             =back
469              
470             =head2 write
471              
472             await $i2c->write( $bytes_out );
473              
474             Performs a complete I²C transaction to send the given bytes to the slave chip.
475             This includes the start condition, sending the addressing byte (which is
476             implied; it should I be included in C<$bytes_out>) and ending in the stop
477             condition.
478              
479             =head2 read
480              
481             $bytes_in = await $i2c->read( $len_in );
482              
483             Performs a complete I²C transaction to receive the given number of bytes back
484             from the slave chip. This includes the start condition, sending the addressing
485             byte and ending in a stop condition.
486              
487             =head2 write_then_read
488              
489             $bytes_in = await $i2c->write_then_read( $bytes_out, $len_in );
490              
491             Performs a complete I²C transaction to first send the given bytes to the slave
492             chip then reads the give number of bytes back, returning them. These two
493             operations must be performed within a single I²C transaction using a repeated
494             start condition.
495              
496             =head2 txn
497              
498             $result = await $i2c->txn( async sub {
499             my ( $helper ) = @_;
500             ...
501             } );
502              
503             Performs a complete custom I²C transaction. Within the code block invoked by
504             the transaction, the C, C and C methods may be
505             called on the passed C<$helper> instance, but they will B cause stop
506             conditions to be sent on the wire. A stop condition will be sent after the
507             code has finished. The return value from this method will be whatever is
508             returned by the inner code block.
509              
510             This method acts as a mutex lock, ensuring only one transaction can run
511             concurrently. This mutex is also used by the C, C and
512             C methods (which may optionally be implemented in terms of
513             the C method internally).
514              
515             =cut
516              
517             =head1 UART PROTOCOL
518              
519             The UART protocol is still subject to ongoing design. In particular, a
520             suitable interface for general-purpose spurious read notifications ha yet to
521             be designed. The current API is suitable for transmit-only, or
522             request/response interfaces where the PC side is in control of communications
523             and knows exactly when, and how many bytes long, data will be received.
524              
525             =head2 Configuration Options
526              
527             =over 4
528              
529             =item baudrate => INT
530              
531             The communication bitrate, in bits per second. Most adapters ought to be able
532             to accept the common ones such as 9600, 19200 or 38400.
533              
534             =item bits => INT
535              
536             The number of bits per character. Usually 8, though some adapters may be able
537             to offer smaller values.
538              
539             =item parity => "n" | "o" | "e"
540              
541             Disables parity generation/checking (when C), or enables it for odd
542             (when C) or even (when C).
543              
544             =item stop => 1 | 2
545              
546             The size of the stop state, in bits. Either 1 or 2.
547              
548             =back
549              
550             =head2 write
551              
552             await $uart->write( $bytes );
553              
554             Transmits the given bytes over the UART TX line.
555              
556             =head2 read
557              
558             $bytes = await $uart->read( $len );
559              
560             Receives the given number of bytes from the UART RX line. The returned future
561             will not complete until the requested number of bytes are available.
562              
563             This API is suitable for PC-first request/response style interfaces, but will
564             not be sufficient for chip-first notifications or other use-cases. A suitable
565             API shape for more generic scenarios is still a matter of ongoing design
566             investigation.
567              
568             =head1 AUTHOR
569              
570             Paul Evans
571              
572             =cut
573              
574             0x55AA;