Ampere Porting Advisor یک فورک از Porting Advisor برای Graviton، یک پروژه منبع باز از AWS است، که به نوبه خود، انشعابی از مشاور پورتینگ گروه Arm High Performance Computing است.

در ابتدا، به عنوان یک ماژول پایتون کدگذاری شد که ناسازگاری های شناخته شده برای کدهای C و Fortran را تجزیه و تحلیل می کرد. این آموزش شما را در ساخت و استفاده از ابزار و نحوه عمل در مورد مسائل شناسایی شده توسط ابزار راهنمایی می کند.

Ampere Porting Advisor یک ابزار خط فرمان است که کد منبع را برای الگوهای کد شناخته شده و کتابخانه های وابستگی تجزیه و تحلیل می کند. سپس گزارشی با هرگونه ناسازگاری با پردازنده های Ampere ایجاد می کند. این ابزار حداقل نسخه های مورد نیاز و/یا توصیه شده را برای اجرا بر روی پردازنده های Ampere برای کتابخانه های زمان اجرا و وابستگی زبان ارائه می دهد.

این می تواند بر روی ماشین های غیر مبتنی بر Arm64 (مانند اینتل و AMD) اجرا شود و پردازنده های Ampere مورد نیاز نیست. این ابزار روی باینری ها کار نمی کند، فقط روی کد منبع کار می کند. هیچ تغییری در کد ایجاد نمی‌کند، توصیه‌های سطح API را ارائه نمی‌کند، و همچنین داده‌ها را به Ampere نمی‌فرستد.

لطفاً توجه داشته باشید: اگرچه تمام تلاش خود را برای یافتن ناسازگاری‌های شناخته شده انجام می‌دهیم، همچنان توصیه می‌کنیم قبل از شروع به تولید، آزمایش‌های مناسب برنامه خود را روی سیستمی مبتنی بر پردازنده‌های آمپر انجام دهید.

این ابزار تمام فایل‌های موجود در یک درخت منبع را بدون توجه به اینکه توسط سیستم ساخت گنجانده شده‌اند یا خیر اسکن می‌کند. به این ترتیب، ممکن است به اشتباه مشکلات موجود در فایل‌هایی را گزارش کند که در درخت منبع ظاهر می‌شوند اما توسط سیستم ساخت حذف شده‌اند. در حال حاضر، این ابزار از زبان ها/وابستگی های زیر پشتیبانی می کند:

پایتون 3+

نسخه پایتون

نسخه PIP

نسخه های وابستگی در فایل requires.txt

جاوا 8+

نسخه جاوا

نسخه های وابستگی در فایل pom.xml

اسکن JAR برای فراخوانی های روش بومی (نیاز به نصب JAVA)

برو 1.11+

نسخه برو

نسخه های وابستگی به فایل go.mod

C، C++، Fortran

مونتاژ درون خطی بدون مونتاژ درون خطی مربوطه aarch64.

فایل های منبع اسمبلی بدون فایل منبع اسمبلی مربوطه aarch64.

شناسایی معماری aarch64 در اسکریپت‌های config.guess autoconf وجود ندارد.

پیوند در برابر کتابخانه هایی که در معماری aarch64 در دسترس نیستند.

استفاده از معماری خاص ذاتی.

خطاهای پیش پردازنده که هنگام کامپایل در aarch64 ایجاد می شوند.

استفاده از زمان اجرا Visual C++ قدیمی (ویندوز خاص).

انواع مشکلات زیر شناسایی می شوند، اما به طور پیش فرض گزارش نمی شوند:

کد خاص کامپایلر که توسط ماکروهای از پیش تعریف شده خاص کامپایلر محافظت می شود.

انواع زیر از مشکلات خاص متقابل کامپایل شناسایی می شوند، اما به طور پیش فرض گزارش نمی شوند.

تشخیص معماری که به میزبان بستگی دارد تا هدف.

استفاده از مصنوعات ساخت در فرآیند ساخت.

برای اطلاعات بیشتر در مورد نحوه اصلاح مشکلات گزارش شده، از راهنمای داخلی ابزار استفاده کنید: ./porting-advisor-linux-x86_64 --help

اگر با هر مشکلی مواجه شدید، فایل CONTRIBUTING ما را در مخزن GitHub پروژه ببینید.

اجرای Ampere Porting Advisor به عنوان یک کانتینر

با استفاده از این گزینه، نیازی نیست نگران نسخه های پایتون یا جاوا یا هر وابستگی دیگری که ابزار به آن نیاز دارد باشید. این سریعترین راه برای شروع است.

پیش نیازها

Docker یا Containerd + nerdctl + buildkit

