DS Technical Information

This is a brief summary of what is known so far about the DS and its various hardware functions by the author.
Don't take these claims for absolute truths, but as guidance in (hopefully) the right direction.

Legend
  d<n>:		Used to denote individual bits. E.g. d7 for bit 7.
  BG*CNT	Denotes any of the BG control registers.
  SBO		Should Be One (a number of bits all set)
  SBZ		Should Be Zero (a number of bits all clear)

 DS Reference

Overview
Hardware Programming
LCD Video Controller
 CPU Reference

ARM946E-S Information
Co-processor 15


 Co-processor 15

The ARM946E-S Co-processor 15 (CP15) controls various aspects of memory, such as caches, tightly coupled memories (TCMs), memory protection etc. It is accessed using two dedicated instructions:
mrc 15, Op1, Rd, Cn, Cm, Op2  (read)
mcr 15, Op1, Rd, Cn, Cm, Op2  (write)
Input and results are given in one of the general registers - denoted Rd. What follows below is a list of the CP15 functions available and an explanation of the corresponding Rd-encoding.

Register 0 - ID Code
mrc 15, 0, Rd, c0, c0, {0,3-7}*
  Bit	Expl.
  0-3	Revision (=0x1)
  4-15	Primary part # (=0x946)
  16-19	ARM Architecture (=0x5)
  20-23 Reserved (=0x0)
  24-31	Implementor (=0x41)

* Op2 can have any of the values 0, 3, 4, 5, 6 or 7.

Register 0 - Cache Type
mrc 15, 0, Rd, c0, c0, 1
  Bit	Expl.
  0-1	Instruction cache words/line (=0x2, 8 words/line)
  2	Instruction cache absent (=0x0)
  3-5	Instruction cache associativity (=0x2, 4-way associative)
  6-9	Instruction cache size (=0x4, 8kB)
  10-11 Reserved (SBZ)
  12-13	Data cache words/line (=0x2, 8 words/line)
  14	Data cache absent (SBZ)
  15-17	Data cache associativity (=0x2, 4-way associative)
  18-21	Data cache size (=0x3)
  22-23	Reserved (SBZ)
  24	Harvard/Unified (=0x1)
  25-28 Cache type (=0x7)
  29-31	Reserved (SBZ)

Register 0 - TCM Size
mrc 15, 0, Rd, c0, c0, 2
  Bit	Expl.
  0-1	Reserved (SBZ)
  2	Instruction TCM absent (=0x0)
  3-5	Reserved (SBZ)
  6-9	Instruction TCM size (=0x5, 16kB)
  10-13 Reserved (SBZ)
  14	Data TCM absent (=0x0)
  15-17	Reserved (SBZ)
  18-21	Data TCM size (=0x5, 16kB)
  22-31	Reserved (SBZ)

Register 1 - Control Register
mrc 15, 0, Rd, c1, c0, 2  (r)
mcr 15, 0, Rd, c1, c0, 2  (w)
  Bit	Expl.
  0	Protection unit enable (clear on reset)*
  1	Reserved (SBZ)
  2	Data cache enable (clear on reset)**
  3-6	Reserved (SBO)
  7	Big-endian (0=Little-endian, 1=Big-endian. clear on reset)
  8-11	Reserved (SBZ)
  12	Instruction cache enable (clear on reset)**
  13	Alternate vector select (0=Exception base vector at 0x00000000, 1=vector at 0xFFFF0000)
  14	Round-robin replacement (0=pseudo-random replacement, 1=round-robin replacement. clear on reset)
  15	Disable loading TBIT
  16	Data TCM enable (clear on reset)
  17	Data TCM load mode
  18	Instruction TCM enable
  19	Instruction TCM load mode
  20-31	Reserved (=0x0)

* You must set up at least one protection region before you enable the protection unit.
** You must also enable the protection unit (bit 0) for caches to work.

