com.oracle.objectfile

Class ObjectFile

java.lang.Object

com.oracle.objectfile.ObjectFile

Direct Known Subclasses:

ELFObjectFile, MachOObjectFile, PECoffObjectFile

public abstract class ObjectFile
extends Object

Abstract superclass for object files. An object file is a binary container for sections, including DWARF debug sections. The currently supported file formats are ELF and Mach-O. In contrast to most object file libraries, we make a strong separation between the logical contents of a file and the details of its layout on disk. ObjectFile only explicitly models the logical contents; layout decisions (offsets, ordering) are modelled separately (see LayoutDecision), being computed on write-out (see WriteLayout).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ObjectFile.Element All headers and sections are subclasses of ObjectFile.Element.
static class	ObjectFile.ElementComparatorByDecidedOffset
static class	ObjectFile.Format
class	ObjectFile.Header
static class	ObjectFile.IntegerDecisionComparator
static interface	ObjectFile.NobitsSectionImpl
static interface	ObjectFile.ProgbitsSectionImpl Abstract notions of section.
static interface	ObjectFile.RelocatableSectionImpl
static class	ObjectFile.RelocationKind
static interface	ObjectFile.RelocationMethod Interface implemented by objects implementing a specific relocation method and size.
static interface	ObjectFile.RelocationRecord Interface for objects representing relocation sites in an object file's contents.
static interface	ObjectFile.RelocationSiteInfo
class	ObjectFile.Section
static interface	ObjectFile.Segment
static class	ObjectFile.SizeTiebreakComparator
static interface	ObjectFile.Symbol An abstraction of symbols within object files.
static interface	ObjectFile.ValueEnum An interface for power-of-two values.

Field Summary

Fields

Modifier and Type	Field and Description
protected ElementList	elements
protected Map<ObjectFile.Element,String>	nameForElement

Constructor Summary

Constructors

Constructor and Description
ObjectFile(int pageSize)

Method Summary