تصویر کانتینر را اجرا کنید

پس از ساخت تصویر، می توانیم ابزار را به صورت یک ظرف اجرا کنیم. ما از -v برای نصب یک حجم از دستگاه میزبان خود به ظرف استفاده می کنیم.

می‌توانیم آن را مستقیماً روی کنسول اجرا کنیم:

 docker run --rm -v my/repo/path:/repo porting-advisor /repo

یا گزارشی تهیه کنید:

 docker run --rm -v my/repo/path:/repo -v my/output:/output porting-advisor /repo --output /output/report.html

مثال ویندوز:

 docker run --rm -v /c/Users/myuser/repo:/repo -v /c/Users/myuser/output:/output porting-advisor /repo --output /output/report.html

اجرای Ampere Porting Advisor به عنوان یک اسکریپت پایتون

پیش نیازها

پایتون 3.10 یا بالاتر (با ماژول PIP3 و venv نصب شده است).

(اختیاری) اگر می‌خواهید فایل‌های JAR را برای روش‌های اصلی اسکن کنید، JDK 17 (یا بالاتر) و Maven 3.5 (یا بالاتر) را باز کنید.

Unzip و jq برای اجرای تست مورد نیاز است.

محیط پایتون را فعال کنید

لینوکس/مک:

 python3 -m venv .venv source .venv/bin/activate

پاورشل:

 python -m venv .venv .\.venv\Scripts\Activate.ps1

الزامات نصب

pip3 install -r requirements.txt

ابزار اجرا (خروجی کنسول)

python3 src/porting-advisor.py ~/my/path/to/my/repo

ابزار اجرا (گزارش HTML)

python3 src/porting-advisor.py ~/my/path/to/my/repo –output report.html

اجرای Ampere Porting Advisor به صورت باینری

تولید باینری

پیش نیازها

پایتون 3.10 یا بالاتر (با ماژول PIP3 و venv نصب شده است).

(در صورت تمایل) JDK 17 (یا بالاتر) و Maven 3.5 (یا بالاتر) را باز کنید اگر می خواهید باینری بتواند فایل های JAR را برای روش های بومی اسکن کند.

اسکریپت build.sh یک باینری مستقل (برای Linux/MacOS) تولید خواهد کرد. خروجی آن در پوشه ای به نام dist خواهد بود.

به طور پیش فرض، یک باینری به نام porting-advisor-linux-x86_64 تولید می کند. با تنظیم متغیر محیطی FILE_NAME می توانید نام فایل تولید شده را سفارشی کنید.

 ./build.sh

برای ویندوز، Build.ps1 یک پوشه با یک EXE و تمام فایل هایی که برای اجرا نیاز دارد تولید می کند.

 .\Build.ps1

اجرای باینری

پیش نیازها

هنگامی که باینری را تولید کردید، فقط به Java 11 Runtime (یا بالاتر) نیاز دارد اگر بخواهید فایل های JAR را برای روش های بومی اسکن کنید. در غیر این صورت، فایل مستقل است و برای اجرا نیازی به پایتون ندارد.

رفتار پیش فرض، خروجی کنسول:

 $ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo

ایجاد گزارش HTML:

 $ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo --output report.html

ایجاد گزارشی از وابستگی‌ها (با این کار یک فایل اکسل فقط با وابستگی‌هایی که در مخزن پیدا کرده‌ایم، بدون هیچ پیشنهادی ایجاد می‌کند):

 $ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo --output dependencies.xlsx --output-format dependencies

درک گزارش مشاور آمپر پورتینگ

در اینجا نمونه ای از گزارش خروجی تولید شده با یک پروژه نمونه است:

 ./dist/porting-advisor-linux-x86_64 ./sample-projects/ | Elapsed Time: 0:00:03 
Porting Advisor for Ampere Processor v1.0.0 Report date: 2023-05-10 11:31:52 
13 files scanned. detected go code. min version 1.16 is required. version 1.18 or above is recommended. we detected that you have version 1.19. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/golang.md for more details. detected python code. if you need pip, version 19.3 or above is recommended. we detected that you have version 22.3.1 detected python code. min version 3.7.5 is required. we detected that you have version 3.10.9. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/python.md for more details. ./sample-projects/java-samples/pom.xml: dependency library: leveldbjni-all is not supported on Ampere processor. ./sample-projects/java-samples/pom.xml: using dependency library snappy-java version 1.1.3. upgrade to at least version 1.1.4 ./sample-projects/java-samples/pom.xml: using dependency library zstd-jni version 1.1.0. upgrade to at least version 1.2.0 ./sample-projects/python-samples/incompatible/requirements.txt:3: using dependency library OpenBLAS version 0.3.16. upgrade to at least version 0.3.17 detected go code. min version 1.16 is required. version 1.18 or above is recommended. we detected that you have version 1.19. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/golang.md for more details. ./sample-projects/java-samples/pom.xml: using dependency library hadoop-lzo. this library requires a manual build more info at: https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/java.md#building-jar-libraries-manually ./sample-projects/python-samples/incompatible/requirements.txt:5: dependency library NumPy is present. min version 1.19.0 is required. detected java code. min version 8 is required. version 17 or above is recommended. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/java.md for more details. 
Use --output FILENAME.html to generate an HTML report.

