TheRock/rocm-systems/projects/rocprofiler-systems/external/dyninst/instructionAPI/doc/API/Operand.tex

\subsection{Operand Class}
\label{sec:operand}

An Operand object contains an AST built from RegisterAST and Immediate leaves,
and information about whether the Operand is read, written, or both. This allows
us to determine which of the registers that appear in the Operand are read and
which are written, as well as whether any memory accesses are reads, writes, or
both. An Operand, given full knowledge of the values of the leaves of the AST,
and knowledge of the logic associated with the tree's internal nodes, can
determine the result of any computations that are encoded in it. It will rarely
be the case that an Instruction is built with its Operands' state fully
specified. This mechanism is instead intended to allow a user to fill in
knowledge about the state of the processor at the time the Instruction is
executed. 

\begin{apient}
Operand(Expression::Ptr val, bool read, bool written)
\end{apient}
\apidesc{
    Create an operand from an \code{Expression} and flags describing whether the
    ValueComputation is read, written, or both.

    \code{val} is a reference-counted pointer to the \code{Expression} that will
    be contained in the \code{Operand} being constructed. \code{read} is true if
    this operand is read. \code{written} is true if this operand is written.
}

\begin{apient}
void getReadSet(std::set<RegisterAST::Ptr> & regsRead) const
\end{apient}
\apidesc{
Get the registers read by this operand. The registers read are inserted into
\code{regsRead}.
}

\begin{apient}
void getWriteSet(std::set<RegisterAST::Ptr> & regsWritten) const
\end{apient}
\apidesc{
Get the registers written by this operand. The registers written are inserted into
\code{regsWritten}.
}

\begin{apient}

bool isRead() const
\end{apient}
\apidesc{
    Returns \code{true} if this operand is read.
}

\begin{apient}
bool isWritten() const
\end{apient}
\apidesc{
Returns \code{true} if this operand is written.
}

\begin{apient}
bool isRead(Expression::Ptr candidate) const
\end{apient}
\apidesc{
    Returns \code{true} if \code{candidate} is read by this operand.
}

\begin{apient}
bool isWritten(Expression::Ptr candidate) const
\end{apient}
\apidesc{
Returns \code{true} if \code{candidate} is written to by this operand.
}

\begin{apient}
bool readsMemory() const
\end{apient}
\apidesc{
    Returns \code{true} if this operand reads memory.
}

\begin{apient}
bool writesMemory() const
\end{apient}
\apidesc{
    Returns \code{true} if this operand writes memory.
}

\begin{apient}
void addEffectiveReadAddresses(std::set<Expression::Ptr> & memAccessors) const
\end{apient}
\apidesc{
    If \code{Operand} is a memory read operand, insert the \code{ExpressionPtr}
    representing the address being read into \code{memAccessors}.
}

\begin{apient}
void addEffectiveWriteAddresses(std::set<Expression::Ptr> & memAccessors) const
\end{apient}
\apidesc{
    If \code{Operand} is a memory write operand, insert the \code{ExpressionPtr}
    representing the address being written into \code{memAccessors}.
}

\begin{apient}
std::string format(Architecture arch, Address addr = 0) const
\end{apient}
\apidesc{
    Return a printable string representation of the operand. The
    \code{arch} parameter must be supplied, as operands do not record
    their architectures. The optional \code{addr} parameter specifies
    the value of the program counter. 
}

\begin{apient}
Expression::Ptr getValue() const
\end{apient}
\apidesc{
    The \code{getValue} method returns an \code{ExpressionPtr} to the AST
    contained by the operand.
}