نام (NAME)

yasm - اسمبلر پیمانه‌ای Yasm

خلاصه دستور (SYNOPSIS)

yasm [-f format] [-o outfile] [other options...] {infile}

yasm -h

توضیحات (DESCRIPTION)

اسمبلر ماژولار Yasm یک اسمبلر قابل‌حمل و با قابلیت تغییر معماری مقصد (retargetable) است که تحت مجوز “جدید” BSD (دو یا سه بندی) نوشته شده است. در حال حاضر Yasm از مجموعه‌دستورالعمل‌های x86 و AMD64 پشتیبانی می‌کند، نحو‌های اسمبلر NASM و GAS را می‌پذیرد، قالب‌های شیء باینری، ELF32، ELF64، COFF، Win32 و Win64 را در خروجی تولید می‌کند و اطلاعات اشکال‌زدایی سورس‌کد را در قالب‌های STABS، DWARF 2 و CodeView 8 می‌سازد.

YASM شامل دستور yasm، کتابخانه اصلی پس‌زمینه libyasm و شمار زیادی از ماژول‌ها است. در حال حاضر، libyasm و ماژول‌های قابل‌بارگذاری به‌صورت ایستا (استاتیک) درون فایل اجرایی yasm کامپایل شده‌اند.

دستور yasm فایل ورودی infile را اسمبل کرده و در صورت مشخص شدن، خروجی را به فایل outfile هدایت می‌کند. اگر outfile مشخص نشده باشد، yasm نام فایل خروجی پیش‌فرض را از نام فایل ورودی استخراج می‌کند، معمولاً با افزودن .o یا .obj، یا با حذف تمام پسوندها برای یک فایل باینری خام. در صورت عدم موفقیت، نام فایل خروجی yasm.out خواهد بود.

اگر infile با مقدار “-” داده شود، yasm ورودی استاندارد را اسمبل کرده و در صورت مشخص بودن، خروجی را به فایل outfile، یا در صورت عدم تعیین outfile به yasm.out هدایت می‌کند.

گزینه‌ها (OPTIONS)

بسیاری از گزینه‌ها می‌توانند به یکی از دو شکل ارائه شوند: یک خط تیره به همراه یک حرف منفرد، یا دو خط تیره به همراه نام کامل گزینه. گزینه‌ها به ترتیب الفبایی فهرست شده‌اند.

گزینه‌های عمومی (General Options)

-a arch یا --arch=arch: انتخاب معماری مقصد

معماری مقصد را انتخاب می‌کند. معماری پیش‌فرض “x86” است که هم از مجموعه‌دستورالعمل‌های IA-32 و مشتقات آن و هم از AMD64 پشتیبانی می‌کند. برای چاپ فهرستی از معماری‌های موجود در خروجی استاندارد، از “help” به‌عنوان arch استفاده کنید. برای مشاهده فهرستی از معماری‌های پشتیبانی‌شده به yasm_arch(7) مراجعه کنید.

-f format یا --oformat=format: انتخاب قالب شیء (Object)

قالب شیء خروجی را انتخاب می‌کند. قالب شیء پیش‌فرض “bin” است که یک باینری تخت بدون قابلیت جابه‌جایی (relocation) است. برای چاپ فهرستی از قالب‌های شیء موجود در خروجی استاندارد، از “help” به‌عنوان format استفاده کنید. برای مشاهده فهرستی از قالب‌های شیء پشتیبانی‌شده به yasm_objfmts(7) مراجعه کنید.

-g debug یا --dformat=debug: انتخاب قالب اشکال‌زدایی (Debug)