Modifier and Type	Method and Description
protected static Iterable<LayoutDecision>	allDecisions(Map<ObjectFile.Element,LayoutDecisionMap> decisions)
int	bake(List<ObjectFile.Element> sortedObjectFileElements)
static HashSet<BuildDependency>	basicDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions, ObjectFile.Element el, boolean sizeOnContent, boolean vaddrOnOffset)
abstract ObjectFile.Symbol	createDefinedSymbol(String name, ObjectFile.Element baseSection, long position, int size, boolean isCode, boolean isGlobal)
protected ElementList	createElementList()
static ObjectFile	createRuntimeDebugInfo(int pageSize)
protected abstract SymbolTable	createSymbolTable()
abstract ObjectFile.Symbol	createUndefinedSymbol(String name, int size, boolean isCode)
void	debugContext(String scopeName, Consumer<org.graalvm.compiler.debug.DebugContext> action) Allows a consumer to retrieve the debug context currently bound to this object file.
protected static Iterable<LayoutDecision>	decisionsByKind(LayoutDecision.Kind kind, Map<ObjectFile.Element,LayoutDecisionMap> decisions)
static LayoutDecisionMap	defaultDecisions(ObjectFile.Element e, LayoutDecisionMap copyingIn)
static HashSet<BuildDependency>	defaultDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions, ObjectFile.Element el)
static <T> T	defaultGetOrDecide(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, ObjectFile.Element el, LayoutDecision.Kind k, T hint)
static byte[]	defaultGetOrDecideContent(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, ObjectFile.Element el, byte[] contentHint)
static int	defaultGetOrDecideOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, ObjectFile.Element el, int offsetHint)
static int	defaultGetOrDecideSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, ObjectFile.Element el, int sizeHint)
static int	defaultGetOrDecideVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, ObjectFile.Element el, int vaddrHint)
ObjectFile.Element	elementForName(String s)
protected boolean	elementsCanSharePage(ObjectFile.Element s1, ObjectFile.Element s2, int offset1, int offset2) Returns whether, according to the semantics of the object file, two sections could reasonably both be placed (partially) on the same page-sized region of virtual memory.
protected Iterable<ObjectFile.Element>	elementsMappedOnPage(long vaddr, Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided)
ObjectFile.Segment	findSegmentByName(String name)
static <E extends Enum<E> & ObjectFile.ValueEnum> long	flagSetAsLong(EnumSet<E> flags) Create a long integer representation of an EnumSet of bitflags.
static <E extends Enum<E> & ObjectFile.ValueEnum> EnumSet<E>	flagSetFromLong(long flags, Class<E> clazz) Create an EnumSet representation of a long integer encoding a set of bitflags.
abstract ByteOrder	getByteOrder()
Map<ObjectFile.Element,LayoutDecisionMap>	getDecisionsByElement()
Map<ObjectFile.Element,LayoutDecisionMap>	getDecisionsTaken()
List<ObjectFile.Element>	getElements()
static String	getFilenameSuffix()
abstract ObjectFile.Format	getFormat()
ObjectFile.Header	getHeader()
protected abstract int	getMinimumFileSize()
static ObjectFile.Format	getNativeFormat()
static ObjectFile	getNativeObjectFile(int pageSize)
ObjectFile.Element	getOffsetBootstrapElement() Something of a HACK: we require that all ObjectFiles tell the build process one element whose offset will be decided first.
protected abstract ObjectFile.Segment	getOrCreateSegment(String maybeSegmentName, String sectionName, boolean writable, boolean executable) Return a Segment object which is appropriate for containing a section of the given name, if such a segment is mandatory according to the object file format specification.
SymbolTable	getOrCreateSymbolTable()
int	getPageSize()
int	getPageSizeShift()
List<ObjectFile.Section>	getSections()
abstract Set<ObjectFile.Segment>	getSegments()
abstract SymbolTable	getSymbolTable()
abstract int	getWordSizeInBytes()
protected static int	greatestCommonDivisor(int arg1, int arg2)
protected int	initialVaddr()
void	installDebugInfo(DebugInfoProvider debugInfoProvider) API method provided to allow a native image generator to provide details of types, code and heap data inserted into a native image.
protected static int	lowestCommonMultiple(int arg1, int arg2)
protected static List<LayoutDecision>	maximalDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, LayoutDecision.Kind k, Comparator<LayoutDecision> cmp)
protected static List<LayoutDecision>	minimalDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, LayoutDecision.Kind k, Comparator<LayoutDecision> cmp)
static HashSet<BuildDependency>	minimalDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions, ObjectFile.Element el)
String	nameForElement(ObjectFile.Element e)
ObjectFile.Section	newDebugSection(String name, ElementImpl impl)
abstract ObjectFile.Section	newNobitsSection(ObjectFile.Segment segment, String name, ObjectFile.NobitsSectionImpl impl)
ObjectFile.Section	newNobitsSection(String name, ObjectFile.NobitsSectionImpl impl)
abstract ObjectFile.Section	newProgbitsSection(ObjectFile.Segment segment, String name, int alignment, boolean writable, boolean executable, ObjectFile.ProgbitsSectionImpl impl)
ObjectFile.Section	newProgbitsSection(String name, int alignment, boolean writable, boolean executable, ObjectFile.ProgbitsSectionImpl impl)
abstract ObjectFile.Section	newUserDefinedSection(ObjectFile.Segment segment, String name, int alignment, ElementImpl impl) Create a new section for holding user data.
ObjectFile.Section	newUserDefinedSection(String name, ElementImpl impl)
protected static int	nextAvailableOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided)
protected static int	nextAvailableVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, int base, int defaultValue)
static int	nextIntegerMultiple(int start, int multipleOf)
static int	nextIntegerMultipleWithCongruence(int start, int multipleOf, int congruentTo, int modulo)
int	roundUpToPageSize(int x)
abstract void	setByteOrder(ByteOrder byteOrder)
abstract boolean	shouldRecordDebugRelocations() Determines whether references between debug sections should be recorded for relocation.
protected static List<LayoutDecision>	sortedDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, LayoutDecision.Kind k, Comparator<LayoutDecision> cmp)
void	withDebugContext(org.graalvm.compiler.debug.DebugContext context, String scopeName, Runnable task) Allows a task to be executed with a debug context in a named subscope bound to the object file and accessible to code executed during the lifetime of the task.
void	write(FileChannel outputChannel)
void	writeBuffer(List<ObjectFile.Element> sortedObjectFileElements, ByteBuffer out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

elements

protected final ElementList elements

nameForElement

protected final Map<ObjectFile.Element,String> nameForElement

Constructor Detail

ObjectFile

public ObjectFile(int pageSize)

Method Detail

getFormat

public abstract ObjectFile.Format getFormat()

flagSetAsLong

public static <E extends Enum<E> & ObjectFile.ValueEnum> long flagSetAsLong(EnumSet<E> flags)

Create a long integer representation of an EnumSet of bitflags.

Parameters:

flags - an EnumSet of flag elements, which must be an enum implementing PowerOfTwoValued

Returns:

a long integer value encoding the same set

flagSetFromLong

public static <E extends Enum<E> & ObjectFile.ValueEnum> EnumSet<E> flagSetFromLong(long flags,
                                                                                    Class<E> clazz)

Create an EnumSet representation of a long integer encoding a set of bitflags.

Parameters:

flags - the long integer encoding the set of flags

clazz - the enum class (implementing PowerOfTwoValued) representing elements of the set

Returns:

the set encoded by the long integer argument

getByteOrder

public abstract ByteOrder getByteOrder()

setByteOrder

public abstract void setByteOrder(ByteOrder byteOrder)

initialVaddr

protected int initialVaddr()

getFilenameSuffix

public static String getFilenameSuffix()

getNativeFormat

public static ObjectFile.Format getNativeFormat()

getNativeObjectFile

public static ObjectFile getNativeObjectFile(int pageSize)

createRuntimeDebugInfo

public static ObjectFile createRuntimeDebugInfo(int pageSize)

getOrCreateSegment

protected abstract ObjectFile.Segment getOrCreateSegment(String maybeSegmentName,
                                                         String sectionName,
                                                         boolean writable,
                                                         boolean executable)

Return a Segment object which is appropriate for containing a section of the given name, if such a segment is mandatory according to the object file format specification. Otherwise, return null.

Parameters:

maybeSegmentName - either null, or the name of a segment which the caller would prefer should contain the given section (in the case where multiple names would be possible for the created segment, so the choice would be ambiguous)

sectionName - a platform-dependent section name

writable - whether the segment contents should be writable

executable - whether the segment contents should be executable

Returns:

the segment object, or null if no such segment is necessary

newUserDefinedSection

public abstract ObjectFile.Section newUserDefinedSection(ObjectFile.Segment segment,
                                                         String name,
                                                         int alignment,
                                                         ElementImpl impl)

Create a new section for holding user data. By default this creates a "regular" a.k.a. "progbits" section, that actually contains data. The object returned is an instance of some format-specific class, taking care of format details. The format-agnostic behavior of the section is specified by an ElementImpl which the user supplies.

Parameters:

segment -

name -

impl -

Returns:

a Section

newProgbitsSection

public abstract ObjectFile.Section newProgbitsSection(ObjectFile.Segment segment,
                                                      String name,
                                                      int alignment,
                                                      boolean writable,
                                                      boolean executable,
                                                      ObjectFile.ProgbitsSectionImpl impl)

newNobitsSection

public abstract ObjectFile.Section newNobitsSection(ObjectFile.Segment segment,
                                                    String name,
                                                    ObjectFile.NobitsSectionImpl impl)

newUserDefinedSection

public ObjectFile.Section newUserDefinedSection(String name,
                                                ElementImpl impl)

newDebugSection

public ObjectFile.Section newDebugSection(String name,
                                          ElementImpl impl)

newProgbitsSection

public ObjectFile.Section newProgbitsSection(String name,
                                             int alignment,
                                             boolean writable,
                                             boolean executable,
                                             ObjectFile.ProgbitsSectionImpl impl)

newNobitsSection

public ObjectFile.Section newNobitsSection(String name,
                                           ObjectFile.NobitsSectionImpl impl)

findSegmentByName

public ObjectFile.Segment findSegmentByName(String name)

nextIntegerMultiple

public static int nextIntegerMultiple(int start,
                                      int multipleOf)

nextIntegerMultipleWithCongruence

public static int nextIntegerMultipleWithCongruence(int start,
                                                    int multipleOf,
                                                    int congruentTo,
                                                    int modulo)

greatestCommonDivisor

protected static int greatestCommonDivisor(int arg1,
                                           int arg2)

lowestCommonMultiple

protected static int lowestCommonMultiple(int arg1,
                                          int arg2)

nextAvailableVaddr

protected static int nextAvailableVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                        int base,
                                        int defaultValue)

