ใช้การปรับให้เหมาะสมตามโปรไฟล์

คำเตือน: ฟีเจอร์นี้เลิกใช้งานแล้วใน Android 14 ขึ้นไป ฟีเจอร์นี้ใช้ได้ต่อไปใน Android 13 หรือก่อนหน้า

ระบบบิลด์ Android สำหรับ Android 13 และต่ำกว่ารองรับการ ใช้การเพิ่มประสิทธิภาพตามโปรไฟล์ (PGO) ของ Clang บนโมดูล Android ดั้งเดิมที่มีกฎการสร้าง พิมพ์เขียว หน้านี้อธิบาย Clang PGO วิธีสร้างและอัปเดตโปรไฟล์ที่ใช้สำหรับ PGO อย่างต่อเนื่อง และวิธีการรวม PGO เข้ากับระบบบิลด์ (พร้อมกรณีการใช้งาน)

หมายเหตุ: เอกสารนี้อธิบายการใช้ PGO ในแพลตฟอร์ม Android หากต้องการเรียนรู้เกี่ยวกับการใช้ PGO จากแอป Android โปรดไปที่ หน้านี้

เกี่ยวกับ แคลง พีจีโอ

เสียงดังกราวสามารถทำการเพิ่มประสิทธิภาพตามโปรไฟล์ได้โดยใช้โปรไฟล์สองประเภท:

• โปรไฟล์ตามเครื่องมือวัด ถูกสร้างขึ้นจากโปรแกรมเป้าหมายที่มีเครื่องมือวัด โปรไฟล์เหล่านี้มีรายละเอียดและมีค่าใช้จ่ายรันไทม์สูง
• โดยทั่วไป โปรไฟล์ตามการสุ่มตัวอย่าง จะถูกสร้างขึ้นโดยการสุ่มตัวอย่างตัวนับฮาร์ดแวร์ โดยกำหนดให้มีค่าใช้จ่ายรันไทม์ต่ำ และสามารถรวบรวมได้โดยไม่ต้องใช้เครื่องมือหรือแก้ไขไบนารี่ใดๆ มีรายละเอียดน้อยกว่าโปรไฟล์ที่อิงตามเครื่องมือวัด

โปรไฟล์ทั้งหมดควรสร้างขึ้นจากปริมาณงานที่เป็นตัวแทนซึ่งใช้ลักษณะการทำงานทั่วไปของแอป แม้ว่า Clang รองรับทั้งแบบอิง AST ( -fprofile-instr-generate ) และแบบ LLVM IR ( -fprofile-generate) แต่ Android รองรับเฉพาะแบบ LLVM IR สำหรับ PGO แบบใช้เครื่องมือวัด

จำเป็นต้องมีแฟล็กต่อไปนี้เพื่อสร้างสำหรับการรวบรวมโปรไฟล์:

• -fprofile-generate สำหรับเครื่องมือวัดที่ใช้ IR ด้วยตัวเลือกนี้ แบ็กเอนด์ใช้วิธีการขยายแบบต้นไม้น้อยที่สุดแบบถ่วงน้ำหนักเพื่อลดจำนวนจุดเครื่องมือวัดและปรับตำแหน่งให้เหมาะสมกับขอบที่มีน้ำหนักต่ำ (ใช้ตัวเลือกนี้สำหรับขั้นตอนการเชื่อมโยงด้วย) ไดรเวอร์ Clang จะส่งผ่านรันไทม์การทำโปรไฟล์ ( libclang_rt.profile- arch -android.a ) ไปยังตัวเชื่อมโยงโดยอัตโนมัติ ไลบรารีนี้มีรูทีนในการเขียนโปรไฟล์ลงดิสก์เมื่อออกจากโปรแกรม
• -gline-tables-only สำหรับการรวบรวมโปรไฟล์ตามการสุ่มตัวอย่างเพื่อสร้างข้อมูลการแก้ไขข้อบกพร่องขั้นต่ำ

โปรไฟล์สามารถใช้สำหรับ PGO โดยใช้ -fprofile-use= pathname หรือ -fprofile-sample-use= pathname สำหรับโปรไฟล์แบบอิงเครื่องมือวัดและแบบอิงการสุ่มตัวอย่างตามลำดับ

หมายเหตุ: เนื่องจากมีการเปลี่ยนแปลงกับโค้ด หาก Clang ไม่สามารถใช้ข้อมูลโปรไฟล์ได้อีกต่อไป มันจะสร้างคำเตือน -Wprofile-instr-out-of-date

