RGBDS(5)

File Formats Manual

RGBDS(5)

نام (NAME)

rgbds — مستندات قالب فایل شیء

توضیحات (DESCRIPTION)

این توضیحات مربوط به قالب فایل شیء RGB است که توسط rgbasm(1) تولید شده و توسط rgblink(1) خوانده می‌شود.

ساختار فایل (FILE STRUCTURE)

انواع داده‌های زیر استفاده می‌شوند:

LONG یک عدد صحیح ۳۲ بیتی ذخیره‌شده در قالب با ترتیب بایت کم‌ارزش (little-endian) است. BYTE یک عدد صحیح ۸ بیتی است. STRING یک رشته از BYTE است که به 0 ختم می‌شود. کروشه‌های بعد از یک نوع (مانند LONG[n]) نشان‌دهنده n عنصر متوالی است (در اینجا، LONGها). همه اقلام به صورت متوالی و بدون پرشدگی (padding) ذخیره می‌شوند—این همچنین بدان معناست که ممکن است در فایل تراز نشده باشند!

REPT n نشان می‌دهد که فیلدهای بین REPT و ENDR متناظر، به تعداد n بار تکرار می‌شوند.

تمام شناسه‌ها به شیءهای درون فایل ارجاع دارند؛ برای نمونه، شناسه نماد به دومین نماد تعریف‌شده در آرایه Symbols این فایل شیء اشاره دارد. تنها استثنا گره‌های Source file info هستند که شناسه‌های آن‌ها معکوس است، یعنی شناسه گره منبع /bin/zsh به آخرین گره در آرایه اشاره دارد، نه اولین گره. ارجاع به فایل‌های شیء دیگر از طریق واردسازی‌ها (نمادها)، با نام (بخش‌ها) و غیره انجام می‌شود—اما هرگز با شناسه (ID).

BYTE Magic[4]: "RGB9"
LONG RevisionNumber: شماره بازنگری قالبی که این فایل استفاده می‌کند. (این مقدار همیشه در تمام بازنگری‌ها در یک مکان ثابت قرار دارد.)
LONG NumberOfSymbols: تعداد نمادهای تعریف‌شده در این فایل شیء.
LONG NumberOfSections: تعداد بخش‌های تعریف‌شده در این فایل شیء.

اطلاعات فایل منبع (Source file info)

LONG NumberOfNodes

تعداد گره‌های زمینه منبع موجود در این فایل.

REPT NumberOfNodes

LONG ParentID

شناسه گره والد؛ مقدار -1 به این معناست که این گره ریشه است.

مهم: گره‌ها در واقع به ترتیب معکوس نوشته می‌شوند، به این معنی که گره با شناسه 0 آخرین گره در فهرست است!

LONG ParentLineNo

شماره خطی که زمینه گره والد در آن ترک شده است؛ برای گره ریشه بی‌معنی است.

BYTE Type

بیت‌های 0 تا 6 نوع گره را نشان می‌دهند:

Value	Meaning
0	گره REPT
1	گره File
2	گره Macro

تنظیم بودن بیت 7 به این معناست که گره "بی‌صدا" شده است (بخش “Excluding locations from backtraces” را در rgbasm(5) ببینید).

IF Type ≠ 0

اگر گره از نوع REPT نباشد...

STRING Name: نام گره: یا نام فایل، یا نام ماکرو با پیشوند نام فایل تعریف آن (مانند ‘src/includes/defines.asm::error’).

ELSE

اگر گره یک REPT باشد، شمارنده تکرار تمام REPTهای والد را نیز در بر دارد.

LONG Depth
LONG Iter[Depth]: تعداد تکرارهای REPT، با افزایش عمق.

ENDC

ENDR

نمادها (Symbols)

REPT NumberOfSymbols

STRING Name

نام این نماد. نمادهای محلی با نام کامل خود ذخیره می‌شوند (‘Scope.symbol’).

BYTE Type