Register 2 - Cache Configuration
mrc 15, 0, Rd, c1, c0, 0  (r) (Data Cache)
mcr 15, 0, Rd, c2, c0, 0  (w) (Data Cache)
mrc 15, 0, Rd, c1, c0, 1  (r) (Instruction Cache)
mcr 15, 0, Rd, c2, c0, 1  (w) (Instruction Cache)
  Bit	Expl.
  0	Region 0 cachable
  1	Region 1 cachable
  2	Region 2 cachable
  3	Region 3 cachable
  4	Region 4 cachable
  5	Region 5 cachable
  6	Region 6 cachable
  7	Region 7 cachable

For more information on memory regions, see register 6.

Register 3 - Write Buffer Control
mrc 15, 0, Rd, c1, c0, 0  (r) (Data Write Buffer)
mcr 15, 0, Rd, c2, c0, 0  (w) (Data Write Buffer)
  Bit	Expl.
  0	Region 0 buffered
  1	Region 1 buffered
  2	Region 2 buffered
  3	Region 3 buffered
  4	Region 4 buffered
  5	Region 5 buffered
  6	Region 6 buffered
  7	Region 7 buffered

For more information on memory regions, see register 6.
The write buffer is implemented as a 16-entry FIFO. The behavior is specified in the below table:
  B   C	  Expl.
  0   0   Non-cached, non-buffered. Writes go straight through to the intended memory location, and
          the processor is stalled until the operation has completed.
  0   1   Write-through. All writes are buffered, regardless of whether they hit or miss. Writes
          that hit the data cache also updates the cache line, but does not mark it as dirty.
          Data cache linefills due to cache misses or prefetches will drain the write buffer prior
          to the linefill.
  1   0   Non-cached. Writes are buffered. Reads will drain the write buffer. Swap instructions in
          this type of region are not buffered.
  1   1   Write-back. Writes that miss the data cache are buffered. Writes that hit the data cache
          updates the cache line, marks it as dirty, and does not go to the write buffer. Data cache
          linefills due to cache misses or prefetches will drain the write buffer prior to the linefill.
B = region buffered AND protection unit enabled
C = region cachable AND data cache enabled AND protection unit enabled

Register 5 - Access Permissions
mrc 15, 0, Rd, c5, c0, 2  (r) (Data Access Permissions)
mcr 15, 0, Rd, c5, c0, 2  (w) (Data Access Permissions)
mrc 15, 0, Rd, c5, c0, 3  (r) (Instruction Access Permissions)
mcr 15, 0, Rd, c5, c0, 3  (w) (Instruction Access Permissions)
  Bit	Expl.
  0-3	Region 0 permissions
  4-7	Region 1 permissions
  8-11	Region 2 permissions
  12-15	Region 3 permissions
  16-19	Region 4 permissions
  20-23	Region 5 permissions
  24-27	Region 6 permissions
  28-31	Region 7 permissions

Permission table:
  Value	Priviledged access	User access
  0	   None			None
  1	   Read/Write		None
  2	   Read/Write		Read
  3	   Read/Write		Read/Write
  5	   Read			None
  6	   Read			Read

  All other values leads to unpredicatble results.

Register 6 - Protection Region Base and Size
mrc 15, 0, Rd, c6, {c0-c7}, 0  (r)*
mcr 15, 0, Rd, c6, {c0-c7}, 0  (w)*
  Bit	Expl.
  0	Region enable (clear on reset)
  1-5	Region size
  12-31	Region base address

* Cm selects the region, e.g. c0 for region 0, c1 for region 1 and so on.

Region size encoding:
  Value		  Size
  0x00-0x0A	  prohibited
  0x0B	 	  4 kB
  0x0C		  8 kB
  0x0D		 16 kB
  0x0E		 32 kB
  0x0F		 64 kB
  0x10		128 kB
  0x11		256 kB
  0x12		512 kB
  0x13		  1 MB
  0x14		  2 MB
  0x15		  4 MB
  0x16		  8 MB
  0x17		 16 MB
  0x18		 32 MB
  0x19		 64 MB
  0x1A		128 MB
  0x1B		256 MB
  0x1C		512 MB
  0x1D		  1 GB
  0x1E		  2 GB
  0x1F		  4 GB