قالب اشکال‌زدایی را برای اطلاعات دیباگ انتخاب می‌کند. اطلاعات اشکال‌زدایی توسط یک اشکال‌زدا (دیباگر) قابل استفاده است تا کد اجرایی را به فایل مبدأ مرتبط سازد یا اطلاعات ساختار داده و نوع را به دست آورد. قالب‌های اشکال‌زدایی موجود در میان قالب‌های مختلف شیء متفاوت است؛ yasm در صورت انتخاب یک ترکیب نامعتبر خطا خواهد داد. قالب اشکال‌زدایی پیش‌فرض بر اساس قالب شیء انتخاب می‌شود. برای چاپ فهرستی از قالب‌های اشکال‌زدایی موجود در خروجی استاندارد، از “help” به‌عنوان debug استفاده کنید. برای مشاهده فهرستی از قالب‌های اشکال‌زدایی پشتیبانی‌شده به yasm_dbgfmts(7) مراجعه کنید.

-L list یا --lformat=list: انتخاب قالب فایل فهرست (List)

قالب/سبک فایل فهرست خروجی را انتخاب می‌کند. فایل‌های فهرست معمولاً سورس‌کد اصلی را با کد ماشین تولیدشده توسط اسمبلر در هم می‌آمیزند. قالب پیش‌فرض فهرست “nasm” است که از قالب فایل فهرست NASM الگوبرداری می‌کند. برای چاپ فهرستی از قالب‌های موجود فایل فهرست در خروجی استاندارد، از “help” به‌عنوان list استفاده کنید.

-l listfile یا --list=listfile: تعیین نام فایل فهرست

نام فایل فهرست خروجی را مشخص می‌کند. اگر این گزینه استفاده نشود، هیچ فایل فهرستی ایجاد نخواهد شد.

-m machine یا --machine=machine: انتخاب معماری ماشین مقصد

معماری ماشین مقصد را انتخاب می‌کند. نوع ماشین که در اصل یک زیرنوع از معماری انتخاب‌شده است، میان زیرمجموعه‌های اصلی یک معماری تمایز قائل می‌شود. برای مثال، برای معماری “x86”، دو ماشین موجود عبارتند از “x86” که برای مجموعه‌دستورالعمل ۳۲ بیتی IA-32 و مشتقات آن به کار می‌رود، و “amd64” که برای مجموعه‌دستورالعمل ۶۴ بیتی استفاده می‌شود. این تمایز برای تولید فایل شیء مناسب در قالب‌های جابه‌جایی‌پذیر (relocatable) نظیر COFF و ELF الزامی است. برای چاپ فهرستی از ماشین‌های موجود برای یک معماری خاص در خروجی استاندارد، از “help” به‌عنوان machine و معماری مورد نظر با استفاده از -a arch استفاده کنید. برای جزئیات بیشتر به yasm_arch(7) مراجعه کنید.

-o filename یا --objfile=filename: تعیین نام فایل شیء

نام فایل خروجی را مشخص کرده و جایگزین هر نام پیش‌فرضی می‌شود که توسط Yasm ایجاد شده است.

-p parser یا --parser=parser: انتخاب تجزیه‌کننده (Parser)

تجزیه‌کننده (سینتکس و نحو اسمبلر) را انتخاب می‌کند. تجزیه‌کننده پیش‌فرض “nasm” است که نحو NASM (اسمبلر Netwide) را شبیه‌سازی می‌کند. تجزیه‌کننده موجود دیگر “gas” است که نحو GNU AS را شبیه‌سازی می‌کند. برای چاپ فهرستی از تجزیه‌کننده‌های موجود در خروجی استاندارد، از “help” به‌عنوان parser استفاده کنید. برای مشاهده فهرستی از تجزیه‌کننده‌های پشتیبانی‌شده به yasm_parsers(7) مراجعه کنید.

-r preproc یا --preproc=preproc: انتخاب پیش‌پردازنده (Preprocessor)