maximalDecisionValues

protected static List<LayoutDecision> maximalDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                                            LayoutDecision.Kind k,
                                                            Comparator<LayoutDecision> cmp)

minimalDecisionValues

protected static List<LayoutDecision> minimalDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                                            LayoutDecision.Kind k,
                                                            Comparator<LayoutDecision> cmp)

sortedDecisionValues

protected static List<LayoutDecision> sortedDecisionValues(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                                           LayoutDecision.Kind k,
                                                           Comparator<LayoutDecision> cmp)

nextAvailableOffset

protected static int nextAvailableOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided)

getWordSizeInBytes

public abstract int getWordSizeInBytes()

shouldRecordDebugRelocations

public abstract boolean shouldRecordDebugRelocations()

Determines whether references between debug sections should be recorded for relocation.

basicDependencies

public static HashSet<BuildDependency> basicDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions,
                                                         ObjectFile.Element el,
                                                         boolean sizeOnContent,
                                                         boolean vaddrOnOffset)

minimalDependencies

public static HashSet<BuildDependency> minimalDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions,
                                                           ObjectFile.Element el)

defaultDependencies

public static HashSet<BuildDependency> defaultDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions,
                                                           ObjectFile.Element el)

defaultGetOrDecide

public static <T> T defaultGetOrDecide(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                       ObjectFile.Element el,
                                       LayoutDecision.Kind k,
                                       T hint)