The region base address must be aligned on a multiple of the region size.

Register 7 - Flush Instruction Cache
mcr 15, 0, Rd, c7, c5, 0  (w)
  Bit	Expl.
  0-31	Reserved (SBZ)

In-progress cache line fetches will finish before the flush is performed.

Register 7 - Flush Instruction Cache Single Entry
mcr 15, 0, Rd, c7, c5, 1  (w)
  Bit	Expl.
  0-4	Reserved (SBZ)
  5-31	Address

In-progress cache line fetches will finish before the flush is performed.

Register 7 - Prefetch Instruction Cache Line
mcr 15, 0, Rd, c7, c13, 1  (w)
  Bit	Expl.
  0-4	Reserved (SBZ)
  5-31	Address

Register 7 - Flush Data Cache
mcr 15, 0, Rd, c7, c6, 0  (w)
  Bit	Expl.
  0-31	Reserved (SBZ)

In-progress cache line fetches will finish before the flush is performed.

Register 7 - Flush Data Cache Single Entry
mcr 15, 0, Rd, c7, c6, 1  (w)
  Bit	Expl.
  0-4	Reserved (SBZ)
  5-31	Address

In-progress cache line fetches will finish before the flush is performed.

Register 7 - Clean Data Cache Entry
mcr 15, 0, Rd, c7, c10, 1  (w)
  Bit	Expl.
  0-4	Reserved (SBZ)
  5-31	Address

In-progress cache line fetches will finish before the cleansing is performed.

Register 7 - Clean Data Cache Entry
mcr 15, 0, Rd, c7, c10, 2  (w)
  Bit	Expl.
  0-4		Reserved (SBZ)
  5-N		Index
  N+1-29	Reserved (SBZ)
  30-31		Segment

N is given through log2(cache_size)-3. So for a 4kB cache, bits 5-9 specify the index, etc.
In-progress cache line fetches will finish before the cleansing is performed.

Register 7 - Clean and Flush Data Cache Entry
mcr 15, 0, Rd, c7, c14, 1  (w)
  Bit	Expl.
  0-4	Reserved (SBZ)
  5-31	Address

In-progress cache line fetches will finish before the cleansing is performed.

Register 7 - Clean and Flush Data Cache Entry
mcr 15, 0, Rd, c7, c14, 2  (w)
  Bit	Expl.
  0-4		Reserved (SBZ)
  5-N		Index
  N+1-29	Reserved (SBZ)
  30-31		Segment

N is given through log2(cache_size)-3. So for a 4kB cache, bits 5-9 specify the index, etc.
In-progress cache line fetches will finish before the cleansing is performed.

Register 9 - TCM Regions
mrc 15, 0, Rd, c9, c1, 0  (r) (DTCM)
mcr 15, 0, Rd, c9, c1, 0  (w) (DTCM)
mrc 15, 0, Rd, c9, c1, 1  (r) (ITCM)
mcr 15, 0, Rd, c9, c1, 1  (w) (ITCM)
  Bit	Expl.
  0	Reserved (=0x0)
  1-5	Region size
  12-31	Region base address

Region size encoding:
  Value		  Size
  0x00-0x02	  prohibited
  0x03	 	  4 kB
  0x04		  8 kB
  0x05		 16 kB
  0x06		 32 kB
  0x07		 64 kB
  0x08		128 kB
  0x09		256 kB
  0x0A		512 kB
  0x0B		  1 MB
  0x0C		  2 MB
  0x0D		  4 MB
  0x0E		  8 MB
  0x0F		 16 MB
  0x10		 32 MB
  0x11		 64 MB
  0x12		128 MB
  0x13		256 MB
  0x14		512 MB
  0x15		  1 GB
  0x16		  2 GB
  0x17		  4 GB
  0x18-0x1F	  prohibited

