Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perlmod / BitFieldTie / 1.09 / man / man3 / BitFieldTie.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BitFieldTie 3"
.TH BitFieldTie 3 "2003-01-23" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
BitFieldTie \- Tie interface for bitfield operations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use BitFieldTie; # or use TRELoad 'BitFieldTie';
.Ve
.PP
.Vb 1
\&  tie %num, 'BitFieldTie';
.Ve
.PP
.Vb 2
\&  $num{'31:0'}  = hex('0x1234');
\&  $num{'63:32'} = hex('0xabcd');
.Ve
.PP
.Vb 2
\&  print "low byte is $num{'7:0'}\en";
\&  print "MSB is $num{63}\en";
.Ve
.PP
.Vb 2
\&  my $obj = tied %num;     # get object
\&  print "Num is $obj\en"; # object prints as hex num
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
.Vb 3
\&  This is a thin wrapper for Bit::Vector that presents a tie interface for
\&  bit vectors.  The bit vector itself can be of arbitrary size, but the
\&  chunk size (the size of an individual bit field) is limited to 32 bits.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module allows users to access bit fields with a hash interface.
.Sh "Introduction"
.IX Subsection "Introduction"
This module provides two components.  The first is a class,
BitFieldTie, that allows users to manipulate bit vectors of arbitrary
size using object methods.  The second is a tie interface.  When a
hash is tied to a BitFieldTie object, a hash interface can be used to
set or exampine bit ranges in the vector.
.Sh "Hash Interface"
.IX Subsection "Hash Interface"
This subsection describes using the tied hash interface.
.PP
\fISetting up a bitfield\fR
.IX Subsection "Setting up a bitfield"
.PP
When you tie a hash to this module, the hash becomes a representation
of bitfields of a number.  By default, a 64\-bit integer is created and
initialized to zero.  You can provide optional arguments to the tie
command to set a different size and initial value, as in:
.PP
.Vb 1
\&  tie %num, 'BitFieldTie', 32, '0x1234abcd';
.Ve
.PP
The first optional agument is the size in bits, and the second is the
initial value \s-1IN\s0 \s-1HEX\s0.
.PP
\fIUsing a bitfield\fR
.IX Subsection "Using a bitfield"
.PP
You can then access fields of the hash.  Hash keys can either be a
single number for single-bit access, or a range in the form of
<high>:<low>.  The values in the hash are integers, so
for istance aftre the above initialization, the value of \f(CW$num\fR{'3:0'}
would be 13 (decimal for 0xd).  The hash provides both read and write
access.  \fBThe major restriction is that the size of the bit range
(i.e., high\-low+1) cannot exceed 32\-bits.\fR  To access larger ranges,
you need to break it up into separate accesses.  The main reason for
that restriction is that if the module allowed larger chunks, it could
not use integers to represent bit fields and performance would suffer
considerably.
.PP
\fIPrinting the bitfield\fR
.IX Subsection "Printing the bitfield"
.PP
Unfortunately, the tied-hash mechanism does not lend itself to object
methods to do un-hash-like things like pretty\-printing.  You must
therefore use the object interface, and there is a little bit of
syntax involved.
.PP
.Vb 1
\&  $obj = tied %num;
.Ve
.PP
This sets \f(CW$obj\fR to the underlying object for the tied hash.  The object
does know how to print itself (among other things).
.PP
.Vb 1
\&  print "Num is $obj\en";
.Ve
.PP
The above statement will print \f(CW%num\fR as a hexidecimal number.
.PP
You can also interpolate the hash directly with a little bit of funny
syntax:
.PP
.Vb 1
\&  print "Num is @{[tied %num]}\en";
.Ve
.PP
This is just a clever perl hack to do the same thing without explictly
referencing \f(CW$obj\fR.
.Sh "Object interface"
.IX Subsection "Object interface"
Objects of type BitFieldTie can be created in 3 ways.  The first is if
a hash is tied to a BitFieldTie object, but no object is specified (as
is the case in the previous examples), one will be created.  This
object can then be referenced by using the 'tied' operator on the
hash, as shown in the previous section.
.PP
Objects can also be created with the \fInew()\fR or \fIclone()\fR methods, as
described in the section on Object Methods.
.PP
Once an object is created, it can be easily manipulated as shown in
the next section.
.PP
\fIMath with Bitfields\fR
.IX Subsection "Math with Bitfields"
.PP
BitFieldTie ties a hash object to an object.  This allows you to use
convenient hash syntax to access bit fields.  To do math, however, you
need to manipulate the object directly.  The perl builtin-function
tied will give you the object associated with a tied hash.
.PP
.Vb 2
\&  my %v1;
\&  tie %v1, 'BitFieldTie', 64, '0x0000ffff0000cccc';
.Ve
.PP
.Vb 1
\&  my $v1 = tied %v1;
.Ve
.PP
The above code creates a new 64\-bit number tied to the hash \f(CW%v1\fR.  The
underlying object is assigned to \f(CW$v1\fR.  Say we had a similar definition
for v2:
.PP
.Vb 3
\&  my %v2;
\&  tie %v2, 'BitFieldTie', 64, '0xffff333300003333';
\&  my $v2 = tied %v2;
.Ve
.PP
You can still access bitfields using hash syntax on \f(CW%v1\fR and \f(CW%v2\fR.  You
can now also call object methods on \f(CW$v1\fR and \f(CW$v2\fR.  For instance:
.PP
.Vb 2
\&  $v2->bitwise_and($v1);
\&  print "$v2";
.Ve
.PP
The above prints: \*(L"0000333300000000\*(R".  Keep in mind that as mentioned
above, when you convert an underlying BitFieldTie object to a string
(as in the print statement), the string is a hexadecimal
representation of the number.
.PP
\fIObject methods\fR
.IX Subsection "Object methods"
.PP
The following are the object methods that BitFieldTie objects respond to.
.ie n .IP "new($size, $hexstring) \s-1OR\s0 new($obj)" 4
.el .IP "new($size, \f(CW$hexstring\fR) \s-1OR\s0 new($obj)" 4
.IX Item "new($size, $hexstring) OR new($obj)"
Class method that creates a new object and returns it.  Arguments are
optional, if a \f(CW$size\fR and/or \f(CW$hexstring\fR is specified, it works just as
the argument list to tie.  If an object is provided, that object is
cloned, and the clone is returned.
.Sp
\&\fInew()\fR can also be called as an object method.  So the following two
statements are identical (assuming \f(CW$obj\fR is a BitFieldTie):
.Sp
.Vb 2
\&  $new = $obj->new();
\&  $new = BitFieldTie->new($obj);
.Ve
.ie n .IP "new_dec($size, $decimal)" 4
.el .IP "new_dec($size, \f(CW$decimal\fR)" 4
.IX Item "new_dec($size, $decimal)"
Same as new, except that the second argument is treated as a decimal
argument, instead of a hex string.
.IP "\fIclone()\fR" 4
.IX Item "clone()"
Returns a new BitFieldTie object that is identical to the old one
\&\s-1EXCEPT\s0 that it is not tied to any hash.
.IP "\fIstringify()\fR" 4
.IX Item "stringify()"
Returns hexadecimal object as a string.  This is called automatically
when you include a BitFieldTie object in double\-quotes.
.ie n .IP "extract($hi, $low)" 4
.el .IP "extract($hi, \f(CW$low\fR)" 4
.IX Item "extract($hi, $low)"
Returns the specified bit range from the object as an integer.  Since
the return value is an integer, the size (i.e., \f(CW$hi\fR \- \f(CW$low\fR + 1) must
be <= 32.
.ie n .IP "store($hi, $low\fR, \f(CW$value)" 4
.el .IP "store($hi, \f(CW$low\fR, \f(CW$value\fR)" 4
.IX Item "store($hi, $low, $value)"
Stores the \f(CW$value\fR (an integer!) in the specified bit range in the
object.  Since the return value is an integer, the size (i.e., \f(CW$hi\fR \-
\&\f(CW$low\fR + 1) must be <= 32.  Also, the \f(CW$value\fR must be an integer, not a string.
.IP "\fIclear()\fR" 4
.IX Item "clear()"
Sets all bits in the bit vector to 0.
.IP "\fIsize()\fR, size($numbits)" 4
.IX Item "size(), size($numbits)"
Sets/Gets the size (in bits) of the number, depending on whether or
not an argument is given.
.IP "left_shift($numbits)" 4
.IX Item "left_shift($numbits)"
Left shifts the number.
.IP "right_shift($numbits)" 4
.IX Item "right_shift($numbits)"
Right shifts the number.
.IP "bitwise_and($obj)" 4
.IX Item "bitwise_and($obj)"
Does a bitwise and between the calling object and \f(CW$obj\fR.  Stores the
result in the calling object.  For example:
.Sp
.Vb 1
\&  $v1->bitwise_and($v2);
.Ve
.Sp
has the C equivalent of:
.Sp
.Vb 1
\&  v1 &= v2;
.Ve
.IP "bitwise_or($obj)" 4
.IX Item "bitwise_or($obj)"
Same as bitwise_and, except it performs an \s-1OR\s0 function.
.IP "bitwise_xor($obj)" 4
.IX Item "bitwise_xor($obj)"
Same as bitwise_and and bitwise_or, except it performs an \s-1XOR\s0 function.
.IP "\fIbitwise_not()\fR" 4
.IX Item "bitwise_not()"
Flips every bit in the number.
.ie n .IP "divide($obj, $remainder)" 4
.el .IP "divide($obj, \f(CW$remainder\fR)" 4
.IX Item "divide($obj, $remainder)"
Divides the calling object by \f(CW$obj\fR and stores the result in the
calling object (i.e., /=).  \f(CW$remainder\fR is initialized to the
remainder.  \f(CW$obj\fR can be an integer, in which case an object the same
size as the calling object is created for it.
.IP "multiply($obj)" 4
.IX Item "multiply($obj)"
Multiplies the calling object by \f(CW$obj\fR and stores the result in the
calling object (i.e., *=).  \f(CW$obj\fR can be an integer, in which
case an object the same size as the calling object is created for it.
.IP "add($obj)" 4
.IX Item "add($obj)"
Adds \f(CW$obj\fR to the calling object.  \f(CW$obj\fR can be an integer, in which
case an object the same size as the calling object is created for it.
.IP "subtract($obj)" 4
.IX Item "subtract($obj)"
Subtracts \f(CW$obj\fR from the calling object.  \f(CW$obj\fR can be an integer, in which
case an object the same size as the calling object is created for it.
.IP "compare($obj)" 4
.IX Item "compare($obj)"
Does a comparison on the calling object and \f(CW$obj\fR (which may be an
integer).  Returns \-1 if the calling object is smaller, 0 if they are
equal, and 1 if the calling object is greater that \f(CW$obj\fR.  Both the
calling object and \f(CW$obj\fR are treated as \s-1SIGNED\s0 integers for the
purposes of comparison.
.IP "ucompare($obj)" 4
.IX Item "ucompare($obj)"
Same as compare, but the calling object and \f(CW$obj\fR are treated as
\&\s-1UNSIGNED\s0 integers.
.Sh "Tying an Existing Object to a Hash"
.IX Subsection "Tying an Existing Object to a Hash"
If you create a BitFieldTie object with \fInew()\fR or \fIclone()\fR, it begins
life not tied to any hash.  You can manipulate it with object methods,
but if you want to access bit fields with hash syntax, you will need
to tie it to a hash first.  Here is an example
.PP
.Vb 2
\& my $obj = BitFieldTie->new(64, '0xdeadbeefcafe0123');
\& tie %h, 'BitFieldTie', $obj;
.Ve
.PP
The contents of \f(CW$h\fR{'15:0'} would then be hex('0123');
.Sh "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None.  Object modules do not export any symbols.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIBit::Vector\fR\|(3).