." SPDX-License-Identifier: MIT ." .Dd August 1, 2026 .Dt RGBDS 5 .Os .Sh "نام (NAME)" .Nm rgbds .Nd مستندات قالب فایل شیء .Sh "توضیحات (DESCRIPTION)" این توضیحات مربوط به قالب فایل شیء RGB است که توسط .Xr rgbasm 1 تولید شده و توسط .Xr rgblink 1 خوانده می‌شود. .Sh "ساختار فایل (FILE STRUCTURE)" انواع داده‌های زیر استفاده می‌شوند: .Pp .Cm LONG یک عدد صحیح ۳۲ بیتی ذخیره‌شده در قالب با ترتیب بایت کم‌ارزش (little-endian) است. .Cm BYTE یک عدد صحیح ۸ بیتی است. .Cm STRING یک رشته از .Cm BYTE است که به 0 ختم می‌شود. کروشه‌های بعد از یک نوع .Pq مانند Cm LONG Ns Bq Ar n نشان‌دهنده .Ar n عنصر متوالی است .Pq در اینجا، Cm LONG Ns ها . همه اقلام به صورت متوالی و بدون پرشدگی (padding) ذخیره می‌شوند\(emاین همچنین بدان معناست که ممکن است در فایل تراز نشده باشند! .Pp .Cm REPT Ar n نشان می‌دهد که فیلدهای بین .Cm REPT و .Cm ENDR متناظر، به تعداد .Ar n بار تکرار می‌شوند. .Pp تمام شناسه‌ها به شیءهای درون فایل ارجاع دارند؛ برای نمونه، شناسه نماد به دومین نماد تعریف‌شده در آرایه .Sx Symbols این فایل شیء اشاره دارد. تنها استثنا گره‌های .Sx Source file info هستند که شناسه‌های آن‌ها معکوس است، یعنی شناسه گره منبع /bin/zsh به .Em آخرین گره در آرایه اشاره دارد، نه اولین گره. ارجاع به فایل‌های شیء دیگر از طریق واردسازی‌ها (نمادها)، با نام (بخش‌ها) و غیره انجام می‌شود\(emاما هرگز با شناسه (ID). .Ss "هدر (Header)" .Bl -tag -width Ds -compact .It Cm BYTE Ar Magic[4] "RGB9" .It Cm LONG Ar RevisionNumber شماره بازنگری قالبی که این فایل استفاده می‌کند. .Pq این مقدار همیشه در تمام بازنگری‌ها در یک مکان ثابت قرار دارد. .It Cm LONG Ar NumberOfSymbols تعداد نمادهای تعریف‌شده در این فایل شیء. .It Cm LONG Ar NumberOfSections تعداد بخش‌های تعریف‌شده در این فایل شیء. .El .Ss "اطلاعات فایل منبع (Source file info)" .Bl -tag -width Ds -compact .It Cm LONG Ar NumberOfNodes تعداد گره‌های زمینه منبع موجود در این فایل. .It Cm REPT Ar NumberOfNodes .Bl -tag -width Ds -compact .It Cm LONG Ar ParentID شناسه گره والد؛ مقدار -1 به این معناست که این گره ریشه است. .Pp .Sy مهم : گره‌ها در واقع به ترتیب .Sy معکوس نوشته می‌شوند، به این معنی که گره با شناسه 0 آخرین گره در فهرست است! .It Cm LONG Ar ParentLineNo شماره خطی که زمینه گره والد در آن ترک شده است؛ برای گره ریشه بی‌معنی است. .It Cm BYTE Ar Type بیت‌های 0 تا 6 نوع گره را نشان می‌دهند: .Bl -column "Value" -compact .It Sy Value Ta Sy Meaning .It 0 Ta گره REPT .It 1 Ta گره File .It 2 Ta گره Macro .El .Pp تنظیم بودن بیت 7 به این معناست که گره "بی‌صدا" شده است .Pq بخش Do Excluding locations from backtraces Dc را در Xr rgbasm 5 ببینید . .It Cm IF Ar Type No \(!= 0 اگر گره از نوع REPT نباشد... .Pp .Bl -tag -width Ds -compact .It Cm STRING Ar Name نام گره: یا نام فایل، یا نام ماکرو با پیشوند نام فایل تعریف آن .Pq مانند Ql src/includes/defines.asm::error . .El .It Cm ELSE اگر گره یک REPT باشد، شمارنده تکرار تمام REPTهای والد را نیز در بر دارد. .Pp .Bl -tag -width Ds -compact .It Cm LONG Ar Depth .It Cm LONG Ar Iter Ns Bq Ar Depth تعداد تکرارهای REPT، با افزایش عمق. .El .It Cm ENDC .El .It Cm ENDR .El .Ss "نمادها (Symbols)" .Bl -tag -width Ds -compact .It Cm REPT Ar NumberOfSymbols .Bl -tag -width Ds -compact .It Cm STRING Ar Name نام این نماد. نمادهای محلی با نام کامل خود ذخیره می‌شوند .Pq Ql Scope.symbol . .It Cm BYTE Ar Type .Bl -column "Value" -compact .It Sy Value Ta Sy Meaning .It 0 Ta Sy Local No نماد محلی تنها در این فایل استفاده می‌شود . .It 1 Ta Sy Import No واردسازی یک نماد صادرشده (با نام) از یک فایل شیء دیگر . .It 2 Ta Sy Exported No نماد صادرشده قابل مشاهده از سایر فایل‌های شیء . .El .It Cm IF Ar Type No \(!= 1 اگر نماد در این فایل شیء تعریف شده باشد... .Pp .Bl -tag -width Ds -compact .It Cm LONG Ar NodeID زمینه‌ای که نماد در آن تعریف شده است. .It Cm LONG Ar LineNo شماره خط در زمینه‌ای که نماد در آن تعریف شد. .It Cm LONG Ar SectionID شناسه بخشی که نماد در آن تعریف شده است. اگر نماد متعلق به هیچ بخش خاصی نباشد (یعنی یک مقدار ثابت باشد)، این فیلد حاوی -1 است. .It Cm LONG Ar Value مقدار نماد. اگر نماد متعلق به یک بخش باشد، این مقدار آفست درون بخش آن نماد است. .El .It Cm ENDC .El .It Cm ENDR .El .Ss "بخش‌ها (Sections)" .Bl -tag -width Ds -compact .It Cm REPT Ar NumberOfSections .Bl -tag -width Ds -compact .It Cm STRING Ar Name نام بخش. .It Cm LONG Ar NodeID زمینه‌ای که بخش در آن تعریف شده است. .It Cm LONG Ar LineNo شماره خط در زمینه‌ای که بخش در آن تعریف شد. .It Cm LONG Ar Size اندازه بخش بر حسب بایت. .It Cm BYTE Ar Type بیت‌های 0 تا 2 نوع بخش را مشخص می‌کنند: .Bl -column "Value" -compact .It Sy Value Ta Sy Meaning .It 0 Ta WRAM0 .It 1 Ta VRAM .It 2 Ta ROMX .It 3 Ta ROM0 .It 4 Ta HRAM .It 5 Ta WRAMX .It 6 Ta SRAM .It 7 Ta OAM .El .Pp تنظیم بودن بیت 7 به این معنی است که بخش یک "union" است .Pq بخش Do Unionized sections Dc را در Xr rgbasm 5 ببینید . تنظیم بودن بیت 6 به این معنی است که بخش یک "fragment" است .Pq بخش Do Section fragments Dc را در Xr rgbasm 5 ببینید . این دو بیت مانعه‌الجمع هستند. .It Cm LONG Ar Address نشانی که این بخش باید در آن قرار گیرد. این نشانی باید برای .Ar Type بخش معتبر باشد .Pq همانند فلگ‌های Fl t یا Fl d در Xr rgblink 1 , یا -1 برای نشان دادن اینکه پیونددهنده باید به طور خودکار تصمیم بگیرد .Pq بخش Dq شناور است . .It Cm LONG Ar Bank شناسه بانک حافظه‌ای که این بخش باید در آن قرار گیرد. این مقدار باید برای .Ar Type بخش معتبر باشد، یا -1 تا پیونددهنده به صورت خودکار تصمیم‌گیری کند. .It Cm BYTE Ar Alignment تعداد بیت‌هایی از نشانی بخش که باید برابر با .Ar AlignOfs باشد، با شروع از کم‌ارزش‌ترین بیت. .It Cm LONG Ar AlignOfs آفست تراز. باید اکیداً کمتر از .Ql 1 << Ar Alignment باشد. .It Cm IF Ar Type No \(eq 2 || Ar Type No \(eq 3 اگر بخش از نوع ROM باشد، حاوی داده است. .Pp .Bl -tag -width Ds -compact .It Cm BYTE Ar Data Ns Bq Size داده‌های خام بخش. بایت‌هایی که باید وصله شوند باید وجود داشته باشند، حتی اگر محتوای آن‌ها بازنویسی شود. .It Cm LONG Ar NumberOfPatches تعداد وصله‌هایی که باید روی .Ar Data این بخش اعمال شوند. .It Cm REPT Ar NumberOfPatches .Bl -tag -width Ds -compact .It Cm LONG Ar NodeID زمینه‌ای که وصله در آن تعریف شده است. .It Cm LONG Ar LineNo شماره خط در زمینه‌ای که وصله در آن تعریف شد. .It Cm LONG Ar Offset آفست درون .Ar Data بخش که وصله باید در آن اعمال شود. نباید بزرگ‌تر از .Ar Size بخش منهای اندازه وصله باشد .Pq Ar Type را در زیر ببینید . .It Cm LONG Ar PCSectionID شناسه بخشی که شمارنده برنامه (PC) در آن قرار دارد. (این مورد معمولاً همان بخشی است که وصله در آن اعمال می‌شود، به جز برای مواردی مانند بلوک‌های .Ql LOAD ، .Do RAM code Dc را در Xr rgbasm 5 ببینید . ) .It Cm LONG Ar PCOffset آفست نماد PC درون بخشی که توسط .Ar PCSectionID مشخص شده است. انتظار می‌رود برای عملوندهای دستورالعمل، PC به اولین بایت دستور اشاره کند (یعنی .Ql jp @ باید یک حلقه بی‌نهایت باشد)، و در غیر این صورت به اولین بایت وصله اشاره کند .Ql ( db , .Ql dw , .Ql dl ) . .It Cm BYTE Ar Type .Bl -column "Value" -compact .It Sy Value Ta Sy Meaning .It 0 Ta وصله تک‌بایتی .It 1 Ta وصله دو بایتی با ترتیب بایت کم‌ارزش .It 2 Ta وصله چهار بایتی با ترتیب بایت کم‌ارزش .It 3 Ta وصله تک‌بایتی Ql jr ؛ مقدار وصله از PC + 2 کم خواهد شد (یعنی .Ql jr @ باید حلقه بی‌نهایت .Ql 18 FE باشد) . .El .It Cm LONG Ar RPNSize اندازه .Ar RPNExpr زیر. .It Cm BYTE Ar RPNExpr Ns Bq RPNSize مقدار وصله، کدگذاری‌شده به عنوان عبارت RPN .Pq Sx RPN expressions را ببینید . .El .It Cm ENDR .El .It Cm ENDC .El .El .Ss "تصدیق‌ها (Assertions)" .Bl -tag -width Ds -compact .It Cm LONG Ar NumberOfAssertions تعداد تصدیق‌هایی که این فایل شیء شامل می‌شود. .It Cm REPT Ar NumberOfAssertions تصدیق‌ها اساساً وصله‌هایی به همراه یک پیام هستند. .Pp .Bl -tag -width Ds -compact .It Cm LONG Ar NodeID زمینه‌ای که تصدیق در آن تعریف شده است. .It Cm LONG Ar LineNo شماره خط در زمینه‌ای که تصدیق در آن تعریف شد. .It Cm LONG Ar Offset بخش استفاده‌نشده باقی‌مانده از ساختار وصله. .It Cm LONG Ar PCSectionID شناسه بخشی که PC در آن قرار دارد. .It Cm LONG Ar PCOffset آفست نماد PC درون بخش مشخص‌شده توسط .Ar PCSectionID . .It Cm BYTE Ar Type توصیف می‌کند در صورتی که عبارت به یک مقدار غیرصفر ارزیابی شود چه رخ می‌دهد. .Bl -column "Value" -compact .It Sy Value Ta Sy Meaning .It 0 Ta چاپ پیام هشدار، و ادامه اتصال به طور عادی. .It 1 Ta چاپ پیام خطا، به طوری که پیوند با شکست مواجه می‌شود، اما سایر تصدیق‌ها نیز ارزیابی می‌شوند. .It 2 Ta چاپ پیام خطای مهلک، و خروج و توقف فوری. .El .It Cm LONG Ar RPNSize اندازه .Ar RPNExpr زیر. .It Cm BYTE Ar RPNExpr Ns Bq RPNSize مقدار وصله، کدگذاری‌شده به عنوان یک عبارت RPN .Pq Sx RPN expressions را ببینید . .It Cm STRING Ar Message پیامی که در صورت ارزیابی عبارت به مقدار غیرصفر نمایش داده می‌شود. در صورت خالی بودن، پیامی عمومی نمایش داده خواهد شد. .El .It Cm ENDR .El .Ss "عبارات RPN (RPN expressions)" عبارات در فایل شیء به صورت RPN یا .Dq نشانه‌گذاری لهستانی معکوس ذخیره می‌شوند؛ نشانه‌گذاری‌ای که امکان محاسبه عبارات دلخواه را با یک پشته ساده فراهم می‌سازد. برای نمونه، عبارت .Ql 2 5 - ابتدا مقدار .Dq 2 را در پشته قرار می‌دهد، سپس .Dq 5 . عملگر .Ql - دو آرگومان را از پشته برمی‌دارد، آن‌ها را تفریق می‌کند و سپس نتیجه .Pq Dq 3 را در پشته برمی‌گرداند. یک عبارت RPN خوش‌ساخت هرگز سعی نمی‌کند از یک پشته خالی داده بردارد، و در پایان دقیقاً یک مقدار در آن باقی می‌گذارد. .Pp مجموعه ابزار RGBDS عبارات RPN را به عنوان آرایه‌ای از .Cm BYTE ها کدگذاری می‌کند. اولین بایت یا یک عملگر را کدگذاری می‌کند یا یک مقدار ثابت که بایت‌های .Cm BYTE بیشتری را پس از خود مصرف می‌کند: .Bl -column "Value" .It Sy Value Ta Sy Meaning .It Li /bin/zsh Ta عملگر جمع Pq Ql + .It Li Ta عملگر تفریق Pq Ql - .It Li Ta عملگر ضرب Pq Ql * .It Li Ta عملگر تقسیم Pq Ql / .It Li Ta عملگر باقی‌مانده Pq Ql % .It Li Ta منفی‌سازی Pq Ql - یکانی .It Li Ta عملگر توان Pq Ql ** .It Li Ta عملگر OR بیتی Pq Ql \&| .It Li Ta عملگر AND بیتی Pq Ql & .It Li Ta عملگر XOR بیتی Pq Ql ^ .It Li Ta عملگر مکمل بیتی Pq Ql ~ یکانی .It Li Ta عملگر AND منطقی Pq Ql && .It Li Ta عملگر OR منطقی Pq Ql || .It Li Ta عملگر نقیض منطقی Pq Ql \&! یکانی .It Li Ta عملگر برابری Pq Ql == .It Li Ta عملگر نابرابری Pq Ql != .It Li Ta عملگر بزرگ‌تر Pq Ql > .It Li Ta عملگر کوچک‌تر Pq Ql < .It Li Ta عملگر بزرگ‌تر یا مساوی Pq Ql >= .It Li Ta عملگر کوچک‌تر یا مساوی Pq Ql <= .It Li Ta عملگر شیفت به چپ Pq Ql << .It Li Ta عملگر شیفت حسابی/علامت‌دار به راست Pq Ql >> .It Li Ta عملگر شیفت منطقی/بدون‌علامت به راست Pq Ql >>> .It Li Ta Fn BANK symbol ؛ به همراه شناسه .Cm LONG مربوط به .Ar symbol . .It Li Ta Fn BANK section ؛ به همراه نام .Cm STRING مربوط به .Ar section . .It Li Ta شناسه Fn BANK مربوط به PC Pq یعنی Ql BANK(@) . .It Li Ta Fn SIZEOF section ؛ به همراه نام .Cm STRING مربوط به .Ar section . .It Li Ta Fn STARTOF section ؛ به همراه نام .Cm STRING مربوط به .Ar section . .It Li Ta Fn SIZEOF sectiontype ؛ به همراه مقدار .Cm BYTE مربوط به .Ar sectiontype .Pq مقادیر Ar Type را در Sx Sections ببینید . .It Li Ta Fn STARTOF sectiontype ؛ به همراه مقدار .Cm BYTE مربوط به .Ar sectiontype .Pq مقادیر Ar Type را در Sx Sections ببینید . .It Li Ta بررسی .Ql ldh . بررسی می‌کند که آیا مقدار یک عملوند معتبر .Ql ldh است .Pq Do Load Instructions Dc را در Xr gbz80 7 ببینید , یعنی اینکه آیا مقدار بین /bin/zsh و ، یا بین و قرار دارد یا خیر. سپس مقدار با /bin/zshFF عملیات AND می‌شود .Pq Ql & . .It Li Ta بررسی .Ql rst . بررسی می‌کند که آیا مقدار یک بردار معتبر .Ql rst است .Pq Do RST vec Dc را در Xr gbz80 7 ببینید , یعنی یکی از مقادیر /bin/zsh، ، ، ، ، ، ، یا . سپس مقدار با عملیات OR می‌شود .Pq Ql \&| . .It Li Ta بررسی .Ql bit/res/set ؛ به همراه ماسک .Cm BYTE دستورالعمل. بررسی می‌کند که آیا مقدار یک شاخص بیت معتبر است یا خیر .Pq برای نمونه Do BIT u3, r8 Dc را در Xr gbz80 7 ببینید , یعنی از 0 تا 7. سپس مقدار با ماسک دستورالعمل OR می‌شود. .It Li Ta بایت .Cm HIGH . .It Li Ta بایت .Cm LOW . .It Li Ta مقدار .Cm BITWIDTH . .It Li Ta مقدار .Cm TZCOUNT . .It Li Ta عدد صحیح ثابت؛ به همراه عدد صحیح .Cm LONG . .It Li Ta مقدار یک نماد؛ به همراه شناسه .Cm LONG نماد. .El .Sh "همچنین ببینید (SEE ALSO)" .Xr rgbasm 1 , .Xr rgbasm 5 , .Xr rgblink 1 , .Xr rgblink 5 , .Xr rgbfix 1 , .Xr rgbgfx 1 , .Xr gbz80 7 , .Xr rgbds 7 .Sh "تاریخچه (HISTORY)" ابزارهای .Xr rgbasm 1 و .Xr rgblink 1 در ابتدا توسط .An Carsten S\(/orensen به عنوان بخشی از بسته ASMotor نوشته شدند، و بعداً در RGBDS توسط .An Justin Lloyd بازبسته‌بندی شدند. در حال حاضر توسط گروهی از مشارکت‌کنندگان در .Lk https://github.com/gbdev/rgbds نگهداری می‌شود.