elftosb::ConversionController Class Reference

Manages the entire elftosb file conversion process. More...

`#include <ConversionController.h>`

Inheritance diagram for elftosb::ConversionController:
[legend]
Collaboration diagram for elftosb::ConversionController:
[legend]

## Public Member Functions

| ConversionController ()
| Default constructor.
virtual | ~ConversionController ()
| Destructor.
EvalContext & | getEvalContext ()
| Returns a reference to the context used for expression evaluation.
Paths
void | setCommandFilePath (const std::string &path)
| Specify the command file that controls the conversion process.
void | addExternalFilePath (const std::string &path)
| Specify the path of a file provided by the user from outside the command file. More...
Conversion
void | run ()
| Process input files. More...
BootImage * | generateOutput (BootImageGenerator *generator)
| Uses a BootImageGenerator object to create the final output boot image. More...
SourceFileManager interface
virtual bool | hasSourceFile (const std::string &name)
| Returns true if a source file with the name name exists.
virtual SourceFile * | getSourceFile (const std::string &name)
| Gets the requested source file.
virtual SourceFile * | getDefaultSourceFile ()
| Returns the default source file, or NULL if none is set.
Public Member Functions inherited from elftosb::OptionDictionary
| OptionDictionary ()
| Default constructor.
| OptionDictionary (OptionContext *parent)
| Constructor taking a parent context.
| ~OptionDictionary ()
| Destructor. More...
OptionContext * | getParent () const
| Returns the current parent context. More...
void | setParent (OptionContext *newParent)
| Change the parent context. More...
virtual bool | hasOption (const std::string &name) const
| Detemine whether the named option is present in the table. More...
virtual const Value * | getOption (const std::string &name) const
| Returns the option's value. More...
virtual void | setOption (const std::string &name, Value *value)
| Adds or changes an option's value. More...
virtual void | deleteOption (const std::string &name)
| Removes an option from the table. More...
bool | isOptionLocked (const std::string &name) const
| Returns true if the specified option is locked from further changes. More...
void | lockOption (const std::string &name)
| Prevent further modifications of an option's value. More...
void | unlockOption (const std::string &name)
| Allow an option to be changed. More...
const Value * | operator[] (const std::string &name) const
| Indexing operator; returns the value for the option name. More...
Public Member Functions inherited from elftosb::OptionContext
virtual | ~OptionContext ()
| Make the dtor virtual.

## Protected Types

typedef std::map< std::string, SourceFile * > | source_map_t
| Map from source name to object.
typedef std::vector< std::string > | path_vector_t
| List of file paths.
typedef std::vector< OutputSection * > | section_vector_t
| List of output sections.
typedef std::vector< std::string > | source_name_vector_t
| List of source names.
typedef std::vector< Keyblob * > | keyblob_vector_t
| List of keyblobs.
Protected Types inherited from elftosb::OptionDictionary
typedef std::map< std::string, OptionValue > | option_map_t
| Map from option name to value.

## Protected Member Functions

AST processing
void | parseCommandFile ()
void | processOptions (ListASTNode *options)
void | processConstants (ListASTNode *constants)
void | processSources (ListASTNode *sources)
void | processKeyblob (ExprASTNode *idExpr, ListASTNode *entires)
void | processSections (ListASTNode *sections)
OutputSection * | convertDataSection (DataSectionContentsASTNode *dataSection, uint32_t sectionID, OptionDictionary *optionsDict)
Statement conversion
OperationSequence * | convertStatementList (ListASTNode *statements)
OperationSequence * | convertOneStatement (StatementASTNode *statement)
OperationSequence * | convertLoadStatement (LoadStatementASTNode *statement)
OperationSequence * | convertCallStatement (CallStatementASTNode *statement)
OperationSequence * | convertFromStatement (FromStatementASTNode *statement)
OperationSequence * | convertModeStatement (ModeStatementASTNode *statement)
OperationSequence * | convertResetStatement (ResetStatementASTNode *statement)
| Creates a Reset Operation object and returns an OperationSequence containing it.
OperationSequence * | convertIfStatement (IfStatementASTNode *statement)
OperationSequence * | convertEraseStatement (EraseStatementASTNode *statement)
OperationSequence * | convertMemEnableStatement (MemEnableStatementASTNode *statement)
OperationSequence * | convertKeywrapStatement (KeywrapStatementASTNode *statement)
OperationSequence * | convertEncryptStatement (EncryptStatementASTNode *statement)
void | handleMessageStatement (MessageStatementASTNode *statement)
Utilities
Value * | convertAssignmentNodeToValue (ASTNode *node, std::string &ident)
SourceFile * | getSourceFromName (std::string *sourceName, int line)
DataSource * | createSourceFromNode (ASTNode *dataNode)
DataTarget * | createTargetFromNode (ASTNode *targetNode)
std::string * | substituteVariables (const std::string *message)
DataSource * | createIVTDataSource (IVTConstASTNode *ivtNode)
Debugging
void | testLexer (ElftosbLexer &lexer)
void | printIntConstExpr (const std::string &ident, IntConstExprASTNode *expr)