The region base address must be aligned on a multiple of the region size.
The instruction TCM (ITCM) has a fixed base address of 0x00000. Writing a non-zero value to the ITCM base address bits results in unpredictable behavior.
The data TCM (DTCM) has a base address of 0x00000 upon reset. Since this overlaps with the ITCM you must set a different base address for the DTCM before enabling DTCM, or you will have unpredictable behavior.

 LCD Video Controller

Registers
LCD I/O Display Control
LCD I/O BG Control
LCD I/O VRAM Control
LCD I/O Texture Image Parameters

VRAM
LCD VRAM LCDC Mode
LCD VRAM Bitmap BG Modes

Sprites

 LCD I/O Display Control

0x04000000 - DISPCNT_L - Display Control, lower 16 bits
0x04000002 - DISPCNT_H - Display Control, upper 16 bits
  Bit	Expl.
  0-2	BG mode (0-6=BG mode 0-6, 7=prohibited)
  3	BG0 2D/3D (0=BG0 used for 2D, 1=BG0 used for 3D)
  4	Character OBJ mapping mode (0=2D mapping, 1=1D mapping (see bit 20-21))
  5-6	Bitmap OBJ mapping mode (0=128x128 bitmap, 1=256x64 bitmap, 2=1D bitmap (see bit 22), 3=prohibited)
  7	Forced blank (1=Blank screen and allow access to VRAM)
  8	Display BG0 (1=Display)
  9	Display BG1
  10	Display BG2
  11	Display BG3
  12	Display OBJ
  13	Display window 0
  14	Display window 1
  15	Display OBJ window
  16-17	Display mode (0=VRAM display (LCDC) mode, 1=BG mode, 2=prohibited, 3=Main RAM display mode)
  18-19	VRAM selection (when LCDC mode is used)
  20-21	Character OBJ extended mapping mode (when 1D char mode is used: 0=32kB capacity, 1=64kB, 2=128kB, 3=256KB)
  22	Bitmap OBJ extended mapping mode (when 1D bitmap mode is used: 0=128kB bitmap, 1=256kB bitmap)
  23	Allow OBJ VRAM access during h-blank
  24-26	Master character offset (added to char base block. offset = n*64kB)
  27-29	Master screen offset (added to screen base block. offset = n*64kB)
  30	Extended BG palette master enable
  31	Extended OBJ palette master enable

0x04001000 - DISPCNT_SUB_L - Sub Display Control, lower 16 bits
0x04001002 - DISPCNT_SUB_H - Sub Display Control, upper 16 bits
  Bit	Expl.
  0-2	BG mode (0-5=BG mode 0-5, 6-7=prohibited)
  3	Unknown
  4	Character OBJ mapping mode
  5-6	Bitmap OBJ mapping mode (0=128x512 bitmap, 1=256x256 bitmap, 2=1D bitmap (see bit 22), 3=prohibited)
  7	Forced blank (1=Blank screen and allow access to VRAM)
  8	Display BG0 (1=Display)
  9	Display BG1
  10	Display BG2
  11	Display BG3
  12	Display OBJ
  13	Display window 0
  14	Display window 1
  15	Display OBJ window
  16	Display mode (0=Unknown, 1=BG mode)
  17-19	Unknown
  20-21	Character OBJ extended mapping mode (when 1D char mode is used: 0=32kB capacity, 1=64kB, 2=128kB, 3=256KB)
  22	Bitmap OBJ extended mapping mode (when 1D bitmap mode is used: 0=128kB bitmap, 1=256kB bitmap)
  23	Unknown
  24-29	Unknown
  30	Extended BG palette master enable
  31	Extended OBJ palette master enable

BG modes 0-2 are tiled modes. Modes 3-5 are mixed tiled/bitmapped modes. Mode 6 is a purely bitmapped mode.

Note that you are limited to 32kB of space for 2D bitmap OBJs on the main core, regardless of the size of the bank. The sub core does not have the same restriction of 32kB capacity for 2D bitmap OBJs as the main core.
Character spacing for 1D OBJ mapping modes differ depending on the memory capacity. Refer to the sections on OBJ mapping.

 LCD I/O BG Control

