Foreword

Description

Contributing

This book is open source, released under the CC0 license. Everyone is welcome to help, provide feedback and propose additions or improvements. The git repository is hosted at github.com/gbadev-org/ndsdoc, where you can learn more about how you can help, find detailed contribution guidelines and procedures, file Issues and send Pull Requests.

Using this document

In the top navigation bar, you will find a series of icons.

By clicking on the icon you will toggle an interactive table of contents to navigate the document. You can also use → and ← keys on your keyboard to go to the following and previous page.

The lets you choose among 6 different themes and color schemes to please your reading experience, including the classic Tonc theme.

You can search anywhere by pressing s on your keyboard or clicking the icon.

The icon allows you to suggest an edit on the current page by directly opening the source file in the git repository.

This document version was produced from git commit 0f156e (2025-01-27 00:38:31 +0000 ).

Nintendo DS Introduction

General introduction to the technical capabilities of the DS.

DS I/O Map

I/O map of the NDS (excluding WiFi and 3D, see their chapters for more information).

DS Memory Control

Registers to map VRAM, WRAM, to setup waitstates for external cartridges, etc.

DS Video

How 2D works from a high-level perspective, how 3D is displayed as part of a 2D layer. How screen capture works.

DS 2D Graphics

Background, sprites, windows.

DS 3D Graphics

This is an introduction to the 3D graphics of the Nintendo DS.

3D Display Control

This chapter talks about the registers used to control the 3D display.

DISP3DCNT: 3D display control (0x4000060, R/W)

To fill the screen: X1=0, Y1=0, X2=255, Y2=191

Note that coordinate (0, 0) is the bottom-left corner of the screen, while ht is the upper-left corner of the screen in the 2D graphics engine.

DISP_1DOT_DEPTH: 1-dot polygon render depth (0x4000610, W)

When a polygon is too small or too far away it is reduced to a single pixel on the screen. This register will determine the cutoff distance that the 3D engine will use to determine whether to render them or not.

This check can be enabled on a per-polygon basis with bit 13 of POLYGON_ATTR.

The comparison always uses the W coordinate regardless of the buffering mode.

ALPHA_TEST_REF: Alpha test reference (0x4000340, W)

When alpha test mode is enabled in DISP3DCNT, pixels will only be rendered if their alpha value is greater than the value in ALPHA_TEST_REF. Normally, when it is disabled, all pixels are rendered if their alpha value is greater than zero. A value of 31 will hide all polygons.

This test is done after applying texture and polygon transparency.

3D Display Control

This chapter talks about the status registers of the 3D hardware.

GXSTAT: Geometry Engine Status Register (0x04000600, mixed R/W)

RAM statistics: Polygon List & Vertex RAM Count (0x04000604, R)

Note: Once a buffer swap has been sent, the counters are reset 10 cycles after V-Blank.

Performance Statistics (0x04000320, R)

3D Geometry Engine

The Geometry Engine on the Nintendo DS is the hardware responsible for taking in 3D Graphics Commands and coverting them to verticies and polygons which can be rendered by the Rendering Engine. It’s jobs include performing various matrix multiplications involving vertex positions, vertex colors, light vectors, etc.

Readable Matricies

The Geometry provides access to the final directional matrix and screen space transformation matrix. (as in, position matricies * projection matrix) Reading these requires the geometry engine to be disabled via bit 27 in the GXSTAT register.

Clip Matrix (0x4000640..=0x400067F, 16 words, R)

Read the 4x4 “Clip matrix” with cells going from row 0 column 0, row by row.

Read Directional Matrix (0x4000680..=0x40006A3, 9 words, R)

Read the “top left” 3x3 segment of the directional matrix with cells going from row 0 column 0, row by row.

3D Command FIFO

The Geometry engine is heavily based upon a Command FIFO and PIPE used to transfer vertex lists, bind textures, set viewport, modify matricies, etc. The FIFO can be directly accessed by writing command numbers and parameters to memory location 0x4000400 or indirectly by writing parameters to the corresponding “Command Ports” at various memory locations from0x4000440..=0x40005FF.

Using the FIFO indirectly

