نام (NAME)

rgblink — پیونددهنده Game Boy

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

rgblink [-dhMtVvwx] [-B param] [--color when] [-l linker_script] [-m map_file] [-n sym_file] [-O overlay_file] [-o out_file] [-p pad_value] [-S spec] [-W warning] file ...

توضیحات (DESCRIPTION)

برنامه rgblink فایل‌های شیء RGB را، که معمولاً توسط rgbasm(1) ایجاد می‌شوند، به یک تک‌فایل ROM مربوط به Game Boy پیوند می‌دهد. قالب فایل شیء در rgbds(5) مستند شده است.

بخش‌های ROM0 در ۱۶ کیبی‌بایت نخست ROM خروجی قرار می‌گیرند، و بخش‌های ROMX در هر “بانک” ۱۶ کیبی‌بایتی به جز اولین بانک جای داده می‌شوند. اگر ROM شما تنها ۳۲ کیبی‌بایت باشد، می‌توانید از گزینه -t برای تغییر این رفتار استفاده کنید.

به همین ترتیب، بخش‌های WRAM0 در ۴ کیبی‌بایت نخست WRAM (“بانک ۰”) قرار می‌گیرند، و بخش‌های WRAMX در هر بانکی از ۴ کیبی‌بایت پایانی قرار داده می‌شوند. اگر ROM شما از WRAM بانک‌بندی‌شده استفاده نمی‌کند، می‌توانید از گزینه -w برای تغییر این رفتار استفاده کنید.

همچنین اگر ROM شما برای یک Game Boy تک‌رنگ طراحی شده است، می‌توانید با استفاده از گزینه -d اطمینان حاصل کنید که از هیچ بخش ناسازگاری استفاده نمی‌کنید؛ این گزینه مستلزم -w است و علاوه بر آن، استفاده از VRAM بانک‌بندی‌شده را نیز ممنوع می‌کند.

آرگومان‌ها (ARGUMENTS)

rgblink گزینه‌های کوتاه و طولانی معمول مانند -V و --version را می‌پذیرد. گزینه‌های بعدی در خط فرمان، گزینه‌های تعیین‌شده در قبل را بازنویسی می‌کنند، مگر در مواردی که گزینه‌های تکراری یک خطا تلقی شوند. گزینه‌ها را می‌توان تا زمانی که سردرگمی ایجاد نکنند، مخفف کرد: --verb همان --verbose است، اما --ver نامعتبر است زیرا می‌تواند نشان‌دهنده --version نیز باشد.

مگر در مواردی که خلاف آن ذکر شده باشد، ارسال ‘-’ (یک خط تیره تکی) به‌عنوان نام فایل باعث می‌شود که rgblink از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند. برای لغو این رفتار و باز کردن فایلی در دایرکتوری جاری که نام واقعی آن ‘-’ است، به جای آن ‘./-’ را ارسال کنید. استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور منفرد ممکن است نتایج غیرمنتظره‌ای به همراه داشته باشد.

rgblink اعداد ده‌دهی، شانزده‌شانزدهی، هشت‌هشتی و دودویی را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد. اعداد ده‌دهی طبق معمول نوشته می‌شوند؛ اعداد شانزده‌شانزدهی باید پیشوندی از ‘$’ یا ‘0x’ داشته باشند؛ اعداد هشت‌هشتی باید پیشوندی از ‘&’ یا ‘0o’ داشته باشند؛ و اعداد دودویی باید پیشوندی از ‘%’ یا ‘0b’ داشته باشند. (پیشوندهای ‘$’ و ‘&’ احتمالاً برای جلوگیری از تفسیر توسط پوسته به گریزدهی یا قرار گرفتن در نقل‌قول نیاز دارند.) صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند. برای نمونه، همه موارد زیر معادل یکدیگرند: ‘42’, ‘042’, ‘0x2A’, ‘0X2A’, ‘0x2a’, ‘&52’, ‘0o52’, ‘0O052’, ‘0b00101010’, ‘0B101010’.

گزینه‌های زیر پذیرفته می‌شوند:

-B param, --backtrace param

