~ruther/vhdl-i2c

2dd83c491968d96294e91abf854adad299b4850a — Rutherther 1 year, 4 months ago 1470daa 
docs: styling
patch browse .tar.gz 
4 files changed, 265 insertions(+), 193 deletions(-)

M .gitignore
M doc/defaults.yaml
M doc/index.md
M flake.nix

M .gitignore => .gitignore +3 -0
@@ 18,3 18,6 @@ impl_1/
stopwatch.runs/
stopwatch.hw/
stopwatch.cache/

*.pdf
.auctex-auto/


M doc/defaults.yaml => doc/defaults.yaml +1 -0
@@ 4,6 4,7 @@ pdf-engine: tectonic
filters:
  - citeproc
  - pandoc-svg.py
  - pandoc-latex-environment
input-files:
  - index.md



M doc/index.md => doc/index.md +238 -191
@@ 21,6 21,17 @@ output:
    fig_caption: yes        
    includes:  
      in_header: figure_placement.tex
header-includes:
- |
  ```{=latex}
  \usepackage{awesomebox}
  ```
pandoc-latex-environment:
  noteblock: [note]
  tipblock: [tip]
  warningblock: [warning]
  cautionblock: [caution]
  importantblock: [important]
---

# Introduction


@@ 64,6 75,13 @@ with 20 registers. The first written byte is treated as an address.
Other read bytes are consecutive reads from the registers. Other
writes are treated as consecutive writes to the registers.

::: note
The port names follow a specific pattern.

Inputs have ``_i`` suffix, whereas outputs have ``_o`` suffix.
When an input or output is active low, it's suffix will include ``n`` at the end.
:::

## SSD1306 display counter
The SSD1306 display is a 128x64 display
that supports various interfacing methods such as I2C.


@@ 118,73 136,91 @@ When setting both start and stop high at the same time,
one byte will be transmitted or received, and then stop condition
generated.

![``master`` entity inputs and outputs diagram](./blocks/svg/master.svg){width=400px}

| **Name**            | **Type**            | **Description** |
|---------------------|---------------------|-----------------|
| clk_i               | std_logic           |                 |
| rst_in              | std_logic           |                 |
| slave_address_i     | std_logic_vector[7] |                 |
| generate_ack_i      | std_logic           |                 |
| expect_ack_i        | std_logic           |                 |
| rx_valid_o          | std_logic           |                 |
| rx_data_o           | std_logic_vector[8] |                 |
| rx_confirm_i        | std_logic           |                 |
| tx_ready_o          | std_logic           |                 |
| tx_valid_i          | std_logic           |                 |
| tx_data_i           | std_logic_vector[8] |                 |
| tx_clear_buffer_i   | std_logic           |                 |
| err_noack_data_o    | std_logic           |                 |
| err_noack_address_o | std_logic           |                 |
| err_arbitration_o   | std_logic           |                 |
| err_general_o       | std_logic           |                 |
| stop_i              | std_logic           |                 |
| start_i             | std_logic           |                 |
| run_i               | std_logic           |                 |
| rw_i                | std_logic           |                 |
| dev_busy_o          | std_logic           |                 |
| bus_busy_o          | std_logic           |                 |
| waiting_o           | std_logic           |                 |
| sda_i               | std_logic           |                 |
| scl_i               | std_logic           |                 |
| sda_enable_o        | std_logic           |                 |
| scl_enable_o        | std_logic           |                 |
The entity supports arbitrary ``scl`` speeds. But only one can be chosen
for instance, via generic argument. The generator always makes sure the
``scl`` is stable for at least ``SCL_MIN_STABLE_CYCLES`` clock cycles.

Table: Ports of ``master`` entity