The simpler and more user friendly method of interacting with the FIFO is via the “Command Ports”, where parameters are written to the corresponding memory address for a given command. The command + parameter combo is automatically sent down the FIFO to the 3D hardware once every parameter has been sent. For commands that don’t have any parameters one may simply write any value to the port.

Using the FIFO directly

When using the FIFO directly, commands are sent by first writing a “Command word” containing up to 4 packed command indicies. Followed by writing the parameters for each command in order. If the last command does not have a parameter, 0 must be written as a dummy parameter in order for the hardware to accept a new “command word”. When trying to specify invalid command indicies they will be treated the same as command index 0. (no command, no parameters) This way of using the fifo is better suited to transferring large chunks of commands, such as via DMA.

“Command word” definition

Notes:

When packing multiple commands you may not leave zeroed indicies (indicating no command) in between non-zeroed indicies. Meaning that when sending one command the top 24 bits must be zero, when sending 2 commands the top 16 bits must be zero, and when sending 3 commands the top 8 bits must be zero.

Command Summary

Vital 3D Hardware Commands

This chapter will go over the various commands required to be able to display graphics on the 3D hardware.

Swap buffers: Port 0x4000540, Index 0x50, 1 Parameter

Swaps the buffers used between the rendering engine, and the geometry engine.

Set 3D viewport: Port 0x4000580, Index 0x60, 1 Parameter

Sets the region of the screen which the 3D hardware may render to.

Notes:

Due to a misimplementation in the hardware, polygons can still be rendered one pixel beyond (X2, Y1)

Setting the viewport should be reserved to only be done once per frame or once before the beginning of a vertex list.

Vertex and Polygon Commands

This chapter explains the various commands used to send verticies to the 3D hardware in order to construct polygons. On top of this theres also basic lighting, materials, and texture mapping attributes. The DS 3D hardware natively supports constructing both triangles and quadrilaterals (which should not self intersect or have concavities).

Usage Overview

Verticies, as well as edges and polygons are to be constructed on the 3D hardware in the following manner:

1. Set Polygon attributes

2. Start a vertex list, where the parameter passed to the start command dictates the type of polygons you wish to construct (Seperated or Connected, Tris or Quads)

3. For each vertex, set relevant vertex attributes in any order. Setting any coordinate of the vertex position sends it to the 3D hardware. Attributes that are left unset will use the values of the previous vertex.

4. End the vertex list.

Notice here that the 3D hardware does not natively support index lists for constructing polygons, only a vertex list that constructs either seperated or connected “strips” of primitives. Another quirk of the 3D hardware is that the last step is optional, as vertex lists are automatically ended when a new one begins or the geometry and rendering engine buffers are swapped. It may still be useful however to manually end it for debugging purposes and the sake of “Completeness”.

Vertex List Commands

Commands used to start and end vertex lists, as well as commands which can only be used once per vertex list.

Start Vertex List: Port 0x04000500, Index 0x40, 1 Parameter

Parameter definition:

End Vertex List: Port 0x04000504, Index 0x41, 0 Parameters

Ends a vertex list, as previously discussed this command is optional, and only require for the sake of debugging

Polygon Attributes: Port 0x040004A4, Index 0x29, 1 Parameter

Sets various miscallenous attributes for polygons created by the next vertex list.

Parameter definition:

Notes: If a polygon attribute command is sent while a vertex list is ongoing, it will be deffered until next time a vertex list is begun. (Repeated calls will not stack, only the last written one will be used) Changes in lighting related attributes will not change until a new normal vector is set/calculated.

Vertex Attribute Commands

These are the commands for various attributes which can be applied to a vertex.

Set Vertex Color: Port 0x04000480, Index 0x20, 1 Parameter

Sets the vertex color used for the next vertex.

Parameter definition:

Set Normal Vector: Port 0x04000484, Index 0x21, 1 Parameter

Sets the “normal vector” used for the next vertex. In reality this will use the currently set light parameters to calculate a new vertex color.

Parameter definition:

Set Texture Coordinates: Port 0x04000488, Index 0x22, 1 Parameter

Sets the UV / ST coordinates for the next vertex. 16 units = 1 texel

Parameter definition:

Set Texture Parameters: Port 0x040004A8, Index 0x2A, 1 Parameter