0x04000008 - BG0CNT - BG 0 Control
  Bit	Expl.
  0-1	Priority (0=highest...3=lowest)
  2-5	Character base block (individual character base offset. n*16kB)
  6	Mosaic enable (1=On, 0=Off)
  7	Color mode (0=16x16 palettes, 1=1x256 palettes)
  8-12	Screen base block (individual screen base offset. n*2kB)
  13	Palette set 0/2 (extended palettes. 0=use set 0, 1=use set 2)
  14-15	Screen size

0x0400000A - BG1CNT - BG 1 Control
  Bit	Expl.
  0-1	Priority (0=highest...3=lowest)
  2-5	Character base block (individual character base offset. n*16kB)
  6	Mosaic enable (1=On, 0=Off)
  7	Color mode (0=16x16 palettes, 1=1x256 palettes)
  8-12	Screen base block (individual screen base offset. n*2kB)
  13	Palette set 1/3 (extended palettes. 0=use set 1, 1=use set 3)
  14-15	Screen size

0x0400000C - BG2CNT - BG 2 Control
  Bit	Expl.
  0-1	Priority (0=highest...3=lowest)
  2-5	Character base block (individual character base offset. n*16kB)*
  6	Mosaic enable (1=On, 0=Off)
  7	Color mode (0=16x16 palettes, 1=1x256 palettes)**
  8-12	Screen base block (individual screen base offset)***
  13	Overflow area wraparound (1=wrap)
  14-15	Screen size

0x0400000E - BG3CNT - BG 3 Control
  Bit	Expl.
  0-1	Priority (0=highest...3=lowest)
  2-5	Character base block (individual character base offset. n*16kB)*
  6	Mosaic enable (1=On, 0=Off)
  7	Color mode (0=16x16 palettes, 1=1x256 palettes)**
  8-12	Screen base block (individual screen base offset)***
  13	Overflow area wraparound (1=wrap)
  14-15	Screen size

*, ** Used for other purposes in some BG modes.
*** Screen base blocks are 2kB for text BGs, 16kB for bitmap BGs.

Screen size table:
  Type		d15  d14  Size
  Text		0     0   256x256
  		0     1   512x256
  		1     0   256x512
  		1     1   512x512

  Rotoscale	0     0   128x128
  		0     1   256x256
  		1     0   512x512
  		1     1   1024x1024

  Ex. rotoscale	0     0   128x128
  		0     1   256x256
  		1     0   512x512
  		1     1   1024x1024

  Bitmap	0     0   128x128
  		0     1   256x256
  		1     0   512x256
  		1     1   512x512

  Large bitmap	0     0   512x1024
  		0     1   1024x512

 LCD I/O 3D Display Control

0x04000060 - DISP3DCNT - 3D Display Control
  Bit	Expl.
  1	Shading selection (0=toon shading, 1=highlight shading)
  2	Alpha test enable (0=Off, 1=On)
  3	Alpha blend enable (0=Off, 1=On)
  4	Antialias enable (0=Off, 1=On)
  5	Edge marking enable (0=Off, 1=On)
  12	Line buffer overflow (1=overflow)*
  13	Polygon list memory / vertex memory overflow (1=overflow)*

* Reading these bits returns the current status. Writing a "1" to these bits will reset the current status.

 LCD I/O VRAM Control

The 9 VRAM banks of the DS are controlled through a set of 8-bit I/O registers. Note that 0x04000247 is used for other purposes, which is why there is a glap between VRAMCNT_G and VRAMCNT_H.

0x04000240 - VRAMCNT_A - VRAM Control A
0x04000241 - VRAMCNT_B - VRAM Control B
0x04000242 - VRAMCNT_C - VRAM Control C
0x04000243 - VRAMCNT_D - VRAM Control D
0x04000244 - VRAMCNT_E - VRAM Control E
0x04000245 - VRAMCNT_F - VRAM Control F
0x04000246 - VRAMCNT_G - VRAM Control G
0x04000248 - VRAMCNT_H - VRAM Control H
0x04000249 - VRAMCNT_I - VRAM Control I
  Bit	Expl.
  0-2	Owner (see below table)
  3-4	Offset (see below table)
  7	Enable (1=On, 0=Off)