چگونگی چاپ ردگیری‌های مکانی را هنگام بروز هشدارها یا خطاها پیکربندی می‌کند. این پرچم را می‌توان چندین بار با پارامترهای گوناگون مشخص کرد که به شکل معناداری با یکدیگر ترکیب می‌شوند. اگر param یک عدد مثبت باشد، حداکثر عمق ردگیری را مشخص می‌کند و ردگیری‌های عمیق‌تر را خلاصه می‌سازد. سایر مقادیر معتبر برای پارامتر عبارتند از:

0: حداکثر عمق ردگیری را محدود نکن؛ این مقدار پیش‌فرض است.
all: چاپ اجباری همه مکان‌ها، حتی مکان‌های «بی‌صدا» (برای جزئیات به “Excluding locations from backtraces” در rgbasm(5) مراجعه کنید).
no-all: مکان‌های «بی‌صدا شده» را در ردگیری‌ها چاپ نکن؛ این مقدار پیش‌فرض است.
collapse: چاپ تمام مکان‌ها در یک خط.
no-collapse: چاپ یک مکان در هر خط؛ این مقدار پیش‌فرض است.

--color when

مشخص می‌کند چه زمانی پیام‌های هشدار و خطا با رنگ برجسته شوند: ‘always’, ‘never’, یا ‘auto’. مقدار ‘auto’ بر اساس متغیرهای محیطی ‘NO_COLOR’ یا ‘FORCE_COLOR’ یا اینکه آیا خروجی به یک TTY است، استفاده از رنگ‌ها را تعیین می‌کند.

-d, --dmg

فعال کردن حالت DMG. استفاده از بخش‌هایی را که در یک DMG وجود ندارند، مانند بانک ۱ VRAM، ممنوع می‌کند. این گزینه به طور خودکار -w را فعال می‌کند.

-h, --help

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

-l linker_script, --linkerscript linker_script

یک فایل اسکریپت پیونددهنده را مشخص می‌کند که به پیونددهنده نحوه قرارگیری بخش‌ها در ROM را اعلام می‌نماید. ویژگی‌های تخصیص‌یافته در اسکریپت پیونددهنده باید با ویژگی‌های تخصیص‌یافته در کد همخوانی داشته باشند. برای اطلاعات بیشتر درباره قالب اسکریپت پیونددهنده به rgblink(5) مراجعه کنید.

-M, --no-sym-in-map

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

-m map_file, --map map_file

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

-n sym_file, --sym sym_file

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

-O overlay_file, --overlay overlay_file

در صورت تعیین شدن، بخش‌ها «بر روی» تصویر ROM در overlay_file هم‌پوشانی می‌شوند: فضای خالی بین بخش‌ها با بایت‌های مربوطه از overlay_file پر خواهد شد. این قابلیت برای وصله زدن یک ROM موجود مفید است. توجه داشته باشید که تمام بخش‌ها باید ثابت (بانک و آدرس اجباری) باشند!

-o out_file, --output out_file

تصویر ROM را در فایل داده‌شده می‌نویسد.

-p pad_value, --pad pad_value

هنگام درج لایه‌گذاری بین بخش‌ها، با این مقدار لایه‌گذاری می‌کند. مقدار پیش‌فرض 0 است.

-S spec, --scramble spec

الگوریتم متفاوتی را تحت عنوان “درهم‌ریزی” برای جای‌گذاری بخش‌ها فعال می‌کند. برای توضیح و شرح spec به بخش الگوریتم درهم‌ریزی در ادامه مراجعه کنید.

-t, --tiny

اندازه بخش ROM0 را از ۱۶ کیبی‌بایت به کل ۳۲ کیبی‌بایت اختصاص‌یافته به ROM گسترش می‌دهد. بخش‌های ROMX که به بانکی غیر از ۱ مقید شده‌اند تبدیل به خطا می‌شوند، و سایر بخش‌های ROMX به عنوان ROM0 در نظر گرفته می‌شوند. برای ROMهایی که در ۳۲ کیبی‌بایت جا می‌شوند مفید است.

-V, --version

نسخه برنامه را چاپ کرده و خارج شو.

-v, --verbose

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