Binds a texture to the upcoming verticies, along with various texture attributes.

Parameter definition:

Notes:

Texture size is calculated as (8 << N) pixels where N is the specified size. Meaning possible resulting values are 8,16,32,64,128,256,512,1024.

Texture flipping on repeats requires that repeats are on.

When a Texture is clamped, the outmost edge pixels are stretched across any out of bounds pixels.

The various Texture Formats are as follows:

Texture Coordinate Transformation Modes:

Set Texture Color Palette: Port 0x040004AC, Index 0x2B, 1 Parameter

Set the color palette used for the currently binded texture. Ignored by non-palette based textures.

Parameter Definition:

Notes: When using 4-color paletted textures the offset is calculated in steps of 8. In any other cases it’s steps of 16.

Diffuse/Ambient Properties: Port 0x040004C0, index 0x30, 1 Parameter

Sets the Diffused/Ambient properties for the next vertex.

Parameter definition:

Specular/Emissive Properties: Port 0x040004C4, index 0x31, 1 Parameter

Sets the Specular/Emissive properties for the next vertex.

Parameter definition:

Vertex Position Commands

All of these commands send a new vertex to the geometry engine once executes. Unless stated otherwise, the vertex coordinates will be a 16bit signed integer with a 12bit fraction. (i.e Range is +7.99 to -8.00)

Position Set (16-bit): Port 0x0400048C, Index 0x23, 2 Parameters

Set all coordinates of the next vertex at once.

Parameter Definition:

Position Set (10-bit): Port 0x04000490, Index 0x24, 1 Parameter

Set all coordinates of the next vertex at once, but with less accuracy.

Parameter Definition:

Position Set XY: Port 0x04000494, Index 0x25, 1 Parameter

Set X and Y coordinate of the next vertex.

Parameter Definition:

Position Set XZ: Port 0x04000498, Index 0x26, 1 Parameter

Set X and Z coordinate of the next vertex.

Parameter Definition:

Position Set YZ: Port 0x0400049C, Index 0x27, 1 Parameter

Set Y and Z coordinate of the next vertex.

Parameter Definition:

Position Set Relative: Port 0x040004A0, Index 0x28, 1 Parameter

Set all coordinates of the next vertex at once, but relative to the last vertex.

Parameter Definition:

Note: As the value is smaller than the fraction, the relative range is very small (+-0.125)

3D Matrix Commands

On the DS there are multiple matrix operations as well as matrix stacks responsible for calculating the resulting light, normal, and position vectors related to any given vertex. These matrix stacks are:

• Projection stack (Size: 1, Mode: 0)
• Coordinate stack (Size: 32, Mode: 1,2)
• Directional stack (Size: 32, Mode: 1,2)
• Texture stack: (Size: 1, Mode: 3)

Mode in this case reffers to what index needs to be sent to CMD 0x10 in order to “select” the given stack. Notice how the coordinate and directional stack share modes 1 and 2. Which indicates how both are changed when in those modes (and also internally share the same stack pointer). The two modes however change both stacks in different ways depending on the commands used.

When working with the matrix commands, you may often stumble upon the term “Current matrix”, which reffers to the matrix at the top of the selected matrix stack(s).

Matrix Stack Commands

Here are the commands which depends on the matrix stack(s):

Set Matrix Mode: Port 0x04000440, Index 0x10, 1 Parameter

Selects the matrix stack which is to be modified

Parameter Definition:

Possible Mode Indicies:

Push Matrix stack: Port 0x04000444, Index 0x11, No Parameter

Pushes the “Current matrix” onto the stack

Pull Matrix stack: Port 0x04000448, Index 0x12, 1 Parameter

Pops N matricies off the current matrix stack

Parameter Definition:

Notes:

On matrix stacks with a size of 1, the parameter is ignored and 1 is always used.

Store Current Matrix on Stack: Port 0x0400044C, Index 0x13, 1 Parameter

Stores the current matrix on another part of the stack. Leaves the stack pointer unchanged.

Parameter Definition:

Note:

A Stack Offset of 31 causes the stack error flag in the GXSTAT register to be set.

On stacks where the size is 1, the parameter is ignored and 0 is always used.

Restore Current Matrix from Stack: Port 0x04000450, Index 0x14, 1 Parameter

