ghidra::CommentSorter Class Reference

A class for sorting comments into and within basic blocks. More...

#include <comment.hh>

Classes
struct	Subsort
	The sorting key for placing a Comment within a specific basic block. More...

Public Types
enum	{ header_basic = 0, header_unplaced = 1 }

Public Member Functions
	CommentSorter (void)
	Constructor.
void	setupFunctionList (uint4 tp, const Funcdata *fd, const CommentDatabase &db, bool displayUnplaced)
	Collect and sort comments specific to the given function. More...
void	setupBlockList (const FlowBlock *bl)
	Prepare to walk comments from a single basic block. More...
void	setupOpList (const PcodeOp *op)
	Establish a p-code landmark within the current set of comments. More...
void	setupHeader (uint4 headerType)
	Prepare to walk comments in the header. More...
bool	hasNext (void) const
	Return true if there are more comments to emit in the current set.
Comment *	getNext (void) const
	Advance to the next comment.

Private Member Functions
bool	findPosition (Subsort &subsort, Comment *comm, const Funcdata *fd)
	Establish sorting key for a Comment. More...

Private Attributes
map< Subsort, Comment * >	commmap
	Comments for the current function, sorted by block.
map< Subsort, Comment * >::const_iterator	start
	Iterator to current comment being walked.
map< Subsort, Comment * >::const_iterator	stop
	Last comment in current set being walked.
map< Subsort, Comment * >::const_iterator	opstop
	Statement landmark within current set of comments.
bool	displayUnplacedComments
	True if unplaced comments should be displayed (in the header)

Detailed Description

A class for sorting comments into and within basic blocks.

The decompiler endeavors to display comments within the flow of the source code statements it generates. Comments should be placed at or near the statement that encompasses the address of the original instruction to which the comment is attached. This is complicated by the fact that instructions may get removed and transformed during decompilation and even whole basic blocks may get removed.

This class sorts comments into the basic block that contains it. As statements are emitted, comments can get picked up, in the correct order, even if there is no longer a specific p-code operation at the comment's address. The decompiler maintains information about basic blocks that have been entirely removed, in which case, the user can elect to not display the corresponding comments.

This class also acts as state for walking comments within a specific basic block or within the header.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
header_basic	Basic header comments.
header_unplaced	Comment that can't be placed in code flow.

Member Function Documentation

findPosition()

bool ghidra::CommentSorter::findPosition ( Subsort &  subsort, Comment *  comm, const Funcdata *  fd  )

private

Establish sorting key for a Comment.

Figure out position of given Comment and initialize its key.

Parameters

subsort	is a reference to the key to be initialized
comm	is the given Comment
fd	is the function owning the Comment

Returns

true if the Comment could be positioned at all

References ghidra::Funcdata::beginOp(), ghidra::Funcdata::beginOpAll(), ghidra::BlockBasic::contains(), ghidra::Funcdata::endOpAll(), ghidra::Comment::getAddr(), ghidra::PcodeOp::getAddr(), ghidra::Funcdata::getAddress(), ghidra::FlowBlock::getIndex(), ghidra::SeqNum::getOrder(), ghidra::PcodeOp::getParent(), ghidra::PcodeOp::getSeqNum(), ghidra::Comment::getType(), ghidra::Comment::header, ghidra::CommentSorter::Subsort::setBlock(), ghidra::CommentSorter::Subsort::setHeader(), and ghidra::Comment::warningheader.

setupBlockList()

void ghidra::CommentSorter::setupBlockList

(

const FlowBlock *

bl

)

Prepare to walk comments from a single basic block.

Find iterators that bound everything in the basic block

Parameters

bl	is the basic block

References ghidra::FlowBlock::getIndex(), ghidra::CommentSorter::Subsort::index, ghidra::CommentSorter::Subsort::order, and ghidra::CommentSorter::Subsort::pos.

Referenced by ghidra::PrintC::emitBlockBasic(), and ghidra::PrintC::emitCommentBlockTree().

setupFunctionList()

void ghidra::CommentSorter::setupFunctionList	(	uint4	tp,
		const Funcdata *	fd,
		const CommentDatabase &	db,
		bool	displayUnplaced
	)

Collect and sort comments specific to the given function.

Only keep comments matching one of a specific set of properties

Parameters

tp	is the set of properties (may be zero)
fd	is the given function
db	is the container of comments to collect from
displayUnplaced	is true if unplaced comments should be displayed in the header

References ghidra::CommentDatabase::beginComment(), ghidra::CommentDatabase::endComment(), ghidra::Funcdata::getAddress(), ghidra::CommentSorter::Subsort::pos, and ghidra::Comment::setEmitted().

Referenced by ghidra::PrintC::docFunction().

setupHeader()

void ghidra::CommentSorter::setupHeader

(

uint4

headerType

)

Prepare to walk comments in the header.

Header comments are grouped together. Set up iterators.

Parameters

headerType

selects either header_basic or header_unplaced comments

References ghidra::CommentSorter::Subsort::index, ghidra::CommentSorter::Subsort::order, and ghidra::CommentSorter::Subsort::pos.

Referenced by ghidra::PrintC::emitCommentFuncHeader().

setupOpList()

void ghidra::CommentSorter::setupOpList

(

const PcodeOp *

op

)

Establish a p-code landmark within the current set of comments.

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.

Parameters

op	is the p-code representing the root of a statement

References ghidra::FlowBlock::getIndex(), ghidra::SeqNum::getOrder(), ghidra::PcodeOp::getParent(), ghidra::PcodeOp::getSeqNum(), ghidra::CommentSorter::Subsort::index, ghidra::CommentSorter::Subsort::order, and ghidra::CommentSorter::Subsort::pos.

Referenced by ghidra::PrintC::emitCommentGroup().

---

The documentation for this class was generated from the following files:

• comment.hh
• comment.cc