Bank A is 128 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6800000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6400000	Main OBJ
  0x83    *		Texture 0
  0x89    0x6020000	Main BG
  0x8A    0x6420000	Main OBJ
  0x8B	  *		Texture 1
  0x91    0x6040000	Main BG
  0x93    *		Texture 2
  0x99    0x6060000	Main BG
  0x9B    *		Texture 3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank B is 128 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6820000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6400000	Main OBJ
  0x83    *		Texture 0
  0x89    0x6020000	Main BG
  0x8A    0x6420000	Main OBJ
  0x8B	  *		Texture 1
  0x91    0x6040000	Main BG
  0x93    *		Texture 2
  0x99    0x6060000	Main BG
  0x9B    *		Texture 3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank C is 128 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6840000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6000000	ARM7 controlled
  0x83    *		Texture 0
  0x84	  0x6200000	Sub BG
  0x89    0x6020000	Main BG
  0x8A    0x6020000	ARM7 controlled
  0x8B	  *		Texture 1
  0x91    0x6040000	Main BG
  0x93    *		Texture 2
  0x99    0x6060000	Main BG
  0x9B    *		Texture 3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank D is 128 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6860000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6000000	ARM7 controlled
  0x83    *		Texture 0
  0x84	  0x6600000	Sub OBJ
  0x89    0x6020000	Main BG
  0x8A    0x6020000	ARM7 controlled
  0x8B	  *		Texture 1
  0x91    0x6040000	Main BG
  0x93    *		Texture 2
  0x99    0x6060000	Main BG
  0x9B    *		Texture 3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank E is 64 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6880000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6400000	Main OBJ
  0x83    *		Texture palette 0-3
  0x84	  *		Extended BG palette 0-3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank F is 16 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6890000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6400000	Main OBJ
  0x83    *		Texture palette 0
  0x84    *		Extended Main BG palette 0-1
  0x85    *		Extended Main OBJ palette
  0x89    0x6004000	Main BG
  0x8A    0x6404000	Main OBJ
  0x8B	  *		Texture palette 1
  0x8C    *		Extended Main BG palette 2-3
  0x91    0x6010000	Main BG
  0x92    0x6410000	Main OBJ
  0x93    *		Texture palette 4
  0x99    0x6014000	Main BG
  0x9A    0x6414000	Main OBJ
  0x9B    *		Texture palette 5
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank G is 16 kB and can be configured as follows:
  Value   Base address	Function
  0x00    N/A		Disabled
  0x80    0x6894000	LCDC
  0x81    0x6000000	Main BG
  0x82    0x6400000	Main OBJ
  0x83    *		Texture palette 0
  0x84    *		Extended Main BG palette 0-1
  0x85    *		Extended Main OBJ palette
  0x89    0x6004000	Main BG
  0x8A    0x6404000	Main OBJ
  0x8B	  *		Texture palette 1
  0x8C    *		Extended Main BG palette 2-3
  0x91    0x6010000	Main BG
  0x92    0x6410000	Main OBJ
  0x93    *		Texture palette 4
  0x99    0x6014000	Main BG
  0x9A    0x6414000	Main OBJ
  0x9B    *		Texture palette 5
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank H is 32 kB and can be configured as follows:
  Value   Address	Function
  0x00    N/A		Disabled
  0x80    0x6898000	LCDC
  0x81    0x6200000	Sub BG
  0x82    *		Extended Sub BG palette 0-3
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

Bank I is 16 kB and can be configured as follows:
  Value   Address	Function
  0x00    N/A		Disabled
  0x80    0x68A0000	LCDC
  0x81    0x6208000	Sub BG
  0x82    0x6600000	Sub OBJ
  0x83    *		Extended Sub OBJ palette