ใช้พีจีโอ

การใช้ PGO เกี่ยวข้องกับขั้นตอนต่อไปนี้:

1. สร้างไลบรารี/ปฏิบัติการด้วยเครื่องมือวัดโดยส่ง -fprofile-generate ไปยังคอมไพเลอร์และตัวเชื่อมโยง
2. รวบรวมโปรไฟล์โดยการรันเวิร์กโหลดตัวแทนบนไบนารี่ที่มีเครื่องมือ
3. โพสต์ประมวลผลโปรไฟล์โดยใช้ยูทิลิตี llvm-profdata (สำหรับรายละเอียด โปรดดูที่ การจัดการไฟล์โปรไฟล์ LLVM )
4. ใช้โปรไฟล์เพื่อใช้ PGO โดยส่ง -fprofile-use=<>.profdata ไปยังคอมไพลเลอร์และตัวเชื่อมโยง

สำหรับ PGO ใน Android ควรรวบรวมโปรไฟล์ออฟไลน์และตรวจสอบควบคู่ไปกับโค้ดเพื่อให้แน่ใจว่าบิลด์สามารถทำซ้ำได้ โปรไฟล์สามารถใช้เป็นวิวัฒนาการของโค้ดได้ แต่จะต้องสร้างใหม่เป็นระยะ (หรือเมื่อใดก็ตามที่ Clang เตือนว่าโปรไฟล์นั้นเก่า)

รวบรวมโปรไฟล์

เสียงดังกราวสามารถใช้โปรไฟล์ที่รวบรวมโดยการรันการวัดประสิทธิภาพโดยใช้บิลด์เครื่องมือของไลบรารี หรือโดยการสุ่มตัวอย่างตัวนับฮาร์ดแวร์เมื่อรันการวัดประสิทธิภาพ ในขณะนี้ Android ยังไม่รองรับการใช้การรวบรวมโปรไฟล์ตามการสุ่มตัวอย่าง ดังนั้นคุณต้องรวบรวมโปรไฟล์โดยใช้โครงสร้างที่มีเครื่องมือ:

1. ระบุเกณฑ์มาตรฐานและชุดของห้องสมุดที่ใช้ร่วมกันโดยเกณฑ์มาตรฐานนั้น
2. เพิ่มคุณสมบัติ pgo ให้กับเกณฑ์มาตรฐานและไลบรารี (รายละเอียดด้านล่าง)
3. สร้างบิลด์ Android ด้วยสำเนาเครื่องมือของไลบรารีเหล่านี้โดยใช้:

   make ANDROID_PGO_INSTRUMENT=benchmark

benchmark คือตัวยึดตำแหน่งที่ระบุคอลเลกชันของไลบรารีที่ติดตั้งไว้ระหว่างการสร้าง อินพุตตัวแทนจริง (และอาจเป็นไฟล์ปฏิบัติการอื่นที่เชื่อมโยงกับไลบรารีที่กำลังทำการวัดประสิทธิภาพ) ไม่ได้เฉพาะเจาะจงสำหรับ PGO และอยู่นอกเหนือขอบเขตของเอกสารนี้

1. แฟลชหรือซิงค์บิวด์เครื่องมือบนอุปกรณ์
2. เรียกใช้การวัดประสิทธิภาพเพื่อรวบรวมโปรไฟล์
3. ใช้เครื่องมือ llvm-profdata (ตามที่กล่าวไว้ด้านล่าง) เพื่อประมวลผลโปรไฟล์ภายหลัง และเตรียมให้พร้อมสำหรับการตรวจสอบในแผนผังต้นทาง

ใช้โปรไฟล์ระหว่างการสร้าง

ตรวจสอบโปรไฟล์ใน toolchain/pgo-profiles ในแผนผัง Android ชื่อควรตรงกับที่ระบุไว้ในคุณสมบัติย่อย profile_file ของคุณสมบัติ pgo สำหรับไลบรารี ระบบบิลด์จะส่งไฟล์โปรไฟล์ไปยัง Clang โดยอัตโนมัติเมื่อสร้างไลบรารี ตัวแปรสภาพแวดล้อม ANDROID_PGO_DISABLE_PROFILE_USE สามารถตั้งค่าเป็น true เพื่อปิดใช้งาน PGO ชั่วคราวและวัดประโยชน์ด้านประสิทธิภาพได้