Sets the current matrix to the values of another matrix on the stack. Leaves the stack pointer unchanged.

Parameter Definition:

Note:

A Stack Offset of 31 causes the stack error flag in the GXSTAT register to be set.

On stacks where the size is 1, the parameter is ignored and 0 is always used.

General Matrix Commands

These are the commands which modify the current matrix:

Load Identity Matrix: Port 0x04000454, Index 0x15, No Parameter

Sets the current matrix to a Unit/Identity matrix. Sometimes denoted as I or 1.

Load 4x4 Matrix: Port 0x04000458, Index 0x16, 16 Parameters

Sets the current matrix to a 4x4 matrix, where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0.

Load 4x3 Matrix: Port 0x0400045C, Index 0x17, 12 Parameters

Sets the current matrix to a 4x3 matrix (padded to a 4x4 matrix which doesn’t scale W), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0.

Multiply 4x4 Matrix: Port 0x04000460, Index 0x18, 16 Parameters

Multiply the current matrix by a 4x4 matrix, where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0.

Multiply 4x3 Matrix: Port 0x04000464, Index 0x19, 12 Parameters

Multiply the current matrix by a 4x3 matrix (padded to a 4x4 matrix which doesn’t scale W), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0.

Multiply 3x3 Matrix: Port 0x04000468, Index 0x1A, 9 Parameters

Multiply the current matrix by a 3x3 matrix (padded to a 4x4 matrix which makes W unnaffected), where each parameter corresponds to a cell in the matrix. Values are loaded row by row. starting at row 0 column 0.

Scale Current Matrix by vector: Port 0x0400046C, Index 0x1B, 3 Parameters

Multiply the current matrix by a scale matrix where each scalar value corresponds to the coordinates in a vector. (W coordinate is always 1)

Translate Current Matrix by vector: Port 0x04000470, Index 0x1C, 3 Parameters

Multiply the current matrix by a translation matrix containing the supplied vector coordinates.

3D Light Commands

These are the commands which specifies the lighting conditions for any upcoming polygons and verticies.

Set Lights Directional Vector: Port 0x040004C8, Index 0x32, 1 Parameter

Sets the direction a given light points in.

Parameter Definition:

all coordinate parameters are in the same format, as in: 1bit sign + 9 bit fraction.

Set Lights Color: Port 0x040004CC, Index 0x33, 1 Parameter

Sets the color of a given light.

Parameter Definition:

Set Shininess table: Port 0x040004D0, Index 0x34, 32 Parameters

Sets the contents of a 128-byte shininess table used for specular reflections. transferred 4 entries (bytes) at a time. 0 = least shiny, 255 = most shiny.

Notes: When the shininess table is disabled, the Rendering Engine will act as if the table is filled with linearly increasing entries from the minimum to the maximum.

3D Test Commands

These Commands test various parameters against desired results by the user. Each command requires that the “test busy” bit of the GXSTAT register is cleared before reading the result.

Test if Cuboid Intersects View Volume: Port 0x040005C0, Index 0x70, 3 Parameters

The result of this command can be read from bit 1 of the GXSTAT register and indicates if any part of the specified cuboid intesects the view volume. A value of 1 indicates that the cuboid would have been visible if drawn.

Parameter definition:

all parameters are in the same format as 16 bit vertex coordinates. As in, 1bit sign + 3 bit integer + 12 bit fraction.

Set Coordinates for Position Test: Port 0x040005C4, Index 0x71, 2 Parameters

Takes the vector (x,y,z,1) and multiplies by the positional and projection matrix stacks. Result can be read from the memory region at 0x04000620..=0x0400062F where each word corresponds to a coordinate of the resulting vector. In format 1bit sign + 19 bit integer + 12 bit fraction.

Parameter Definition:

all parameters are in the same format as 16 bit vertex coordinates. As in, 1bit sign + 3 bit integer + 12 bit fraction.

Notes: This command should not be issued while a vertex list is being constructed. As any vertex position commands that inherit the coordinates of the previous vertex will instead inherit the coordinates set by this command.

Set Directional vector for Direction Test: Port 0x040005C8, Index 0x72, 1 Parameter

