Daniel Carvalho has submitted this change. (
https://gem5-review.googlesource.com/c/public/gem5/+/43248 )
Change subject: base: Document the SymbolTable
......................................................................
base: Document the SymbolTable
Add Doxygen documentation to SymbolTable's contents.
Some parameters were renamed to make their purpose
easier to understand.
Change-Id: Ia4f18bf60d3d8eab7a775f34f553d420816d62b9
Signed-off-by: Daniel R. Carvalho <[email protected]>
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/43248
Tested-by: kokoro <[email protected]>
Reviewed-by: Giacomo Travaglini <[email protected]>
Maintainer: Giacomo Travaglini <[email protected]>
---
M src/base/loader/symtab.hh
1 file changed, 164 insertions(+), 28 deletions(-)
Approvals:
Giacomo Travaglini: Looks good to me, approved; Looks good to me, approved
kokoro: Regressions pass
diff --git a/src/base/loader/symtab.hh b/src/base/loader/symtab.hh
index 03fbb8e..3e287c2 100644
--- a/src/base/loader/symtab.hh
+++ b/src/base/loader/symtab.hh
@@ -1,4 +1,5 @@
/*
+ * Copyright (c) 2021 Daniel R. Carvalho
* Copyright (c) 2002-2005 The Regents of The University of Michigan
* All rights reserved.
*
@@ -64,16 +65,24 @@
typedef std::shared_ptr<SymbolTable> SymbolTablePtr;
private:
+ /** Vector containing all the symbols in the table. */
typedef std::vector<Symbol> SymbolVector;
- // Map addresses to an index into the symbol vector.
+ /** Map addresses to an index into the symbol vector. */
typedef std::multimap<Addr, int> AddrMap;
- // Map a symbol name to an index into the symbol vector.
+ /** Map a symbol name to an index into the symbol vector. */
typedef std::map<std::string, int> NameMap;
SymbolVector symbols;
AddrMap addrMap;
NameMap nameMap;
+ /**
+ * Get the first address larger than the given address, if any.
+ *
+ * @param addr The address to compare against.
+ * @param iter An iterator to the larger-address entry.
+ * @return True if successful; false if no larger addresses exist.
+ */
bool
upperBound(Addr addr, AddrMap::const_iterator &iter) const
{
@@ -87,8 +96,21 @@
return true;
}
+ /**
+ * A function that applies an operation on a symbol with respect to a
+ * symbol table. The operation can, for example, simply add the symbol
+ * to the table; modify and insert the symbol; do nothing at all; etc.
+ */
typedef std::function<void(SymbolTable &symtab,
const Symbol &symbol)> SymTabOp;
+
+ /**
+ * Create a derived symbol table by applying an operation on the
symbols
+ * of the current table. The current table is not modified.
+ *
+ * @param op The operation to be applied to the new table.
+ * @return The new table.
+ */
SymbolTablePtr
operate(SymTabOp op) const
{
@@ -98,7 +120,20 @@
return symtab;
}
+ /**
+ * A function that applies a condition to the symbol provided to decide
+ * whether the symbol is accepted, or if it must be filtered out.
+ */
typedef std::function<bool(const Symbol &symbol)> SymTabFilter;
+
+ /**
+ * Applies a filter to the symbols of the table to generate a new
table.
+ * The filter decides whether the symbols will be inserted in the new
+ * table or not.
+ *
+ * @param filter The filter to be applied.
+ * @return A new table, filtered.
+ */
SymbolTablePtr
filter(SymTabFilter filter) const
{
@@ -111,6 +146,13 @@
return operate(apply_filter);
}
+ /**
+ * Generate a new table by applying a filter that only accepts the
symbols
+ * whose binding matches the given binding.
+ *
+ * @param The binding that must be matched.
+ * @return A new table, filtered by binding.
+ */
SymbolTablePtr
filterByBinding(Symbol::Binding binding) const
{
@@ -124,27 +166,66 @@
typedef SymbolVector::iterator iterator;
typedef SymbolVector::const_iterator const_iterator;
+ /** @return An iterator to the beginning of the symbol vector. */
const_iterator begin() const { return symbols.begin(); }
+
+ /** @return An iterator to the end of the symbol vector. */
const_iterator end() const { return symbols.end(); }
+ /** Clears the table. */
void clear();
- // Insert either a single symbol or the contents of an entire symbol
table
- // into this one.
+
+ /**
+ * Insert a new symbol in the table if it does not already exist. The
+ * symbol must have a defined name.
+ *
+ * @param symbol The symbol to be inserted.
+ * @return True if successful; false if table already contains the
symbol.
+ */
bool insert(const Symbol &symbol);
+
+ /**
+ * Copies the symbols of another table to this table if there are no
+ * common symbols between the tables.
+ *
+ * @param symbol The symbol to be inserted.
+ * @return True if successful; false if tables contain any common
symbols.
+ */
bool insert(const SymbolTable &other);
+
+ /**
+ * Verifies whether the table is empty.
+ *
+ * @return Whether the symbol table is empty.
+ */
bool empty() const { return symbols.empty(); }
+ /**
+ * Generate a new table by applying an offset to the symbols of the
+ * current table. The current table is not modified.
+ *
+ * @param addr_offset The offset to be applied.
+ * @return The new table.
+ */
SymbolTablePtr
- offset(Addr by) const
+ offset(Addr addr_offset) const
{
- SymTabOp op = [by](SymbolTable &symtab, const Symbol &symbol) {
- Symbol sym = symbol;
- sym.address += by;
- symtab.insert(sym);
- };
+ SymTabOp op =
+ [addr_offset](SymbolTable &symtab, const Symbol &symbol) {
+ Symbol sym = symbol;
+ sym.address += addr_offset;
+ symtab.insert(sym);
+ };
return operate(op);
}
+ /**
+ * Generate a new table by a mask to the symbols of the current table.
+ * The current table is not modified.
+ *
+ * @param m The mask to be applied.
+ * @return The new table.
+ */
SymbolTablePtr
mask(Addr m) const
{
@@ -156,10 +237,13 @@
return operate(op);
}
- /// Modify symbol name with a given transform function.
- /// @param func The transform function accepting the
reference of
- /// symbol name.
- /// @retval SymbolTablePtr A pointer to the modified SymbolTable copy.
+ /**
+ * Modify the symbols' name with a given transform function.
+ *
+ * @param func The transform function accepting the reference of the
+ * symbol's name.
+ * @retval SymbolTablePtr A pointer to the modified SymbolTable copy.
+ */
SymbolTablePtr
rename(std::function<void(std::string&)> func) const
{
@@ -171,28 +255,66 @@
return operate(op);
}
+ /**
+ * Generates a new symbol table containing only global symbols.
+ *
+ * @return The new table.
+ */
SymbolTablePtr
globals() const
{
return filterByBinding(Symbol::Binding::Global);
}
+ /**
+ * Generates a new symbol table containing only local symbols.
+ *
+ * @return The new table.
+ */
SymbolTablePtr
locals() const
{
return filterByBinding(Symbol::Binding::Local);
}
+ /**
+ * Generates a new symbol table containing only weak symbols.
+ *
+ * @return The new table.
+ */
SymbolTablePtr
weaks() const
{
return filterByBinding(Symbol::Binding::Weak);
}
+ /**
+ * Serialize the table's contents.
+ *
+ * @param base The base section.
+ * @param cp The checkpoint to use.
+ */
void serialize(const std::string &base, CheckpointOut &cp) const;
+
+ /**
+ * Populate the table by unserializing a checkpoint.
+ *
+ * @param base The base section.
+ * @param cp The checkpoint to use.
+ * @param default_binding The binding to be used if an unserialized
+ * symbol's binding is not found.
+ */
void unserialize(const std::string &base, CheckpointIn &cp,
Symbol::Binding
default_binding=Symbol::Binding::Global);
+ /**
+ * Search for a symbol by its address. Since many symbols can map to
the
+ * same address, this function returns the first found. If the symbol
is
+ * not found this function returns the end() iterator.
+ *
+ * @param address The address of the symbol being searched for.
+ * @return A const iterator to the symbol. end() if not found.
+ */
const_iterator
find(Addr address) const
{
@@ -205,6 +327,13 @@
return symbols.begin() + i->second;
}
+ /**
+ * Search for a symbol by its name. If the symbol is not found this
+ * function returns the end() iterator.
+ *
+ * @param name The name of the symbol being searched for.
+ * @return A const iterator to the symbol. end() if not found.
+ */
const_iterator
find(const std::string &name) const
{
@@ -215,26 +344,31 @@
return symbols.begin() + i->second;
}
- /// Find the nearest symbol equal to or less than the supplied
- /// address (e.g., the label for the enclosing function).
- /// @param addr The address to look up.
- /// @param nextaddr Address of following symbol (for
- /// determining valid range of symbol).
- /// @retval A const_iterator which points to the symbol if found, or
end.
+ /**
+ * Find the nearest symbol equal to or less than the supplied
+ * address (e.g., the label for the enclosing function).
+ *
+ * @param addr The address to look up.
+ * @param next_addr Address of following symbol (to determine the valid
+ * range of the symbol).
+ * @retval A const_iterator which points to the symbol if found, or
end.
+ */
const_iterator
- findNearest(Addr addr, Addr &nextaddr) const
+ findNearest(Addr addr, Addr &next_addr) const
{
AddrMap::const_iterator i = addrMap.end();
if (!upperBound(addr, i))
return end();
- nextaddr = i->first;
+ next_addr = i->first;
--i;
return symbols.begin() + i->second;
}
- /// Overload for findNearestSymbol() for callers who don't care
- /// about nextaddr.
+ /**
+ * Overload for findNearestSymbol() for callers who don't care
+ * about nextaddr.
+ */
const_iterator
findNearest(Addr addr) const
{
@@ -247,10 +381,12 @@
}
};
-/// Global unified debugging symbol table (for target). Conceptually
-/// there should be one of these per System object for full system,
-/// and per Process object for non-full-system, but so far one big
-/// global one has worked well enough.
+/**
+ * Global unified debugging symbol table (for target). Conceptually
+ * there should be one of these per System object for full system,
+ * and per Process object for non-full-system, but so far one big
+ * global one has worked well enough.
+ */
extern SymbolTable debugSymbolTable;
} // namespace loader
10 is the latest approved patch-set.
No files were changed between the latest approved patch-set and the
submitted one.
--
To view, visit https://gem5-review.googlesource.com/c/public/gem5/+/43248
To unsubscribe, or for help writing mail filters, visit
https://gem5-review.googlesource.com/settings
Gerrit-Project: public/gem5
Gerrit-Branch: develop
Gerrit-Change-Id: Ia4f18bf60d3d8eab7a775f34f553d420816d62b9
Gerrit-Change-Number: 43248
Gerrit-PatchSet: 12
Gerrit-Owner: Daniel Carvalho <[email protected]>
Gerrit-Reviewer: Bobby R. Bruce <[email protected]>
Gerrit-Reviewer: Daniel Carvalho <[email protected]>
Gerrit-Reviewer: Giacomo Travaglini <[email protected]>
Gerrit-Reviewer: kokoro <[email protected]>
Gerrit-MessageType: merged
_______________________________________________
gem5-dev mailing list -- [email protected]
To unsubscribe send an email to [email protected]
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s