หากต้องการระบุไดเร็กทอรีโปรไฟล์เฉพาะผลิตภัณฑ์เพิ่มเติม ให้ผนวกเข้ากับ PGO_ADDITIONAL_PROFILE_DIRECTORIES สร้างตัวแปรใน BoardConfig.mk หากมีการระบุพาธเพิ่มเติม โปรไฟล์ในพาธเหล่านี้จะแทนที่โปรไฟล์ใน toolchain/pgo-profiles

เมื่อสร้างอิมเมจที่เผยแพร่โดยใช้เป้าหมาย dist เพื่อ make ระบบ build จะเขียนชื่อของไฟล์โปรไฟล์ที่หายไปไปที่ $DIST_DIR/pgo_profile_file_missing.txt คุณสามารถตรวจสอบไฟล์นี้เพื่อดูว่าไฟล์โปรไฟล์ใดถูกทิ้งโดยไม่ตั้งใจ (ซึ่งจะปิดใช้งาน PGO โดยไม่แจ้งให้ทราบ)

เปิดใช้งาน PGO ในไฟล์ Android.bp

หากต้องการเปิดใช้งาน PGO ในไฟล์ Android.bp สำหรับโมดูลดั้งเดิม เพียงระบุคุณสมบัติ pgo คุณสมบัตินี้มีคุณสมบัติย่อยดังต่อไปนี้:

คุณสมบัติ	คำอธิบาย
instrumentation	ตั้งค่าเป็น true สำหรับ PGO โดยใช้เครื่องมือวัด ค่าเริ่มต้นเป็น false
sampling	ตั้งค่าเป็น true สำหรับ PGO โดยใช้การสุ่มตัวอย่าง ค่าเริ่มต้นเป็น false
benchmarks	รายการสตริง โมดูลนี้สร้างขึ้นสำหรับการจัดทำโปรไฟล์หากมีการระบุเกณฑ์มาตรฐานในรายการในตัวเลือกการสร้าง ANDROID_PGO_INSTRUMENT
profile_file	ไฟล์โปรไฟล์ (สัมพันธ์กับ toolchain/pgo-profile ) เพื่อใช้กับ PGO บิลด์เตือนว่าไฟล์นี้ไม่มีอยู่โดยการเพิ่มไฟล์นี้ใน $DIST_DIR/pgo_profile_file_missing.txt ยกเว้นว่า คุณสมบัติ enable_profile_use ถูกตั้งค่าเป็น false หรือ ตัวแปรบิลด์ ANDROID_PGO_NO_PROFILE_USE ถูกตั้งค่าเป็น true
enable_profile_use	ตั้งค่าเป็น false หากไม่ควรใช้โปรไฟล์ในระหว่างการสร้าง สามารถใช้ระหว่างบูตสแตรปเพื่อเปิดใช้งานการรวบรวมโปรไฟล์หรือปิดใช้งาน PGO ชั่วคราว ค่าเริ่มต้นเป็น true
cflags	รายการแฟล็กเพิ่มเติมที่จะใช้ระหว่างการสร้างเครื่องมือ

ตัวอย่างของโมดูลที่มี PGO:

cc_library {
    name: "libexample",
    srcs: [
        "src1.cpp",
        "src2.cpp",
    ],
    static: [
        "libstatic1",
        "libstatic2",
    ],
    shared: [
        "libshared1",
    ]
    pgo: {
        instrumentation: true,
        benchmarks: [
            "benchmark1",
            "benchmark2",
        ],
        profile_file: "example.profdata",
    }
}

หากการวัดประสิทธิภาพ benchmark1 และ benchmark2 ใช้พฤติกรรมตัวแทนสำหรับไลบรารี libstatic1 , libstatic2 หรือ libshared1 คุณสมบัติ pgo ของไลบรารีเหล่านี้ก็สามารถรวมการวัดประสิทธิภาพได้เช่นกัน โมดูล defaults ใน Android.bp สามารถรวมข้อกำหนด pgo ทั่วไปสำหรับชุดไลบรารีเพื่อหลีกเลี่ยงการสร้างกฎการสร้างเดียวกันซ้ำสำหรับหลายโมดูล

หากต้องการเลือกไฟล์โปรไฟล์อื่นหรือเลือกปิดใช้งาน PGO สำหรับสถาปัตยกรรม ให้ระบุคุณสมบัติ profile_file , enable_profile_use และ cflags ตามสถาปัตยกรรม ตัวอย่าง (โดยมีเป้าหมายสถาปัตยกรรมเป็น ตัวหนา ):