defaultGetOrDecideOffset

public static int defaultGetOrDecideOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                           ObjectFile.Element el,
                                           int offsetHint)

defaultGetOrDecideContent

public static byte[] defaultGetOrDecideContent(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                               ObjectFile.Element el,
                                               byte[] contentHint)

defaultGetOrDecideSize

public static int defaultGetOrDecideSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                         ObjectFile.Element el,
                                         int sizeHint)

defaultGetOrDecideVaddr

public static int defaultGetOrDecideVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                                          ObjectFile.Element el,
                                          int vaddrHint)

defaultDecisions

public static LayoutDecisionMap defaultDecisions(ObjectFile.Element e,
                                                 LayoutDecisionMap copyingIn)

elementsCanSharePage

protected boolean elementsCanSharePage(ObjectFile.Element s1,
                                       ObjectFile.Element s2,
                                       int offset1,
                                       int offset2)

Returns whether, according to the semantics of the object file, two sections could reasonably both be placed (partially) on the same page-sized region of virtual memory. Usually this means accounting for segment-level permissions/flags, as well as the physical layout of the file.

Parameters:

s1 - one section

s2 - another section

installDebugInfo

public void installDebugInfo(DebugInfoProvider debugInfoProvider)

API method provided to allow a native image generator to provide details of types, code and heap data inserted into a native image.