| **Name**            | **Type**            | **Description**                                                    |
|---------------------|---------------------|--------------------------------------------------------------------|
| clk_i               | std_logic           | Clock input                                                        |
| rst_in              | std_logic           | Asynchronous reset (active low)                                    |
| slave_address_i     | std_logic_vector[7] | Address of the slave to choose                                     |
| generate_ack_i      | std_logic           | Whether to generate acknowledges on received data                  |
| expect_ack_i        | std_logic           | Whether to expect acknowledges on transmitted data                 |
| rx_valid_o          | std_logic           | ``rx_data`` are valid                                              |
| rx_data_o           | std_logic_vector[8] | Received data                                                      |
| rx_confirm_i        | std_logic           | Confirm read of ``rx_data`` to fill with next data                 |
| tx_ready_o          | std_logic           | ``tx_data`` may be received                                        |
| tx_valid_i          | std_logic           | ``tx_data`` are valid                                              |
| tx_data_i           | std_logic_vector[8] | Data to transmit                                                   |
| tx_clear_buffer_i   | std_logic           | Clear transmit buffer (clear data that weren't sent)               |
| err_noack_data_o    | std_logic           | Got NACK when transmitting                                         |
| err_noack_address_o | std_logic           | Got NACK on first byte with address                                |
| err_arbitration_o   | std_logic           | Got unexpected value on ``sda``                                    |
| err_general_o       | std_logic           | Other errors, such as getting start condition unexpectedly         |
| stop_i              | std_logic           | Generate stop condition when possible                              |
| start_i             | std_logic           | Generate start condition when possible                             |
| run_i               | std_logic           |                                                                    |
| rw_i                | std_logic           | Read or write transaction (R = 1)                                  |
| dev_busy_o          | std_logic           | Master device is currently busy                                    |
| bus_busy_o          | std_logic           | Bus is busy (but master is not)                                    |
| waiting_o           | std_logic           | Waiting for data on transmit or for read on receive if buffer full |
| sda_i               | std_logic           | I2C ``sda`` line                                                   |
| scl_i               | std_logic           | I2C ``scl`` line                                                   |
| sda_enable_o        | std_logic           | Pull ``sda`` low                                                   |
| scl_enable_o        | std_logic           | Pull ``scl`` low                                                   |

Table: Generic arguments of ``master`` entity

| **Name**              | **Type** | **Default value**                           |
|-----------------------|----------|---------------------------------------------|
| SCL_FALLING_DELAY     | natural  | How many clock cycles to wait               |
|                       |          | after scl falling to set ``sda``            |
| SCL_MIN_STABLE_CYCLES | natural  | Minimum clock cycles to keep ``scl`` stable |

### Entity ``slave``
Slave entity is a top level for I2C slave.

It outputs the current state upon receiving _commands_ from the master.

![``slave`` entity inputs and outputs diagram](./blocks/svg/slave.svg){width=400px}

| **Name**          | **Type**            | **Description** |
|-------------------|---------------------|-----------------|
| clk_i             | std_logic           |                 |
| rst_in            | std_logic           |                 |
| address_i         | std_logic_vector[7] |                 |
| generate_ack_i    | std_logic           |                 |
| expect_ack_i      | std_logic           |                 |
| rx_valid_o        | std_logic           |                 |
| rx_data_o         | std_logic_vector[8] |                 |
| rx_confirm_i      | std_logic           |                 |
| rx_stretch_i      | std_logic           |                 |
| tx_ready_o        | std_logic           |                 |
| tx_valid_i        | std_logic           |                 |
| tx_data_i         | std_logic_vector[8] |                 |
| tx_stretch_i      | std_logic           |                 |
| tx_clear_buffer_i | std_logic           |                 |
| err_noack_o       | std_logic           |                 |
| err_sda_o         | std_logic           |                 |
| rw_o              | std_logic           |                 |
| dev_busy_o        | std_logic           |                 |
| bus_busy_o        | std_logic           |                 |
| waiting_o         | std_logic           |                 |
| sda_i             | std_logic           |                 |
| scl_i             | std_logic           |                 |
| sda_enable_o      | std_logic           |                 |
| scl_enable_o      | std_logic           |                 |

\newpage
Table: Ports of ``slave`` entity

| **Name**          | **Type**            | **Description**                                                    |
|-------------------|---------------------|--------------------------------------------------------------------|
| clk_i             | std_logic           | Clock input                                                        |
| rst_in            | std_logic           | Asynchronous reset (active low)                                    |
| address_i         | std_logic_vector[7] | Address of the slave                                               |
| generate_ack_i    | std_logic           | Whether to generate ack on every read                              |
| expect_ack_i      | std_logic           | Whether to expect acknowledges on transmitted data                 |
| rx_valid_o        | std_logic           | ``rx_data`` are valid                                              |
| rx_data_o         | std_logic_vector[8] | Received data                                                      |
| rx_confirm_i      | std_logic           | Confirm data of ``rx_data`` to fill with next data                 |
| rx_stretch_i      | std_logic           | Allow stretching on receiving (when read buffer full)              |
| tx_ready_o        | std_logic           | ``tx_data`` may be received                                        |
| tx_valid_i        | std_logic           | ``tx_data`` are valid                                              |
| tx_data_i         | std_logic_vector[8] | Data to transmit                                                   |
| tx_stretch_i      | std_logic           | Allow stretching on transmitting (when data missing)               |
| tx_clear_buffer_i | std_logic           | Clear transmit buffer (clear data that weren't sent)               |
| err_noack_o       | std_logic           | Got NACK when transmitting                                         |
| err_sda_o         | std_logic           | Got unexpected value on ``sda``                                    |
| rw_o              | std_logic           | Read or write transaction (R = 1)                                  |
| dev_busy_o        | std_logic           | Master device is currently busy                                    |
| bus_busy_o        | std_logic           | Bus is busy (but master is not)                                    |
| waiting_o         | std_logic           | Waiting for data on transmit or for read on receive if buffer full |
| sda_i             | std_logic           | I2C ``sda`` line                                                   |
| scl_i             | std_logic           | I2C ``scl`` line                                                   |
| sda_enable_o      | std_logic           | Pull ``sda`` low                                                   |
| scl_enable_o      | std_logic           | Pull ``scl`` low                                                   |

Table: Generic arguments of ``slave`` entity

| **Name**          | **Type** | **Default value**                   |
|-------------------|----------|-------------------------------------|
| SCL_FALLING_DELAY | natural  | How many clock cycles to wait after |
|                   |          | scl falling to set ``sda``          |

### Common
All of the blocks responsible for receiving or sending data
should get the``scl`` state from the input going to the FPGA/ASIC,


@@ 193,58 229,60 @@ This makes sure that features such as scl stretching or arbitration
are supported. If scl from ``scl_generator`` were to be used, there
would be no possibility to detect either one of those.

:::note
Some of the entities accept delayed falling pulse of ``scl``.
This is to make sure ``sda`` is changed AFTER ``scl`` is indeed
low. If ``sda`` was changed right away, it's possible there would
be a device that would detect start or stop condition when
there is no condition.
:::

#### Entity ``address_generator``
Address generator is responsible for sending
address upon requested. It's used in the I2C master
to select a slave. Currently it supports only 7 bit addresses.

![``address_generator`` entity inputs and outputs diagram](./blocks/svg/address_generator.svg){width=400px}

| **Name**              | **Type**            | **Description** |
|-----------------------|---------------------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| address_i             | std_logic_vector[7] | The address to send                |
| rw_i                  | std_logic           | R/W to send (R = 1)                |
| store_address_rw_i    | std_logic           | When to store address and ``rw``                |
| start_i               | std_logic           | Start sending address                |
| scl_rising_i          | std_logic           | ``scl`` rising pulse                |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse delayed                |
| sda_enable_o          | std_logic           | Keep ``sda`` low                |
| sda_i                 | std_logic           | Current ``sda`` level                |
| noack_o               | std_logic           | Did not get acknowledge                |
| unexpected_sda_o      | std_logic           | ``sda`` detected at ``scl`` rising edge is wrong. (Arbitration lost)                |
| done_o                | std_logic           | Address sent                |
Table: Ports of ``address_generator`` entity

| **Name**              | **Type**            | **Description**                                   |
|-----------------------|---------------------|---------------------------------------------------|
| clk_i                 | std_logic           | Clock input                                       |
| rst_in                | std_logic           | Synchronous reset (active low)                    |
| address_i             | std_logic_vector[7] | The address to send                               |
| rw_i                  | std_logic           | R/W to send (R = 1)                               |
| store_address_rw_i    | std_logic           | When to store address and ``rw``                  |
| start_i               | std_logic           | Start sending address                             |
| scl_rising_i          | std_logic           | ``scl`` rising pulse                              |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse delayed                     |
| sda_enable_o          | std_logic           | Keep ``sda`` low                                  |
| sda_i                 | std_logic           | Current ``sda`` level                             |
| noack_o               | std_logic           | Did not get acknowledge                           |
| unexpected_sda_o      | std_logic           | ``sda`` detected at ``scl`` rising edge is wrong. |
|                       |                     | (Arbitration lost)                                |
| done_o                | std_logic           | Address sent                                      |

#### Entity ``address_detector``
Address detector looks at the received data to check
if the address matches the address of the slave.
Currently it supports only 7 bit addresses.

![``address_detector`` entity inputs and outputs diagram](./blocks/svg/address_detector.svg){width=400px}

| **Name**              | **Type**            | **Description** |
|-----------------------|---------------------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| address_i             | std_logic_vector[7] | The address to detect                |
| store_address_i       | std_logic           | When to store the address to buffer                |
| scl_rising            | std_logic           | ``scl`` rising pulse                |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse delayed                |
| sda_enable_o          | std_logic           | Keep ``sda`` low                |
| sda_i                 | std_logic           | Current ``sda`` level                |
| start_i               | std_logic           | Start detecting address with next ``scl``                |
| rw_o                  | std_logic           | Detected R/W value                |
| success_o             | std_logic           | Address matching. ``rw`` set                |
| fail_o                | std_logic           | Address not matching                |
Table: Ports of ``address_detector`` entity

| **Name**              | **Type**            | **Description**                           |
|-----------------------|---------------------|-------------------------------------------|
| clk_i                 | std_logic           | Clock input                               |
| rst_in                | std_logic           | Synchronous reset (active low)            |
| address_i             | std_logic_vector[7] | The address to detect                     |
| store_address_i       | std_logic           | When to store the address to buffer       |
| scl_rising            | std_logic           | ``scl`` rising pulse                      |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse delayed             |
| sda_enable_o          | std_logic           | Keep ``sda`` low                          |
| sda_i                 | std_logic           | Current ``sda`` level                     |
| start_i               | std_logic           | Start detecting address with next ``scl`` |
| rw_o                  | std_logic           | Detected R/W value                        |
| success_o             | std_logic           | Address matching. ``rw`` set              |
| fail_o                | std_logic           | Address not matching                      |

\newpage
#### Entity ``rx``
Receiver entity is responsible for receiving data from the
data bit line (``sda``), and delivering the bytes received.


@@ 261,27 299,26 @@ to get high level.
The entity is also responsible for acknowledging the received data.
All data are acknowledged.

![``rx`` entity inputs and outputs diagram](./blocks/svg/rx.svg){width=400px}

| **Name**              | **Type**            | **Description** |
|-----------------------|---------------------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| start_read_i          | std_logic           | Read should be initiated on next scl                |
| rst_i2c_i             | std_logic           | Reset only i2c logic, keep data                |
| scl_rising            | std_logic           | ``scl`` rising pulse                |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse, delayed                |
| scl_stretch_o         | std_logic           | Keep ``scl`` low                |
Table: Ports of ``rx`` entity

| **Name**              | **Type**            | **Description**                      |
|-----------------------|---------------------|--------------------------------------|
| clk_i                 | std_logic           | Clock input                          |
| rst_in                | std_logic           | Synchronous reset (active low)       |
| start_read_i          | std_logic           | Read should be initiated on next scl |
| rst_i2c_i             | std_logic           | Reset only i2c logic, keep data      |
| scl_rising            | std_logic           | ``scl`` rising pulse                 |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse, delayed       |
| scl_stretch_o         | std_logic           | Keep ``scl`` low                     |
| sda_i                 | std_logic           | Current ``sda`` level                |
| sda_enable_o          | std_logic           | Whether to keep ``sda`` low                |
| done_o                | std_logic           | Byte received, acknowledged                |
| generate_ack_i        | std_logic           | Generate acknowledge after received                |
| read_valid_o          | std_logic           | ``read_data`` are valid for reading                |
| read_ready_o          | std_logic           | Ready for next transaction                |
| read_data_o           | std_logic_vector[8] | Read data                |
| confirm_read_i        | std_logic           | Confirm data were read                |

\newpage
| sda_enable_o          | std_logic           | Whether to keep ``sda`` low          |
| done_o                | std_logic           | Byte received, acknowledged          |
| generate_ack_i        | std_logic           | Generate acknowledge after received  |
| read_valid_o          | std_logic           | ``read_data`` are valid for reading  |
| read_ready_o          | std_logic           | Ready for next transaction           |
| read_data_o           | std_logic_vector[8] | Read data                            |
| confirm_read_i        | std_logic           | Confirm data were read               |

#### Entity ``tx``
Receiver entity is responsible for transmitting data to the
data bit line (``sda``), and for storing the data to be sent next.


@@ 301,70 338,69 @@ the entity signals
The entity is also responsible for verifying acknowledge at the right time,
and signaling that no acknowledge has been received.

![``tx`` entity inputs and outputs diagram](./blocks/svg/tx.svg){width=400px}
Table: Ports of ``tx`` entity

| **Name**              | **Type**            | **Description** |
|-----------------------|---------------------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| **Name**              | **Type**            | **Description**                           |
|-----------------------|---------------------|-------------------------------------------|
| clk_i                 | std_logic           | Clock input                               |
| rst_in                | std_logic           | Synchronous reset (active low)            |
| start_write_i         | std_logic           | Write should be initiated                 |
| rst_i2c_i             | std_logic           | Reset only i2c logic, keep data                |
| clear_buffer_i        | std_logic           | Clear transmit buffer                |
| done_o                | std_logic           | Data transmitted, and acknowledged                |
| unexpected_sda_o      | std_logic           | ``sda`` value was wrong on ``scl`` rising                |
| noack_o               | std_logic           | Did not get ACK                |
| scl_rising            | std_logic           | ``scl`` rising pulse                |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse, delayed                |
| scl_stretch_o         | std_logic           | Keep ``scl`` low                |
| sda_i                 | std_logic           | Current ``sda`` level                |
| sda_enable_o          | std_logic           | Keep ``sda`` low                |
| ready_o               | std_logic           | Ready for new data                |
| valid_i               | std_logic           | Data in ``write_data`` are valid                |
| write_data_i          | std_logic_vector[8] | Data to transmit                |
| rst_i2c_i             | std_logic           | Reset only i2c logic, keep data           |
| clear_buffer_i        | std_logic           | Clear transmit buffer                     |
| done_o                | std_logic           | Data transmitted, and acknowledged        |
| unexpected_sda_o      | std_logic           | ``sda`` value was wrong on ``scl`` rising |
| noack_o               | std_logic           | Did not get ACK                           |
| scl_rising            | std_logic           | ``scl`` rising pulse                      |
| scl_falling_delayed_i | std_logic           | ``scl`` falling pulse, delayed            |
| scl_stretch_o         | std_logic           | Keep ``scl`` low                          |
| sda_i                 | std_logic           | Current ``sda`` level                     |
| sda_enable_o          | std_logic           | Keep ``sda`` low                          |
| ready_o               | std_logic           | Ready for new data                        |
| valid_i               | std_logic           | Data in ``write_data`` are valid          |
| write_data_i          | std_logic_vector[8] | Data to transmit                          |

\newpage
#### Entity ``scl_generator``
Scl generator generates the ``scl`` while making sure
to keep the signal high or low for at least specified number of cycles.
It may send a signal when the ``scl`` cannot be set to high level,
that could signal a slave pulling down the line.

![``scl_generator`` entity inputs and outputs diagram](./blocks/svg/scl_generator.svg){width=400px}
Table: Ports of ``scl_generator`` entity

| **Name**         | **Type**  | **Description** |
|------------------|-----------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| scl_i            | std_logic | Current level of ``scl``                |
| scl_rising_i     | std_logic | ``scl`` rising pulse                |
| scl_falling_i    | std_logic | ``scl`` falling pulse               |
| gen_continuous_i | std_logic | Generate continuous ``scl`` clock                |
| gen_rising_i     | std_logic | Generate rising edge                |
| gen_falling_i    | std_logic | Generate falling edge                |
| scl_enable_o     | std_logic | Keep ``scl`` low                |
| cannot_comply_o  | std_logic | Cannot set ``scl`` high                |
| **Name**         | **Type**  | **Description**                   |
|------------------|-----------|-----------------------------------|
| clk_i            | std_logic | Clock input                       |
| rst_in           | std_logic | Synchronous reset (active low)    |
| scl_i            | std_logic | Current level of ``scl``          |
| scl_rising_i     | std_logic | ``scl`` rising pulse              |
| scl_falling_i    | std_logic | ``scl`` falling pulse             |
| gen_continuous_i | std_logic | Generate continuous ``scl`` clock |
| gen_rising_i     | std_logic | Generate rising edge              |
| gen_falling_i    | std_logic | Generate falling edge             |
| scl_enable_o     | std_logic | Keep ``scl`` low                  |
| cannot_comply_o  | std_logic | Cannot set ``scl`` high           |

Table: Generic arguments of ``scl_generator`` entity

| **Name**          | **Type** | **Description** |
|-------------------|----------|-------------------|
| MIN_STABLE_CYCLES | natural  | How many clock cycles to keep ``scl`` on stable                 |
| **Name**          | **Type** | **Description**                |
|-------------------|----------|--------------------------------|
| MIN_STABLE_CYCLES | natural  | How many clock cycles to keep ``scl`` on stable |

#### Entity ``startstop_condition_detector``
This entity detects either start or stop condition.
It produces a pulse for duration of one clock cycle
when either start or stop is detected.

![``startstop_condition_detector`` entity inputs and outputs diagram](./blocks/svg/startstop_condition_detector.svg){width=300px}
Table: Ports of ``startstop_condition_detector`` entity

| **Name** | **Type**  | **Description** |
|----------|-----------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| sda_i                 | std_logic           | Current ``sda`` level                |
| scl_i            | std_logic | Current level of ``scl``                |
| start_o  | std_logic | Start condition detected                |
| stop_o   | std_logic | Stop condition detected                |
| **Name** | **Type**  | **Description**          |
|----------|-----------|--------------------------|
| clk_i    | std_logic | Clock input              |
| sda_i    | std_logic | Current ``sda`` level    |
| scl_i    | std_logic | Current level of ``scl`` |
| start_o  | std_logic | Start condition detected |
| stop_o   | std_logic | Stop condition detected  |

\newpage
#### Entity ``startstop_condition_generator``
Generates either start or stop condition. If the
scl has to be changed to different level, it generates


@@ 378,30 414,30 @@ after that, ``scl`` is requested to be high, and as last, the
``sda`` is changed to generate the condition. Some of those might
be omitted according to the actual state of the ``sda`` and ``scl``.

![``startstop_condition_generator`` entity inputs and outputs diagram](./blocks/svg/startstop_condition_generator.svg){width=400px}

| **Name**              | **Type**  | **Description** |
|-----------------------|-----------|-----------------|
| clk_i                 | std_logic           | Clock input                |
| rst_in                | std_logic           | Synchronous reset (active low)                |
| sda_i                 | std_logic | Current level of ``sda``                |
| scl_rising_i     | std_logic | ``scl`` rising pulse                |
| scl_falling_i    | std_logic | ``scl`` falling pulse               |
| scl_falling_delayed_i | std_logic | ``scl`` delayed falling pulse                |
| sda_enable_o          | std_logic | Keep ``sda`` low                |
| start_condition_i     | std_logic | Start condition detected                |
| stop_condition_i      | std_logic | Stop condition detected                |
| gen_start_i           | std_logic | Generate start condition                |
| gen_stop_i            | std_logic | Generate stop condition                |
| req_scl_fall_o        | std_logic | Request scl falling edge                |
| req_scl_rise_o        | std_logic | Request scl rising edge                |
| early_condition_o     | std_logic | Detected early condition (prior to generating ourselves)                |
| done_o                | std_logic | Requested condition generated                |


| **Name** | **Type** | **Description** |
|----------|----------|-------------------|
| DELAY    | natural         | How long to wait after each operation                  |
Table: Ports of ``startstop_condition_generator`` entity

| **Name**              | **Type**  | **Description**                                          |
|-----------------------|-----------|----------------------------------------------------------|
| clk_i                 | std_logic | Clock input                                              |
| rst_in                | std_logic | Synchronous reset (active low)                           |
| sda_i                 | std_logic | Current level of ``sda``                                 |
| scl_rising_i          | std_logic | ``scl`` rising pulse                                     |
| scl_falling_i         | std_logic | ``scl`` falling pulse                                    |
| scl_falling_delayed_i | std_logic | ``scl`` delayed falling pulse                            |
| sda_enable_o          | std_logic | Keep ``sda`` low                                         |
| start_condition_i     | std_logic | Start condition detected                                 |
| stop_condition_i      | std_logic | Stop condition detected                                  |
| gen_start_i           | std_logic | Generate start condition                                 |
| gen_stop_i            | std_logic | Generate stop condition                                  |
| req_scl_fall_o        | std_logic | Request scl falling edge                                 |
| req_scl_rise_o        | std_logic | Request scl rising edge                                  |
| early_condition_o     | std_logic | Detected early condition (prior to generating ourselves) |
| done_o                | std_logic | Requested condition generated                            |


| **Name** | **Type** | **Description**                       |
|----------|----------|---------------------------------------|
| DELAY    | natural  | How long to wait after each operation |

#### Entity ``master_state`` 
This entity is a FSM for the ``master`` entity.


@@ 414,7 450,6 @@ start request.

Inputs and outputs from other entities, should be explained by other entities well already.

![``master_state`` entity inputs and outputs diagram](./blocks/svg/master_state.svg){width=400px}

#### Entity ``slave_state`` 
This entity is a FSM for the ``slave`` entity.


@@ 425,7 460,19 @@ The errors are cleared upon next start condition.

Inputs and outputs from other entities, should be explained by other entities well already.

![``slave_state`` entity inputs and outputs diagram](./blocks/svg/slave_state.svg){width=400px}
### Block diagrams

![``master`` entity inputs and outputs diagram](./blocks/svg/master.svg){width=50%}
![``slave`` entity inputs and outputs diagram](./blocks/svg/slave.svg){width=50%}
![``address_generator`` entity inputs and outputs diagram](./blocks/svg/address_generator.svg){width=50%}
![``address_detector`` entity inputs and outputs diagram](./blocks/svg/address_detector.svg){width=50%}
![``rx`` entity inputs and outputs diagram](./blocks/svg/rx.svg){width=50%}
![``tx`` entity inputs and outputs diagram](./blocks/svg/tx.svg){width=50%}
![``scl_generator`` entity inputs and outputs diagram](./blocks/svg/scl_generator.svg){width=50%}
![``startstop_condition_detector`` entity inputs and outputs diagram](./blocks/svg/startstop_condition_detector.svg){width=40%}
![``startstop_condition_generator`` entity inputs and outputs diagram](./blocks/svg/startstop_condition_generator.svg){width=50%}
![``master_state`` entity inputs and outputs diagram](./blocks/svg/master_state.svg){width=50%}
![``slave_state`` entity inputs and outputs diagram](./blocks/svg/slave_state.svg){width=50%}

# Conclusion
Both master and slave have been verified to be working in simulation and on an FPGA board.


@@ 441,8 488,8 @@ are incorporated on the bus.
There are some things that could be added or changed in the future, such as:
- 10 bit addressing support
- More error states (timeout)
- Disabling data acknowledge
- Adding behavioral i2c master and i2c slave modules for simulation
- Multiple possible ``scl`` frequencies
- Adding behavioral I2C master and I2C slave modules for simulation

The 10 bit addressing is not currently supported, although its support should not be hard
to implement. ``address_generator`` and ``address_detector`` entities interfaces make


@@ 455,10 502,10 @@ for the master. That means if the line stays low indefinitely, the master will b
without notifying the application about a possible problem. One of the slave devices could
be erroneously holding down the line.

Currently it's not possible to disable the data acknowledge in the rx entity.
Some applications don't produce acknowledge if data are not ready yet or
if wrong command has been received. Although I don't think this complies with the standard,
it could come in handy to support this as well.
The ``master`` entity supports only one frequency for ``scl`` for now.
That could be changed by passing in an array of values instead of one generic argument.
Then it could be chosen by index, and changed in runtime when the index would be set
as an input port.

The simulation currently uses blocking procedures for testing.
These procedures are called from the top level simulation entities.


M flake.nix => flake.nix +23 -2
@@ 17,7 17,7 @@
      };
      inherit (poetry2nix.lib.mkPoetry2Nix {
        inherit pkgs;
      }) mkPoetryPackages defaultPoetryOverrides;
      }) mkPoetryPackages mkPoetryScriptsPackage mkPoetryApplication defaultPoetryOverrides;

      python-env = pkgs.python311.withPackages(ps: [
        (ps.buildPythonPackage rec {


@@ 59,13 59,34 @@

      devShells.${system} = {
        docs = pkgs.mkShell {
          packages = [
          packages =  let
            pandoc-latex-environment = pkgs.stdenv.mkDerivation rec {
              pname = "pandoc_latex_environment";
              version = "1.1.6.2";

              src = pkgs.fetchPypi {
                inherit pname version;
                hash = "sha256-61L0oYzXRFHMgTmWRJtCuqGDzaqhQfaQEBsCp7Rx+5c=";
              };

              installPhase = ''
                install -Dm755 pandoc_latex_environment.py $out/bin/pandoc-latex-environment
              '';

              propagatedBuildInputs = [
                (pkgs.python3.withPackages(ps: [
                  ps.panflute
                ]))
              ];
            };
        in [
            pkgs.pandoc
            pkgs.tectonic
            pkgs.inkscape
            (pkgs.python3.withPackages(ps: [
              ps.pandocfilters
            ]))
            pandoc-latex-environment
          ];
        };
Do not follow this link