cc_library {
    name: "libexample",
    srcs: [
          "src1.cpp",
          "src2.cpp",
    ],
    static: [
          "libstatic1",
          "libstatic2",
    ],
    shared: [
          "libshared1",
    ],
    pgo: {
         instrumentation: true,
         benchmarks: [
              "benchmark1",
              "benchmark2",
         ],
    }

    target: {
         android_arm: {
              pgo: {
                   profile_file: "example_arm.profdata",
              }
         },
         android_arm64: {
              pgo: {
                   profile_file: "example_arm64.profdata",
              }
         }
    }
}

หากต้องการแก้ไขการอ้างอิงไปยังไลบรารีรันไทม์การทำโปรไฟล์ระหว่างการทำโปรไฟล์ตามเครื่องมือ ให้ส่งแฟล็ก build -fprofile-generate ไปยังตัวเชื่อมโยง ไลบรารีแบบสแตติกที่ติดตั้ง PGO ไลบรารีแบบแบ่งใช้ทั้งหมด และไบนารีใดๆ ที่ขึ้นอยู่กับไลบรารีแบบคงที่โดยตรงจะต้องถูกติดตั้งสำหรับ PGO ด้วย อย่างไรก็ตาม ไลบรารีที่แบ่งใช้หรือโปรแกรมปฏิบัติการดังกล่าวไม่จำเป็นต้องใช้โปรไฟล์ PGO และสามารถตั้งค่าคุณสมบัติ enable_profile_use เป็น false ได้ นอกเหนือจากข้อจำกัดนี้ คุณสามารถใช้ PGO กับไลบรารีแบบคงที่ ไลบรารีแบบแบ่งใช้ หรือไฟล์ปฏิบัติการได้

จัดการไฟล์โปรไฟล์ LLVM

การเรียกใช้ไลบรารี่ที่มีเครื่องมือหรือไฟล์เรียกทำงานจะสร้างไฟล์โปรไฟล์ชื่อ default_ unique_id _0.profraw ใน /data/local/tmp (โดยที่ unique_id คือแฮชตัวเลขที่ไม่ซ้ำกับไลบรารีนี้) หากไฟล์นี้มีอยู่แล้ว รันไทม์การทำโปรไฟล์จะรวมโปรไฟล์ใหม่เข้ากับไฟล์เก่าขณะเขียนโปรไฟล์ โปรดทราบว่า /data/local/tmp ไม่สามารถเข้าถึงได้สำหรับนักพัฒนาแอป พวกเขาควรใช้ที่ไหนสักแห่งเช่น /storage/emulated/0/Android/data/ packagename /files แทน หากต้องการเปลี่ยนตำแหน่งของไฟล์โปรไฟล์ ให้ตั้งค่าตัวแปรสภาพแวดล้อม LLVM_PROFILE_FILE ณ รันไทม์

จากนั้นยูทิลิตี้ llvm-profdata จะใช้ในการแปลงไฟล์ .profraw (และอาจรวมไฟล์ .profraw หลายไฟล์เข้าด้วยกัน) เป็นไฟล์ .profdata :

  llvm-profdata merge -output=profile.profdata <.profraw and/or .profdata files>

จากนั้นสามารถตรวจสอบ profile.profdata ในแผนผังต้นทางเพื่อใช้ระหว่างการสร้างได้

หากมีการโหลดไบนารี/ไลบรารีที่มีเครื่องมือหลายรายการระหว่างการวัดประสิทธิภาพ แต่ละไลบรารีจะสร้างไฟล์ .profraw แยกต่างหากโดยมี ID ที่ไม่ซ้ำกันแยกกัน โดยทั่วไป ไฟล์เหล่านี้ทั้งหมดสามารถรวมเป็นไฟล์ .profdata ไฟล์เดียวและใช้สำหรับบิลด์ PGO ในกรณีที่ห้องสมุดถูกใช้งานโดยการวัดประสิทธิภาพอื่น ห้องสมุดนั้นจะต้องได้รับการปรับให้เหมาะสมโดยใช้โปรไฟล์จากการวัดประสิทธิภาพทั้งสอง ในสถานการณ์นี้ ตัวเลือก show ของ llvm-profdata จะมีประโยชน์:

  llvm-profdata merge -output=default_unique_id.profdata default_unique_id_0.profraw
llvm-profdata show -all-functions default_unique_id.profdata

