EmBIOS Monitor Protocol
This article describes the USB communcation protocol of emBIOS monitor.
Contents
- 1 Endpoints
- 2 General Structure
- 3 Commands
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 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
| Offset | Size (bytes) | Description |
|---|---|---|
| 0 | 4 | Command ID (1) |
| 4 | 4 | Requested information type (0) |
| 8 | 8 | Should be zero |
| 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 |
| 12 | 4 | Device Type |
Get packet size information
| Offset | Size (bytes) | Description |
|---|---|---|
| 0 | 4 | Command ID (1) |
| 4 | 4 | Requested information type (1) |
| 8 | 8 | Should be zero |
| 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 |
2: Reset
Reboot the device.
| 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.
| 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.
| 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.
| 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).
| 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 |
| Offset | Size (bytes) | Description |
|---|---|---|
| 0 | 4 | Status Code (1) |
| 4 | 12 | Undefined |
| 16 | variable | The data read from memory |
5: Read 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).
| 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 |
| 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.
| 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 |
| 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.
| 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 |
| 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.
| 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.
| 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: Read from 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.
| 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.
| 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 OUT 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.
| Offset | Size (bytes) | Description |
|---|---|---|
| 0 | 4 | Command ID (10) |
| 4 | 4 | Number of bytes requested |
| 8 | 8 | Should be zero |
| Offset | Size (bytes) | Description |
|---|---|---|
| 0 | 4 | Status Code (1 or 3) |
| 4 | 4 | Actual number of valid response bytes |
| 8 | 4 | Size of the on-device USB console buffer |
| 12 | 4 | Number of bytes still waiting in the on-device USB console buffer |
| 16 | variable | Valid console data padded with undefined data to meet the requested size |