*) Data is written while in LCDC mode, then the bank is switched into the appropriate mode.

 LCD I/O Fragment Alpha Test Setting

0x04000340 - ALPHA_TEST - Fragment Alpha Test Setting
  Bit	Expl.
  0-4	Threshold

Pixels with alpha less than the threshold will not be rendered. The test is done after texture blending has been performed.
Set bit 2 of DISP3DCNT to enable alpha testing.

 LCD I/O Polygon Attributes

0x040004A4 - POLYGON_ATTR - Polygon Attributes
  Bit	Expl.
  0	Light0 enable (0=Off, 1=On)
  1	Light1 enable
  2	Light2 enable
  3	Light3 enable
  4-5	Polygon mode (0=modulate, 1=decal, 2=toon/highlight shade, 3=shadow)
  6-7	Culling (0=front and back, 1=front, 2=back, 3=none)
  15	Fog blending (0=Off, 1=On)
  16-20	Alpha (0=wireframe, 31=opaque, 1-30=translucent)*
  24-29	Polygon ID

* You can use the ALPHA_TEST I/O register to hide the outlines of polygons with zero alpha.

 LCD I/O Texture Image Parameters

0x040004A8 - TEXIMG_PARAM - Texture Image Parameters
  Bit	Expl.
  0-15	Texture address (offset within the given bank)
  16	Horizontal repeat (1=repeat)
  17	Vertical repeat (1=repeat)
  18	Horizontal flip (1=flip)
  19	Vertical flip (1=flip)
  20-22	Texture width (0=8 px, 1=16, 2=32, ..., 7=1024)
  23-25	Texture height (0=8 px, 1=16, 2=32, ..., 7=1024)
  26-28	Texture format (see below table)
  29	Color 0 transparency (0=color 0 can be used, 1=color 0 is transparent)
  30-31	Texture coordinate generation

Texture formats:
  Value	 Bits/pixel	Format
  0 	  N/A		No texture
  1 	  8		32 color paletted with alpha. Lower 5 bits specify index, upper 3 bits specify alpha.
  2 	  2		4 color paletted.
  3 	  4		16 color paletted.
  4 	  8		256 color paletted.
  5 	  ?		Compressed
  6 	  8		8 color paletted with alpha. Lower 3 bits specify index, upper 5 bits specify alpha.
  7 	  16		Direct color (A1B5G5R5).

 LCD I/O Cutoff Depth

0x04000610 - CUTOFF_DEPTH - Cutoff Depth
  Bit	Expl.
  0-2	Fractional part
  3-14	Integer part

For polygons whose transformed size is one pixel or less, this value specifies the cutoff depth beyond which such polygons will not be shown.

 LCD VRAM Banks

The DS has 9 VRAM banks, as listed below:
  Bank	Size
  A	128 kB
  B	128 kB
  C	128 kB
  D	128 kB
  E	 64 kB
  F	 16 kB
  G	 16 kB
  H	 32 kB
  I	 16 kB
These banks can be mapped to various regions of VRAM using the VRAMCNT I/O registers.

 LCD VRAM Extended Palettes

Extended palettes are groups - or sets - of 256-color palettes which allow for 4096 simultaneous colors to be displayed using 8 bits per pixel (with the limitation of 256 colors per tile). They are available for both text BGs and rotoscaled BGs, as well as OBJs.

 LCD VRAM LCDC Mode

 LCD VRAM Bitmap BG Modes

BG modes 3-5 are applicable on both cores and allow for up to two bitmapped layers combined with text/3D layers. The bitmaps can be either 8 bits per pixel for 256 colors, or 16 bits per pixel for 32768 colors (with one bit used for alpha).

Common for mode 3-5:
  BG0 can be used as a text BG or for 3D.
  BG1 is always a text BG.

BG2 and BG3 work as follows:
  Mode 3: BG2 = text, BG3 = extended rotoscale
  Mode 4: BG2 = rotoscale, BG3 = extended rotoscale
  Mode 5: BG2 = extended rotoscale, BG3 = extended rotoscale

There are three types of extended rotoscale BGs, controlled through bits 2 and 7 of BG*CNT:
  d7  d2   Function
  0   0    rotoscale bg with extended palette (16 palettes x 256 colors)
  1   0    256-color bitmap
  1   1    direct color bitmap (ABGR, not xBGR)

Rotoscale bg with extended palette
These work much like the rotoscale BGs on the GBA, except the screen data is two bytes per entry instead of a single byte. In case the proper extended palette set has been enabled, d12-d15 of each screen entry will be used to select one of the 16 256-color palettes. Otherwise the normal BG palette is used.
There are four sets of extended palettes - each set holding 16 palettes of 256 colors for a total of 4096 colors. Thus the size of each set is 8kB.
You must use a matching set number for the BG (i.e. set 2 for BG2 and set 3 for BG3). You can either map VRAM bank E as extended palettes to enable all palette sets, or you can enable just sets 0+1 or 2+3 using banks F or G. For the sub core you must use VRAM bank H for the extended palettes. This will fit all four sets.

The procedure for loading your palette data into set 3 of VRAM bank E would be as follows:
  1. Map bank E to LCDC at 0x06880000 (VRAMCNT_E = 0x80)
  2. Write your data starting at 0x06886000 (each set is 0x2000 bytes, 0x2000*3 = 0x6000)
  3. Map bank E as extended palettes (VRAMCNT_E = 0x84)
Similarly for banks F and G, except the VRAMCNT values and the data address would differ.
You also need to set bit 30 of DISPCNT to enable extended palettes.

256-color bitmap
The selectable sizes (d14-d15 of BG*CNT) are 128x128, 256x256, 512x256 and 512x512.
Each screen base block is 16kB, meaning you can map the screen to any offset up to 31*16kB = 496kB. Thus for the main core you can use any of VRAM banks A-D for the screen data, except for when the screen size is 512x512 pixels, which requires two VRAM banks to hold the screen data. For the sub core you are a bit more limited in which banks you can use.

An example of setting BG2 as a 256x256 bitmap at offset 0x4000 for the main core would be:
  1. Map bank A to main BG at 0x06000000 (VRAMCNT_A = 0x81)
  2. Set 256x256 size, 256-color mode, screen base 0x4000 (BG2CNT = 0x4180)

Direct color bitmap
The selectable sizes (d14-d15 of BG*CNT) are 128x128, 256x256, 512x256 and 512x512.
Each screen base block is 16kB, meaning you can map the screen to any offset up to 31*16kB = 496kB. Thus for the main core you can use any of VRAM banks A..D for the screen data, except for when the screen size is 512x256 or 512x512 pixels, which requires at least two VRAM banks to hold the screen data. For the sub core you are a bit more limited in which banks you can use.
Note that the color format for the direct color BGs uses bit 15 of the color as an alpha bit. This is to allow for transparency when using more than one layer.

In all three cases, BG*CNT d13 controls wrapping as follows:
  d13 Effect
  0   Area outside bitmap is transparent
  1   Area outside bitmap will wrap around

BG mode 6
This mode is only applicable on the main core.
BG0 can be used for 3D.
BG2 holds a large 256-color bitmap.
BG1 and BG3 are unused.

BG2CNT d14 controls the size of the bitmap as follows:
  d14  Size
  0   512x1024 pixels
  1   1024x512 pixels
Since the bitmap uses 512kB of VRAM either way you need to allocate VRAM banks A-D to the main BG. This is done by writing 0x81, 0x89, 0x91, 0x99 to VRAMCNT_A, B, C, D respectively. With this setup the bitmap will start at address 0x06000000.
BG2CNT d13 controls wrapping (d13=1 to wrap).

"Common" pitfalls
 LCD OBJ VRAM Bitmap Mapping

 LCD OBJ VRAM Character Mapping

 About this document

Credits
This document was written 2005 by Mic. Layout code was borrowed from GBATEK (2001-2002 Martin Korth).

Contact
Send your flame baits to micol972 <curly a> gmail <dot> com