| 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-2023 -- leonerd@leonerd.org.uk | ||||||||||||||||||||
| 5 | |||||||||||||||||||||
| 6 | 9 | ▶ | use v5.26; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 7 | 9 | ▶ | use warnings; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 8 | 9 | ▶ | use Object::Pad 0.800; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | |||||||||||||||||||||
| 10 | package Device::Chip 0.27; | ||||||||||||||||||||
| 11 | class Device::Chip :repr(HASH); | ||||||||||||||||||||
| 12 | |||||||||||||||||||||
| 13 | 9 | ▶ | use Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 14 | |||||||||||||||||||||
| 15 | 9 | ▶ | use Future::AsyncAwait 0.38; # async method | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 16 | |||||||||||||||||||||
| 17 | =head1 NAME | ||||||||||||||||||||
| 18 | |||||||||||||||||||||
| 19 | C<Device::Chip> - an abstraction of a hardware chip IO driver | ||||||||||||||||||||
| 20 | |||||||||||||||||||||
| 21 | =head1 DESCRIPTION | ||||||||||||||||||||
| 22 | |||||||||||||||||||||
| 23 | =for highlighter language=perl | ||||||||||||||||||||
| 24 | |||||||||||||||||||||
| 25 | =over 2 | ||||||||||||||||||||
| 26 | |||||||||||||||||||||
| 27 | B<Note>: this document is currently under heavy development. Details will be | ||||||||||||||||||||
| 28 | added, changed, and evolved as it progresses. Be warned that currently | ||||||||||||||||||||
| 29 | anything may be changed from one version to the next. | ||||||||||||||||||||
| 30 | |||||||||||||||||||||
| 31 | =back | ||||||||||||||||||||
| 32 | |||||||||||||||||||||
| 33 | This package describes an interface that classes can use to implement a driver | ||||||||||||||||||||
| 34 | to talk to a specific hardware chip or module. An instance implementing this | ||||||||||||||||||||
| 35 | interface would communicate with the actual hardware device via some instance | ||||||||||||||||||||
| 36 | of the related interface, L<Device::Chip::Adapter>. | ||||||||||||||||||||
| 37 | |||||||||||||||||||||
| 38 | The documentation in this file is aimed primarily at users of C<Device::Chip> | ||||||||||||||||||||
| 39 | subclasses. For more information on authoring such a module, see instead | ||||||||||||||||||||
| 40 | L<Device::Chip::Authoring>. | ||||||||||||||||||||
| 41 | |||||||||||||||||||||
| 42 | =head2 USING A CHIP DRIVER | ||||||||||||||||||||
| 43 | |||||||||||||||||||||
| 44 | To actually use a chip driver to talk to a specific piece of hardware that is | ||||||||||||||||||||
| 45 | connected to the computer, an adapter must be supplied. This will be an | ||||||||||||||||||||
| 46 | instance of some class that satisfies the L<Device::Chip::Adapter> interface. | ||||||||||||||||||||
| 47 | The chip driver will use this adapter instance to access the underlying | ||||||||||||||||||||
| 48 | hardware port used to electrically connect to the chip and communicate with | ||||||||||||||||||||
| 49 | it. This is supplied by invoking the L</mount> method. For example: | ||||||||||||||||||||
| 50 | |||||||||||||||||||||
| 51 | my $chip = Device::Chip::MAX7219->new; | ||||||||||||||||||||
| 52 | |||||||||||||||||||||
| 53 | my $adapter = Device::Chip::Adapter::FTDI->new; | ||||||||||||||||||||
| 54 | |||||||||||||||||||||
| 55 | await $chip->mount( $adapter ); | ||||||||||||||||||||
| 56 | |||||||||||||||||||||
| 57 | =cut | ||||||||||||||||||||
| 58 | |||||||||||||||||||||
| 59 | =head1 CONSTRUCTOR | ||||||||||||||||||||
| 60 | |||||||||||||||||||||
| 61 | =cut | ||||||||||||||||||||
| 62 | |||||||||||||||||||||
| 63 | =head2 new | ||||||||||||||||||||
| 64 | |||||||||||||||||||||
| 65 | $chip = Device::Chip->new; | ||||||||||||||||||||
| 66 | |||||||||||||||||||||
| 67 | Returns a new instance of a chip driver object. | ||||||||||||||||||||
| 68 | |||||||||||||||||||||
| 69 | =cut | ||||||||||||||||||||
| 70 | |||||||||||||||||||||
| 71 | =head1 METHODS | ||||||||||||||||||||
| 72 | |||||||||||||||||||||
| 73 | The following methods documented in an C<await> expression return L<Future> | ||||||||||||||||||||
| 74 | instances. | ||||||||||||||||||||
| 75 | |||||||||||||||||||||
| 76 | This allows them to easily be used as a simple synchronous method by using the | ||||||||||||||||||||
| 77 | trailing L<Future/get> call. Alternatively, if the underlying adapter allows a | ||||||||||||||||||||
| 78 | fully asynchronous mode of operation, they can be combined in the usual ways | ||||||||||||||||||||
| 79 | for futures to provide more asynchronous use of the device. | ||||||||||||||||||||
| 80 | |||||||||||||||||||||
| 81 | =cut | ||||||||||||||||||||
| 82 | |||||||||||||||||||||
| 83 | 9 | field $_adapter; | |||||||||||||||||||
| 84 | method adapter | ||||||||||||||||||||
| 85 | 0 | ▶ | { | ||||||||||||||||||
|
Subroutine
adapter: not called CC=2 SCAR=17.9
Pod
undocumented
| |||||||||||||||||||||
| 86 | 0 | ▶ | return $_adapter // | ||||||||||||||||||
|
Condition0%0/2
$_adapter // croak("This chip has not yet been mounted on an adapter")
MC/DC0%0/1
$_adapter // croak("This chip has not yet been mounted on an adapter")
$_adapter
Truth table0%0/2
A
A= $_adapter
| |||||||||||||||||||||
| 87 | croak "This chip has not yet been mounted on an adapter"; | ||||||||||||||||||||
| 88 | 9 | } | |||||||||||||||||||
| 89 | |||||||||||||||||||||
| 90 | 9 | field $_protocol; | |||||||||||||||||||
| 91 | method protocol | ||||||||||||||||||||
| 92 | 17 | ▶ | { | ||||||||||||||||||
|
Subroutine
protocol: called CC=2 SCAR=7.6
Pod
undocumented
| |||||||||||||||||||||
| 93 | 17 | ▶ | return $_protocol // | ||||||||||||||||||
|
Condition50%1/2
$_protocol // croak("This chip has not yet been connected to a protocol")
MC/DC0%0/1
$_protocol // croak("This chip has not yet been connected to a protocol")
$_protocol
Truth table50%1/2
A
A= $_protocol
| |||||||||||||||||||||
| 94 | croak "This chip has not yet been connected to a protocol"; | ||||||||||||||||||||
| 95 | 9 | } | |||||||||||||||||||
| 96 | |||||||||||||||||||||
| 97 | =head2 mount | ||||||||||||||||||||
| 98 | |||||||||||||||||||||
| 99 | $chip = await $chip->mount( $adapter, %params ); | ||||||||||||||||||||
| 100 | |||||||||||||||||||||
| 101 | Supplies the chip driver with the means to actually communicate with the | ||||||||||||||||||||
| 102 | connected device, via some electrical interface connected to the computer. | ||||||||||||||||||||
| 103 | |||||||||||||||||||||
| 104 | The parameters given in C<%params> will vary depending on the specific chip in | ||||||||||||||||||||
| 105 | question, and should be documented there. | ||||||||||||||||||||
| 106 | |||||||||||||||||||||
| 107 | =cut | ||||||||||||||||||||
| 108 | |||||||||||||||||||||
| 109 | 2 | ▶ | async method mount ( $adapter, %params ) | ||||||||||||||||||
|
Subroutine
mount: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||
| 110 | 2 | { | |||||||||||||||||||
| 111 | 2 | $_adapter = $adapter; | |||||||||||||||||||
| 112 | |||||||||||||||||||||
| 113 | 2 | my $pname = $self->PROTOCOL; | |||||||||||||||||||
| 114 | |||||||||||||||||||||
| 115 | 2 | $_protocol = await $_adapter->make_protocol( $pname ); | |||||||||||||||||||
| 116 | |||||||||||||||||||||
| 117 | 2 | ▶ | my $code = $self->can( "${pname}_options" ) or | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 118 | return $self; | ||||||||||||||||||||
| 119 | |||||||||||||||||||||
| 120 | 0 | await $self->protocol->configure( | |||||||||||||||||||
| 121 | $self->$code( %params ) | ||||||||||||||||||||
| 122 | ); | ||||||||||||||||||||
| 123 | |||||||||||||||||||||
| 124 | 0 | return $self; | |||||||||||||||||||
| 125 | 9 | } | |||||||||||||||||||
| 126 | |||||||||||||||||||||
| 127 | # Perl 5.36+ can distinguish this; but this still works fine on older perls | ||||||||||||||||||||
| 128 | 9 | ▶ | use constant true => (1 == 1); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 129 | |||||||||||||||||||||
| 130 | 4 | ▶ | sub _parse_options ( $, $str ) | ||||||||||||||||||
|
Subroutine
_parse_options: called CC=3 SCAR=11.0
| |||||||||||||||||||||
| 131 | { | ||||||||||||||||||||
| 132 | 4 | ▶ | return map { m/^([^=]+)=(.*)$/ ? ( $1 => $2 ) : ( $_ => true ) } | ||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$str // ""
MC/DC100%1/1
$str // ""
$str
Truth table100%2/2
A
A= $str
| |||||||||||||||||||||
| 133 | split m/,/, $str // ""; | ||||||||||||||||||||
| 134 | |||||||||||||||||||||
| 135 | } | ||||||||||||||||||||
| 136 | |||||||||||||||||||||
| 137 | =head2 mount_from_paramstr | ||||||||||||||||||||
| 138 | |||||||||||||||||||||
| 139 | $chip = await $chip->mount_from_paramstr( $adapter, $paramstr ); | ||||||||||||||||||||
| 140 | |||||||||||||||||||||
| 141 | A variant of L</mount> that parses its options from the given string. This | ||||||||||||||||||||
| 142 | string should be a comma-separated list of parameters, where each is given as | ||||||||||||||||||||
| 143 | a name and value separated by equals sign. If there is no equals sign, the | ||||||||||||||||||||
| 144 | value is implied as true, as a convenience for parameters that are simple | ||||||||||||||||||||
| 145 | boolean flags. | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | =cut | ||||||||||||||||||||
| 148 | |||||||||||||||||||||
| 149 | 0 | ▶ | async method mount_from_paramstr ( $adapter, $paramstr ) | ||||||||||||||||||
|
Subroutine
mount_from_paramstr: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 150 | 0 | { | |||||||||||||||||||
| 151 | 0 | await $self->mount( $adapter, $self->_parse_options( $paramstr ) ); | |||||||||||||||||||
| 152 | 9 | } | |||||||||||||||||||
| 153 | |||||||||||||||||||||
| 154 | =head1 AUTHOR | ||||||||||||||||||||
| 155 | |||||||||||||||||||||
| 156 | Paul Evans <leonerd@leonerd.org.uk> | ||||||||||||||||||||
| 157 | |||||||||||||||||||||
| 158 | =cut | ||||||||||||||||||||
| 159 | |||||||||||||||||||||
| 160 | 9 | 0x55AA; | |||||||||||||||||||