نام (NAME)

rgbfix — ابزار سرایند Game Boy و اصلاح‌کننده checksum

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

rgbfix [-hjsVvw] [-C | -c] [--color when] [-f fix_spec] [-i game_id] [-k licensee_str] [-L logo_file] [-l licensee_id] [-m mbc_type] [-n rom_version] [-o out_file] [-p pad_value] [-r ram_size] [-t title_str] [-W warning] file ...

توضیحات (DESCRIPTION)

برنامه rgbfix هدرهای ایمیج‌های ROM گیم‌بوی (Game Boy) را که معمولاً توسط rgblink(1) تولید شده‌اند تغییر می‌دهد، اگرچه با هر ROM گیم‌بوی دیگری نیز کار خواهد کرد. این برنامه همچنین سایر عملیات درستی‌سنجی مانند پدینگ (padding) را انجام می‌دهد. rgbfix تنها فیلدهایی را تغییر می‌دهد که مقداری برای آن‌ها مشخص شده باشد. به توسعه‌دهندگان توصیه می‌شود پیش از اجرای ، آن فیلدها را در کد منبع خود با بایت‌های 0x00 پر کنند، و فیلدهایی را که با rgbfix مشخص نکرده‌اند از قبل مقداردهی کرده باشند.

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

rgbfix گزینه‌های معمول کوتاه و بلند مانند -V و --version را می‌پذیرد. گزینه‌های بعدی در خط فرمان، مقادیر تنظیم‌شده قبلی را بازنویسی (override) می‌کنند، مگر در مواردی که گزینه‌های تکراری به عنوان خطا در نظر گرفته شوند. گزینه‌ها را می‌توان تا زمانی که سردرگم‌کننده نباشند به صورت مخفف نوشت: --ver همان --version است، اما --v نامعتبر است زیرا می‌تواند به معنای --validate نیز باشد.

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

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

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

-C, --color-only

تنظیم پرچم Game Boy Color–only (0x143) روی 0xC0. این گزینه در صورت تنظیم قبلی -c -، آن را بازنویسی می‌کند.

-c, --color-compatible

تنظیم پرچم Game Boy Color–compatible: (0x143) روی 0x80. این گزینه در صورت تنظیم قبلی -c -، آن را بازنویسی می‌کند.

--color when

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

-f fix_spec, --fix-spec fix_spec

اصلاح مقادیر خاصی از هدر که Game Boy درستی آن‌ها را بررسی می‌کند. همچنین می‌توان با نوشتن معکوس دودویی (binary inverse) آنها، این مقادیر را عمداً تخریب کرد. fix_spec رشته‌ای است شامل هر ترکیبی از نویسه‌های زیر:

l

اصلاح لوگوی Nintendo (0x104–0x133).

L

تخریب لوگوی Nintendo.

h

اصلاح چک‌سام هدر (0x14D).

H

تخریب چک‌سام هدر.

g

اصلاح چک‌سام سراسری (global checksum) (0x14E–0x14F).

G

تخریب چک‌سام سراسری.

-h, --help

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

-i game_id, --game-id game_id

تنظیم رشته شناسه بازی (game ID) (0x13F–0x142) به رشته مشخص‌شده. اگر طول آن بیش از ۴ نویسه باشد، بریده خواهد شد.

-j, --non-japanese

تنظیم پرچم منطقه غیرژاپنی (non-Japanese region) (0x14A) روی 0x01.

-k licensee_str, --new-licensee licensee_str

تنظیم رشته دارنده امتیاز جدید (new licensee) (0x144–0x145) به رشته مشخص‌شده. اگر طول آن بیش از ۲ نویسه باشد، بریده خواهد شد.

-L logo_file, --logo logo_file

مشخص کردن یک فایل لوگو برای استفاده به جای لوگوی رسمی Nintendo. فایل باید شامل ۴۸ بایت از داده‌های تایل 1bpp باشد؛ تصویر منبع باید دارای عرض ۴۸ پیکسل و ارتفاع ۸ پیکسل باشد.

-l licensee_id, --old-licensee licensee_id

تنظیم کد دارنده امتیاز قدیمی (old licensee) (0x14B) به مقدار مشخص‌شده از 0 تا 0xFF. این مقدار منسوخ شده است و در تمامی نرم‌افزارهای جدید باید روی 0x33 تنظیم شود.

-m mbc_type, --mbc-type mbc_type

تنظیم نوع MBC.Pq Ad 0x147 به یک مقدار داده‌شده از 0 تا 0xFF.

این مقدار همچنین می‌تواند نام یک MBC باشد. فهرست نام‌های پذیرفته‌شده را می‌توان با دادن ‘help’ یا ‘list’ به‌عنوان آرگومان به دست آورد. هر میزانی از فاصله‌های خالی (فاصله و تب) در اطراف علامت‌های مثبت مجاز است، و ترتیب «مؤلفه‌ها» آزاد است، تا زمانی که نام MBC در ابتدا باشد. ملاحظات ویژه‌ای برای نگاشت‌گر TPP1 وجود دارد؛ به بخش TPP1 در زیر مراجعه کنید.

-n rom_version, --rom-version rom_version

تنظیم نسخهٔ ROM (0x14C) به یک مقدار داده‌شده از 0 تا 0xFF.

-o out_file, --output out_file

نوشتن تصویر ROM تغییریافته در فایل داده‌شده، یا '-' برای نوشتن در خروجی استاندارد. در صورت عدم تعیین، فایل‌های ورودی درجا تغییر می‌یابند، یا در صورت خوانده شدن از ورودی استاندارد، در خروجی استاندارد نوشته می‌شوند.

-p pad_value, --pad-value pad_value

پد کردن تصویر ROM تا یک اندازهٔ معتبر با یک مقدار پد مشخص از 0 تا 255 (0xFF). rgbfix به‌طور خودکار اندازه‌ای را از 32 KiB، 64 KiB، 128 KiB، ...، 8192 KiB انتخاب خواهد کرد. بایت اندازهٔ کارتریج (0x148) برای بازتاب این اندازهٔ جدید تغییر خواهد کرد. مقدار پد توصیه‌شده 0xFF است، تا سرعت نوشتن ROM روی تراشه‌های فلش افزایش یابد، و از «nop slide»ها به داخل VRAM جلوگیری شود.

-r ram_size, --ram-size ram_size

تنظیم اندازهٔ RAM (0x149) به یک مقدار داده‌شده از 0 تا 0xFF.

-s, --sgb-compatible

تنظیم پرچم SGB (0x146) روی 0x03. این پرچم توسط SGB نادیده گرفته خواهد شد، مگر اینکه کد دارندهٔ مجوز قدیمی (-l) برابر 0x33 باشد!

-t title, --title title

تنظیم رشتهٔ عنوان (0x134–0x143) به یک رشتهٔ داده‌شده. اگر عنوان از بیشینهٔ طول طولانی‌تر باشد، کوتاه خواهد شد. بیشینهٔ طول ۱۱ نویسه است اگر شناسهٔ بازی (-i) مشخص شده باشد، ۱۵ نویسه اگر پرچم CGB (-c یا -C) مشخص شده باشد اما شناسهٔ بازی تعیین نشده باشد، و در غیر این صورت ۱۶ نویسه است.

-V, --version

چاپ نسخهٔ برنامه و خروج.

-v, --validate

معادل با -f lhg.

-W warning, --warning warning

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

-w

غیرفعال کردن تمام خروجی‌های هشدار، حتی زمانی که به خطا تبدیل شده باشند.

@at_file

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

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

-Werror

تبدیل تمام هشدارها به خطا. این مورد را می‌توان با -Wno-error نفی کرد تا از تبدیل همهٔ هشدارها به خطا جلوگیری شود.

-Werror=

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

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

-Wall

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

-Weverything

به معنای واقعی کلمه همهٔ هشدارها را فعال می‌کند.

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

-Wno-mbc

هشدار هنگام وجود ناسازگاری یا نکات قابل‌توجه درباره نوع MBC مشخص‌شده.

-Wno-obsolete

هشدار هنگام مواجهه با قابلیت‌های منسوخی که دیگر پشتیبانی نمی‌شوند و ممکن است بعداً حذف شوند.

-Wno-overwrite

هشدار هنگام بازنویسی بایت‌های غیرصفر متفاوت در سرایند.

-Wno-sgb

هشدار هنگام تداخل پرچم SGB (-s) با کد مجوزدهندهٔ قدیمی (-l).

-Wno-truncation

هشدار هنگام کوتاه کردن مقادیر برای جا شدن در فضای موجود.

مثال‌ها (EXAMPLES)

بیشتر مقادیر موجود در سرایند ROM برای خود کنسول اهمیتی ندارند و به هر حال بیشتر آن‌ها به‌ندرت مفید واقع می‌شوند. حداقل ملزومات برای یک برنامهٔ قابل اجرا، چک‌سام سرایند، لوگوی Nintendo و (در صورت نیاز) پرچم‌های CGB/SGB هستند. همچنین پر کردن (padding) اندازهٔ تصویر تا یک اندازهٔ معتبر ایدهٔ خوبی است (“معتبر” به معنای توانی از ۲، ضرب در 32 KiB).

دستور زیر یک بازی معمولی و غیررنگی Game Boy را بدون بررسی اندازهٔ معتبر می‌سازد:

دستور زیر یک بازی با قابلیت SGB و رنگی با عنوان “foobar” می‌سازد و آن را تا یک اندازهٔ معتبر پر می‌کند. (خود Game Boy از عنوان استفاده نمی‌کند، اما برخی شبیه‌سازها یا مدیران ROM از آن استفاده می‌کنند.)

دستور زیر سرایند بازی “Survival Kids” را بدون چک‌سام سراسری تکثیر می‌کند:

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

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

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

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

تاریخچه (HISTORY)

rgbfix در ابتدا توسط Carsten Sørensen به‌عنوان یک برنامه مستقل به نام GBFix نوشته شد، که سپس در ASMotor قرار گرفت و بعدها در RGBDS توسط Justin Lloyd مجدداً بسته‌بندی شد. این پروژه اکنون توسط چندین مشارکت‌کننده در https://github.com/gbdev/rgbds نگه‌داری می‌شود.