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

#include <ConversionController.h>

Inheritance diagram for elftosb::ConversionController:

Collaboration diagram for elftosb::ConversionController:

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:

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:

Possible load target node types:

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.

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:

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

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation