Difference between revisions of "Xbox Debug Monitor"
m (Correct location of config file) |
(→delete (Delete file)) |
||
(27 intermediate revisions by 2 users not shown) | |||
Line 3: | Line 3: | ||
==Name Answering Protocol== | ==Name Answering Protocol== | ||
− | An Xbox Development Kit (XDK) can be assigned a ''debug name'' that identifies it on the local network. XBDM provides the ability to resolve a debug name to an IP address (forward lookup), resolve an IP address to a debug name (reverse lookup), and discover all XDKs on the local network using a very simple UDP-based protocol. | + | An Xbox Development Kit (XDK) can be assigned a ''debug name'' that identifies it on the local network. XBDM provides the ability to resolve a debug name to an IP address ([[#Forward Lookup|forward lookup]]), resolve an IP address to a debug name ([[#Reverse Lookup|reverse lookup]]), and [[#Console Discovery|discover]] all XDKs on the local network using a very simple UDP-based protocol. |
{|class="wikitable" style="margin: 0 auto; text-align: center;" | {|class="wikitable" style="margin: 0 auto; text-align: center;" | ||
Line 48: | Line 48: | ||
==Remote Debugging and Control Protocol== | ==Remote Debugging and Control Protocol== | ||
− | The Remote Debugging and Control Protocol (RDCP) is a text-based | + | The Remote Debugging and Control Protocol (RDCP) is a text-based protocol transmitted over a TCP connection on port 731. RDCP resembles protocols like FTP and SMTP, making it possible to communicate with XBDM using just a Telnet client in many cases. |
− | === | + | When a connection is established, XBDM sends <code>201- connected</code> (or <code>200- connected</code> in version 3944) followed by <CR><LF> (that is, a carriage return character followed by a line feed character). The RDCP client is then free to send a [[#Commands|command]] followed by <CR><LF> or <CR><NUL>. |
+ | |||
+ | After executing a command, XBDM replies with a response line consisting of a three-digit status code and message of the form <code>999- message text<CR><LF></code>. Note that unlike similar protocols, the <code>-</code> (dash) is always present in responses and messages cannot span multiple lines. | ||
+ | |||
+ | ===Status codes=== | ||
+ | |||
+ | In responses, 2xx status codes indicate success and 4xx codes indicate failure. Most codes have a default message, but some commands leave the message field empty while others use the message field to hold whatever data was requested by the client or additional information about an error. | ||
+ | |||
+ | ====2xx Success==== | ||
+ | |||
+ | ; <span id="status_200">200- OK</span> | ||
+ | : Standard response for successful execution of a command. | ||
+ | ; <span id="status_201">201- connected</span> | ||
+ | : Initial response sent after a connection is established. The client does not need to send anything to solicit this response. | ||
+ | ; <span id="status_202">202- multiline response follows</span> | ||
+ | : The response line is followed by one or more additional lines of data terminated by a line containing only a <code>.</code> (period). The client must read all available lines before sending another command. | ||
+ | ; <span id="status_203">203- binary response follows</span> | ||
+ | : The response line is followed by raw binary data, the length of which is indicated in some command-specific way. The client must read all available data before sending another command. | ||
+ | ; <span id="status_204">204- send binary data</span> | ||
+ | : The command is expecting additional binary data from the client. After the client sends the required number of bytes, XBDM will send another response line with the final result of the command. | ||
+ | ; <span id="status_205">205- connection dedicated</span> | ||
+ | : The connection has been moved to a dedicated handler thread (see [[#Connection dedication]]). | ||
+ | |||
+ | ====4xx Failure==== | ||
+ | |||
+ | ; <span id="status_400">400- unexpected error</span> | ||
+ | : An internal error occurred that could not be translated to a standard error code. The message is typically more descriptive, such as "out of memory" or "bad parameter". | ||
+ | ; <span id="status_401">401- max number of connections exceeded</span> | ||
+ | : The connection could not be established because XBDM is already serving the maximum number of clients (4). | ||
+ | ; <span id="status_402">402- file not found</span> | ||
+ | : An operation was attempted on a file that does not exist. | ||
+ | ; <span id="status_403">403- no such module</span> | ||
+ | : An operation was attempted on a module that does not exist. | ||
+ | ; <span id="status_404">404- memory not mapped</span> | ||
+ | : An operation was attempted on a region of memory that is not mapped in the page table. | ||
+ | ; <span id="status_405">405- no such thread</span> | ||
+ | : An operation was attempted on a thread that does not exist. | ||
+ | ; <span id="status_406">406-</span> | ||
+ | : An attempt to set the system time with the <code>[[#cmd_setsystime|setsystime]]</code> command failed. This status code is undocumented. | ||
+ | ; <span id="status_407">407- unknown command</span> | ||
+ | : The command is not recognized. | ||
+ | ; <span id="status_408">408- not stopped</span> | ||
+ | : The target thread is not stopped. | ||
+ | ; <span id="status_409">409- file must be copied</span> | ||
+ | : A move operation was attempted on a file that can only be copied. | ||
+ | ; <span id="status_410">410- file already exists</span> | ||
+ | : A file could not be created or moved because one already exists with the same name. | ||
+ | ; <span id="status_411">411- directory not empty</span> | ||
+ | : A directory could not be deleted because it still contains files and/or directories. | ||
+ | ; <span id="status_412">412- filename is invalid</span> | ||
+ | : The specified file contains invalid characters or is too long. | ||
+ | ; <span id="status_413">413- file cannot be created</span> | ||
+ | : The file cannot be created for some unspecified reason. | ||
+ | ; <span id="status_414">414- access denied</span> | ||
+ | : The file cannot be accessed at the connection's current privilege level (see [[#Security]]). | ||
+ | ; <span id="status_415">415- no room on device</span> | ||
+ | : The target device has run out of storage space. | ||
+ | ; <span id="status_416">416- not debuggable</span> | ||
+ | : The title is not debuggable. | ||
+ | ; <span id="status_417">417- type invalid</span> | ||
+ | : The performance counter type is invalid. | ||
+ | ; <span id="status_418">418- data not available</span> | ||
+ | : The performance counter data is not available. | ||
+ | ; <span id="status_420">420- box not locked</span> | ||
+ | : The command can only be executed when security is enabled (see [[#Security]]). | ||
+ | ; <span id="status_421">421- key exchange required</span> | ||
+ | : The client must perform a key exchange with the <code>[[#cmd_keyxchg|keyxchg]]</code> command (see [[#Security]]). | ||
+ | ; <span id="status_422">422- dedicated connection required</span> | ||
+ | : The command can only be executed on a dedicated connection (see [[#Connection dedication]]). | ||
+ | |||
+ | ===Connection dedication=== | ||
+ | |||
+ | '''Connection dedication''' is the process of moving a client connection from the ''global server thread'' to a ''threaded command handler thread'' with the <code>dedicate</code> command. | ||
+ | |||
+ | By default, commands sent to XBDM are processed on the global server thread. Built-in commands and custom command handlers registered with <code>DmRegisterCommandProcessor</code> are run on this thread and may only execute kernel APIs. Commands that need to call CRT or XAPI functions must run in a threaded command handler, registered with <code>DmRegisterCommandProcessorEx</code> or <code>DmRegisterThreadedCommandProcessor</code>. | ||
+ | |||
+ | A client that has not dedicated its connection will receive a <code>422- dedicated connection required</code> response if it tries to execute a threaded command on the global server thread. After dedicating itself to a threaded command handler, the client can no longer send built-in or non-threaded commands until it re-dedicates itself to the global server thread. | ||
+ | |||
+ | ===Security=== | ||
TODO | TODO | ||
Line 56: | Line 134: | ||
===Commands=== | ===Commands=== | ||
− | + | ''See also: [[XBDM commands by version]]'' | |
+ | |||
+ | A command consists of a name and zero or more parameters separated by whitespace characters. The format of the parameters is defined by the command, but most commands use the form <code>key=value</code>. Parameter values that contain whitespace characters must be surrounded by double quotes (e.g. <code>"some value"</code> or <code>key="some value"</code>). | ||
+ | |||
+ | In the command descriptions below, the following data types are used: | ||
+ | |||
+ | {| class="wikitable" style="margin: 0 auto" | ||
+ | ! Type !! Description | ||
+ | |- | ||
+ | | DWORD || A 32-bit integer in hexadecimal format (e.g. <code>0x1234ABCD</code>). | ||
+ | |- | ||
+ | | QWORD || A 64-bit integer in hexadecimal format, but prefixed with 0q instead of 0x (e.g. <code>0q0123456789ABCDEF</code>). | ||
+ | |- | ||
+ | | STRING || An ASCII-encoded string, optionally surrounded by double quotes. | ||
+ | |} | ||
+ | |||
+ | ====<span id="cmd_adminpw">adminpw</span> (Set administrator password)==== | ||
+ | |||
+ | {{XBDM command|version=4039+|text=adminpw none|privs=manage}} | ||
+ | |||
+ | Clear the administrator password. | ||
+ | |||
+ | {{XBDM command|version=4039+|text=adminpw passwd=QWORD|privs=manage}} | ||
+ | |||
+ | Set the administrator password to the value of the <code>passwd</code> parameter. Note that <code>passwd</code> is a 64-bit integer instead of a string. The details of the conversion from a string password to a 64-bit integer are currently unknown. | ||
+ | |||
+ | ====<span id="cmd_altaddr">altaddr</span>==== | ||
+ | ====<span id="cmd_authuser">authuser</span> (Authenticate user)==== | ||
+ | ====<span id="cmd_boxid">boxid</span>==== | ||
+ | ====<span id="cmd_break">break</span>==== | ||
+ | ====<span id="cmd_bye">bye</span> (Close connection)==== | ||
+ | ====<span id="cmd_capcontrol">capcontrol</span>/<span id="cmd_capctrl">capctrl</span>==== | ||
+ | ====<span id="cmd_continue">continue</span>==== | ||
+ | ====<span id="cmd_crashdump">crashdump</span>==== | ||
+ | ====<span id="cmd_d3dopcode">d3dopcode</span>==== | ||
+ | ====<span id="cmd_dbgname">dbgname</span> (Get/set debug name)==== | ||
+ | ====<span id="cmd_dbgoptions">dbgoptions</span>==== | ||
+ | ====<span id="cmd_debugger">debugger</span>==== | ||
+ | ====<span id="cmd_debugmode">debugmode</span>==== | ||
+ | ====<span id="cmd_dedicate">dedicate</span> (Dedicate connection)==== | ||
+ | ====<span id="cmd_deftitle">deftitle</span>==== | ||
+ | ====<span id="cmd_delete">delete</span> (Delete file or directory)==== | ||
+ | |||
+ | {{XBDM command|text=delete name=STRING dir}} | ||
+ | |||
+ | Deletes a file or directory. | ||
+ | |||
+ | To delete a directory, the optional <code>dir</code> attribute must be present. | ||
+ | |||
+ | ====<span id="cmd_dirlist">dirlist</span> (List files in directory)==== | ||
+ | ====<span id="cmd_dmversion">dmversion</span> (Get debug monitor version)==== | ||
+ | ====<span id="cmd_drivefreespace">drivefreespace</span> (Get free space on drive)==== | ||
+ | ====<span id="cmd_drivelist">drivelist</span> (List drive letters)==== | ||
+ | |||
+ | {{XBDM command|text=drivelist}} | ||
+ | |||
+ | Returns a string which contains the drive-letter for each accessible drive. | ||
+ | |||
+ | ====<span id="cmd_dvdblk">dvdblk</span> (Read block from DVD)==== | ||
+ | ====<span id="cmd_dvdperf">dvdperf</span>==== | ||
+ | ====<span id="cmd_fileeof">fileeof</span>==== | ||
+ | ====<span id="cmd_flash">flash</span> (Flash BIOS image)==== | ||
+ | ====<span id="cmd_fmtfat">fmtfat</span> (Format FAT partition)==== | ||
+ | ====<span id="cmd_funccall">funccall</span>==== | ||
+ | ====<span id="cmd_getcontext">getcontext</span> (Get thread context)==== | ||
+ | ====<span id="cmd_getd3dstate">getd3dstate</span> (Get Direct3D state)==== | ||
+ | ====<span id="cmd_getextcontext">getextcontext</span> (Get extended thread context)==== | ||
+ | |||
+ | ====<span id="cmd_getfile">getfile</span> (Download file)==== | ||
+ | |||
+ | {{XBDM command|text=getfile name=STRING}} | ||
+ | |||
+ | Retrieve the entire contents of the named file. | ||
+ | The received data is prefixed with a 32 bit little endian value, which contains the number of bytes which have been read. | ||
+ | |||
+ | {{XBDM command|text=getfile name=STRING offset=DWORD size=DWORD}} | ||
+ | |||
+ | Retrieve <code>size</code> bytes starting at <code>offset</code> from the named file. | ||
+ | The received data is prefixed with a 32 bit little endian value, which contains the number of bytes which have been read. | ||
+ | |||
+ | ====<span id="cmd_getfileattributes">getfileattributes</span> (Get file attributes)==== | ||
+ | ====<span id="cmd_getgamma">getgamma</span> (Get gamma table)==== | ||
+ | ====<span id="cmd_getmem">getmem</span> (Read memory)==== | ||
+ | ====<span id="cmd_getmem2">getmem2</span> (Read memory)==== | ||
+ | ====<span id="cmd_getpalette">getpalette</span>==== | ||
+ | ====<span id="cmd_getpid">getpid</span>==== | ||
+ | ====<span id="cmd_getsum">getsum (Generate memory checksums)</span>==== | ||
+ | |||
+ | {{XBDM command|version=5120+|text=getsum addr=DWORD length=DWORD blocksize=DWORD}} | ||
+ | |||
+ | Generates one or more checksums from memory. | ||
+ | |||
+ | The function will return <code>length</code> divided by <code>blocksize</code> 32-bit little endian checksums for the memory starting at virtual address <code>addr</code>. | ||
+ | |||
+ | The <code>addr</code>, <code>length</code> and <code>blocksize</code> must be multiples of 8. | ||
+ | Picking bad values can lead to crashes. | ||
+ | |||
+ | Each checksum is equal to <code>ReverseBitOrder(CRC32(address + blockoffset, blocksize) XOR 0xFFFFFFFF)</code> for the respective block. | ||
+ | |||
+ | ====<span id="cmd_getsurf">getsurf</span>==== | ||
+ | ====<span id="cmd_getuserpriv">getuserpriv</span> (Get user's privilege level)==== | ||
+ | ====<span id="cmd_getutildrvinfo">getutildrvinfo</span> (Get utility drive information)==== | ||
+ | ====<span id="cmd_go">go</span>==== | ||
+ | ====<span id="cmd_gpucount">gpucount</span> (Toggle GPU counters)==== | ||
+ | ====<span id="cmd_halt">halt</span>==== | ||
+ | ====<span id="cmd_irtsweep">irtsweep</span>==== | ||
+ | ====<span id="cmd_isbreak">isbreak</span>==== | ||
+ | ====<span id="cmd_isdebugger">isdebugger</span>==== | ||
+ | ====<span id="cmd_isstopped">isstopped</span>==== | ||
+ | ====<span id="cmd_kd">kd</span> (Enable/disable kernel debugger)==== | ||
+ | ====<span id="cmd_keyxchg">keyxchg</span> (Perform key exchange)==== | ||
+ | ====<span id="cmd_lockmode">lockmode</span>==== | ||
+ | ====<span id="cmd_lop">lop</span>==== | ||
+ | ====<span id="cmd_magicboot">magicboot (Boot into new title)</span>==== | ||
+ | |||
+ | {{XBDM command|text=magicboot title=STRING debug}} | ||
+ | |||
+ | Boots into another title, specified by the path to XBE in <code>title</code>. | ||
+ | |||
+ | If the optional <code>debug</code> is provided, XBDM will remain loaded while the title is running. | ||
+ | |||
+ | ====<span id="cmd_memtrack">memtrack</span>==== | ||
+ | ====<span id="cmd_mkdir">mkdir</span> (Create directory)==== | ||
+ | ====<span id="cmd_mmglobal">mmglobal</span>==== | ||
+ | ====<span id="cmd_modlong">modlong</span>==== | ||
+ | ====<span id="cmd_modsections">modsections</span>==== | ||
+ | ====<span id="cmd_modules">modules</span>==== | ||
+ | ====<span id="cmd_nostopon">nostopon</span>==== | ||
+ | ====<span id="cmd_notify">notify</span>==== | ||
+ | ====<span id="cmd_notifyat">notifyat</span>==== | ||
+ | ====<span id="cmd_pbsnap">pbsnap</span>==== | ||
+ | ====<span id="cmd_pclist">pclist</span> (List performance counters)==== | ||
+ | ====<span id="cmd_pdbinfo">pdbinfo</span>==== | ||
+ | ====<span id="cmd_pssnap">pssnap</span>==== | ||
+ | ====<span id="cmd_querypc">querypc</span> (Query performance counter)==== | ||
+ | ====<span id="cmd_reboot">reboot</span>==== | ||
+ | ====<span id="cmd_rename">rename</span> (Rename file)==== | ||
+ | ====<span id="cmd_resume">resume</span>==== | ||
+ | ====<span id="cmd_screenshot">screenshot</span> (Take screenshot)==== | ||
+ | ====<span id="cmd_sendfile">sendfile</span> (Upload file)==== | ||
+ | ====<span id="cmd_servname">servname</span>==== | ||
+ | ====<span id="cmd_setconfig">setconfig</span>==== | ||
+ | ====<span id="cmd_setcontext">setcontext</span> (Set thread context)==== | ||
+ | ====<span id="cmd_setfileattributes">setfileattributes</span> (Set file attributes)==== | ||
+ | ====<span id="cmd_setsystime">setsystime</span> (Set system time)==== | ||
+ | ====<span id="cmd_setuserpriv">setuserpriv</span> (Set user's privilege level)==== | ||
+ | ====<span id="cmd_signcontent">signcontent</span>==== | ||
+ | ====<span id="cmd_stop">stop</span>==== | ||
+ | ====<span id="cmd_stopon">stopon</span>==== | ||
+ | ====<span id="cmd_suspend">suspend</span>==== | ||
+ | ====<span id="cmd_sysfileupd">sysfileupd</span> (Update system file)==== | ||
+ | ====<span id="cmd_systime">systime</span> (Get system time)==== | ||
+ | ====<span id="cmd_threadinfo">threadinfo</span> (Get thread information)==== | ||
+ | ====<span id="cmd_threads">threads</span> (List threads)==== | ||
+ | ====<span id="cmd_title">title</span>==== | ||
+ | ====<span id="cmd_user">user</span>==== | ||
+ | ====<span id="cmd_userlist">userlist</span> (List users)==== | ||
+ | ====<span id="cmd_vssnap">vssnap</span>==== | ||
+ | ====<span id="cmd_walkmem">walkmem</span>==== | ||
+ | ====<span id="cmd_writefile">writefile</span>==== | ||
+ | ====<span id="cmd_xbeinfo">xbeinfo</span>==== | ||
+ | ====<span id="cmd_xtlinfo">xtlinfo</span>==== | ||
==See Also== | ==See Also== | ||
Line 64: | Line 303: | ||
==External Links== | ==External Links== | ||
− | |||
* [https://github.com/Ernegien/ViridiX ViridiX] – An open-source collection of Xbox debugging libraries and tools written in C#. | * [https://github.com/Ernegien/ViridiX ViridiX] – An open-source collection of Xbox debugging libraries and tools written in C#. | ||
+ | * [https://github.com/docbrown/xbdm-rs xbdm-rs] - An open-source XBDM client written in Rust. |
Latest revision as of 16:09, 16 February 2019
The Xbox Debug Monitor (XBDM) is a feature of Xbox Development Kits that provides remote debugging, file management, console discovery, and other services on TCP/UDP port 731. It is loaded by debug kernels at startup from C:\xbdm.dll
and its configuration is read from E:\xbdm.ini
. XBDM is distinct from KD and uses a different wire protocol.
Contents
- 1 Name Answering Protocol
- 2 Remote Debugging and Control Protocol
- 2.1 Status codes
- 2.2 Connection dedication
- 2.3 Security
- 2.4 Commands
- 2.4.1 adminpw (Set administrator password)
- 2.4.2 altaddr
- 2.4.3 authuser (Authenticate user)
- 2.4.4 boxid
- 2.4.5 break
- 2.4.6 bye (Close connection)
- 2.4.7 capcontrol/capctrl
- 2.4.8 continue
- 2.4.9 crashdump
- 2.4.10 d3dopcode
- 2.4.11 dbgname (Get/set debug name)
- 2.4.12 dbgoptions
- 2.4.13 debugger
- 2.4.14 debugmode
- 2.4.15 dedicate (Dedicate connection)
- 2.4.16 deftitle
- 2.4.17 delete (Delete file or directory)
- 2.4.18 dirlist (List files in directory)
- 2.4.19 dmversion (Get debug monitor version)
- 2.4.20 drivefreespace (Get free space on drive)
- 2.4.21 drivelist (List drive letters)
- 2.4.22 dvdblk (Read block from DVD)
- 2.4.23 dvdperf
- 2.4.24 fileeof
- 2.4.25 flash (Flash BIOS image)
- 2.4.26 fmtfat (Format FAT partition)
- 2.4.27 funccall
- 2.4.28 getcontext (Get thread context)
- 2.4.29 getd3dstate (Get Direct3D state)
- 2.4.30 getextcontext (Get extended thread context)
- 2.4.31 getfile (Download file)
- 2.4.32 getfileattributes (Get file attributes)
- 2.4.33 getgamma (Get gamma table)
- 2.4.34 getmem (Read memory)
- 2.4.35 getmem2 (Read memory)
- 2.4.36 getpalette
- 2.4.37 getpid
- 2.4.38 getsum (Generate memory checksums)
- 2.4.39 getsurf
- 2.4.40 getuserpriv (Get user's privilege level)
- 2.4.41 getutildrvinfo (Get utility drive information)
- 2.4.42 go
- 2.4.43 gpucount (Toggle GPU counters)
- 2.4.44 halt
- 2.4.45 irtsweep
- 2.4.46 isbreak
- 2.4.47 isdebugger
- 2.4.48 isstopped
- 2.4.49 kd (Enable/disable kernel debugger)
- 2.4.50 keyxchg (Perform key exchange)
- 2.4.51 lockmode
- 2.4.52 lop
- 2.4.53 magicboot (Boot into new title)
- 2.4.54 memtrack
- 2.4.55 mkdir (Create directory)
- 2.4.56 mmglobal
- 2.4.57 modlong
- 2.4.58 modsections
- 2.4.59 modules
- 2.4.60 nostopon
- 2.4.61 notify
- 2.4.62 notifyat
- 2.4.63 pbsnap
- 2.4.64 pclist (List performance counters)
- 2.4.65 pdbinfo
- 2.4.66 pssnap
- 2.4.67 querypc (Query performance counter)
- 2.4.68 reboot
- 2.4.69 rename (Rename file)
- 2.4.70 resume
- 2.4.71 screenshot (Take screenshot)
- 2.4.72 sendfile (Upload file)
- 2.4.73 servname
- 2.4.74 setconfig
- 2.4.75 setcontext (Set thread context)
- 2.4.76 setfileattributes (Set file attributes)
- 2.4.77 setsystime (Set system time)
- 2.4.78 setuserpriv (Set user's privilege level)
- 2.4.79 signcontent
- 2.4.80 stop
- 2.4.81 stopon
- 2.4.82 suspend
- 2.4.83 sysfileupd (Update system file)
- 2.4.84 systime (Get system time)
- 2.4.85 threadinfo (Get thread information)
- 2.4.86 threads (List threads)
- 2.4.87 title
- 2.4.88 user
- 2.4.89 userlist (List users)
- 2.4.90 vssnap
- 2.4.91 walkmem
- 2.4.92 writefile
- 2.4.93 xbeinfo
- 2.4.94 xtlinfo
- 3 See Also
- 4 External Links
Name Answering Protocol
An Xbox Development Kit (XDK) can be assigned a debug name that identifies it on the local network. XBDM provides the ability to resolve a debug name to an IP address (forward lookup), resolve an IP address to a debug name (reverse lookup), and discover all XDKs on the local network using a very simple UDP-based protocol.
Offsets | Octet | 0 | 1 | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Octet | Bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
0 | 0 | Type | Name Length | ||||||||||||||
2 | 16+ | Name |
A NAP packet contains 3 fields, the last of which is variable-length. The minimum length of a NAP packet is 2 bytes and the maximum is 257. Invalid packets are silently dropped by XBDM.
- Type
- This unsigned 8-bit field may contain the values 1 (lookup), 2 (reply), or 3 (wildcard).
- Name Length
- This unsigned 8-bit field specifies the length of the Name field and should be a value from 0 to 255. For Type 3 packets, this field should always be 0. For Type 1 and Type 2 packets, this field should never be 0.
- Name
- This variable-length field contains the ASCII-encoded debug name for Type 1 and Type 2 packets. The number of bytes in this field is given by the Length field. It should not contain any
NUL
characters.
Forward Lookup
To resolve a debug name to an IP address, send a Type 1 NAP packet containing the debug name to be resolved to UDP address 255.255.255.255:731. The XDK with that name will respond with a Type 2 NAP packet and its IP address can be retrieved from the UDP header. There is no way to prevent multiple XDKs being assigned the same debug name, so it's possible that the client may receive replies from multiple IP addresses.
Reverse Lookup
To resolve an IP address to a debug name, send a Type 3 NAP packet with no name (length 0) to the IP address on UDP port 731. Assuming the target is actually an XDK, it will respond with a Type 2 NAP packet containing its name. This is very similar to the Console Discovery process (below), except that by sending the wildcard packet to a single IP address, only that XDK will respond.
Console Discovery
To discover all XDKs on the local network, send a Type 3 NAP packet with no name (length 0) to the UDP address 255.255.255.255:731. Each XDK will respond with a Type 2 NAP packet containing its name. As with a forward lookup, the client may receive multiple replies with the same name, but different IP addresses.
Remote Debugging and Control Protocol
The Remote Debugging and Control Protocol (RDCP) is a text-based protocol transmitted over a TCP connection on port 731. RDCP resembles protocols like FTP and SMTP, making it possible to communicate with XBDM using just a Telnet client in many cases.
When a connection is established, XBDM sends 201- connected
(or 200- connected
in version 3944) followed by <CR><LF> (that is, a carriage return character followed by a line feed character). The RDCP client is then free to send a command followed by <CR><LF> or <CR><NUL>.
After executing a command, XBDM replies with a response line consisting of a three-digit status code and message of the form 999- message text<CR><LF>
. Note that unlike similar protocols, the -
(dash) is always present in responses and messages cannot span multiple lines.
Status codes
In responses, 2xx status codes indicate success and 4xx codes indicate failure. Most codes have a default message, but some commands leave the message field empty while others use the message field to hold whatever data was requested by the client or additional information about an error.
2xx Success
- 200- OK
- Standard response for successful execution of a command.
- 201- connected
- Initial response sent after a connection is established. The client does not need to send anything to solicit this response.
- 202- multiline response follows
- The response line is followed by one or more additional lines of data terminated by a line containing only a
.
(period). The client must read all available lines before sending another command. - 203- binary response follows
- The response line is followed by raw binary data, the length of which is indicated in some command-specific way. The client must read all available data before sending another command.
- 204- send binary data
- The command is expecting additional binary data from the client. After the client sends the required number of bytes, XBDM will send another response line with the final result of the command.
- 205- connection dedicated
- The connection has been moved to a dedicated handler thread (see #Connection dedication).
4xx Failure
- 400- unexpected error
- An internal error occurred that could not be translated to a standard error code. The message is typically more descriptive, such as "out of memory" or "bad parameter".
- 401- max number of connections exceeded
- The connection could not be established because XBDM is already serving the maximum number of clients (4).
- 402- file not found
- An operation was attempted on a file that does not exist.
- 403- no such module
- An operation was attempted on a module that does not exist.
- 404- memory not mapped
- An operation was attempted on a region of memory that is not mapped in the page table.
- 405- no such thread
- An operation was attempted on a thread that does not exist.
- 406-
- An attempt to set the system time with the
setsystime
command failed. This status code is undocumented. - 407- unknown command
- The command is not recognized.
- 408- not stopped
- The target thread is not stopped.
- 409- file must be copied
- A move operation was attempted on a file that can only be copied.
- 410- file already exists
- A file could not be created or moved because one already exists with the same name.
- 411- directory not empty
- A directory could not be deleted because it still contains files and/or directories.
- 412- filename is invalid
- The specified file contains invalid characters or is too long.
- 413- file cannot be created
- The file cannot be created for some unspecified reason.
- 414- access denied
- The file cannot be accessed at the connection's current privilege level (see #Security).
- 415- no room on device
- The target device has run out of storage space.
- 416- not debuggable
- The title is not debuggable.
- 417- type invalid
- The performance counter type is invalid.
- 418- data not available
- The performance counter data is not available.
- 420- box not locked
- The command can only be executed when security is enabled (see #Security).
- 421- key exchange required
- The client must perform a key exchange with the
keyxchg
command (see #Security). - 422- dedicated connection required
- The command can only be executed on a dedicated connection (see #Connection dedication).
Connection dedication
Connection dedication is the process of moving a client connection from the global server thread to a threaded command handler thread with the dedicate
command.
By default, commands sent to XBDM are processed on the global server thread. Built-in commands and custom command handlers registered with DmRegisterCommandProcessor
are run on this thread and may only execute kernel APIs. Commands that need to call CRT or XAPI functions must run in a threaded command handler, registered with DmRegisterCommandProcessorEx
or DmRegisterThreadedCommandProcessor
.
A client that has not dedicated its connection will receive a 422- dedicated connection required
response if it tries to execute a threaded command on the global server thread. After dedicating itself to a threaded command handler, the client can no longer send built-in or non-threaded commands until it re-dedicates itself to the global server thread.
Security
TODO
Commands
See also: XBDM commands by version
A command consists of a name and zero or more parameters separated by whitespace characters. The format of the parameters is defined by the command, but most commands use the form key=value
. Parameter values that contain whitespace characters must be surrounded by double quotes (e.g. "some value"
or key="some value"
).
In the command descriptions below, the following data types are used:
Type | Description |
---|---|
DWORD | A 32-bit integer in hexadecimal format (e.g. 0x1234ABCD ).
|
QWORD | A 64-bit integer in hexadecimal format, but prefixed with 0q instead of 0x (e.g. 0q0123456789ABCDEF ).
|
STRING | An ASCII-encoded string, optionally surrounded by double quotes. |
adminpw (Set administrator password)
4039+ | adminpw none
|
manage |
---|
Clear the administrator password.
4039+ | adminpw passwd=QWORD
|
manage |
---|
Set the administrator password to the value of the passwd
parameter. Note that passwd
is a 64-bit integer instead of a string. The details of the conversion from a string password to a 64-bit integer are currently unknown.
altaddr
authuser (Authenticate user)
boxid
break
bye (Close connection)
capcontrol/capctrl
continue
crashdump
d3dopcode
dbgname (Get/set debug name)
dbgoptions
debugger
debugmode
dedicate (Dedicate connection)
deftitle
delete (Delete file or directory)
3944+ | delete name=STRING dir
|
- |
---|
Deletes a file or directory.
To delete a directory, the optional dir
attribute must be present.
dirlist (List files in directory)
dmversion (Get debug monitor version)
drivefreespace (Get free space on drive)
drivelist (List drive letters)
3944+ | drivelist
|
- |
---|
Returns a string which contains the drive-letter for each accessible drive.
dvdblk (Read block from DVD)
dvdperf
fileeof
flash (Flash BIOS image)
fmtfat (Format FAT partition)
funccall
getcontext (Get thread context)
getd3dstate (Get Direct3D state)
getextcontext (Get extended thread context)
getfile (Download file)
3944+ | getfile name=STRING
|
- |
---|
Retrieve the entire contents of the named file. The received data is prefixed with a 32 bit little endian value, which contains the number of bytes which have been read.
3944+ | getfile name=STRING offset=DWORD size=DWORD
|
- |
---|
Retrieve size
bytes starting at offset
from the named file.
The received data is prefixed with a 32 bit little endian value, which contains the number of bytes which have been read.
getfileattributes (Get file attributes)
getgamma (Get gamma table)
getmem (Read memory)
getmem2 (Read memory)
getpalette
getpid
getsum (Generate memory checksums)
5120+ | getsum addr=DWORD length=DWORD blocksize=DWORD
|
- |
---|
Generates one or more checksums from memory.
The function will return length
divided by blocksize
32-bit little endian checksums for the memory starting at virtual address addr
.
The addr
, length
and blocksize
must be multiples of 8.
Picking bad values can lead to crashes.
Each checksum is equal to ReverseBitOrder(CRC32(address + blockoffset, blocksize) XOR 0xFFFFFFFF)
for the respective block.
getsurf
getuserpriv (Get user's privilege level)
getutildrvinfo (Get utility drive information)
go
gpucount (Toggle GPU counters)
halt
irtsweep
isbreak
isdebugger
isstopped
kd (Enable/disable kernel debugger)
keyxchg (Perform key exchange)
lockmode
lop
magicboot (Boot into new title)
3944+ | magicboot title=STRING debug
|
- |
---|
Boots into another title, specified by the path to XBE in title
.
If the optional debug
is provided, XBDM will remain loaded while the title is running.
memtrack
mkdir (Create directory)
mmglobal
modlong
modsections
modules
nostopon
notify
notifyat
pbsnap
pclist (List performance counters)
pdbinfo
pssnap
querypc (Query performance counter)
reboot
rename (Rename file)
resume
screenshot (Take screenshot)
sendfile (Upload file)
servname
setconfig
setcontext (Set thread context)
setfileattributes (Set file attributes)
setsystime (Set system time)
setuserpriv (Set user's privilege level)
signcontent
stop
stopon
suspend
sysfileupd (Update system file)
systime (Get system time)
threadinfo (Get thread information)
threads (List threads)
title
user
userlist (List users)
vssnap
walkmem
writefile
xbeinfo
xtlinfo
See Also
- Xbox Neighborhood – An XDK tool that utilizes the XBDM protocols