IRBuilder.h revision 22add6ff3426df1a85089fe6a6e1597ee3b6f300
1//===- IRBuilder.h --------------------------------------------------------===// 2// 3// The MCLinker Project 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9// 10// IRBuilder is a class used as a convenient way to create MCLinker sections 11// with a consistent and simplified interface. 12// 13//===----------------------------------------------------------------------===// 14#ifndef MCLD_IRBUILDER_H 15#define MCLD_IRBUILDER_H 16 17#include <mcld/MC/MCLDInput.h> 18#include <mcld/MC/InputBuilder.h> 19 20#include <mcld/LD/LDSection.h> 21#include <mcld/LD/EhFrame.h> 22 23#include <mcld/Fragment/Fragment.h> 24#include <mcld/Fragment/Relocation.h> 25#include <mcld/Fragment/RegionFragment.h> 26#include <mcld/Fragment/FillFragment.h> 27 28#include <mcld/Support/Path.h> 29#include <mcld/Support/FileHandle.h> 30#include <mcld/Support/raw_mem_ostream.h> 31 32namespace mcld { 33 34class Module; 35class LinkerConfig; 36class InputTree; 37 38/** \class IRBuilder 39 * \brief IRBuilder provides an uniform API for creating sections and 40 * inserting them into a input file. 41 * 42 * Ahead-of-time virtual machines (VM) usually compiles an intermediate 43 * language into a system-dependent binary. IRBuilder helps such kind of VMs 44 * to emit binaries in native object format, such as ELF or MachO. 45 */ 46class IRBuilder 47{ 48public: 49 enum ObjectFormat { 50 ELF, 51 MachO, 52 COFF 53 }; 54 55public: 56 IRBuilder(Module& pModule, const LinkerConfig& pConfig); 57 58 ~IRBuilder(); 59 60 const InputBuilder& getInputBuilder() const { return m_InputBuilder; } 61 InputBuilder& getInputBuilder() { return m_InputBuilder; } 62 63/// @} 64/// @name Input Files On The Command Line 65/// @{ 66 67 /// CreateInput - To create an input file and append it to the input tree. 68 /// This function is like to add an input file in the command line. 69 /// 70 /// There are four types of the input files: 71 /// - relocatable objects, 72 /// - shared objects, 73 /// - archives, 74 /// - and user-defined objects. 75 /// 76 /// If Input::Unknown type is given, MCLinker will automatically 77 /// open and read the input file, and create sections of the input. Otherwise, 78 /// users need to manually create sections by IRBuilder. 79 /// 80 /// @see mcld::Input 81 /// 82 /// @param pName [in] The name of the input file. 83 /// @param pPath [in] The path of the input file. 84 /// @param pType [in] The type of the input file. MCLinker will parse the 85 /// input file to create sections only if pType is 86 /// Input::Unknown. 87 /// @return the created mcld::Input. 88 Input* CreateInput(const std::string& pName, 89 const sys::fs::Path& pPath, 90 Input::Type pType); 91 92 /// ReadInput - To read an input file and append it to the input tree. 93 /// This function is like to add an input file in the command line. 94 /// 95 /// This funciton is equal to call 96 /// @ref IRBuilder::CreateInput(pName, pPath, Input::Unknown); 97 /// 98 /// MCLinker will automatically open and read the input file, and create 99 /// sections of the input. 100 /// 101 /// @see mcld::Input 102 /// 103 /// @param pName [in] The name of the input file. 104 /// @param pPath [in] The path of the input file. 105 /// @return the created mcld::Input. 106 Input* ReadInput(const std::string& pName, const sys::fs::Path& pPath); 107 108 /// ReadInput - To read an input file and append it to the input tree. 109 /// 110 /// This function is equal to -l option. This function tells MCLinker to 111 /// search for lib[pNameSpec].so or lib[pNameSpec].a in the search path. 112 /// 113 /// @param pNameSpec [in] The namespec of the input file. 114 /// @return the created mcld::Input. 115 Input* ReadInput(const std::string& pNameSpec); 116 117 /// ReadInput - To read an input file and append it to the input tree. 118 /// 119 /// This function is like to add an input in the command line. 120 /// 121 /// LLVM compiler usually emits outputs by llvm::raw_ostream. 122 /// mcld::raw_mem_ostream inherits llvm::raw_ostream and is suitable to be 123 /// the output of LLVM compier. Users can connect LLVM compiler and MCLinker 124 /// by passing mcld::raw_mem_ostream from LLVM compiler to MCLinker. 125 /// 126 /// @param pMemOStream [in] The input raw_mem_stream 127 /// @param the create mcld::Input. 128 Input* ReadInput(raw_mem_ostream& pMemOStream); 129 130 /// ReadInput - To read an input file and append it to the input tree. 131 /// Another way to open file manually. Use MCLinker's mcld::FileHandle. 132 Input* ReadInput(FileHandle& pFileHandle); 133 134 /// ReadInput - To read an input file and append it to the input tree. 135 /// 136 /// This function is like to add an input in the command line. 137 /// 138 /// This function tells MCLinker to read pRawMemory as an image of an object 139 /// file. So far, MCLinekr only supports ELF object format, but it will 140 /// support various object formats in the future. MCLinker relies triple to 141 /// know the object format of pRawMemory. 142 /// @param [in] pName The name of the input file 143 /// @param [in] pRawMemory An image of object file 144 /// @param [in] pSize The size of the memory 145 /// @return The created mcld::Input 146 Input* ReadInput(const std::string& pName, void* pRawMemory, size_t pSize); 147 148 /// StartGroup - Add an opening tag of group. 149 /// 150 /// This function is equal to --start-group option. This function tells 151 /// MCLinker to create a new archive group and to add the following archives 152 /// in the created group. The archives in a group are searched repeatedly 153 /// until no new undefined references are created. 154 bool StartGroup(); 155 156 /// EndGroup - Add a closing tag of group. 157 /// 158 /// This function is equal to --end-group option. This function tells 159 /// MCLinker to stop adding following archives in the created group. 160 bool EndGroup(); 161 162/// @} 163/// @name Positional Options On The Command Line 164/// @{ 165 166 /// WholeArchive - Append a --whole-archive option on the command line 167 /// 168 /// This function is equal to --whole-archive option. This function tells 169 /// MCLinker to include every object files in the following archives. 170 void WholeArchive(); 171 172 /// NoWholeArchive - Append a --no-whole-archive option on the command line. 173 /// 174 /// This function is equal to --no-whole-archive option. This function tells 175 /// MCLinker to stop including every object files in the following archives. 176 /// Only used object files in the following archives are included. 177 void NoWholeArchive(); 178 179 /// AsNeeded - Append a --as-needed option on the command line. 180 /// 181 /// This function is equal to --as-needed option. This function tells 182 /// MCLinker to not add a DT_NEEDED tag in .dynamic sections for the 183 /// following shared objects that are not really used. MCLinker will add tags 184 // only for the following shared objects which is really used. 185 void AsNeeded(); 186 187 /// NoAsNeeded - Append a --no-as-needed option on the command line. 188 /// 189 /// This function is equal to --no-as-needed option. This function tells 190 /// MCLinker to add a DT_NEEDED tag in .dynamic section for every shared 191 /// objects that is created after this option. 192 void NoAsNeeded(); 193 194 /// CopyDTNeeded - Append a --add-needed option on the command line. 195 /// 196 /// This function is equal to --add-needed option. This function tells 197 /// NCLinker to copy all DT_NEEDED tags of every following shared objects 198 /// to the output file. 199 void CopyDTNeeded(); 200 201 /// NoCopyDTNeeded - Append a --no-add-needed option on the command line. 202 /// 203 /// This function is equal to --no-add-needed option. This function tells 204 /// MCLinker to stop copying all DT_NEEDS tags in the following shared 205 /// objects to the output file. 206 void NoCopyDTNeeded(); 207 208 /// AgainstShared - Append a -Bdynamic option on the command line. 209 /// 210 /// This function is equal to -Bdynamic option. This function tells MCLinker 211 /// to search shared objects before archives for the following namespec. 212 void AgainstShared(); 213 214 /// AgainstStatic - Append a -static option on the command line. 215 /// 216 /// This function is equal to -static option. This function tells MCLinker to 217 /// search archives before shared objects for the following namespec. 218 void AgainstStatic(); 219 220/// @} 221/// @name Input Methods 222/// @{ 223 224 /// CreateELFHeader - To create and append a section header in the input file 225 /// 226 /// @param OF [in] The file format. @see ObjectFormat 227 /// @param pInput [in, out] The input file. 228 /// @param pName [in] The name of the section. 229 /// @param pType [in] The meaning of the content in the section. The 230 /// value is format-dependent. In ELF, the value is 231 /// SHT_* in normal. 232 /// @param pFlag [in] The format-dependent flag. In ELF, the value is 233 /// SHF_* in normal. 234 /// @param pAlign [in] The alignment constraint of the section 235 /// @return The created section header. 236 static LDSection* CreateELFHeader(Input& pInput, 237 const std::string& pName, 238 uint32_t pType, 239 uint32_t pFlag, 240 uint32_t pAlign); 241 242 /// CreateSectionData - To create a section data for given pSection. 243 /// @param [in, out] pSection The given LDSection. It can be in either an 244 /// input or the output. 245 /// pSection.getSectionData() is set to a valid section data. 246 /// @return The created section data. If the pSection already has section 247 /// data, or if the pSection's type should not have a section data 248 /// (.eh_frame or relocation data), then an assertion occurs. 249 static SectionData* CreateSectionData(LDSection& pSection); 250 251 /// CreateRelocData - To create a relocation data for given pSection. 252 /// @param [in, out] pSection The given LDSection. It can be in either an 253 /// input or the output. 254 /// pSection.getRelocData() is set to a valid relocation data. 255 /// @return The created relocation data. If the pSection already has 256 /// relocation data, or if the pSection's type is not 257 /// LDFileFormat::Relocation, then an assertion occurs. 258 static RelocData* CreateRelocData(LDSection &pSection); 259 260 /// CreateEhFrame - To create a eh_frame for given pSection 261 /// @param [in, out] pSection The given LDSection. It can be in either an 262 /// input or the output. 263 /// pSection.getEhFrame() is set to a valid eh_frame. 264 /// @return The created eh_frame. If the pSection already has eh_frame data, 265 /// or if the pSection's type is not LDFileFormat::EhFrame, then an 266 /// assertion occurs. 267 static EhFrame* CreateEhFrame(LDSection& pSection); 268 269 /// CreateBSS - To create a bss section for given pSection 270 /// @param [in, out] pSection The given LDSection. It can be in either an 271 /// input or the output. 272 /// pSection.getSectionData() is set to a valid section data and 273 /// contains a fillment fragment whose size is pSection.size(). 274 /// @return The create section data. It the pSection already has a section 275 /// data, or if the pSection's type is not LDFileFormat::BSS, then 276 /// an assertion occurs. 277 static SectionData* CreateBSS(LDSection& pSection); 278 279 /// CreateRegion - To create a region fragment in the input file. 280 /// This function tells MCLinker to read a piece of data from the input 281 /// file, and to create a region fragment that carries the data. The data 282 /// will be deallocated automatically when pInput is destroyed. 283 /// 284 /// @param pInput [in, out] The input file. 285 /// @param pOffset [in] The starting file offset of the data 286 /// @param pLength [in] The number of bytes of the data 287 /// @return If pLength is zero or failing to request a region, return a 288 /// FillFragment. 289 static Fragment* CreateRegion(Input& pInput, size_t pOffset, size_t pLength); 290 291 /// CreateRegion - To create a region fragment wrapping the given memory. 292 /// This function tells MCLinker to create a region fragment by the data 293 /// directly. Since the data is given from outside, not read from the input 294 /// file, users should deallocated the data manually. 295 /// 296 /// @param pMemory [in] The start address of the given data 297 /// @param pLength [in] The number of bytes of the data 298 /// @return If pLength is zero or failing to request a region, return a 299 /// FillFragment. 300 static Fragment* CreateRegion(void* pMemory, size_t pLength); 301 302 /// AppendFragment - To append pFrag to the given SectionData pSD. 303 /// This function tells MCLinker to append a fragment to section data, and 304 /// update size of the section header. 305 /// 306 /// @note In order to keep the alignment of pFrag, This function inserts an 307 /// AlignFragment before pFrag if the section header's alignment is larger 308 /// than 1. 309 /// @note This function does not update offset of section headers. 310 /// 311 /// @param pFrag [in, out] The appended fragment. Its offset is set as the 312 /// section offset in pSD. 313 /// @param pSD [in, out] The section data. Size of the header is also 314 /// updated. 315 /// @return Total size of the inserted fragments. 316 static uint64_t AppendFragment(Fragment& pFrag, SectionData& pSD); 317 318 /// AppendRelocation - To append a relocation to a relocation data. 319 /// This function tells MCLinker to add a general relocation to the 320 /// relocation data. This function does not update offset and size of section 321 /// headers. 322 /// 323 /// @param pReloc [in] The appended relocation. 324 /// @param pRD [in, out] The relocation data being appended. 325 static void AppendRelocation(Relocation& pRelocation, RelocData& pRD); 326 327 /// AppendEhFrame - To append a fragment to a EhFrame. 328 /// @note In order to keep the alignment of pFrag, This function inserts an 329 /// AlignFragment before pFrag if the section header's alignment is larger 330 /// than 1. 331 /// @note This function also update size of the section header, but does not 332 /// update header's offset. 333 /// 334 /// @param pFrag [in, out] The appended fragment. 335 /// @param pEhFrame [in, out] The EhFrame. 336 /// @return Total size of the inserted fragments. 337 static uint64_t AppendEhFrame(Fragment& pFrag, EhFrame& pEhFrame); 338 339 /// AppendEhFrame - To append a FDE to the given EhFrame pEhFram. 340 /// @note In order to keep the alignment of pFrag, This function inserts an 341 /// AlignFragment before pFrag if the section header's alignment is larger 342 /// than 1. 343 /// @note This function also update size of the section header, but does not 344 /// update header's offset. 345 /// 346 /// @param [in, out] pFDE The appended FDE entry. 347 /// @param [in, out] pEhFrame The eh_frame being appended. 348 /// @return Total size of the inserted fragments. 349 static uint64_t AppendEhFrame(EhFrame::FDE& pFDE, EhFrame& pEhFrame); 350 351 /// AppendEhFrame - To append a CIE to the given EhFrame pEhFram. 352 /// @note In order to keep the alignment of pFrag, This function inserts an 353 /// AlignFragment before pFrag if the section header's alignment is larger 354 /// than 1. 355 /// @note This function also update size of the section header, but does not 356 /// update header's offset. 357 /// 358 /// @param [in, out] pCIE The appended CIE entry. 359 /// @param [in, out] pEhFrame The eh_frame being appended. 360 /// @return Total size of the inserted fragments. 361 static uint64_t AppendEhFrame(EhFrame::CIE& pCIE, EhFrame& pEhFrame); 362 363private: 364 Module& m_Module; 365 const LinkerConfig& m_Config; 366 367 InputBuilder m_InputBuilder; 368}; 369 370} // end of namespace mcld 371 372#endif 373