1 2# Copyright (c) 1997 by Steffen Beyer. All rights reserved. 3# This package is free software; you can redistribute it 4# and/or modify it under the same terms as Perl itself. 5 6package Bit::ShiftReg; 7 8use strict; 9use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $VERSION); 10 11require Exporter; 12require DynaLoader; 13 14@ISA = qw(Exporter DynaLoader); 15 16@EXPORT = qw(); 17 18@EXPORT_OK = qw( bits_of_byte bits_of_short bits_of_int bits_of_long 19LSB_byte MSB_byte LSB_short MSB_short LSB_int MSB_int LSB_long MSB_long 20ROL_byte ROR_byte SHL_byte SHR_byte ROL_short ROR_short SHL_short SHR_short 21ROL_int ROR_int SHL_int SHR_int ROL_long ROR_long SHL_long SHR_long ); 22 23%EXPORT_TAGS = (all => [@EXPORT_OK]); 24 25$VERSION = '2.0'; 26 27bootstrap Bit::ShiftReg $VERSION; 28 291; 30 31__END__ 32 33=head1 NAME 34 35Bit::ShiftReg - Bit Shift Registers with Rotate / Shift Operations 36 37Implements rotate left, rotate right, shift left and shift right 38operations with carry flag for all C integer types 39 40=head1 SYNOPSIS 41 42=over 4 43 44=item * 45 46C<use Bit::ShiftReg qw( bits_of_byte bits_of_short bits_of_int bits_of_long> 47C<LSB_byte MSB_byte LSB_short MSB_short LSB_int MSB_int LSB_long MSB_long> 48C<ROL_byte ROR_byte SHL_byte SHR_byte ROL_short ROR_short SHL_short SHR_short> 49C<ROL_int ROR_int SHL_int SHR_int ROL_long ROR_long SHL_long SHR_long );> 50 51imports all (or some, by leaving some out) of the available operations 52and functions 53 54=item * 55 56C<use Bit::ShiftReg qw(:all);> 57 58imports all available operations and functions 59 60=item * 61 62C<$version = Bit::ShiftReg::Version();> 63 64returns the module's version number 65 66=item * 67 68C<$bits = bits_of_byte();> 69 70returns the number of bits in a byte (unsigned char) on your machine 71 72=item * 73 74C<$bits = bits_of_short();> 75 76returns the number of bits in an unsigned short on your machine 77 78=item * 79 80C<$bits = bits_of_int();> 81 82returns the number of bits in an unsigned int on your machine 83 84=item * 85 86C<$bits = bits_of_long();> 87 88returns the number of bits in an unsigned long on your machine 89 90=item * 91 92C<$lsb = LSB_byte($value);> 93 94returns the least significant bit (LSB) of a byte (unsigned char) 95 96=item * 97 98C<$msb = MSB_byte($value);> 99 100returns the most significant bit (MSB) of a byte (unsigned char) 101 102=item * 103 104C<$lsb = LSB_short($value);> 105 106returns the least significant bit (LSB) of an unsigned short 107 108=item * 109 110C<$msb = MSB_short($value);> 111 112returns the most significant bit (MSB) of an unsigned short 113 114=item * 115 116C<$lsb = LSB_int($value);> 117 118returns the least significant bit (LSB) of an unsigned int 119 120=item * 121 122C<$msb = MSB_int($value);> 123 124returns the most significant bit (MSB) of an unsigned int 125 126=item * 127 128C<$lsb = LSB_long($value);> 129 130returns the least significant bit (LSB) of an unsigned long 131 132=item * 133 134C<$msb = MSB_long($value);> 135 136returns the most significant bit (MSB) of an unsigned long 137 138=item * 139 140C<$carry = ROL_byte($value);> 141 142=item * 143 144C<$carry = ROR_byte($value);> 145 146=item * 147 148C<$carry_out = SHL_byte($value,$carry_in);> 149 150=item * 151 152C<$carry_out = SHR_byte($value,$carry_in);> 153 154=item * 155 156C<$carry = ROL_short($value);> 157 158=item * 159 160C<$carry = ROR_short($value);> 161 162=item * 163 164C<$carry_out = SHL_short($value,$carry_in);> 165 166=item * 167 168C<$carry_out = SHR_short($value,$carry_in);> 169 170=item * 171 172C<$carry = ROL_int($value);> 173 174=item * 175 176C<$carry = ROR_int($value);> 177 178=item * 179 180C<$carry_out = SHL_int($value,$carry_in);> 181 182=item * 183 184C<$carry_out = SHR_int($value,$carry_in);> 185 186=item * 187 188C<$carry = ROL_long($value);> 189 190=item * 191 192C<$carry = ROR_long($value);> 193 194=item * 195 196C<$carry_out = SHL_long($value,$carry_in);> 197 198=item * 199 200C<$carry_out = SHR_long($value,$carry_in);> 201 202=back 203 204B<Note that "$value" must be a variable in the calls of the functions> 205B<ROL, ROR, SHL and SHR, and that the contents of this variable are> 206B<altered IMPLICITLY by these functions!> 207 208B<Note also that the "carry" input value is always truncated to the least> 209B<significant bit, i.e., input values for "carry" must be either 0 or 1!> 210 211B<Finally, note that the return values of the functions LSB, MSB, ROL, ROR,> 212B<SHL and SHR are always either 0 or 1!> 213 214=head1 DESCRIPTION 215 216This module implements rotate left, rotate right, shift left and shift 217right operations with carry flag for all C integer types. 218 219The results depend on the number of bits that the integer types unsigned 220char, unsigned short, unsigned int and unsigned long have on your machine. 221 222The module automatically determines the number of bits of each integer type 223and adjusts its internal constants accordingly. 224 225How the operations work: 226 227=over 4 228 229=item ROL 230 231Rotate Left: 232 233 carry: value: 234 235 +---+ +---+---+---+--- ---+---+---+---+ 236 | 1 | <---+--- | 1 | 0 | 0 | 1 ... 1 | 0 | 1 | 1 | <---+ 237 +---+ | +---+---+---+--- ---+---+---+---+ | 238 | | 239 +------------------------------------------------+ 240 241=item ROR 242 243Rotate Right: 244 245 value: carry: 246 247 +---+---+---+--- ---+---+---+---+ +---+ 248 +---> | 1 | 0 | 0 | 1 ... 1 | 0 | 1 | 1 | ---+---> | 1 | 249 | +---+---+---+--- ---+---+---+---+ | +---+ 250 | | 251 +------------------------------------------------+ 252 253=item SHL 254 255Shift Left: 256 257 carry value: carry 258 out: in: 259 +---+ +---+---+---+--- ---+---+---+---+ +---+ 260 | 1 | <--- | 1 | 0 | 0 | 1 ... 1 | 0 | 1 | 1 | <--- | 1 | 261 +---+ +---+---+---+--- ---+---+---+---+ +---+ 262 263=item SHR 264 265Shift Right: 266 267 carry value: carry 268 in: out: 269 +---+ +---+---+---+--- ---+---+---+---+ +---+ 270 | 1 | ---> | 1 | 0 | 0 | 1 ... 1 | 0 | 1 | 1 | ---> | 1 | 271 +---+ +---+---+---+--- ---+---+---+---+ +---+ 272 273=back 274 275=head1 EXAMPLE 276 277Suppose you want to implement shift registers in a machine-independent 278way. 279 280The only C integer type whose length in bits you can be pretty sure about 281is probably a byte, since the C standard only prescribes minimum lengths 282for char, short, int and long and that C<sizeof(char)> C<E<lt>=> 283C<sizeof(short)> C<E<lt>=> C<sizeof(int)> C<E<lt>=> C<sizeof(long)>. 284 285How to implement a 4-byte shift register and the 4 operations ROL, ROR, 286SHL and SHR on it: 287 288First, you need to define 4 byte registers: 289 290 $byte0 = 0; 291 $byte1 = 0; 292 $byte2 = 0; 293 $byte3 = 0; 294 295Then proceed as follows: 296 297=over 4 298 299=item ROL 300 301Rotate left: 302 303 $carry = SHL_byte($byte3, SHL_byte($byte2, SHL_byte($byte1, 304 SHL_byte($byte0, MSB_byte($byte3))))); 305 306=item ROR 307 308Rotate right: 309 310 $carry = SHR_byte($byte0, SHR_byte($byte1, SHR_byte($byte2, 311 SHR_byte($byte3, LSB_byte($byte0))))); 312 313=item SHL 314 315Shift left: 316 317 $carry_out = SHL_byte($byte3, SHL_byte($byte2, SHL_byte($byte1, 318 SHL_byte($byte0, $carry_in)))); 319 320=item SHR 321 322Shift right: 323 324 $carry_out = SHR_byte($byte0, SHR_byte($byte1, SHR_byte($byte2, 325 SHR_byte($byte3, $carry_in)))); 326 327=back 328 329=head1 SEE ALSO 330 331perl(1), perlsub(1), perlmod(1), perlxs(1), perlxstut(1), perlguts(1). 332 333=head1 VERSION 334 335This man page documents Bit::ShiftReg version 2.0. 336 337=head1 AUTHOR 338 339Steffen Beyer <sb@sdm.de>. 340 341=head1 COPYRIGHT 342 343Copyright (c) 1997 by Steffen Beyer. All rights reserved. 344 345=head1 LICENSE AGREEMENT 346 347This package is free software; you can redistribute it 348and/or modify it under the same terms as Perl itself. 349 350