در این گزارش، چندین زمان اجرا زبان (پایتون، پیپ، گلانگ، جاوا) و نسخه‌های آن‌ها شناسایی شده‌اند. همه این پیام‌ها حداقل نسخه و نسخه توصیه شده برای این زبان‌ها را در اختیار شما قرار می‌دهند. برخی از این خطوط تشخیص می‌دهند که نسخه‌های پیش‌نیاز پیدا شده‌اند و صرفاً آموزنده هستند.

ما همچنین پیام هایی از وابستگی های شناسایی شده در Project Object Model (POM) یا پروژه جاوا می بینیم. اینها وابستگی هایی هستند که به عنوان بخشی از فرآیند ساخت Maven دانلود و استفاده می شوند و ما سه نوع پیام قابل اجرا را می بینیم:

وابستگی به نسخه جدیدتری نیاز دارد

./sample-projects/java-samples/pom.xml: با استفاده از کتابخانه وابستگی snappy-java نسخه 1.1.3. حداقل به نسخه 1.1.4 ارتقا دهید

پیام‌هایی از این نوع نشان می‌دهد که باید از نسخه جدیدتری از وابستگی استفاده کنیم، که قبل از ادامه، نیاز به بازسازی و اعتبارسنجی پروژه دارد.

وابستگی نیاز به ساخت دستی دارد

./sample-projects/java-samples/pom.xml: با استفاده از کتابخانه وابستگی hadoop-lzo. این کتابخانه به اطلاعات بیشتر در مورد ساخت دستی نیاز دارد: https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/java.md#building-jar-libraries-manually

در این مورد، یک وابستگی از معماری پشتیبانی می‌کند، اما به دلایلی (شاید برای آزمایش ویژگی‌های سخت‌افزاری موجود و ساختن یک نسخه بهینه از پروژه برای پلتفرم هدف)، پروژه باید به‌جای تکیه بر یک مصنوع باینری از قبل موجود، به‌صورت دستی بازسازی شود.

وابستگی به این معماری در دسترس نیست

./sample-projects/java-samples/pom.xml: کتابخانه وابستگی: leveldbjni-all در پردازنده Ampere پشتیبانی نمی شود.

در این مورد، پروژه به عنوان یک وابستگی مشخص می شود اما برای پلت فرم Ampere در دسترس نیست. یک مهندس ممکن است مجبور شود آنچه را که در ساخت کد از کامپایل وابستگی به درستی در پلتفرم هدف دخیل است بررسی کند. این فرآیند می‌تواند ساده باشد، اما ممکن است زمان و تلاش قابل توجهی نیز ببرد. از طرف دیگر، می‌توانید پروژه خود را با استفاده از یک بسته جایگزین که عملکرد مشابهی را ارائه می‌کند که از معماری Ampere پشتیبانی می‌کند، تطبیق دهید و کد پروژه خود را به‌طور مناسب برای استفاده از این جایگزین تغییر دهید.

یک مثال انتقال برای C/C++

MEGAHIT یک ابزار اسمبلر NGS است که به صورت باینری برای x86_64 موجود است. مشتری می خواست MEGAHIT را در Arm64 به عنوان بخشی از یک انتقال معماری اجرا کند. اما کامپایل در Arm64 در فایل اول شکست خورد:

توسعه دهنده می خواست بداند چه چیزی باید تغییر کند تا MEGAHIT به درستی در Arm64 کامپایل شود.

در این مورد، Ampere Porting Advisor (APA) می تواند نقش کلیدی ایفا کند. پس از اسکن مخزن منبع پروژه MEGAHIT با APA، لیستی از مسائلی را دریافت می کنیم که باید قبل از بازسازی MEGAHIT در Arm64 بررسی شوند:

بیایید هر نوع خطا را در لیست بررسی کنیم و در صورت لزوم آنها را برای Arm64 تصحیح کنیم.

گزینه های ساخت خاص معماری