## Protected Attributes

smart_ptr< std::string > | m_commandFilePath
| Path to command file.
smart_ptr< CommandFileASTNode > | m_ast
| Root of the abstract syntax tree.
EvalContext | m_context
| Evaluation context for expressions.
source_map_t | m_sources
| Map of source names to file objects.
path_vector_t | m_externPaths
| Paths provided on the command line by the user.
SourceFile * | m_defaultSource
| Source to use when one isn't provided.
section_vector_t | m_outputSections
| List of output sections the user wants.
source_name_vector_t | m_failedSources
| List of sources that failed to open successfully.
keyblob_vector_t | m_keyblobs
| List of keyblobs the user defines.
Keyblob * | m_keywrapKeyblob
| Keyblob used for keywrapping.
Keyblob * | m_encryptKeyblob
| Keyblob used for OTFAD encryption.
Protected Attributes inherited from elftosb::OptionDictionary
OptionContext * | m_parent
| Our parent context.
option_map_t | m_options
| The option dictionary.

## Detailed Description

Manages the entire elftosb file conversion process.

Instances of this class are intended to be used only once. There is no way to reset an instance once it has started or completed a conversion. Thus the run() method is not reentrant. State information is stored in the object during the conversion process.

Two things need to be done before the conversion can be started. The command file path has to be set with the setCommandFilePath() method, and the paths of any externally provided (i.e., from the command line) files need to be added with addExternalFilePath(). Once these tasks are completed, the run() method can be called to parse and execute the command file. After run() returns, pass an instance of BootImageGenerator to the generateOutput() method in order to get an instance of BootImage that can be written to the output file.

## Member Function Documentation

void ConversionController::addExternalFilePath | ( | const std::string & | path | ) |

Specify the path of a file provided by the user from outside the command file.

The paths provided to this method are added to an array and accessed with the "extern(N)" notation in the command file. So the path provided in the third call to addExternalFilePath() will be found with N=2 in the source definition.

Value * ConversionController::convertAssignmentNodeToValue | ( | ASTNode * | node,
|  | std::string & | ident
| ) |  |

protected

Parameters

  | node | The AST node instance for the assignment expression.
  [out] | ident | Upon exit this string will be set the the left hand side of the assignment expression, the identifier name.

Returns
  An object that is a subclass of Value is returned. The specific subclass will depend on the type of the right hand side of the assignment expression whose AST node was provided in the node argument.

Exceptions

  semantic_error | Thrown for any error where an AST node is an unexpected type. This may be the node argument itself, if it is not an AssignmentASTNode. Or it may be an unexpected type for either the right or left hand side of the assignment. The message for the exception will contain a description of the error.

OperationSequence * ConversionController::convertCallStatement | ( | CallStatementASTNode * | statement | ) |

protected

Possible call target node types:

- SymbolASTNode
- ExprASTNode

Possible call argument node types:

- ExprASTNode
- NULL

OutputSection * ConversionController::convertDataSection | ( | DataSectionContentsASTNode * | dataSection,
|  | uint32_t | sectionID,
|  | OptionDictionary * | optionsDict
| ) |  |

protected

Creates an instance of BinaryDataSection from the AST node passed in the dataSection parameter. The section-specific options for this node will have already been converted into an OptionDictionary, the one passed in the optionsDict parameter.

The dataSection node will have as its contents one of the AST node classes that represents a source of data. The member function createSourceFromNode() is used to convert this AST node into an instance of a DataSource subclass. Then the method imageDataSource() converts the segments of the DataSource into a raw binary buffer that becomes the contents of the BinaryDataSection this is returned.