Takes the vector (x,y,z,0) and multiplies by the directional matrix stack. (according to no$ also requires matrix mode 2?) Result can be read from the memory region at 0x04000630..=0x04000635 where each 2byte half word corresponds to a coordinate of the resulting vector. In format 4bit sign + 12 bit fraction. (sign is either 0b0000 or 0b1111)

Parameter Definition:

all parameters are in the same format as those for other light direction commands, as in: 1bit sign + 9 bit fraction.

3D Rendering Engine

The Rendering Engine on the Nintendo DS is responsible for taking in the Vertex And Polygon buffers from the Geometry Engine and constructing frames of video. This can either be displayed as background 0 on the main 2D PPU or captured by the capture unit to be used as a bitmap image.

The Rendering Engine uses a 48-line “Scanline Cache” as opposed to a full framebuffer containing the entire output of a frame when rendering.

DS Sound

Hardware sound channels, microphone, audio capture.

DS Peripherals

Math co-processors, IPC (FIFO), Timers, RTC, SPI, touch screen, power management.

DS WiFi communications

The DS supports IEEE 802.11b wireless communications.

DS WiFi I/O Map

The following registers are only accessible from the ARM7. They are located at addresses 0x4808000 to 0x4808FFF. Addresses not included in the following list aren’t used. Also, many of the registers that are used aren’t understood.

Important note: 8-bit writes don’t work on WiFi registers and RAM, they are ignored.

General registers

Power registers

Receive control

Transmit control

WiFi timers

Configuration ports

Baseband chip

Internal registers

RF chip

WiFi statistics

Internal diagnostics

DS WiFi General Registers

W_ID: Chip ID (0x4808000, R)

This register returns 0x1440 in NDS, 0xC340 in NDS lite.

W_MODE_RST: Reset (0x4808004, R/W)

W_MODE_WEP: WEP mode (0x4808006, R/W)

W_TXSTATCNT: Beacons status register (0x4808008, R/W)

W_X_00A: Unknown (0x480800A, R/W)

W_IF: Interrupt request flags (0x4808010, R/W)

W_IE: Interrupt enable (0x4808012, R/W)

W_MACADDR_0: Hardware MAC address (0x4808018, R/W)

W_MACADDR_1: Hardware MAC address (0x480801A, R/W)

W_MACADDR_2: Hardware MAC address (0x480801C, R/W)

W_BSSID_0: BSSID (0x4808020, R/W)

W_BSSID_1: BSSID (0x4808022, R/W)

W_BSSID_2: BSSID (0x4808024, R/W)

W_AID_LOW: Unknown (0x4808028, R/W)

W_AID_FULL: Association ID (0x480802A, R/W)

W_TX_RETRYLIMIT: TX retry limit (0x480802C, R/W)

W_INTERNAL_02E: Unknown (0x480802E, R/W)

W_RXCNT: RX control (0x4808030, R/W)

W_WEP_CNT: WEP encryption enable (0x4808032, R/W)

W_INTERNAL_034: Unknown (0x4808034, R?)

Nintendo DSi Introduction

General introduction to the technical capabilities of the DSi, differences with the DS.

DSi I/O Map

New registers added in DSi (excluding WiFi and DSP, see their chapters for more information).

DSi Control Registers

SCFG, MBK registers.

DSi Shared WRAM

New shared WRAM.

DSi New DMA (NDMA)

New DMA channels.

DSi Sound

New microphone, getting sound into and out of the DSP.

DSi Touch Screen

Touch screen information.

DSi I2C Bus

I2C Bus usage.

DSi Cameras

Front and back cameras of the DSi.

DSi SD and MMC

How to access the SD and the NAND.

DSi GPIO

DSi AES Engine

DSi WiFi communications

The DSi supports IEEE 802.11b wireless communications.

DSi DSP XpertTeak

Other

Section for other information that is shared, or that doesn’t belong to either console model.

DS Cartridges

How to read DS cartridges. Maybe something about flashcards.

DS ROM Header

DS ROM header, differences with DSi ROM header.

DS CPU References

General description, links to ARM documentation (maybe we can add the PDF files to the repository).

DS BIOS Functions

DS and DSi BIOS functions. Handling of interrupts and exceptions.