Device/Chip/Base/RegisteredI2C.pm

filter: Statementstmt 100% 136 / 136 Branchbran 82.1% 23 / 28 Conditioncond 80.9% 17 / 21 MC/DCmcdc 64.2% 9 / 14 Subroutinesub 100% 19 / 19 Podpod 83.3% 5 / 6 totaltotal 93.3% 209 / 224 CC 26 SCAR 14.4
CC
26
Cov
95%
cached_write_reg_masked
6.1
write_reg
6.0
read_reg
6.0
CRAP 4.2
« Device/Chip/Adapter.pm ↑ Summary Test/Device/Chip/Adapter.pm »
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-2026 -- leonerd@leonerd.org.uk
5  
6 1 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use Object::Pad 0.800;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 package Device::Chip::Base::RegisteredI2C 0.27;
11 class Device::Chip::Base::RegisteredI2C :isa(Device::Chip);
12  
13 1 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 1 ▶use meta;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 1 ▶use Future::AsyncAwait 0.38; # async method
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 1 ▶no warnings 'meta::experimental';
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 1 ▶use constant PROTOCOL => "I2C";
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 1 ▶use constant REG_ADDR_SIZE => 8;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 1 ▶use constant REG_DATA_SIZE => 8;
Subroutine BEGIN: called CC=1 SCAR=0.0
26  
27 =encoding UTF-8
28  
29 =head1 NAME
30  
31 C<Device::Chip::Base::RegisteredI2C> - base class for drivers of register-oriented I²C chips
32  
33 =head1 DESCRIPTION
34  
35 =for highlighter language=perl
36  
37 This subclass of L<Device::Chip> provides some handy utility methods to
38 implement a chip driver that supports a chip which (largely) operates on the
39 common pattern of registers; that is, that writes to and reads from the chip
40 are performed on numerically-indexed register locations, holding independent
41 values. This is a common pattern that a lot of I²C chips adhere to.
42  
43 =cut
44  
45 =head1 CONSTANTS
46  
47 =cut
48  
49 =head2 REG_DATA_SIZE
50  
51 Gives the number of bits of data each register occupies. Normally this value
52 is 8, but sometimes chips like high-resolution ADCs and DACs might work with a
53 larger size like 16 or 24. This value ought to be a multiple of 8.
54  
55 Overriding this constant to a different value will affect the interpretation
56 of the C<$len> parameter to the register reading and writing methods.
57  
58 =cut
59  
60 2 ▶method REG_DATA_BYTES ()
Subroutine REG_DATA_BYTES: called CC=2 SCAR=7.0
Pod undocumented
61 {
62 2 my $bytes = int( ( $self->REG_DATA_SIZE + 7 ) / 8 );
63  
64 # cache it for next time
65 2 ▶ my $pkg = ref $self || $self;
Condition33%1/3
ref $self || $self
l!l&&r!l&&!r
200
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table33%1/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
66 2 my $metapkg = meta::package->get( $pkg );
67 2 ▶ $metapkg->add_named_sub( REG_DATA_BYTES => method () { $bytes } );
Subroutine __ANON__: called CC=1 SCAR=0.0
68  
69 2 return $bytes;
70 1 }
71  
72 =head1 METHODS
73  
74 The following methods documented in an C<await> expression return L<Future>
75 instances.
76  
77 =cut
78  
79 1 field @_regcache;
80  
81 =head2 read_reg
82  
83 $val = await $chip->read_reg( $reg, $len );
84  
85 Performs a C<write_then_read> I²C transaction, sending the register number as
86 a single byte value, then attempts to read the given number of register slots.
87  
88 =cut
89  
90 8 ▶async method read_reg ( $reg, $len, $__forcecache = 0 )
Subroutine read_reg: called CC=6 SCAR=17.9
Pod documented
91 8 {
92 8 ▶ $self->REG_ADDR_SIZE == 8 or
Branch: 1 branch
BranchTrueFalseTotal
$self->REG_ADDR_SIZE == 8 or croak("TODO: Currently unable to cope with REG_ADDR_SIZE != 8") 8 0 8
93 croak "TODO: Currently unable to cope with REG_ADDR_SIZE != 8";
94  
95 8 my $f = $self->protocol->write_then_read( pack( "C", $reg ), $len * $self->REG_DATA_BYTES );
96  
97 8 foreach my $offs ( 0 .. $len-1 ) {
98 8 $__forcecache || $_regcache[$reg + $offs] and
99 8 ▶ $_regcache[$reg + $offs] = $f->then( async sub ( $bytes ) {
Subroutine __ANON__: called CC=1 SCAR=0.0
100 8 return substr $bytes, $offs * $self->REG_DATA_BYTES, $self->REG_DATA_BYTES
101 10 ▶ });
Branch: 1 branch
BranchTrueFalseTotal
$__forcecache || $_regcache[$reg + $offs] and 8 2 10
Condition100%3/3
$__forcecache or $_regcache[$reg + $offs]
l!l&&r!l&&!r
712
MC/DC100%2/2
$__forcecache or $_regcache[$reg + $offs]
$__forcecache $_regcache[$reg + $offs]
Truth table100%3/3
A or B
A= $__forcecacheB= $_regcache[$reg + $offs]
ABresult
1X1
011
000
102 }
103  
104 8 return await $f;
105 1 }
106  
107 =head2 write_reg
108  
109 await $chip->write_reg( $reg, $val );
110  
111 Performs a C<write> I²C transaction, sending the register number as a single
112 byte value followed by the data to write into it.
113  
114 =cut
115  
116 9 ▶async method write_reg ( $reg, $val, $__forcecache = 0 )
Subroutine write_reg: called CC=6 SCAR=17.9
Pod documented
117 9 {
118 9 ▶ $self->REG_ADDR_SIZE == 8 or
Branch: 1 branch
BranchTrueFalseTotal
$self->REG_ADDR_SIZE == 8 or croak("TODO: Currently unable to cope with REG_ADDR_SIZE != 8") 9 0 9
119 croak "TODO: Currently unable to cope with REG_ADDR_SIZE != 8";
120  
121 9 my $len = length( $val ) / $self->REG_DATA_BYTES;
122  
123 9 foreach my $offs ( 0 .. $len-1 ) {
124 12 ▶ $__forcecache || defined $_regcache[$reg + $offs] and
Branch: 1 branch
BranchTrueFalseTotal
$__forcecache || defined $_regcache[$reg + $offs] and $_regcache[$reg + $offs] = "Future"->done(my $bytes = substr($val, $offs * $self->REG_DATA_BYTES, $self->REG_DATA_BYTES)) 10 2 12
Condition100%3/3
$__forcecache or defined $_regcache[$reg + $offs]
l!l&&r!l&&!r
912
MC/DC100%2/2
$__forcecache or defined $_regcache[$reg + $offs]
$__forcecache defined $_regcache[$reg + $offs]
Truth table100%3/3
A or B
A= $__forcecacheB= defined $_regcache[$reg + $offs]
ABresult
1X1
011
000
125 $_regcache[$reg + $offs] = Future->done(
126 my $bytes = substr $val, $offs * $self->REG_DATA_BYTES, $self->REG_DATA_BYTES
127 );
128 }
129  
130 9 await $self->protocol->write( pack( "C", $reg ) . $val );
131 1 }
132  
133 =head2 cached_read_reg
134  
135 $val = await $chip->cached_read_reg( $reg, $len );
136  
137 Implements a cache around the given register location. Returns the last value
138 known to have been read from or written to the register; or reads it from the
139 actual chip if no interaction has yet been made. Once a cache slot has been
140 created for the register by calling this method, the L<read_reg> and
141 L<write_reg> methods will also keep it updated.
142  
143 This method should be used by chip drivers for interacting with
144 configuration-style registers; that is, registers that the chip itself will
145 treat as simple storage of values. It is not suitable for registers that the
146 chip itself will update.
147  
148 =cut
149  
150 10 ▶async method cached_read_reg ( $reg, $len )
Subroutine cached_read_reg: called CC=5 SCAR=16.1
Pod documented
151 10 {
152 10 my @f;
153  
154 10 my $endreg = $reg + $len;
155  
156 10 ▶ while( $reg < $endreg ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($reg < $endreg) 19 10 29
157 19 ▶ if( defined $_regcache[$reg] ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_regcache[$reg]) { } 14 5 19
158 14 push @f, $_regcache[$reg++];
159 }
160 else {
161 5 $len = 1;
162 5 ▶ $len++ while $reg + $len < $endreg and
Branch: 1 branch
BranchTrueFalseTotal
$reg + $len < $endreg and not defined $_regcache[$reg + $len] and do { ++$len } 2 5 7
Condition100%3/3
$reg + $len < $endreg and not defined $_regcache[$reg + $len]
!ll&&!rl&&r
412
MC/DC100%2/2
$reg + $len < $endreg and not defined $_regcache[$reg + $len]
$reg + $len < $endreg not defined $_regcache[$reg + $len]
Truth table100%3/3
A and not(B)
A= $reg + $len < $endregB= not defined $_regcache[$reg + $len]
ABresult
0X0
100
111
163 !defined $_regcache[ $reg + $len ];
164  
165 5 my $thisreg = $reg;
166 5 push @f, $self->read_reg( $reg, $len, "forcecache" );
167  
168 5 $reg += $len;
169 }
170 }
171  
172 10 return join "", await Future->needs_all( @f );
173 1 }
174  
175 =head2 cached_write_reg
176  
177 await $chip->cached_write_reg( $reg, $val );
178  
179 Optionally writes a new value for the given register location. This method
180 will invoke C<write_reg> except if the register already exists in the cache
181 and already has the given value according to the cache.
182  
183 This method should be used by chip drivers for interacting with
184 configuration-style registers; that is, registers that the chip itself will
185 treat as simple storage of values. It is not suitable for registers that the
186 chip itself will update.
187  
188 =cut
189  
190 8 ▶async method cached_write_reg ( $reg, $val )
Subroutine cached_write_reg: called CC=6 SCAR=17.9
Pod documented
191 8 {
192 8 my $len = length( $val ) / ( my $datasize = $self->REG_DATA_BYTES );
193  
194 my @current = await Future->needs_all(
195 map {
196 8 ▶ $_regcache[$reg + $_] // Future->done( "" )
Condition66%2/3
$_regcache[$reg + $_] // "Future"->done("")
l!l&&r!l&&!r
1440
MC/DC0%0/2
$_regcache[$reg + $_] // "Future"->done("")
$_regcache[$reg + $_] "Future"->done("")
Truth table66%2/3
A // B
A= $_regcache[$reg + $_]B= "Future"->done("")
ABresult
1X1
011
000
197 } 0 .. $len-1
198 );
199  
200 8 my @want = $val =~ m/(.{$datasize})/sg;
201  
202 # Determine chunks that need rewriting
203 8 my @f;
204 8 my $offs = 0;
205 8 ▶ while( $offs < $len ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($offs < $len) 15 8 23
206 15 ▶ $offs++, next if $current[$offs] eq $want[$offs];
Branch: 1 branch
BranchTrueFalseTotal
if $current[$offs] eq $want[$offs] 9 6 15
207  
208 6 my $startoffs = $offs++;
209 6 ▶ $offs++ while $offs < $len and
Branch: 1 branch
BranchTrueFalseTotal
$offs < $len and $current[$offs] ne $want[$offs] and do { ++$offs } 3 6 9
Condition100%3/3
$offs < $len and $current[$offs] ne $want[$offs]
!ll&&!rl&&r
513
MC/DC100%2/2
$offs < $len and $current[$offs] ne $want[$offs]
$offs < $len $current[$offs] ne $want[$offs]
Truth table100%3/3
A and B
A= $offs < $lenB= $current[$offs] ne $want[$offs]
ABresult
0X0
100
111
210 $current[$offs] ne $want[$offs];
211  
212 6 push @f, $self->write_reg( $reg + $startoffs,
213 join( "", @want[$startoffs..$offs-1] ), "forcecache" );
214 }
215  
216 8 await Future->needs_all( @f );
217 1 }
218  
219 =head2 cached_write_reg_masked
220  
221 await $chip->cached_write_reg_masked( $reg, $val, $mask );
222  
223 Performs a read-modify-write operation to update the given register location.
224 This method will first read the current value of the register for the length
225 of the value and mask. It will then modify this value, taking bits from the
226 value given by I<$val> where the corresponding bit in I<$mask> is set, or
227 leaving them unchanged where the I<$mask> bit is clear. This updated value is
228 then written back.
229  
230 Both the initial read and the subsequent write operation will pass through the
231 cache as for L</cached_read_reg> and L</cached_write_reg>.
232  
233 The length of I<$mask> must equal the length of I<$val>. A mask value with all
234 bits set is equivalent to just calling L</cached_write_reg>. A mask value with
235 all bits clear is equivalent to no update (except that the chip registers may
236 still be read to fill the cache.
237  
238 This method should be used by chip drivers for interacting with
239 configuration-style registers; that is, registers that the chip itself will
240 treat as simple storage of values. It is not suitable for registers that the
241 chip itself will update.
242  
243 =cut
244  
245 1 ▶async method cached_write_reg_masked ( $reg, $val, $mask )
Subroutine cached_write_reg_masked: called CC=6 SCAR=18.0
Pod documented
246 1 {
247 1 ▶ length $mask == length $val or
Branch: 1 branch
BranchTrueFalseTotal
length $mask == length $val or croak("Require length(mask) == length(val)") 1 0 1
248 croak "Require length(mask) == length(val)";
249  
250 1 my $readreg = $reg;
251 1 my $readlen = ( length $val ) / ( my $datasize = $self->REG_DATA_BYTES );
252 1 my $wasval = "";
253  
254 1 pos( $mask ) = 0;
255 1 ▶ while( $readlen and $mask =~ m/\G\xFF{$datasize}/g ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($readlen and $mask =~ /\G\xFF{$datasize}/gu) 1 1 2
Condition66%2/3
$readlen and $mask =~ /\G\xFF{$datasize}/gu
!ll&&!rl&&r
011
MC/DC50%1/2
$readlen and $mask =~ /\G\xFF{$datasize}/gu
$readlen $mask =~ /\G\xFF{$datasize}/gu
Truth table66%2/3
A and B
A= $readlenB= $mask =~ /\G\xFF{$datasize}/gu
ABresult
0X0
100
111
256 1 $readreg++, $readlen--;
257 1 $wasval .= "\0" x $datasize;
258 }
259  
260 1 ▶ if( $mask =~ m/(\xFF{$datasize})+$/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($mask =~ /(\xFF{$datasize})+$/u) 1 0 1
261 1 $readlen -= ( $+[0] - $-[0] ) / $datasize;
262 }
263  
264 1 ▶ $wasval .= await $self->cached_read_reg( $readreg, $readlen ) if $readlen > 0;
Branch: 1 branch
BranchTrueFalseTotal
if $readlen > 0 1 0 1
265  
266 1 $val &= $mask;
267 1 $val |= ( $wasval & ~$mask );
268  
269 1 await $self->cached_write_reg( $reg, $val );
270 1 }
271  
272 =head1 AUTHOR
273  
274 Paul Evans <leonerd@leonerd.org.uk>
275  
276 =cut
277  
278 1 0x55AA;
« Device/Chip/Adapter.pm ↑ Summary Test/Device/Chip/Adapter.pm »