llvm-ifs - shared object stubbing tool

概要

llvm-ifs [選項] 輸入

描述

llvm-ifs 是一個工具，可以從 ELF shared object 或 text-based stub 共同產生人類可讀的 text-based stub (.ifs 檔案) 以及可連結的 shared object stub (.so 檔案)。text-based stub 適用於監控 shared object 的 ABI 變更。可連結的 shared object stub 可用於避免在共享函式的 ABI 沒有變更時進行不必要的重新連結。

IFS 格式

以下是由 llvm-ifs 產生的 shared object text representation (IFS) 範例

--- !ifs-v1
IFSVersion: 3.0
SoName: libtest.so /* Optional */
Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
NeededLibs:
  - libc.so.6
Symbols:
  - { Name: sym0, Type: Notype }
  - { Name: sym1, Type: Object, Size: 0 }
  - { Name: sym2, Type: Func, Weak: false }
  - { Name: sym3, Type: TLS }
  - { Name: sym4, Type: Unknown, Warning: foo }
...

  • IFSVersion：IFS 檔案的版本，用於讀取器相容性。

  • SoName (選用)：正在 stubbed 的 shared object 檔案名稱。

  • Target (選用)：此 shared object 的架構、endianness 和 bitwise 資訊。它可以是明確的格式或隱含的 LLVM triple 格式。它可以是選用的，並且可以從命令行選項中覆寫。

  • NeededLibs：此函式庫相依的外部 shared object 列表。

  • Symbols：每個符號連結物件所需的所有資料集合，依名稱升序排序。

    • Name：符號名稱。

    • Type：符號是物件、函式、no-type、thread local storage 或 unknown。不明確支援的符號類型會映射為 unknown，以提高訊號雜訊比。

    • Size：相關符號的大小，不適用於函式，對於 NoType 符號是選用的。

    • Undefined：符號是否在此 shared object 檔案中定義。

    • Weak：符號是否應被視為 weak。

    • Warning (選用)：當連結此符號時輸出的警告文字。

此基於 YAML 的 text 格式包含產生可連結的 ELF shared object 以及 Apple TAPI 格式檔案所需的一切。符號的順序已排序，因此可以使用 diff 工具輕鬆比較這些檔案。如果檔案內容變更，則表示可能發生 ABI 破壞性變更。

ELF STUB 格式

linker 可以使用的最小 ELF 檔案應正確填入以下 section

  • ELF 標頭。

  • Section 標頭。

  • Dynamic symbol table (.dynsym section)。

  • Dynamic string table (.dynstr section)。

  • Dynamic table (.dynamic section)。

    • DT_SYMTAB 條目。

    • DT_STRTAB 條目。

    • DT_STRSZ 條目。

    • DT_NEEDED 條目。（選用）

    • DT_SONAME 條目。（選用）

  • Section header string table (.shstrtab section)

此 ELF 檔案可能與依賴 program header 的 ELF 分析工具存在相容性問題。像 LLD 這樣的 Linker 可以使用這種最小 ELF 檔案正常工作，而不會發生錯誤。

選項

--input-format=[IFS|ELF|OtherObjectFileFormats]

指定輸入檔案格式。目前僅支援 text IFS 檔案和 ELF shared object 檔案。此標誌是選用的，因為可以推斷輸入格式。

--output-elf=<output-filename>

指定 ELF shared object stub 的輸出檔案。

--output-ifs=<output-filename>

指定 text IFS 的輸出檔案。

--output-tbd=<output-filename>

指定 Apple TAPI tbd 的輸出檔案。

--arch=[x86_64|AArch64|...]

此標誌是選用的，僅應在讀取未定義 Arch (架構) 的 IFS 檔案時使用。此標誌定義輸出檔案的架構，可以是 ELF 'e_machine' 欄位支援的任何字串。如果該值與 IFS 檔案衝突，將報告錯誤並且程式將停止。

--endianness=[little|big]

此標誌是選用的，僅應在讀取未定義 Endianness 的 IFS 檔案時使用。此標誌定義輸出檔案的 endianness。如果該值與 IFS 檔案衝突，將報告錯誤並且程式將停止。

--bitwidth=[32|64]

此標誌是選用的，僅應在讀取未定義 BitWidth 的 IFS 檔案時使用。此標誌定義輸出檔案的 bit width。如果該值與輸入 IFS 檔案衝突，將報告錯誤並且程式將停止。

--target=<target triple>

此標誌是選用的，僅應在讀取未定義任何 target 資訊的 IFS 檔案時使用。此標誌使用 llvm target triple 定義輸出檔案的架構、endianness 和 bit width。此標誌不能與其他 target 相關標誌同時使用。

--hint-ifs-target=<target triple>

此標誌是選用的，僅應在讀取 ELF shared object 並產生 IFS 檔案時使用。預設情況下，llvm-ifs 將使用 'Arch, Endianness 和 BitWidth' 欄位來反映來自輸入物件檔案的 target 資訊。使用此標誌將告訴 llvm-ifs 輸出 IFS 檔案中預期的 target triple。如果該值與來自物件檔案的 target 資訊相符，則此值將用於產生的 IFS 中的 'Target:' 欄位。如果它與輸入物件檔案衝突，將報告錯誤並且程式將停止。

--hint-ifs-target

此標誌是選用的，僅應在輸出 IFS 檔案時使用。此標誌從 IFS 檔案中移除 Arch 欄位，以便稍後可以覆寫它。

--strip-ifs-endianness

此標誌是選用的，僅應在輸出 IFS 檔案時使用。此標誌從 IFS 檔案中移除 Endianness 欄位，以便稍後可以覆寫它。

--strip-ifs-bitwidth

此標誌是選用的，僅應在輸出 IFS 檔案時使用。此標誌從 IFS 檔案中移除 BitWidth 欄位，以便稍後可以覆寫它。

--strip-ifs-target

此標誌是選用的，僅應在輸出 IFS 檔案時使用。此標誌從 IFS 檔案中移除 Target 欄位，以便稍後可以覆寫它。

--write-if-changed

設定此標誌後，llvm-ifs 將僅在輸出檔案尚不存在或內容與現有檔案不同時寫入輸出檔案。

--strip-size

設定此標誌後，llvm-ifs 將從輸出 ifs 檔案中移除 size 欄位。這對於僅打算針對不需要複製重定位的位置獨立程式碼連結的 shared object，或物件大小不是要追蹤的 ABI 的有用部分的情況很有用。

結束狀態

如果 llvm-ifs 成功，它將以 0 結束。否則，如果發生錯誤，它將以非零值結束。