Value	Meaning
0	Local نماد محلی تنها در این فایل استفاده می‌شود.
1	Import واردسازی یک نماد صادرشده (با نام) از یک فایل شیء دیگر.
2	Exported نماد صادرشده قابل مشاهده از سایر فایل‌های شیء.

IF Type ≠ 1

اگر نماد در این فایل شیء تعریف شده باشد...

LONG NodeID: زمینه‌ای که نماد در آن تعریف شده است.
LONG LineNo: شماره خط در زمینه‌ای که نماد در آن تعریف شد.
LONG SectionID: شناسه بخشی که نماد در آن تعریف شده است. اگر نماد متعلق به هیچ بخش خاصی نباشد (یعنی یک مقدار ثابت باشد)، این فیلد حاوی -1 است.
LONG Value: مقدار نماد. اگر نماد متعلق به یک بخش باشد، این مقدار آفست درون بخش آن نماد است.

ENDC

ENDR

بخش‌ها (Sections)

REPT NumberOfSections

STRING Name

نام بخش.

LONG NodeID

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

LONG LineNo

شماره خط در زمینه‌ای که بخش در آن تعریف شد.

LONG Size

اندازه بخش بر حسب بایت.

BYTE Type

بیت‌های 0 تا 2 نوع بخش را مشخص می‌کنند:

Value	Meaning
0	WRAM0
1	VRAM
2	ROMX
3	ROM0
4	HRAM
5	WRAMX
6	SRAM
7	OAM

تنظیم بودن بیت 7 به این معنی است که بخش یک "union" است (بخش “Unionized sections” را در rgbasm(5) ببینید). تنظیم بودن بیت 6 به این معنی است که بخش یک "fragment" است (بخش “Section fragments” را در rgbasm(5) ببینید). این دو بیت مانعه‌الجمع هستند.

LONG Address

نشانی که این بخش باید در آن قرار گیرد. این نشانی باید برای Type بخش معتبر باشد (همانند فلگ‌های -t -یا -d -در rgblink(1)), یا -1 برای نشان دادن اینکه پیونددهنده باید به طور خودکار تصمیم بگیرد (بخش “شناور است”).

LONG Bank

شناسه بانک حافظه‌ای که این بخش باید در آن قرار گیرد. این مقدار باید برای Type بخش معتبر باشد، یا -1 تا پیونددهنده به صورت خودکار تصمیم‌گیری کند.

BYTE Alignment

تعداد بیت‌هایی از نشانی بخش که باید برابر با AlignOfs باشد، با شروع از کم‌ارزش‌ترین بیت.

LONG AlignOfs

آفست تراز. باید اکیداً کمتر از ‘

1 <<
          Alignment

’ باشد.

IF Type = 2 || Type = 3

اگر بخش از نوع ROM باشد، حاوی داده است.

BYTE Data[Size]

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

LONG NumberOfPatches

تعداد وصله‌هایی که باید روی Data این بخش اعمال شوند.

REPT NumberOfPatches

LONG NodeID

زمینه‌ای که وصله در آن تعریف شده است.

LONG LineNo

شماره خط در زمینه‌ای که وصله در آن تعریف شد.

LONG Offset

آفست درون Data بخش که وصله باید در آن اعمال شود. نباید بزرگ‌تر از Size بخش منهای اندازه وصله باشد (Type را در زیر ببینید).

LONG PCSectionID

شناسه بخشی که شمارنده برنامه (PC) در آن قرار دارد. (این مورد معمولاً همان بخشی است که وصله در آن اعمال می‌شود، به جز برای مواردی مانند بلوک‌های ‘LOAD’ ، “RAM code” را در rgbasm(5) ببینید.)

LONG PCOffset

آفست نماد PC درون بخشی که توسط PCSectionID مشخص شده است. انتظار می‌رود برای عملوندهای دستورالعمل، PC به اولین بایت دستور اشاره کند (یعنی ‘jp @’ باید یک حلقه بی‌نهایت باشد)، و در غیر این صورت به اولین بایت وصله اشاره کند (‘db’, ‘dw’, ‘dl’).