این خطاها زمانی که APA تشخیص دهد که گزینه های ساخت در Arm64 معتبر نیستند، ایجاد می شوند.

CMakeList.txt اصلی به طور پیش فرض از پرچم های کامپایل x86_64 بدون بررسی معماری CPU استفاده می کند. برای رفع این مشکل، می‌توانیم یک شرط CMAKE_SYSTEM_PROCESSOR را آزمایش کنیم تا مطمئن شویم که پرچم‌های گزارش‌شده توسط APA فقط برای معماری‌های x86_64 اعمال می‌شوند.

دستورالعمل های خاص معماری

خطای دستورالعمل‌های خاص معماری زمانی که APA تشخیص دهد که توابع غیر Arm64 C در کد استفاده می‌شوند، ایجاد می‌شود. دستورالعمل‌های ذاتی توسط کامپایلر مستقیماً در کد اسمبلی مخصوص پلتفرم کامپایل می‌شوند، و معمولاً هر پلتفرم مجموعه‌ای از دستورالعمل‌های کد ذاتی و اسمبلی خود را دارد که برای آن پلتفرم بهینه شده‌اند.

در این مورد، می‌توانیم از شرطی‌های پیش‌پردازنده استفاده کنیم تا فقط دستورالعمل‌های _pdep_u32/64 و __cpuid/ex را کامپایل کنیم، زمانی که #if defined(x86_64) برای توابع HasPopcnt() و HasBmi2() صادق باشد. برای vec_vsx_ld، قبلاً در یک پیش پردازشگر مشروط پیچیده شده است و فقط در معماری Power PC کامپایل می شود، بنابراین می توانیم آن را همانطور که هست رها کنیم.

مجموعه درون خطی خاص معماری

هنگامی که APA تشخیص داد که کد اسمبلی در کد استفاده می شود، خطای دستورالعمل های خاص معماری فعال می شود. باید بررسی کنیم که آیا قطعه کد اسمبلی برای Arm64 است یا خیر.

پروژه MEGAHIT تنها زمانی از کد اسمبلی bswap در phmap_bits.h استفاده می کند که در معماری x86_64 کامپایل می شود. هنگامی که بر روی معماری های دیگر کامپایل می شود، یک پیاده سازی بازگشتی را از glibc کامپایل می کند. بنابراین هیچ تغییری در phmap_bits.h لازم نیست.

در cpu_dispatch.h، دو تابع درون خطی () HasPopcnt و () HasBmi2 بدون قید و شرط شامل cpuid دستورالعمل اسمبلی x86_64 برای آزمایش ویژگی‌های CPU در x86_64 می‌شوند. می‌توانیم یک پرچم شرطی پیش‌کامپایلر #if defined ( x86_64 ) اضافه کنیم تا مطمئن شویم این کد در Arm64 فراخوانی نمی‌شود و همیشه false را برمی‌گردانیم.

معماری خاص SIMD ذاتی

هنگامی که APA تشخیص داد دستورات SIMD x86_64 مانند AVX256 یا AVX512 در کد استفاده شده است، خطای دستورالعمل‌های خاص معماری فعال می‌شود. این دستورالعمل‌های SIMD توسط پرچم‌های شرطی پیش‌کامپایلر پیچیده شده‌اند و معمولاً هیچ مشکلی در عملکرد Arm64 ایجاد نمی‌کنند.

اگر اجرای الگوریتم SIMD برای Arm64 وجود نداشت، ممکن است یک شکاف عملکرد در مقایسه با x86_64 وجود داشته باشد. در این مورد، یک پیاده سازی NEON SIMD برای Arm64 در xxh3.h وجود دارد و این پیاده سازی توسط کامپایلر بر اساس معماری CPU انتخاب می شود. هیچ اقدام دیگری لازم نیست انجام شود.

خطای پیش پردازنده در AArch64

خطای پیش پردازنده توسط APA ایجاد می شود تا نشان دهد که معماری Arm64 ممکن است در مرحله پیش کامپایل قرار نگیرد. در این مورد، می بینیم که شرطی پیش کامپایل فقط برای x86_64 است و به معماری Arm64 مربوط نمی شود.

بازسازی و تست کنید

وقتی همه این تنظیمات انجام شد، می‌توانیم پروژه را بازسازی کنیم:

پروژه با موفقیت تدوین شد. سپس بررسی کردیم که آیا این مجموعه آزمایشی پروژه را پشت سر گذاشته است یا خیر:

پس از بررسی دستی و رفع مشکلات احتمالی گزارش شده توسط APA، MEGAHIT اکنون می تواند پردازنده های Ampere را بسازد و اجرا کند.

خبرکاو