Parameters

  dataSection | The AST node for the data section.
  sectionID | Unique tag value the user has assigned to this section.
  optionsDict | Options that apply only to this section. This dictionary will be assigned as the options dictionary for the resulting section object. Its parent is the conversion controller itself.

Returns
  An instance of BinaryDataSection. Its contents are a contiguous binary representation of the contents of dataSection.

OperationSequence * ConversionController::convertEncryptStatement | ( | EncryptStatementASTNode * | statement | ) |

protected

First this method sets the keyblob to the keyblob number identified in the encrypt statement. Then the statements within the encrypt block are processed recursively by calling convertStatementList(). The resulting operation sequence is returned.

OperationSequence * ConversionController::convertFromStatement | ( | FromStatementASTNode * | statement | ) |

protected

First this method sets the default source to the source identified in the from statement. Then the statements within the from block are processed recursively by calling convertStatementList(). The resulting operation sequence is returned.

OperationSequence * ConversionController::convertIfStatement | ( | IfStatementASTNode * | statement | ) |

protected

Else branches, including else-if, are handled recursively, so there is a limit on the number of them based on the stack size.

Returns
  Returns the operation sequence for the branch of the if statement that evaluated to true. If the statement did not have an else branch and the condition expression evaluated to false, then NULL will be returned.

OperationSequence * ConversionController::convertKeywrapStatement | ( | KeywrapStatementASTNode * | statement | ) |

protected

First this method sets the keyblob to the keyblob number identified in the keywrap statement. Then the statements within the keywrap block are processed recursively by calling convertStatementList(). The resulting operation sequence is returned.

OperationSequence * ConversionController::convertLoadStatement | ( | LoadStatementASTNode * | statement | ) |

protected

Possible load data node types:

- StringConstASTNode
- ExprASTNode
- SourceASTNode
- SectionMatchListASTNode

Possible load target node types:

- SymbolASTNode
- NaturalLocationASTNode
- AddressRangeASTNode

OperationSequence * ConversionController::convertModeStatement | ( | ModeStatementASTNode * | statement | ) |

protected

Evaluates the expression to get the new boot mode value. Then creates a BootModeOperation object and returns an OperationSequence containing it.

Exceptions

  elftosb::semantic_error | Thrown if a semantic problem is found with the boot mode expression.

OperationSequence * ConversionController::convertOneStatement | ( | StatementASTNode * | statement | ) |

protected

Uses C++ RTTI to identify the particular subclass of StatementASTNode that the statement argument matches. Then the appropriate conversion method is called.

See also
  convertLoadStatement()
  convertCallStatement()
  convertFromStatement()

OperationSequence * ConversionController::convertStatementList | ( | ListASTNode * | statements | ) |

protected

Builds up a sequence of Operation objects that are equivalent to the statements in the statements list. The statement list is simply iterated over and the results of convertOneStatement() are used to build up the final result sequence.

See also
  convertOneStatement()

DataSource * ConversionController::createSourceFromNode | ( | ASTNode * | dataNode | ) |

protected

Takes an AST node that is one of the following subclasses and creates the corresponding type of DataSource object from it.

- StringConstASTNode
- ExprASTNode
- SourceASTNode
- SectionASTNode
- SectionMatchListASTNode
- BlobConstASTNode
- IVTConstASTNode

Exceptions

  elftosb::semantic_error | Thrown if a semantic problem is found with the data node.
  std::runtime_error | Thrown if an error occurs that shouldn't be possible based on the grammar.

DataTarget * ConversionController::createTargetFromNode | ( | ASTNode * | targetNode | ) |

protected

Takes an AST node subclass and returns an appropriate DataTarget object that contains the same information. Supported AST node types are:

- SymbolASTNode
- NaturalLocationASTNode
- AddressRangeASTNode

Exceptions

  elftosb::semantic_error | Thrown if a semantic problem is found with the target node.

BootImage * ConversionController::generateOutput | ( | BootImageGenerator * | generator | ) |

Uses a BootImageGenerator object to create the final output boot image.

Parameters

  generator | The generator to use.

SourceFile * ConversionController::getSourceFromName | ( | std::string * | sourceName,
|  | int | line
| ) |  |

protected

Parameters

  sourceName | Pointer to string containing the name of the source to look up. May be NULL, in which case the default source is used.
  line | The line number on which the source name was located.

Returns
  A source file object that was previously created in the processSources() stage.

Exceptions

  std::runtime_error | Thrown if the source name is invalid, or if it was NULL and there is no default source (i.e., we're not inside a from statement).

void ConversionController::handleMessageStatement | ( | MessageStatementASTNode * | statement | ) |

protected

Message statements are executed immediately, by this method. They are not converted into an abstract operation. All messages are passed through substituteVariables() before being output.

Parameters

  statement | The message statement AST node object.

void ConversionController::parseCommandFile | ( |  | ) |

protected

Opens the command file and runs it through the lexer and parser. The resulting abstract syntax tree is held in the m_ast member variable. After parsing, the command file is closed.

Exceptions

  std::runtime_error | Several problems will cause this exception to be raised, including an unspecified command file path or an error opening the file.

void ConversionController::printIntConstExpr | ( | const std::string & | ident,
|  | IntConstExprASTNode * | expr
| ) |  |

protected

Prints out the value of an integer constant expression AST node. Also prints the name of the identifier associated with that node, as well as the integer size.

void ConversionController::processConstants | ( | ListASTNode * | constants | ) |

protected

Scans the constant definition AST nodes, evaluates expression nodes by calling their elftosb::ExprASTNode::reduce() method, and updates the evaluation context member so those constant values can be used in other expressions.

Exceptions

  std::runtime_error | Various errors will cause this exception to be thrown. These include AST nodes being an unexpected type or expression not evaluating to integers.

void ConversionController::processKeyblob | ( | ExprASTNode * | idExpr,
|  | ListASTNode * | entries
| ) |  |

protected

Iterates over the keyblob definition AST nodes.

Exceptions

  std::runtime_error | Various errors will cause this exception to be thrown. These include AST nodes being an unexpected type or expression not evaluating to integers.

void ConversionController::processOptions | ( | ListASTNode * | options | ) |

protected

Iterates over the option definition AST nodes. elftosb::Value objects are created for each option value and added to the option dictionary.

Exceptions

  std::runtime_error | Various errors will cause this exception to be thrown. These include AST nodes being an unexpected type or expression not evaluating to integers.

void ConversionController::processSources | ( | ListASTNode * | sources | ) |

protected

Exceptions

  std::runtime_error | Various errors will cause this exception to be thrown. These include AST nodes being an unexpected type or expression not evaluating to integers.

void ConversionController::run | ( |  | ) |

Process input files.

These steps are executed while running this method:

- The command file is parsed into an abstract syntax tree.
- The list of options is extracted.
- Constant expressions are evaluated.
- The list of source files is extracted and source file objects created.
- Section definitions are extracted.

This method does not produce any output. It processes the input files and builds a representation of the output in memory. Use the generateOutput() method to produce a BootImage object after this method returns.

Note
  This method is not reentrant. And in fact, the whole class is not designed to be reentrant.

Exceptions

  std::runtime_error | Any number of problems will cause this exception to be thrown.

See also
  parseCommandFile()
  processOptions()
  processConstants()
  processSources()
  processSections()

std::string * ConversionController::substituteVariables | ( | const std::string * | message | ) |

protected

Performs shell-like variable substitution on the string passed into it. Both sources and constants can be substituted. Sources will be replaced with their path and constants with their integer value. The syntax allows for some simple formatting for constants.

The syntax is mostly standard. A substitution begins with a dollar-sign and is followed by the source or constant name in parentheses. For instance, "$(mysource)" or "$(myconst)". The parentheses are always required.

Constant names can be prefixed by a single formatting character followed by a colon. The only formatting characters currently supported are 'd' for decimal and 'x' for hex. For example, "$(x:myconst)" will be replaced with the value of the constant named "myconst" formatted as hexadecimal. The default is decimal, so the 'd' formatting character isn't really ever needed.

Parameters

  message | The string to perform substitution on.

Returns
  Returns a newly allocated std::string object that has all substitutions replaced with the associated value. The caller is responsible for freeing the string object using the delete operator.

void ConversionController::testLexer | ( | ElftosbLexer & | lexer | ) |

protected

Exercises the lexer by printing out the value of every token produced by the lexer. It is assumed that the lexer object has already be configured to read from some input file. The method will return when the lexer has exhausted all tokens, or an error occurs.

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

- ConversionController.h
- ConversionController.cpp