This file documents the changes in rel3 of the RTL library.  These notes were
written by Eric Smith.

rel3 includes changes to the arity of some functions.

Most of the RTL primitives now return nonnegative integers (natp's)
unconditionally, and most have nice bvecp lemmas like this one:

(defthm bits-bvecp
  (implies (and (<= (+ 1 i (- j)) n)
                (case-split (integerp n))
                )
           (bvecp (bits x i j) n)))

(I have yet to have my way with logand, logior, or logxor; these functions
don't behave quite as nicely yet.)  The function setbits (and setbitn, which
used to be a macro) now takes an extra parameter, w, indicating the width of
the value it returns.  The bvecp lemmas for setbits and setbitn are now quite
nice.  More importantly, setbits should always get rewritten to cat without
free-variable problems.  There is also a rule to rewrite setbitn to setbits
(and thus to cat) when the index to setbitn is a constant.  See the "setbits"
section of lib/bits.lisp for the details.

I've changed some lemma names to increase consistency.  My scheme:

1) A lemma about a single RTL primitive has a name starting with that primitive
(e.g, cat-natp, cat-bvecp).

2) A lemma about several RTL primitives has a name reflecting the left-hand
side of the rule.  Thus:

(defthm bitn-comp1 ;used to be called comp1-bitn
    (implies ...
	     (equal (bitn (comp1 x m) n)
		    (comp1 (bitn x n) 1))))

Natp lemmas are all of the form: <fnname>-natp. There's no more natp-cat,
cat-nat, cat-nat-eric, or whatever. Only cat-natp.  bvecp lemmas are all of the
form: <fnname>-bvecp.

Here are some helpful hints about lemmas that got renamed or deleted or aren't
necessary any more: key: [old name] -> [see this lemma in rel3]

bitn-rewrite -> bitn-def
bits- -> bits-with-indices-in-the-wrong-order
bits-neg-1 -> bits-with-indices-in-the-wrong-order
setbits-rewrite-1 -> setbits-rewrite
setbits-rewrite-2 -> setbits-rewrite
integerp-comp1-nat -> comp1-nonnegative-integer-type
comp1-comp1-rewrite -> comp1-comp1
comp1-bitn -> bitn-comp1
bits-shift-2 -> bitn-bits
bits-shift-3 -> [bits-bits-1 or] bits-bits
bits-shift-4 -> bits-bits-2 or bits-bits
bits-logxor-2 -> bits-logxor
exact-bits-a-b -> exact-bits-1
exact-bits-a-c -> exact-bits-2
exact-bits-a-d -> exact-bits-3

I think the new names will make it easier to look at the sorted lists of rules
that ACL2 prints -- all rules about cat will now appear together, etc.

Random note:

I disable a lot of the built-in type-presctription rules (after proving my
own), so don't use :pe foo to see whether the function foo is disabled (by
looking for the little "d").  Instead, use :disabledp foo.