BYTE Type

Value	Meaning
0	وصله تک‌بایتی
1	وصله دو بایتی با ترتیب بایت کم‌ارزش
2	وصله چهار بایتی با ترتیب بایت کم‌ارزش
3	وصله تک‌بایتی ‘`jr`’ ؛ مقدار وصله از PC + 2 کم خواهد شد (یعنی ‘`jr @`’ باید حلقه بی‌نهایت ‘`18 FE`’ باشد) .

LONG RPNSize

اندازه RPNExpr زیر.

BYTE RPNExpr[RPNSize]

مقدار وصله، کدگذاری‌شده به عنوان عبارت RPN (RPN expressions را ببینید).

ENDR

ENDC

تصدیق‌ها (Assertions)

LONG NumberOfAssertions

تعداد تصدیق‌هایی که این فایل شیء شامل می‌شود.

REPT NumberOfAssertions

تصدیق‌ها اساساً وصله‌هایی به همراه یک پیام هستند.

LONG NodeID

زمینه‌ای که تصدیق در آن تعریف شده است.

LONG LineNo

شماره خط در زمینه‌ای که تصدیق در آن تعریف شد.

LONG Offset

بخش استفاده‌نشده باقی‌مانده از ساختار وصله.

LONG PCSectionID

شناسه بخشی که PC در آن قرار دارد.

LONG PCOffset

آفست نماد PC درون بخش مشخص‌شده توسط PCSectionID.

BYTE Type

توصیف می‌کند در صورتی که عبارت به یک مقدار غیرصفر ارزیابی شود چه رخ می‌دهد.

Value	Meaning
0	چاپ پیام هشدار، و ادامه اتصال به طور عادی.
1	چاپ پیام خطا، به طوری که پیوند با شکست مواجه می‌شود، اما سایر تصدیق‌ها نیز ارزیابی می‌شوند.
2	چاپ پیام خطای مهلک، و خروج و توقف فوری.

LONG RPNSize

اندازه RPNExpr زیر.

BYTE RPNExpr[RPNSize]

مقدار وصله، کدگذاری‌شده به عنوان یک عبارت RPN (RPN expressions را ببینید).

STRING Message

پیامی که در صورت ارزیابی عبارت به مقدار غیرصفر نمایش داده می‌شود. در صورت خالی بودن، پیامی عمومی نمایش داده خواهد شد.

ENDR

عبارات RPN (RPN expressions)

عبارات در فایل شیء به صورت RPN یا “نشانه‌گذاری لهستانی معکوس” ذخیره می‌شوند؛ نشانه‌گذاری‌ای که امکان محاسبه عبارات دلخواه را با یک پشته ساده فراهم می‌سازد. برای نمونه، عبارت ‘2 5 -’ ابتدا مقدار “2” را در پشته قرار می‌دهد، سپس “5”. عملگر ‘-’ دو آرگومان را از پشته برمی‌دارد، آن‌ها را تفریق می‌کند و سپس نتیجه (“3”) را در پشته برمی‌گرداند. یک عبارت RPN خوش‌ساخت هرگز سعی نمی‌کند از یک پشته خالی داده بردارد، و در پایان دقیقاً یک مقدار در آن باقی می‌گذارد.

مجموعه ابزار RGBDS عبارات RPN را به عنوان آرایه‌ای از BYTE ها کدگذاری می‌کند. اولین بایت یا یک عملگر را کدگذاری می‌کند یا یک مقدار ثابت که بایت‌های BYTE بیشتری را پس از خود مصرف می‌کند:

Value	Meaning
`/bin/zsh`	عملگر جمع (‘`+`’)
	عملگر تفریق (‘`-`’)
	عملگر ضرب (‘`*`’)
	عملگر تقسیم (‘`/`’)
	عملگر باقی‌مانده (‘`%`’)
	منفی‌سازی (‘`- یکانی`’)
	عملگر توان (‘`**`’)
	عملگر OR بیتی (‘`\|`’)
	عملگر AND بیتی (‘`&`’)
	عملگر XOR بیتی (‘`^`’)
	عملگر مکمل بیتی (‘`~ یکانی`’)
	عملگر AND منطقی (‘`&&`’)
	عملگر OR منطقی (‘`\|\|`’)
	عملگر نقیض منطقی (‘`! یکانی`’)
	عملگر برابری (‘`==`’)
	عملگر نابرابری (‘`!=`’)
	عملگر بزرگ‌تر (‘`>`’)
	عملگر کوچک‌تر (‘`<`’)
	عملگر بزرگ‌تر یا مساوی (‘`>=`’)
	عملگر کوچک‌تر یا مساوی (‘`<=`’)
	عملگر شیفت به چپ (‘`<<`’)
	عملگر شیفت حسابی/علامت‌دار به راست (‘`>>`’)
	عملگر شیفت منطقی/بدون‌علامت به راست (‘`>>>`’)
	`BANK`(`symbol`, `؛`) به همراه شناسه `LONG` مربوط به `symbol`.
	`BANK`(`section`, `؛`) به همراه نام `STRING` مربوط به `section`.
	شناسه `BANK`(`مربوط`, `به`, `PC`) (یعنی ‘`BANK(@)`’).
	`SIZEOF`(`section`, `؛`) به همراه نام `STRING` مربوط به `section`.
	`STARTOF`(`section`, `؛`) به همراه نام `STRING` مربوط به `section`.
	`SIZEOF`(`sectiontype`, `؛`) به همراه مقدار `BYTE` مربوط به `sectiontype` (مقادیر `Type را در` Sections ببینید).
	`STARTOF`(`sectiontype`, `؛`) به همراه مقدار `BYTE` مربوط به `sectiontype` (مقادیر `Type را در` Sections ببینید).
	بررسی ‘`ldh`’. بررسی می‌کند که آیا مقدار یک عملوند معتبر ‘`ldh`’ است (“Load Instructions” را در gbz80(7) ببینید), یعنی اینکه آیا مقدار بین /bin/zsh و ، یا بین و قرار دارد یا خیر. سپس مقدار با /bin/zshFF عملیات AND می‌شود (‘`&`’).
	بررسی ‘`rst`’. بررسی می‌کند که آیا مقدار یک بردار معتبر ‘`rst`’ است (“RST vec” را در gbz80(7) ببینید), یعنی یکی از مقادیر /bin/zsh، ، ، ، ، ، ، یا . سپس مقدار با عملیات OR می‌شود (‘`\|`’).
	بررسی ‘`bit/res/set`’ ؛ به همراه ماسک `BYTE` دستورالعمل. بررسی می‌کند که آیا مقدار یک شاخص بیت معتبر است یا خیر (برای نمونه “BIT u3, r8” را در gbz80(7) ببینید), یعنی از 0 تا 7. سپس مقدار با ماسک دستورالعمل OR می‌شود.
	بایت `HIGH`.
	بایت `LOW`.
	مقدار `BITWIDTH`.
	مقدار `TZCOUNT`.
	عدد صحیح ثابت؛ به همراه عدد صحیح `LONG`.
	مقدار یک نماد؛ به همراه شناسه `LONG` نماد.

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

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

تاریخچه (HISTORY)

ابزارهای rgbasm(1) و rgblink(1) در ابتدا توسط Carsten Sørensen به عنوان بخشی از بسته ASMotor نوشته شدند، و بعداً در RGBDS توسط Justin Lloyd بازبسته‌بندی شدند. در حال حاضر توسط گروهی از مشارکت‌کنندگان در https://github.com/gbdev/rgbds نگهداری می‌شود.

August 1, 2026

Linux 6.12.107+deb13-amd64