หากต้องการแมป Unique_id s กับไลบรารีแต่ละรายการ ให้ค้นหาเอาต์พุต show สำหรับแต่ละ Unique_id เพื่อหาชื่อฟังก์ชันที่ไม่ซ้ำกับไลบรารี

กรณีศึกษา: PGO สำหรับ ART

กรณีศึกษานี้นำเสนอ ART เป็นตัวอย่างที่เกี่ยวข้อง อย่างไรก็ตาม มันไม่ใช่คำอธิบายที่ถูกต้องเกี่ยวกับชุดห้องสมุดจริงที่ทำโปรไฟล์สำหรับ ART หรือการพึ่งพาซึ่งกันและกัน

คอมไพเลอร์ล่วงหน้า dex2oat ใน ART ขึ้นอยู่กับ libart-compiler.so ซึ่งจะขึ้นอยู่กับ libart.so รันไทม์ ART ถูกนำมาใช้เป็นหลักใน libart.so เกณฑ์มาตรฐานสำหรับคอมไพลเลอร์และรันไทม์จะแตกต่างกัน:

เกณฑ์มาตรฐาน	ไลบรารีโปรไฟล์
dex2oat	dex2oat (ปฏิบัติการได้), libart-compiler.so , libart.so
art_runtime	libart.so

1. เพิ่มคุณสมบัติ pgo ต่อไปนี้ใน dex2oat , libart-compiler.so :

       pgo: {
           instrumentation: true,
           benchmarks: ["dex2oat",],
           profile_file: "dex2oat.profdata",
       }

2. เพิ่มคุณสมบัติ pgo ต่อไปนี้ใน libart.so :

       pgo: {
           instrumentation: true,
           benchmarks: ["art_runtime", "dex2oat",],
           profile_file: "libart.profdata",
       }

3. สร้างการสร้างเครื่องมือสำหรับการวัดประสิทธิภาพ dex2oat และ art_runtime โดยใช้:

       make ANDROID_PGO_INSTRUMENT=dex2oat
       make ANDROID_PGO_INSTRUMENT=art_runtime

อีกทางหนึ่ง สร้างบิลด์ที่มีเครื่องมือเดียวโดยมีไลบรารีทั้งหมดที่มีเครื่องมือโดยใช้:

    make ANDROID_PGO_INSTRUMENT=dex2oat,art_runtime
    (or)
    make ANDROID_PGO_INSTRUMENT=ALL

คำสั่งที่สองสร้างโมดูลที่เปิดใช้งาน PGO ทั้งหมด สำหรับการทำโปรไฟล์

4. รันการวัดประสิทธิภาพโดยใช้ dex2oat และ art_runtime เพื่อรับ:
   • ไฟล์ .profraw สามไฟล์จาก dex2oat ( dex2oat_exe.profdata , dex2oat_libart-compiler.profdata และ dexeoat_libart.profdata ) ระบุโดยใช้วิธีการที่อธิบายไว้ใน การจัดการไฟล์โปรไฟล์ LLVM
   • art_runtime_libart.profdata เดียว
5. สร้างไฟล์ profdata ทั่วไปสำหรับปฏิบัติการ dex2oat และ libart-compiler.so โดยใช้:

   llvm-profdata merge -output=dex2oat.profdata \
       dex2oat_exe.profdata dex2oat_libart-compiler.profdata

6. รับโปรไฟล์สำหรับ libart.so โดยการรวมโปรไฟล์จากการวัดประสิทธิภาพทั้งสอง:

   llvm-profdata merge -output=libart.profdata \
       dex2oat_libart.profdata art_runtime_libart.profdata

   จำนวนดิบสำหรับ libart.so จากทั้งสองโปรไฟล์อาจแตกต่างกัน เนื่องจากการวัดประสิทธิภาพแตกต่างกันในจำนวนกรณีทดสอบและระยะเวลาที่เรียกใช้ ในกรณีนี้ คุณสามารถใช้การผสานแบบถ่วงน้ำหนักได้:

   llvm-profdata merge -output=libart.profdata \
       -weighted-input=2,dex2oat_libart.profdata \
       -weighted-input=1,art_runtime_libart.profdata

   คำสั่งดังกล่าวจะกำหนดน้ำหนักเป็นสองเท่าให้กับโปรไฟล์จาก dex2oat น้ำหนักจริงควรพิจารณาจากความรู้โดเมนหรือการทดลอง

7. ตรวจสอบไฟล์โปรไฟล์ dex2oat.profdata และ libart.profdata ลงใน toolchain/pgo-profiles เพื่อใช้ระหว่างการ build