Difference between revisions of "EmBIOS Monitor Protocol"

From freemyipod.org
Jump to: navigation, search
Line 135: Line 135:
 
|-
 
|-
 
| style="text-align:right" | 12 || style="text-align:right" | 4 || Maximum Data IN Endpoint packet size
 
| style="text-align:right" | 12 || style="text-align:right" | 4 || Maximum Data IN Endpoint packet size
 +
|-
 +
|}
 +
 +
 +
==== Get user memory address range ====
 +
Provides information about the range of memory not used by emBIOS itself.
 +
 +
{| class="wikitable prettytable"
 +
|+ Command Packet
 +
|-
 +
! Offset !! Size (bytes) !! Description
 +
|-
 +
| style="text-align:right" | 0 || style="text-align:right" | 4 || Command ID (1)
 +
|-
 +
| style="text-align:right" | 4 || style="text-align:right" | 4 || Requested information type (2)
 +
|-
 +
| style="text-align:right" | 8 || style="text-align:right" | 8 || Should be zero
 +
|-
 +
|}
 +
 +
{| class="wikitable prettytable"
 +
|+ Response Packet
 +
|-
 +
! Offset !! Size (bytes) !! Description
 +
|-
 +
| style="text-align:right" | 0 || style="text-align:right" | 4 || Status Code (1)
 +
|-
 +
| style="text-align:right" | 4 || style="text-align:right" | 4 || Lower bound (inclusive) of the usable memory range
 +
|-
 +
| style="text-align:right" | 8 || style="text-align:right" | 4 || Upper bound (exclusive) of the usable memory range
 +
|-
 +
| style="text-align:right" | 12 || style="text-align:right" | 4 || Undefined
 
|-
 
|-
 
|}
 
|}
Line 755: Line 787:
 
|-
 
|-
 
| style="text-align:right" | 4 || style="text-align:right" | 12 || Undefined
 
| style="text-align:right" | 4 || style="text-align:right" | 12 || Undefined
|-
 
|}
 
 
 
=== 21: Get user memory address range ===
 
Provides information about the range of memory not used by emBIOS itself.
 
 
{| class="wikitable prettytable"
 
|+ Command Packet
 
|-
 
! Offset !! Size (bytes) !! Description
 
|-
 
| style="text-align:right" | 0 || style="text-align:right" | 4 || Command ID (21)
 
|-
 
| style="text-align:right" | 4 || style="text-align:right" | 12 || Should be zero
 
|-
 
|}
 
 
{| class="wikitable prettytable"
 
|+ Response Packet
 
|-
 
! Offset !! Size (bytes) !! Description
 
|-
 
| style="text-align:right" | 0 || style="text-align:right" | 4 || Status Code (1)
 
|-
 
| style="text-align:right" | 4 || style="text-align:right" | 4 || Lower bound (inclusive) of the usable memory range
 
|-
 
| style="text-align:right" | 8 || style="text-align:right" | 4 || Upper bound (exclusive) of the usable memory range
 
|-
 
| style="text-align:right" | 12 || style="text-align:right" | 4 || Undefined
 
 
|-
 
|-
 
|}
 
|}

Revision as of 01:09, 6 August 2010

This article describes the USB communcation protocol of emBIOS monitor.


Endpoints

The emBIOS Monitor interface contains 4 bulk endpoints, in the following order:

  • Command OUT Endpoint
  • Command IN Endpoint
  • Data OUT Endpoint
  • Data IN Endpoint

If not stated otherwise, everything is little endian.


General Structure

Each packet send to the Command OUT Endpoint has a 16 byte header. The first 4 bytes, interpreted as a 32bit little endian word, contain the command ID. The meaning of the other bytes depends on the command. For commands that send data to the device, it will immediately follow that header.

After sending a packet to the Command OUT Endpoint, listen on the Command IN Endpoint for a response. The response also has a 16 byte header, followed by an optional data stage, depending on the command. The first 4 bytes of the header, interpreted as a 32bit word, is the status code, the meaning of the other bytes depends on the command.

Status Codes
Status Code Description
0 Invalid response, you should bail out when receiving this
1 OK (everything went fine)
2 Command not supported
3 Device is busy, retry later (another asynchronous command is already running)


Commands

0: Invalid

Never issue this command. It will be rejected with status code 2.