چاپ پیکربندی rgblink پیش از انجام اقدامات.
چاپ یک اعلان پیش از اقدامات مهم.
چاپ برخی از نتایج میانی اقدامات.
چاپ برخی اطلاعات اشکال‌زدایی داخلی.
چاپ اطلاعات دقیق داخلی.

سطح پرگویی از ۶ فراتر نمی‌رود.

توجه داشته باشید که خروجی پرگو تنها برای خوانده شدن توسط انسان طراحی شده است و ممکن است بدون اطلاع قبلی بین نسخه‌های RGBDS تغییر کند؛ تکیه بر آن‌ها در اسکریپت‌ها توصیه نمی‌شود.

-W warning, --warning warning

تنظیم پرچم هشدار warning. اگر warning یک پرچم هشدار ناشناخته باشد، پیام هشداری چاپ خواهد شد. برای مشاهده فهرست هشدارها به بخش خطاها (DIAGNOSTICS) مراجعه کنید.

-w, --wramx

اندازه بخش WRAM0 را از ۴ کیبی‌بایت به کل ۸ کیبی‌بایت اختصاص‌یافته به WRAM گسترش می‌دهد. بخش‌های WRAMX که به بانکی غیر از ۱ مقید شده‌اند تبدیل به خطا می‌شوند، و سایر بخش‌های WRAMX به عنوان WRAM0 در نظر گرفته می‌شوند.

-x, --nopad

لایه‌گذاری انتهای فایل نهایی را غیرفعال می‌کند. این گزینه به طور خودکار -t را فعال می‌کند. می‌توانید از این گزینه برای ایجاد فایل‌های باینری که ROM نیستند استفاده کنید. هنگام ساخت ROM، توجه داشته باشید که عدم استفاده از این گزینه جایگزینی برای گزینه -p برنامه rgbfix(1) نیست!

@at_file

گزینه‌ها و آرگومان‌های بیشتری را از یک فایل می‌خواند، گویی محتویات آن در خط فرمان ارائه شده است. آرگومان‌ها با فاصله خالی یا خط جدید جدا می‌شوند. خطوطی که با علامت هش (‘#’) شروع می‌شوند دیدگاه محسوب شده و نادیده گرفته می‌شوند.

هیچ پردازش پوسته‌ای مانند بسط نویسه‌های عام یا بسط متغیرها انجام نمی‌شود. هیچ پشتیبانی برای گریزدهی یا نقل‌قول کردن فاصله‌های خالی برای گنجاندن در آرگومان‌ها وجود ندارد. گزینه استاندارد ‘--’ برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند. توجه داشته باشید که با اینکه ‘--’ می‌تواند درون یک at-file استفاده شود، تنها پردازش گزینه را درون آن at-file غیرفعال می‌کند و پردازش در دامنه والد ادامه می‌یابد.

الگوریتم درهم‌ریزی

الگوریتم پیش‌فرض جای‌گذاری بخش‌ها تلاش می‌کند بخش‌ها را در کمترین تعداد بانک ممکن جای دهد. (مشخص شده است که جای‌گذاری بخش‌ها یک مسئله NP-کامل موسوم به «بسته‌بندی سطل‌ها» است، بنابراین rgblink تلاشی برای یافتن راه‌حل بهینه نمی‌کند، بلکه از یک روش اکتشافی «اولین برازش» برای یافتن پاسخی مناسب در مدت زمانی معقول استفاده می‌نماید.) هیچ تضمینی در مورد محل قرارگیری بخش‌ها توسط این الگوریتم، فارغ از محدودیت‌های بانک، آدرس و ترازسازی که به طور دستی برای بخش‌ها تعیین شده‌اند، وجود ندارد.

“درهم‌ریزی” در عوض، بخش‌ها را درون یک استخر داده‌شده از بانک‌ها جای می‌دهد و تلاش می‌کند تعداد بخش‌هایی را که یک بانک مشترک دارند به حداقل برساند. این قابلیت برای شناسایی فرضیات نادرست در مورد بانک‌ها مفید است، مانند انتظار اینکه دو بخش مختلف در یک بانک قرار گیرند (این امر تضمین نمی‌شود مگر اینکه برای هر دوی آن‌ها به طور دستی شماره بانک یکسانی تعیین شده باشد). همچنان هیچ تضمینی در مورد مکان قرارگیری بخش‌ها توسط این الگوریتم، به جز اندازه استخر بانک‌ها و هرگونه محدودیت‌های دستی تعیین‌شده برای بخش‌ها، وجود ندارد.

یک مشخصه درهم‌ریزی فهرستی جداشده با کاما از مشخصه‌های ناحیه است. یک کامای انتهایی، و همچنین فاصله خالی میان تمامی مشخصه‌ها و مؤلفه‌های آن‌ها مجاز است. هر مشخصه ناحیه به شکل زیر است:

region[=size]

region نوع بخش را مشخص می‌کند، و size تعداد بانک‌های موجود در استخر را برای آن نوع بخش تعیین می‌نماید. region باید یکی از مقادیر زیر باشد (غیرحساس به بزرگی و کوچکی حروف)، در حالی که size باید یک عدد صحیح مثبت ده‌دهی بین ۱ و حداکثر مقدار مربوطه باشد. برخی نواحی اجازه حذف اندازه را می‌دهند، که در این صورت مقدار پیش‌فرض آن برابر با بیشینه مقدار آن خواهد بود.

نام ناحیه	بیشینه اندازه	اندازه اختیاری
`romx`	65535	خیر
`sram`	255	خیر
`wramx`	7	بله

یک size برابر با ۰ درهم‌ریزی را برای آن ناحیه غیرفعال می‌کند.

برای نمونه، ‘romx=64,wramx,sram=4’ بخش‌های ROMX را میان بانک‌های ROM از ۱ تا ۶۴، بخش‌های WRAMX را میان بانک‌های RAM از ۱ تا ۷، و بخش‌های SRAM را میان بانک‌های SRAM از ۰ تا ۳ درهم می‌ریزد.

مشخصه‌های ناحیه که بعدتر می‌آیند موارد پیشین را باطل و بازنویسی می‌کنند؛ برای مثال، ‘romx=42, Romx=0’ درهم‌ریزی را برای romx غیرفعال می‌کند.

درهم‌ریزی wramx در صورت ارسال -w (از جمله اگر توسط -d اعمال شده باشد) در سکوت نادیده گرفته می‌شود، زیرا بخش‌های WRAMX به‌عنوان WRAM0 در نظر گرفته خواهند شد.

خطاها (DIAGNOSTICS)

هشدارها پیام‌های تشخیصی هستند که رفتارهای احتمالاً اشتباهی را نشان می‌دهند که لزوماً روند پیوند زدن را مختل نمی‌کنند. گزینه‌های زیر نحوه پردازش هشدارها را تغییر می‌دهند.

-Werror: تبدیل همه هشدارها به خطا. می‌توان این گزینه را با -Wno-error نقیض کرد تا از تبدیل تمام هشدارها به خطا جلوگیری شود.
-Werror=: تبدیل هشدار یا فرا-هشدار مشخص‌شده به خطا. نام یک هشدار پیوست می‌شود (مثال: -Werror=obsolete -،) و این هشدار به طور ضمنی فعال شده و به یک خطا تبدیل می‌شود. می‌توان این را با -Wno-error= نقیض کرد تا از تبدیل یک هشدار مشخص به خطا جلوگیری شود، حتی اگر -Werror فعال باشد.

هشدارهای زیر فرا-هشدار (“meta”) هستند، که مجموعه‌ای از هشدارهای دیگر را فعال می‌کنند. اگر یک هشدار مشخص هم از طریق یک پرچم فرا و هم یک پرچم خاص تغییر وضعیت دهد، پرچم خاص‌تر اولویت دارد. موقعیت در خط فرمان به عنوان معیار تعیین‌کننده نهایی عمل می‌کند و آخرین مورد اثرگذار خواهد بود.

-Wall: این گزینه هشدارهایی را فعال می‌کند که احتمالاً نشان‌دهنده یک خطا یا رفتار نامطلوب هستند و می‌توانند به‌راحتی برطرف شوند.
-Weverything: دقیقاً تک‌تک هشدارها را فعال می‌کند.

هشدارهای زیر پرچم‌های واقعی هشدار هستند؛ همراه با هر شرح، پرچم هشدار مربوطه نیز آورده شده است. توجه داشته باشید که هر یک از این پرچم‌ها دارای یک نقیض نیز هستند (برای مثال، -Wobsolete هشداری را فعال می‌کند که -Wno-obsolete آن را غیرفعال می‌سازد؛ و -Wall هر هشداری را که -Wno-all غیرفعال می‌کند، فعال می‌سازد). در اینجا فقط پرچم‌های غیرپیش‌فرض فهرست شده‌اند. با صرف‌نظر از پیشوند “no-،” مدخل‌ها بر اساس حروف الفبا فهرست شده‌اند.

-Wno-assert: هنگامی که ادعاهای نوع WARN شکست می‌خورند، هشدار بده. (برای ASSERT به “Aborting the assembly process” در rgbasm(5) مراجعه کنید).
-Wdiv: هنگام تقسیم کوچک‌ترین عدد صحیح منفی (-2**31) بر -1 هشدار بده، که به دلیل سرریز عدد صحیح خودِ آن عدد حاصل می‌شود. این هشدار توسط -Wall فعال می‌شود.
-Wno-large-constant: هنگام مواجهه با ثابتی که بزرگ‌تر از آن است که در یک عدد صحیح ۳۲ بیتی علامت‌دار بگنجد، هشدار بده.
-Wno-obsolete: هنگام مواجهه با ویژگی‌های منسوخ‌شده هشدار بده، که منسوخ شده‌اند و ممکن است در آینده حذف شوند.
-Wshift: هنگام شیفت دادن یک مقدار منفی به راست هشدار بده. به جای آن از تقسیم بر 2**N استفاده کنید. این هشدار توسط -Wall فعال می‌شود.
-Wshift-amount: هنگامی که عملوندِ شیفت منفی یا بزرگ‌تر از ۳۲ باشد، هشدار بده. این هشدار توسط -Wall فعال می‌شود.
-Wtruncation=: هنگامی که یک کوتاه کردن ضمنی (برای مثال، db به یک مقدار ۸ بیتی) باعث از دست رفتن برخی بیت‌ها شود، هشدار بده. -Wtruncation=0 یا -Wno-truncation این هشدار را غیرفعال می‌کند. -Wtruncation=1 یا صرفاً -Wtruncation زمانی هشدار می‌دهد که یک مقدار N بیتی، برابر یا بزرگ‌تر از 2**N یا کوچک‌تر از -2**N باشد. -Wtruncation=2 علاوه بر این زمانی هشدار می‌دهد که یک مقدار N بیتی کمتر از -2**(N-1) باشد، که در کدگذاری مکمل دو نمی‌گنجد.

مثال‌ها (EXAMPLES)

تنها چیزی که برای یک ROM پایه‌ای نیاز دارید یک فایل شیء است که می‌توان آن را به شکل زیر به یک تصویر ROM تبدیل کرد:

$ rgblink -o bar.gb
  foo.o

فایل حاصل bar.gb دارای مجموع‌های مقابله‌ای صحیح نخواهد بود (مگر اینکه آن‌ها را در سورس اسمبلی قرار داده باشید). شما باید از rgbfix(1) برای اصلاح این موارد استفاده کنید تا برنامه واقعاً در یک Game Boy اجرا شود:

$ rgbfix -v bar.gb

در اینجا یک مثال کامل‌تر آورده شده است:

$ rgblink -o bin/game.gb -n
  bin/game.sym -p 0xFF obj/title.o obj/engine.o

گزارش باگ‌ها (BUGS)

لطفاً باگ‌ها یا اشتباهات موجود در این مستندات را در GitHub گزارش دهید.

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

rgbasm(1), rgblink(5), rgbfix(1), rgbgfx(1), gbz80(7), rgbds(5), rgbds(7)

تاریخچه (HISTORY)

rgblink در ابتدا توسط Carsten Sørensen به‌عنوان بخشی از بسته ASMotor نوشته شد و بعداً توسط Justin Lloyd در RGBDS مجدداً بسته‌بندی گردید. این پروژه اکنون توسط تعدادی از مشارکت‌کنندگان در https://github.com/gbdev/rgbds نگه‌داری می‌شود.