Parameters:

debugInfoProvider - an implementation of the provider interface that communicates details of the relevant types, code and heap data.

allDecisions

protected static Iterable<LayoutDecision> allDecisions(Map<ObjectFile.Element,LayoutDecisionMap> decisions)

decisionsByKind

protected static Iterable<LayoutDecision> decisionsByKind(LayoutDecision.Kind kind,
                                                          Map<ObjectFile.Element,LayoutDecisionMap> decisions)

getDecisionsTaken

public Map<ObjectFile.Element,LayoutDecisionMap> getDecisionsTaken()

elementsMappedOnPage

protected Iterable<ObjectFile.Element> elementsMappedOnPage(long vaddr,
                                                            Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided)

createElementList

protected ElementList createElementList()

getElements

public List<ObjectFile.Element> getElements()

elementForName

public ObjectFile.Element elementForName(String s)

nameForElement

public String nameForElement(ObjectFile.Element e)

getSections

public List<ObjectFile.Section> getSections()

getSegments

public abstract Set<ObjectFile.Segment> getSegments()

getHeader

public ObjectFile.Header getHeader()

Returns:

a platform-dependent ObjectFile.Header. Depending on the mode of the object file (read or write), the header is newly created or read from the buffer.

getOffsetBootstrapElement

public ObjectFile.Element getOffsetBootstrapElement()

Something of a HACK: we require that all ObjectFiles tell the build process one element whose offset will be decided first. It is an error if this element's OFFSET decision depends on any other offset decision.

write

public final void write(FileChannel outputChannel)

bake

public int bake(List<ObjectFile.Element> sortedObjectFileElements)

getDecisionsByElement

public Map<ObjectFile.Element,LayoutDecisionMap> getDecisionsByElement()

writeBuffer

public void writeBuffer(List<ObjectFile.Element> sortedObjectFileElements,
                        ByteBuffer out)

getMinimumFileSize

protected abstract int getMinimumFileSize()

getPageSize

public int getPageSize()

getPageSizeShift

public int getPageSizeShift()

roundUpToPageSize

public int roundUpToPageSize(int x)

createDefinedSymbol

public abstract ObjectFile.Symbol createDefinedSymbol(String name,
                                                      ObjectFile.Element baseSection,
                                                      long position,
                                                      int size,
                                                      boolean isCode,
                                                      boolean isGlobal)

createUndefinedSymbol

public abstract ObjectFile.Symbol createUndefinedSymbol(String name,
                                                        int size,
                                                        boolean isCode)

createSymbolTable

protected abstract SymbolTable createSymbolTable()

getSymbolTable

public abstract SymbolTable getSymbolTable()

getOrCreateSymbolTable

public final SymbolTable getOrCreateSymbolTable()

withDebugContext

public void withDebugContext(org.graalvm.compiler.debug.DebugContext context,
                             String scopeName,
                             Runnable task)

Allows a task to be executed with a debug context in a named subscope bound to the object file and accessible to code executed during the lifetime of the task. Invoked code may obtain access to the debug context using method ObjectFile.debugContext.

Parameters:

context - a context to be bound to the object file for the duration of the task execution.

scopeName - a name to be used to define a subscope current while the task is being executed.

task - a task to be executed while the context is bound to the object file.

debugContext

public void debugContext(String scopeName,
                         Consumer<org.graalvm.compiler.debug.DebugContext> action)

Allows a consumer to retrieve the debug context currently bound to this object file. This method must only called underneath an invocation of method ObjectFile.withDebugContext(org.graalvm.compiler.debug.DebugContext, java.lang.String, java.lang.Runnable).

Parameters:

scopeName - a name to be used to define a subscope current while the consumer is active.

action - an action parameterised by the debug context.