1: Get device information

Use this command to figure out various device properties.

Get version information

Command Packet
Offset Size (bytes) Description
0 4 Command ID (1)
4 4 Requested information type (0)
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 SVN Revision Number
8 1 Major version
9 1 Minor version
10 1 Patch version
11 1 Software Type ID
12 4 Device Type ID
Software Types
Software Type ID Description
0 invalid
1 emBIOS Debugger
Hardware Types
Software Type ID Description
0 invalid
0x47324e49 iPod Nano 2G
0x47334e49 iPod Nano 3G
0x47344e49 iPod Nano 4G
0x4c435049 iPod Classic


Get packet size information

Command Packet
Offset Size (bytes) Description
0 4 Command ID (1)
4 4 Requested information type (1)
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 2 Maximum Command OUT Endpoint packet size
6 2 Maximum Command IN Endpoint packet size
8 4 Maximum Data OUT Endpoint packet size
12 4 Maximum Data IN Endpoint packet size


Get user memory address range

Provides information about the range of memory not used by emBIOS itself.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (1)
4 4 Requested information type (2)
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 Lower bound (inclusive) of the usable memory range
8 4 Upper bound (exclusive) of the usable memory range
12 4 Undefined


2: Reset

Reboot the device.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (2)
4 4 Type: Reboot forcibly (0) / Reboot gracefully (1)
8 8 Should be zero

Graceful reboots are asynchronous commands. Forced reboots won't send a response packet before rebooting.

Response Packet
Offset Size (bytes) Description
0 4 Status Code (1 or 3)
4 12 Undefined

The response indicates that the request has been acknowledged, however there might be substantial delay before device actually reboots.


3: Power off

Power the device off.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (3)
4 4 Type: Power off forcibly (0) / Shut down gracefully (1)
8 8 Should be zero

Both variants are asynchronous commands.

Response Packet
Offset Size (bytes) Description
0 4 Status Code (1 or 3)
4 12 Undefined

The response indicates that the request has been acknowledged, however there might be substantial delay before device actually powers off.


4: Read memory

Use this command to read small amouts of memory through the command pipe. You may not request a transfer that would exceed the maximum Command IN Endpoint packet size (including the header).

Command Packet
Offset Size (bytes) Description
0 4 Command ID (4)
4 4 Memory address to read from
8 4 Number of bytes to be read
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined
16 variable The data read from memory


5: Write memory

Use this command to write small amouts of memory through the command pipe. You may not request a transfer that would exceed the maximum Command OUT Endpoint packet size (including the header).

Command Packet
Offset Size (bytes) Description
0 4 Command ID (5)
4 4 Memory address to write to
8 4 Number of bytes to write
12 4 Should be zero
16 variable The data to be written
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


6: Read memory using DMA

Use this command to read large amouts of memory through the data pipe. You may not request a transfer that would exceed the maximum Data IN Endpoint packet size.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (6)
4 4 Memory address to read from
8 4 Number of bytes to be read
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined

After receiving the response, read the requested data from the Data IN Endpoint.


7: Write memory using DMA

Use this command to read large amouts of memory through the data pipe. You may not request a transfer that would exceed the maximum Data OUT Endpoint packet size.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (7)
4 4 Memory address to write to
8 4 Number of bytes to be written
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined

After receiving the response, send the data to be written to the Data OUT Endpoint.


8: Read from I2C device

Use this command to read from an I2C slave. You may not request a transfer that would exceed the maximum Command IN Endpoint packet size (including the header) or 255 bytes (excluding the header), whichever is smaller.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (8)
4 1 I2C bus index
5 1 I2C slave address (in the upper 7 bits)
6 1 Start address on the I2C device
7 1 Number of bytes to be read
8 8 Should be zero

I2C transactions are asynchronous commands.

Response Packet
Offset Size (bytes) Description
0 4 Status Code (1 or 3)
4 12 Undefined
16 variable The data read from the I2C device (undefined if the status code is not 1)


9: Write to I2C device

Use this command to write to an I2C slave. You may not request a transfer that would exceed the maximum Command OUT Endpoint packet size (including the header) or 255 bytes (excluding the header), whichever is smaller.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (8)
4 1 I2C bus index
5 1 I2C slave address (in the upper 7 bits)
6 1 Start address on the I2C device
7 1 Number of bytes to be written
8 8 Should be zero
16 variable The data to be written to the I2C device

