Candidate release of source code.

Ghidra/Features/Decompiler/src/decompile/cpp/comment.cc

@@ -0,0 +1,397 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "comment.hh"
+#include "funcdata.hh"
+
+/// \param tp is the set of properties to associate with the comment (or 0 for no properties)
+/// \param fad is the Address of the function containing the comment
+/// \param ad is the Address of the instruction associated with the comment
+/// \param uq is used internally to sub-sort comments at the same address
+/// \param txt is the body of the comment
+Comment::Comment(uint4 tp,const Address &fad,
+			     const Address &ad,int4 uq,
+			     const string &txt) :
+  type(tp), funcaddr(fad), addr(ad), uniq(uq), text(txt)
+{
+}
+
+/// The single comment is saved as a \<comment> tag.
+/// \param s is the output stream
+void Comment::saveXml(ostream &s) const
+
+{
+  string tpname = Comment::decodeCommentType(type);
+  s << "<comment";
+  a_v(s,"type",tpname);
+  s << ">\n";
+  s << "  <addr";
+  funcaddr.getSpace()->saveXmlAttributes(s,funcaddr.getOffset());
+  s << "/>\n";
+  s << "  <addr";
+  addr.getSpace()->saveXmlAttributes(s,addr.getOffset());
+  s << "/>\n";
+  s << "  <text>";
+  xml_escape(s,text.c_str());
+  s << "  </text>\n";
+  s << "</comment>\n";
+}
+
+/// The comment is parsed from a \<comment> tag.
+/// \param el is the \<comment> element
+/// \param manage is a manager for resolving address space references
+void Comment::restoreXml(const Element *el,const AddrSpaceManager *manage)
+
+{
+  type = 0;
+  type = Comment::encodeCommentType(el->getAttributeValue("type"));
+  const List &list(el->getChildren());
+  List::const_iterator iter;
+
+  iter = list.begin();
+  funcaddr = Address::restoreXml(*iter,manage);
+  ++iter;
+  addr = Address::restoreXml(*iter,manage);
+  ++iter;
+  if (iter != list.end())
+    text = (*iter)->getContent();
+}
+
+/// \param name is a string representation of a single comment property
+/// \return the enumerated property type
+uint4 Comment::encodeCommentType(const string &name)
+
+{
+  if (name == "user1")
+    return Comment::user1;
+  if (name == "user2")
+    return Comment::user2;
+  if (name == "user3")
+    return Comment::user3;
+  if (name == "header")
+    return Comment::header;
+  if (name == "warning")
+    return Comment::warning;
+  if (name == "warningheader")
+    return Comment::warningheader;
+  throw LowlevelError("Unknown comment type: "+name);
+}
+
+/// \param val is a single comment property
+/// \return the string representation of the property
+string Comment::decodeCommentType(uint4 val)
+
+{
+  switch(val) {
+  case user1:
+    return "user1";
+  case user2:
+    return "user2";
+  case user3:
+    return "user3";
+  case header:
+    return "header";
+  case warning:
+    return "warning";
+  case warningheader:
+    return "warningheader";
+  default:
+    break;
+  }
+  throw LowlevelError("Unknown comment type");
+}
+
+/// \param a is the first Comment to compare
+/// \param b is the second
+/// \return \b true is the first is ordered before the second
+bool CommentOrder::operator()(const Comment *a,const Comment *b) const
+
+{
+  if (a->getFuncAddr() != b->getFuncAddr())
+    return (a->getFuncAddr() < b->getFuncAddr());
+  if (a->getAddr() != b->getAddr())
+    return (a->getAddr() < b->getAddr());
+  if (a->getUniq() != b->getUniq())
+    return (a->getUniq() < b->getUniq());
+  return false;
+}
+
+CommentDatabaseInternal::CommentDatabaseInternal(void)
+  : CommentDatabase()
+{
+}
+
+CommentDatabaseInternal::~CommentDatabaseInternal(void)
+
+{
+  CommentSet::iterator iter;
+
+  for(iter=commentset.begin();iter!=commentset.end();++iter)
+    delete *iter;
+}
+
+void CommentDatabaseInternal::clear(void)
+
+{
+  CommentSet::iterator iter;
+
+  for(iter=commentset.begin();iter!=commentset.end();++iter)
+    delete *iter;
+  commentset.clear();
+}
+
+void CommentDatabaseInternal::clearType(const Address &fad,uint4 tp)
+
+{
+  Comment testcommbeg(0,fad,Address(Address::m_minimal),0,"");
+  Comment testcommend(0,fad,Address(Address::m_maximal),65535,"");
+
+  CommentSet::iterator iterbegin = commentset.lower_bound(&testcommbeg);
+  CommentSet::iterator iterend = commentset.lower_bound(&testcommend);
+  CommentSet::iterator iter;
+  while(iterbegin != iterend) {
+    iter = iterbegin;
+    ++iter;
+    if (((*iterbegin)->getType()&tp)!=0) {
+      delete (*iterbegin);
+      commentset.erase(iterbegin);
+    }
+    iterbegin = iter;
+  }
+}
+
+void CommentDatabaseInternal::addComment(uint4 tp,const Address &fad,
+					 const Address &ad,
+					 const string &txt)
+{
+  Comment *newcom = new Comment(tp,fad,ad,65535,txt);
+  // Find first element greater
+  CommentSet::iterator iter = commentset.lower_bound(newcom);
+  // turn into last element less than
+  if (iter != commentset.begin())
+    --iter;
+  newcom->uniq = 0;
+  if (iter != commentset.end()) {
+    if (((*iter)->getAddr() == ad)&&((*iter)->getFuncAddr()==fad))
+      newcom->uniq = (*iter)->getUniq() + 1;
+  }
+  commentset.insert(newcom);
+}
+
+bool CommentDatabaseInternal::addCommentNoDuplicate(uint4 tp,const Address &fad,
+						    const Address &ad,const string &txt)
+{
+  Comment *newcom = new Comment(tp,fad,ad,65535,txt);
+
+  // Find first element greater
+  CommentSet::iterator iter = commentset.lower_bound(newcom);
+  newcom->uniq = 0;		// Set the uniq AFTER the search
+  while(iter != commentset.begin()) {
+    --iter;
+    if (((*iter)->getAddr()==ad)&&((*iter)->getFuncAddr()==fad)) {
+      if ((*iter)->getText() == txt) { // Matching text, don't store it
+	delete newcom;
+	return false;
+      }
+      if (newcom->uniq == 0)
+	newcom->uniq = (*iter)->getUniq() + 1;
+    }
+    else
+      break;
+  }
+  commentset.insert(newcom);
+  return true;
+}
+
+void CommentDatabaseInternal::deleteComment(Comment *com)
+
+{
+  commentset.erase(com);
+  delete com;
+}
+
+CommentSet::const_iterator CommentDatabaseInternal::beginComment(const Address &fad) const
+
+{
+  Comment testcomm(0,fad,Address(Address::m_minimal),0,"");
+  return commentset.lower_bound(&testcomm);
+}
+
+CommentSet::const_iterator CommentDatabaseInternal::endComment(const Address &fad) const
+
+{
+  Comment testcomm(0,fad,Address(Address::m_maximal),65535,"");
+  return commentset.lower_bound(&testcomm);
+}
+
+void CommentDatabaseInternal::saveXml(ostream &s) const
+
+{
+  CommentSet::const_iterator iter;
+
+  s << "<commentdb>\n";
+  for(iter=commentset.begin();iter!=commentset.end();++iter)
+    (*iter)->saveXml(s);
+  s << "</commentdb>\n";
+}
+
+void CommentDatabaseInternal::restoreXml(const Element *el,const AddrSpaceManager *manage)
+
+{
+  const List &list(el->getChildren());
+  List::const_iterator iter;
+  
+  for(iter=list.begin();iter!=list.end();++iter) {
+    Comment com;
+    com.restoreXml(*iter,manage);
+    addComment(com.getType(),com.getFuncAddr(),com.getAddr(),com.getText());
+  }
+}
+
+/// Figure out position of given Comment and initialize its key.
+/// \param subsort is a reference to the key to be initialized
+/// \param comm is the given Comment
+/// \param fd is the function owning the Comment
+/// \return \b true if the Comment could be positioned at all
+bool CommentSorter::findPosition(Subsort &subsort,Comment *comm,const Funcdata *fd)
+
+{
+  if (comm->getType() == 0) return false;
+  const Address &fad( fd->getAddress() );
+  if (((comm->getType() & (Comment::header | Comment::warningheader))!=0)&&(comm->getAddr() == fad)) {
+    // If it is a header comment at the address associated with the beginning of the function
+    subsort.setHeader(header_basic);
+    return true;
+  }
+
+  // Try to find block containing comment
+  // Find op at lowest address greater or equal to comment's address
+  PcodeOpTree::const_iterator opiter = fd->beginOp(comm->getAddr());
+  PcodeOp *backupOp = (PcodeOp *)0;
+  if (opiter != fd->endOpAll()) {	// If there is an op at or after the comment
+    PcodeOp *op = (*opiter).second;
+    BlockBasic *block = op->getParent();
+    if (block->contains(comm->getAddr())) { // If the op's block contains the address
+      // Associate comment with this op
+      subsort.setBlock(block->getIndex(), (uint4)op->getSeqNum().getOrder());
+      return true;
+    }
+    if (comm->getAddr() == op->getAddr())
+      backupOp = op;
+  }
+  if (opiter != fd->beginOpAll()) {	// If there is a previous op
+    --opiter;
+    PcodeOp *op = (*opiter).second;
+    BlockBasic *block = op->getParent();
+    if (block->contains(comm->getAddr())) { // If the op's block contains the address
+      // Treat the comment as being in this block at the very end
+      subsort.setBlock(block->getIndex(),0xffffffff);
+      return true;
+    }
+  }
+  if (backupOp != (PcodeOp *)0) {
+    // Its possible the op migrated from its original basic block.
+    // Since the address matches exactly, hang the comment on it
+    subsort.setBlock(backupOp->getParent()->getIndex(),(uint4)backupOp->getSeqNum().getOrder());
+    return true;
+  }
+  if (fd->beginOpAll() == fd->endOpAll()) {	// If there are no ops at all
+    subsort.setBlock(0,0);	// Put comment at the beginning of the first block
+    return true;
+  }
+  if (displayUnplacedComments) {
+    subsort.setHeader(header_unplaced);
+    return true;
+  }
+  return false;		// Basic block containing comment has been excised
+}
+
+/// \brief Collect and sort comments specific to the given function.
+///
+/// Only keep comments matching one of a specific set of properties
+/// \param tp is the set of properties (may be zero)
+/// \param fd is the given function
+/// \param db is the container of comments to collect from
+/// \param displayUnplaced is \b true if unplaced comments should be displayed in the header
+void CommentSorter::setupFunctionList(uint4 tp,const Funcdata *fd,const CommentDatabase &db,bool displayUnplaced)
+{
+  commmap.clear();
+  displayUnplacedComments = displayUnplaced;
+  if (tp == 0) return;
+  const Address &fad( fd->getAddress() );
+  CommentSet::const_iterator iter = db.beginComment(fad);
+  CommentSet::const_iterator lastiter = db.endComment(fad);
+  Subsort subsort;
+
+  subsort.pos = 0;
+
+  while(iter != lastiter) {
+    Comment *comm = *iter;
+    if (findPosition(subsort, comm, fd)) {
+      commmap[ subsort ] = comm;
+      subsort.pos += 1;		// Advance the uniqueness counter
+    }
+    ++iter;
+  }
+}
+
+/// This will generally get called with the root p-code op of a statement
+/// being emitted by the decompiler. This establishes a key value within the
+/// basic block, so it is known where to stop emitting comments within the
+/// block for emitting the statement.
+/// \param op is the p-code representing the root of a statement
+void CommentSorter::setupOpList(const PcodeOp *op)
+
+{
+  if (op == (const PcodeOp *)0) { // If NULL op
+    opstop = stop;		// pick up any remaining comments in this basic block
+    return;
+  }
+  Subsort subsort;
+  subsort.index = op->getParent()->getIndex();
+  subsort.order = (uint4)op->getSeqNum().getOrder();
+  subsort.pos = 0xffffffff;
+  opstop = commmap.upper_bound(subsort);
+}
+
+/// Find iterators that bound everything in the basic block
+///
+/// \param bl is the basic block
+void CommentSorter::setupBlockList(const FlowBlock *bl)
+
+{
+  Subsort subsort;
+  subsort.index = bl->getIndex();
+  subsort.order = 0;
+  subsort.pos = 0;
+  start = commmap.lower_bound(subsort);
+  subsort.order = 0xffffffff;
+  subsort.pos = 0xffffffff;
+  stop = commmap.upper_bound(subsort);
+}
+
+/// Header comments are grouped together. Set up iterators.
+/// \param headerType selects either \b header_basic or \b header_unplaced comments
+void CommentSorter::setupHeader(uint4 headerType)
+
+{
+  Subsort subsort;
+  subsort.index = -1;
+  subsort.order = headerType;
+  subsort.pos = 0;
+  start = commmap.lower_bound(subsort);
+  subsort.pos = 0xffffffff;
+  opstop = commmap.upper_bound(subsort);
+}