com.oracle.objectfile.pecoff

Class PECoffUserDefinedSection

java.lang.Object

com.oracle.objectfile.ObjectFile.Element

com.oracle.objectfile.ObjectFile.Section

com.oracle.objectfile.pecoff.PECoffObjectFile.PECoffSection

com.oracle.objectfile.pecoff.PECoffUserDefinedSection

All Implemented Interfaces:

ElementImpl, ObjectFile.RelocatableSectionImpl

Direct Known Subclasses:

PECoffNobitsSection, PECoffProgbitsSection

public class PECoffUserDefinedSection
extends PECoffObjectFile.PECoffSection
implements ObjectFile.RelocatableSectionImpl

Clients defining their own kinds of section typically want to do so in a way that is agnostic w.r.t. PECoff, Mach-O or other object file formats. "User-defined section" means a section whose implementation delegates to an ElementImpl implementation. By implementing this interface, clients can breaks out of the PECoff class hierarchy and implement common functionality (e.g. DWARF debugging sections) in a format-agnostic way. PECoffUserDefinedSection is the glue layer that forwards calls to the ElementImpl.

Field Summary

Fields

Modifier and Type	Field and Description
protected ElementImpl	impl

Method Summary

Modifier and Type	Method and Description
LayoutDecisionMap	getDecisions(LayoutDecisionMap copyingIn)
Iterable<BuildDependency>	getDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions) Implementing this method allows to declare dependencies to other Sections (i.e.
ElementImpl	getImpl()
int	getMemSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided) Implement this method to provide the section size in memory (at runtime).
ObjectFile.Element	getOrCreateRelocationElement(boolean useImplicitAddend) Force the creation of a relocation section/element for this section, and return it.
byte[]	getOrDecideContent(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, byte[] contentHint) Implement this method to deliver the content of the section.
int	getOrDecideOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, int offsetHint) Implement this method to provide the offset this section should be placed at.
int	getOrDecideSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, int sizeHint) Implement this method to provide the size of this section.
int	getOrDecideVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided, int vaddrHint) Implement this method to provide the virtual address of this section.
ObjectFile.RelocationRecord	markRelocationSite(int offset, ByteBuffer bb, ObjectFile.RelocationKind k, String symbolName, boolean useImplicitAddend, Long explicitAddend) Record (in a format-specific way) that data at the given offset in the file, for the given number of bytes, should be fixed up according to the value of the given symbol and the given kind of relocation.
void	setImpl(ElementImpl impl)

Methods inherited from class com.oracle.objectfile.pecoff.PECoffObjectFile.PECoffSection

getEntrySize, getFlags, getLinkedInfo, getLinkedSection, getOwner, getRelocEntries, getSectionID, isLoadable, isReferenceable, setFlags, setRelocEntries, setSectionID

Methods inherited from class com.oracle.objectfile.ObjectFile.Element

getAlignment, getElement, getElementName, getName, setElement, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.oracle.objectfile.ElementImpl

getAlignment, getElement, isLoadable, isReferenceable, setElement

Field Detail

impl

protected ElementImpl impl

Method Detail

getImpl

public ElementImpl getImpl()

Specified by:

getImpl in class ObjectFile.Element

setImpl

public void setImpl(ElementImpl impl)

getDependencies

public Iterable<BuildDependency> getDependencies(Map<ObjectFile.Element,LayoutDecisionMap> decisions)

Description copied from interface: ElementImpl

Implementing this method allows to declare dependencies to other Sections (i.e. information about other sections needed to construct this section). The information will be used to construct the buildOrder in ObjectFile.writeInternal(). A good example can be found at: ELFObjectFile.ProgramHeaderTable.getDependencies

Specified by:

getDependencies in interface ElementImpl

getOrDecideOffset

public int getOrDecideOffset(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                             int offsetHint)

Description copied from interface: ElementImpl

Implement this method to provide the offset this section should be placed at.

Specified by:

getOrDecideOffset in interface ElementImpl

getOrDecideSize

public int getOrDecideSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                           int sizeHint)

Description copied from interface: ElementImpl

Implement this method to provide the size of this section.

Specified by:

getOrDecideSize in interface ElementImpl

getOrDecideContent

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

Description copied from interface: ElementImpl

Implement this method to deliver the content of the section.

Specified by:

getOrDecideContent in interface ElementImpl

getOrDecideVaddr

public int getOrDecideVaddr(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided,
                            int vaddrHint)

Description copied from interface: ElementImpl

Implement this method to provide the virtual address of this section. For loadable sections, this is where the section is expected to be mapped to at runtime (see ElementImpl.isLoadable()).

Specified by:

getOrDecideVaddr in interface ElementImpl

getMemSize

public int getMemSize(Map<ObjectFile.Element,LayoutDecisionMap> alreadyDecided)

Description copied from interface: ElementImpl

Implement this method to provide the section size in memory (at runtime).

Specified by:

getMemSize in interface ElementImpl

Overrides:

getMemSize in class ObjectFile.Element

getDecisions

public LayoutDecisionMap getDecisions(LayoutDecisionMap copyingIn)

Specified by:

getDecisions in interface ElementImpl

Specified by:

getDecisions in class ObjectFile.Element

getOrCreateRelocationElement

public ObjectFile.Element getOrCreateRelocationElement(boolean useImplicitAddend)

Description copied from interface: ObjectFile.RelocatableSectionImpl

Force the creation of a relocation section/element for this section, and return it. This is necessary to avoid the on-demand instantiation of relocation sections at write()-time, which leads to unpredictable results (e.g. not appearing in the ELF SHT, if the SHT was written before the section was created).

Specified by:

getOrCreateRelocationElement in interface ObjectFile.RelocatableSectionImpl

Parameters:

useImplicitAddend - whether the relocation section of interest is for implicit addends

Returns:

the element which will hold relocation records (of the argument-specified kind) for this section

markRelocationSite

public ObjectFile.RelocationRecord markRelocationSite(int offset,
                                                      ByteBuffer bb,
                                                      ObjectFile.RelocationKind k,
                                                      String symbolName,
                                                      boolean useImplicitAddend,
                                                      Long explicitAddend)

Description copied from interface: ObjectFile.RelocatableSectionImpl

Record (in a format-specific way) that data at the given offset in the file, for the given number of bytes, should be fixed up according to the value of the given symbol and the given kind of relocation. Depending on the object file format, kind of file, and target architecture, the available kinds of relocation and addend modes all vary considerably. Supporting a uniform interface is therefore complicated. In particular, the implementation of these methods somehow has to tell the caller how to fix up the section content, or fix it up itself. For example, ELF uses explicit addends for dynamic linking on x86-64, but Mach-O in the same case always uses implicit (inline) addends and cannot encode explicit addends. I can see two solutions. Firstly, the Mach-O implementation could come back to the caller saying "here is what you need to add to the current section contents". Or secondly, the section implementation could take care of it somehow, but that assumes it has access to the actual contents s.t. any changes will not later be clobbered. TODO: CHECK whether this is true of our native native image code.

Specified by:

markRelocationSite in interface ObjectFile.RelocatableSectionImpl

Parameters:

offset - the offset into the section contents of the beginning of the fixed-up bytes

bb - the byte buffer representing the encoded section contents, at least as far as offset + length bytes

k - the kind of fixup to be applied

symbolName - the name of the symbol whose value is used to compute the fixed-up bytes

useImplicitAddend - whether the current bytes are to be used as an addend

explicitAddend - a full-width addend, or null if useImplicitAddend is true

Returns:

the relocation record created (or found, if it exists already)