I2C transactions are asynchronous commands.

Response Packet
Offset Size (bytes) Description
0 4 Status Code (1 or 3)
4 12 Undefined


10: Read from the USB console

Use this command to get data written to the USB console. You may not request a transfer that would exceed the maximum Command IN Endpoint packet size (including the header).

As long as the console application is running, make sure to issue this request at least once a second. Otherwise the console might start dropping data and inserting an "\n\n[overflowed]\n\n" mark. If you can't receive any data but need to keep the console from dropping data, issue zero-length read requests.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (10)
4 4 Number of bytes requested
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 Actual number of valid response bytes
8 4 Size of the on-device USB console read buffer
12 4 Number of bytes still waiting in the on-device USB console read buffer
16 variable Valid console data padded with undefined data to meet the requested size


11: Write to the USB console

Use this command to write data to the USB console. You may not request a transfer that would exceed the maximum Command OUT Endpoint packet size (including the header).

Command Packet
Offset Size (bytes) Description
0 4 Command ID (11)
4 4 Number of bytes to be written
8 8 Should be zero
16 variable Data to be written
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 Actual number of bytes written (the remainder will have to be resent)
8 4 Size of the on-device USB console write buffer
12 4 Number of bytes still free in the on-device USB console write buffer


12: Write to device's consoles

Use this command to write data to one or more of the consoles. This is equivalent to the cwrite system call. You may not request a transfer that would exceed the maximum Command OUT Endpoint packet size (including the header).

Command Packet
Offset Size (bytes) Description
0 4 Command ID (12)
4 4 Bitmask of consoles to be written to
8 4 Number of bytes to be written
12 4 Should be zero
16 variable Data to be written
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


13: Read from device's consoles

Use this command to read data from one or more of the consoles. This is equivalent to the cread system call. You may not request a transfer that would exceed the maximum Command IN Endpoint packet size (including the header). This command will not block until there is data available.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (13)
4 4 Bitmask of consoles to be read from
8 4 Number of bytes to be read
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 Number of bytes actually read
8 8 Undefined
16 variable The data read, padded with undefined data to meet the requested size


14: Flush device's console buffers

Use this command to flush one or more console's buffers. This is equivalent to the cflush system call.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (14)
4 4 Bitmask of consoles to be flushed
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


15: Get process information

Use this command to obtain the current state of the scheduler. You may not request a transfer that would exceed the maximum Command OUT Endpoint packet size (including the header).

Command Packet
Offset Size (bytes) Description
0 4 Command ID (15)
4 4 Offset of first byte requested
8 4 Number of bytes requested
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 Process information struct version (incremented each time the format changes)
8 4 Total size of the process information table
12 4 Undefined
16 variable The requested data, padded with undefined data to meet the requested size, if it exceeds bounds


16: (Un)Freeze scheduler

Use this command to prevent execution of userspace code on the device while dumping or manipulating critical data.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (16)
4 4 Lock (1) or unlock (0) the scheduler
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


17: (Un)Suspend thread

Suspend or resume a thread

Command Packet
Offset Size (bytes) Description
0 4 Command ID (17)
4 4 Suspend (1) or resume (0) the thread
8 4 Thread ID
12 4 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


18: Kill thread

Kill a thread

Command Packet
Offset Size (bytes) Description
0 4 Command ID (18)
4 4 Thread ID
8 8 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined


19: Create thread

Create a new thread. This command uses an extended command size of 32 bytes.

Command Packet
Offset Size (bytes) Description
0 4 Command ID (19)
4 4 Pointer to thread name or NULL
8 4 Pointer to entry point of the new thread
12 4 Pointer to stack of the new thread
16 4 Size of the new thread's stack in bytes
20 4 Type: User thread (0) or system thread (1)
24 4 Priority of the new thread (1-255)
28 4 Initial state: Ready (1) or suspended (0)
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 4 ID of the created thread (positive) or error code (negative)
8 8 Undefined


20: Flush CPU caches

Flushes the CPU's instruction and data caches

Command Packet
Offset Size (bytes) Description
0 4 Command ID (20)
4 12 Should be zero
Response Packet
Offset Size (bytes) Description
0 4 Status Code (1)
4 12 Undefined