پیش‌پردازنده‌ای را که باید قبل از ارسال فایل ورودی به تجزیه‌کننده روی آن اعمال شود انتخاب می‌کند. پیش‌پردازنده‌ها اغلب قابلیت‌های ماکرویی ارائه می‌دهند که در تجزیه‌کننده اصلی گنجانده نشده است. پیش‌پردازنده پیش‌فرض “nasm” است که یک نسخه واردشده از پیش‌پردازنده اصلی NASM است. یک پیش‌پردازنده “raw” نیز در دسترس است که فرآیند پیش‌پردازش را نادیده گرفته و فایل ورودی را مستقیماً به تجزیه‌کننده ارسال می‌کند. برای چاپ فهرستی از پیش‌پردازنده‌های موجود در خروجی استاندارد، از “help” به‌عنوان preproc استفاده کنید.

-h یا --help: چاپ خلاصه گزینه‌ها

خلاصه‌ای از گزینه‌های فراخوانی را چاپ می‌کند. تمام گزینه‌های دیگر نادیده گرفته شده و هیچ فایل خروجی تولید نمی‌شود.

--version: دریافت نسخه Yasm

این گزینه باعث می‌شود Yasm شماره نسخه و خلاصه‌ای از مجوز را در خروجی استاندارد چاپ کند. تمامی گزینه‌های دیگر نادیده گرفته شده و هیچ فایل خروجی تولید نمی‌شود.

گزینه‌های هشدار (Warning Options)

گزینه‌های -W دارای دو حالت متضاد هستند: -Wname و -Wno-name. در اینجا فقط حالت‌های غیرپیش‌فرض نشان داده شده‌اند.

گزینه‌های هشدار به همان ترتیبی که در خط فرمان وارد شده‌اند پردازش می‌شوند، بنابراین اگر پس از -w گزینه -Worphan-labels بیاید، تمام هشدارها خاموش می‌شوند به‌جز orphan-labels.

-w: غیرفعال کردن تمامی پیام‌های هشدار

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

-Werror: در نظر گرفتن هشدارها به عنوان خطا

این گزینه باعث می‌شود Yasm تمامی هشدارها را به عنوان خطا در نظر بگیرد. در حالت عادی، هشدارها مانع از تولید فایل شیء نمی‌شوند و وضعیت خروج ناموفق از yasm تولید نمی‌کنند، در حالی که خطاها چنین می‌کنند. این گزینه هشدارها را از نظر این رفتار معادل خطا قرار می‌دهد.

-Wno-unrecognized-char: عدم هشدار در مورد کاراکترهای ناشناخته ورودی

باعث می‌شود Yasm در مورد کاراکترهای ناشناخته موجود در ورودی هشدار ندهد. در حالت عادی Yasm برای هر کاراکتر غیر ASCII موجود در فایل ورودی هشدار تولید می‌کند.

-Worphan-labels: هشدار در مورد برچسب‌های فاقد دونقطه پایانی

هنگام استفاده از تجزیه‌کننده سازگار با NASM، باعث می‌شود Yasm در مورد برچسب‌هایی که به تنهایی روی یک خط بدون دو‌نقطه (colon) پایانی قرار گرفته‌اند هشدار دهد. با وجود اینکه این برچسب‌ها در نحو NASM مجاز هستند، اما ممکن است ناخواسته و ناشی از اشتباه تایپی یا ترتیب تعریف ماکروها باشند.

-X style: تغییر شیوه گزارش خطا/هشدار

یک قالب خروجی خاص را برای پیام‌های خطا و هشدار انتخاب می‌کند. پیش‌فرض قالب “gnu” است که خروجی gcc را تقلید می‌کند. قالب “vc” نیز موجود است که خروجی کامپایلر Visual C++ مایکروسافت را تقلید می‌کند.

این گزینه به منظور یکپارچگی طبیعی‌تر Yasm با محیط‌های IDE مانند Visual Studio یا Emacs فراهم شده است، تا IDE بتواند پیام‌های خطا و هشدار را به‌درستی تشخیص دهد و به خط دارای ایراد در سورس‌کد پیوند دهد.

گزینه‌های پیش‌پردازنده (Preprocessor Options)

