Change in em100[master]: Update protocol specification

[Stefan Reinauer (Code Review)]

Stefan Reinauer has uploaded this change for review. ( https://review.coreboot.org/c/em100/+/36806 )

Change subject: Update protocol specification
......................................................................

Update protocol specification

Cleaning up appearance, and adding:
 - FPGA image change (1.8/3.3V)
 - Initial documentation of FPGA commands

Change-Id: I03db203c6e254c8caca7bbddcc3e12b9f88b062d
Signed-off-by: Stefan Reinauer 
---
M usb-protocol.md
1 file changed, 96 insertions(+), 7 deletions(-)

git pull ssh://review.coreboot.org:29418/em100 refs/changes/06/36806/1

diff --git a/usb-protocol.md b/usb-protocol.md
index 166a528..cfdf61d 100644
--- a/usb-protocol.md
+++ b/usb-protocol.md
@@ -112,7 +112,7 @@

## 2. FPGA related operations

-### 2.1. Reconfig FPGA:
+### 2.1. Reconfig FPGA

USB Out:

@@ -129,7 +129,7 @@
 ```

-### 2.2. Check FPGA configuration status:
+### 2.2. Check FPGA configuration status

USB Out:

@@ -170,7 +170,7 @@
 Value: Register Value
 ```

-### 2.4. Reconfig FPGA:
+### 2.4. Reconfigure FPGA

USB Out:

@@ -187,7 +187,97 @@
 Value: Register Value
 ```

-## 3. SPI flash related operations:
+See chapter 7 for more information on FPGA commands.
+
+### 2.5. Switch FPGA configuration image
+
+```EM100Pro-G2 only```
+
+EM100Pro-G2 has two FPGA images, one for 1.8V and one for 3.3V SPI flash devices.
+The EM100Pro-G2 defaults to the 3.3V image on power-on.
+
+USB command to switch between the two images.
+
+USB Out:
+
+| Command | Parameter                 | Data |
+|---------|---------------------------|------|
+| 0x24    | Address (4B, high to low) | None |
+
+USB In:
+
+```NONE```
+
+```
+Address = 0x00000: Switch to 3.3V image
+Address = 0x78000: Switch to 1.8V image
+```
+
+After sending the `Switch FPGA configuration image` command, check bit 15 of firmware version (DWORD):
+
+```
+0: 3.3V
+1: 1.8V
+```
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro-G2 | 3.3         | 2.014        |
+
+
+### 2.6. FPGA Reconfiguration
+
+Description of some FPGA command registers (incomplete).
+
+#### 2.6.1. Default Address Length Setting
+
+FPGA command:
+
+| Address | R/W | Description               |
+|---------|-----|---------------------------|
+| 0x4F    | WO  | Set default address space |
+
+| Bit | Description                                    | Initial value |
+|-----|------------------------------------------------|---------------|
+| 0   | Command address length: 0: 3 bytes, 1: 4 bytes | 0             |
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro    | 2.27        | 0.091        |
+EM100Pro-G2 | 3.3         | 2.014        |
+
+#### 2.6.2. CS Pin Selection
+
+FPGA command:
+
+| Address | R/W | Description               |
+|---------|-----|---------------------------|
+| 0xE0    | WO  | Set default address space |
+
+| Bit | Description                  | Initial value |
+|-----|------------------------------|---------------|
+| 0   | 0: Select CS1, 1: Select CS2 | 0             |
+
+
+Note:
+CS selection has different internal behavior on EM100Pro and EM100Pro-G2. On
+EM100Pro, switching to CS2 will use internal memory starting at 0x80000000. On
+EM100Pro-G2, only the CS pin is switched. Since  the memory space is shared, only
+one chip can be emulated at a time.
+
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro-G2 | 3.3         | 2.014        |
+
+
+## 3. SPI flash related operations

### 3.1. Get SPI flash ID

@@ -324,7 +414,7 @@
 | None   |Data read from SDRAM |

-## 5. SPI Hyperterminal related operations:
+## 5. SPI Hyperterminal related operations

### 5.1. Read HT Registers

@@ -409,7 +499,7 @@
 DCNT: number of bytes successfully read from uFIFO.
 ```

-## 6. SPI Trace related operations:
+## 6. SPI Trace related operations

### 6.1. Get SPI Trace

@@ -425,7 +515,6 @@
 |--------|-----------|
 | None   | SPI Trace |

-
 ```
  TraceLen: The unit of TraceLen is 4KB.
  Timeout: It defines the max waiting time on MCU side for each 4KB trace data, unit is ms.

[David Hendricks (Code Review)]

David Hendricks has posted comments on this change. ( https://review.coreboot.org/c/em100/+/36806 )

Change subject: Update protocol specification
......................................................................

Patch Set 2: Code-Review+1

[Patrick Georgi (Code Review)]

Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/em100/+/36806 )

Change subject: Update protocol specification
......................................................................

Patch Set 2: Code-Review+2

[Patrick Georgi (Code Review)]

Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/em100/+/36806 )

Change subject: Update protocol specification
......................................................................

Update protocol specification

Cleaning up appearance, and adding:
 - FPGA image change (1.8/3.3V)
 - Initial documentation of FPGA commands

Change-Id: I03db203c6e254c8caca7bbddcc3e12b9f88b062d
Signed-off-by: Stefan Reinauer 
Reviewed-on: https://review.coreboot.org/c/em100/+/36806
Tested-by: build bot (Jenkins) 
Reviewed-by: David Hendricks 
Reviewed-by: Patrick Georgi 
---
M usb-protocol.md
1 file changed, 96 insertions(+), 7 deletions(-)

Approvals:
  build bot (Jenkins): Verified
  Patrick Georgi: Looks good to me, approved
  David Hendricks: Looks good to me, but someone else must approve

diff --git a/usb-protocol.md b/usb-protocol.md
index 166a528..cfdf61d 100644
--- a/usb-protocol.md
+++ b/usb-protocol.md
@@ -112,7 +112,7 @@

## 2. FPGA related operations

-### 2.1. Reconfig FPGA:
+### 2.1. Reconfig FPGA

USB Out:

@@ -129,7 +129,7 @@
 ```

-### 2.2. Check FPGA configuration status:
+### 2.2. Check FPGA configuration status

USB Out:

@@ -170,7 +170,7 @@
 Value: Register Value
 ```

-### 2.4. Reconfig FPGA:
+### 2.4. Reconfigure FPGA

USB Out:

@@ -187,7 +187,97 @@
 Value: Register Value
 ```

-## 3. SPI flash related operations:
+See chapter 7 for more information on FPGA commands.
+
+### 2.5. Switch FPGA configuration image
+
+```EM100Pro-G2 only```
+
+EM100Pro-G2 has two FPGA images, one for 1.8V and one for 3.3V SPI flash devices.
+The EM100Pro-G2 defaults to the 3.3V image on power-on.
+
+USB command to switch between the two images.
+
+USB Out:
+
+| Command | Parameter                 | Data |
+|---------|---------------------------|------|
+| 0x24    | Address (4B, high to low) | None |
+
+USB In:
+
+```NONE```
+
+```
+Address = 0x00000: Switch to 3.3V image
+Address = 0x78000: Switch to 1.8V image
+```
+
+After sending the `Switch FPGA configuration image` command, check bit 15 of firmware version (DWORD):
+
+```
+0: 3.3V
+1: 1.8V
+```
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro-G2 | 3.3         | 2.014        |
+
+
+### 2.6. FPGA Reconfiguration
+
+Description of some FPGA command registers (incomplete).
+
+#### 2.6.1. Default Address Length Setting
+
+FPGA command:
+
+| Address | R/W | Description               |
+|---------|-----|---------------------------|
+| 0x4F    | WO  | Set default address space |
+
+| Bit | Description                                    | Initial value |
+|-----|------------------------------------------------|---------------|
+| 0   | Command address length: 0: 3 bytes, 1: 4 bytes | 0             |
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro    | 2.27        | 0.091        |
+EM100Pro-G2 | 3.3         | 2.014        |
+
+#### 2.6.2. CS Pin Selection
+
+FPGA command:
+
+| Address | R/W | Description               |
+|---------|-----|---------------------------|
+| 0xE0    | WO  | Set default address space |
+
+| Bit | Description                  | Initial value |
+|-----|------------------------------|---------------|
+| 0   | 0: Select CS1, 1: Select CS2 | 0             |
+
+
+Note:
+CS selection has different internal behavior on EM100Pro and EM100Pro-G2. On
+EM100Pro, switching to CS2 will use internal memory starting at 0x80000000. On
+EM100Pro-G2, only the CS pin is switched. Since  the memory space is shared, only
+one chip can be emulated at a time.
+
+
+Minimum firmware version requirements:
+
+Device      | MCU version | FPGA version |
+------------|-------------|--------------|
+EM100Pro-G2 | 3.3         | 2.014        |
+
+
+## 3. SPI flash related operations

### 3.1. Get SPI flash ID

@@ -324,7 +414,7 @@
 | None   |Data read from SDRAM |

-## 5. SPI Hyperterminal related operations:
+## 5. SPI Hyperterminal related operations

### 5.1. Read HT Registers

@@ -409,7 +499,7 @@
 DCNT: number of bytes successfully read from uFIFO.
 ```

-## 6. SPI Trace related operations:
+## 6. SPI Trace related operations

### 6.1. Get SPI Trace

@@ -425,7 +515,6 @@
 |--------|-----------|
 | None   | SPI Trace |

-
 ```
  TraceLen: The unit of TraceLen is 4KB.
  Timeout: It defines the max waiting time on MCU side for each 4KB trace data, unit is ms.