اگرچه این گزینه‌های پیش‌پردازنده از نظر تئوری روی هر پیش‌پردازنده‌ای اثر می‌گذارند، اما در حال حاضر تنها پیش‌پردازنده موجود در Yasm پیش‌پردازنده “nasm” است.

-D macro[=value]: تعریف اولیه یک ماکرو

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

-e یا --preproc-only: فقط پیش‌پردازش

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

-I path: افزودن مسیر فایل‌های Include

دایرکتوری path را به مسیر جستجوی فایل‌های include اضافه می‌کند. مسیر جستجو به‌طور پیش‌فرض تنها شامل دایرکتوری است که فایل مبدأ در آن قرار دارد.

-P filename: گنجاندن اولیه یک فایل (Pre-include)

فایل filename را از ابتدا ضمیمه می‌کند، به‌گونه‌ای که گویی filename در ابتدای ورودی اضافه شده است. این گزینه برای افزودن ماکروهای چندخطی که -D نمی‌تواند پشتیبانی کند مفید است.

-U macro: لغو تعریف یک ماکرو

تعریف یک ماکروی تک‌خطی را لغو می‌کند (می‌تواند یک ماکروی داخلی باشد یا ماکرویی که پیش‌تر در خط فرمان با -D تعریف شده است).

مثال‌ها (EXAMPLES)

برای اسمبل سورس‌کد ۳۲ بیتی x86 با نحو NASM از source.asm به فایل ELF source.o، با هشدار در مورد برچسب‌های بدون دونقطه (orphan labels):

yasm -f elf32 -Worphan-labels source.asm

برای اسمبل سورس‌کد AMD64 با نحو NASM از x.asm به فایل Win64 object.obj:

yasm -f win64 -o object.obj x.asm

برای اسمبل سورس‌کد x86 با نحو NASM که قبلاً پیش‌پردازش شده است از y.asm به فایل باینری تخت (flat binary) y.com:

yasm -f bin -r raw -o y.com y.asm

عیب‌یابی (DIAGNOSTICS)

دستور yasm در صورت موفقیت با وضعیت 0 خارج می‌شود و در صورت بروز خطا مقداری غیر صفر بازمی‌گرداند.

سازگاری (COMPATIBILITY)

اگرچه تجزیه‌کننده و پیش‌پردازنده NASM در Yasm تلاش می‌کنند تا حد امکان با NASM سازگار باشند، اما به دلیل ساختار داخلی متفاوت Yasm، ناسازگاری‌های اندکی وجود دارد.

تجزیه‌کننده و پیش‌پردازنده GAS در Yasm فاقد تعدادی از ویژگی‌های موجود در GNU AS هستند.

محدودیت‌ها (RESTRICTIONS)

از آنجا که فایل‌های شیء اغلب به معماری و نوع ماشین وابسته هستند، تمام ترکیب‌های قالب‌های شیء، معماری‌ها و ماشین‌ها مجاز نیستند؛ تلاش برای استفاده از یک ترکیب نامعتبر منجر به خطا خواهد شد.

هیچ پشتیبانی از نگاشت نمادها (symbol maps) وجود ندارد.

همچنین ببینید (SEE ALSO)

yasm_arch(7), yasm_dbgfmts(7), yasm_objfmts(7), yasm_parsers(7)

ابزارهای مرتبط: as(1), ld(1), nasm(1)

اشکالات (BUGS)

هنگام استفاده از معماری “x86”، تولید کد AMD64 (با استفاده از دستورالعمل BITS 64) و هم‌زمان تولید یک فایل شیء ۳۲ بیتی (به دلیل عدم تعیین -m amd64 یا عدم انتخاب یک قالب شیء ۶۴ بیتی مانند ELF64 در خط فرمان) بسیار آسان رخ می‌دهد.

نویسنده (AUTHOR)

Peter Johnson <peter@tortall.net>

نویسنده اصلی.