From 5b561c2d68a05eb705fb5439bacabaf47e667f8d Mon Sep 17 00:00:00 2001 From: "-T.K.-" Date: Mon, 21 Aug 2023 15:21:55 -0700 Subject: [PATCH 1/3] ADD: add docs for peripheral devices --- docs/Generators/SiFive-Generators.rst | 145 ++++++++++++++++++++++++-- 1 file changed, 135 insertions(+), 10 deletions(-) diff --git a/docs/Generators/SiFive-Generators.rst b/docs/Generators/SiFive-Generators.rst index c3840297..37e659af 100644 --- a/docs/Generators/SiFive-Generators.rst +++ b/docs/Generators/SiFive-Generators.rst @@ -11,24 +11,18 @@ Last-Level Cache Generator To learn more about configuring this L2 cache, please refer to the :ref:`memory-hierarchy` section. -Peripheral Devices -------------------- +Peripheral Devices Overview +---------------------------- ``sifive-blocks`` includes multiple peripheral device generators, such as UART, SPI, PWM, JTAG, GPIO and more. These peripheral devices usually affect the memory map of the SoC, and its top-level IO as well. -To integrate one of these devices in your SoC, you will need to define a custom config fragment with the approriate address for the device using the Rocket Chip parameter system. As an example, for a GPIO device you could add the following config fragment to set the GPIO address to ``0x10012000``. This address is the start address for the GPIO configuration registers. - -.. literalinclude:: ../../generators/chipyard/src/main/scala/config/fragments/PeripheralFragments.scala - :language: scala - :start-after: DOC include start: gpio config fragment - :end-before: DOC include end: gpio config fragment +All the peripheral blocks comes with a default memory address that would not collide with each other, but if integrating multiple duplicated blocks in the SoC is needed, you will need to explicitly specify an approriate memory address for that device. Additionally, if the device requires top-level IOs, you will need to define a config fragment to change the top-level configuration of your SoC. When adding a top-level IO, you should also be aware of whether it interacts with the test-harness. This example instantiates a top-level module with include GPIO ports, and then ties-off the GPIO port inputs to 0 (``false.B``). - Finally, you add the relevant config fragment to the SoC config. For example: .. literalinclude:: ../../generators/chipyard/src/main/scala/config/PeripheralDeviceConfigs.scala @@ -36,4 +30,135 @@ Finally, you add the relevant config fragment to the SoC config. For example: :start-after: DOC include start: GPIORocketConfig :end-before: DOC include end: GPIORocketConfig -Some of the devices in ``sifive-blocks`` (such as GPIO) may already have pre-defined config fragments within the Chipyard example project. You may be able to use these config fragments directly, but you should be aware of their addresses within the SoC address map. + +General Purpose I/Os (GPIO) Device +---------------------------------- + +GPIO device is a periphery device provided by ``sifive-blocks``. Each general-purpose I/O port has five 32-bit configuration registers (GPIOx_INPUT_EN, GPIOx_OUTPUT_EN, GPIOx_PUE GPIOx_DS, and GPIOx_XOR), two 32-bit data registers (GPIOx_INPUT_VAL and GPIOx_OUTPUT_VAL) and eight 32-bit interrupt control/status register (GPIOx_RISE_IE, GPIOx_RISE_IP, GPIOx_FALL_IE, GPIOx_FALL_IP, GPIOx_HIGH_IE, GPIOx_HIGH_IP, GPIOx_LOW_IE, GPIOx_LOW_IP). In addition, all GPIOs can have two 32-bit alternate function selection registers (GPIOx_IOF_EN and GPIOx_IOF_SEL). + + +GPIO main features +~~~~~~~~~~~~~~~~~~~~~~~ + +* Output states: push-pull or open drain with optional pull-up/down resistors + +* Output data from output value register (GPIOx_OUTPUT_VAL) or peripheral (alternate function output) + +* 3-bit drive strength selection for each I/O + +* Input states: floating, pull-up, or pull-down + +* Input data to input value register (GPIOx_INPUT_VAL) or peripheral (alternate function input) + +* Alternate function selection registers + +* Bit invert register (GPIOx_OUTPUT_XOR) for fast output inversion + + +Including GPIO in the SoC +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: scala + + class ExampleChipConfig extends Config( + // ... + + // ================================== + // Set up Memory Devices + // ================================== + // ... + + // Peripheral section + new chipyard.config.WithGPIO(address = 0x10010000, width = 32) ++ + + // ... + ) + + +Universal Asynchronous Receiver/Transmitter (UART) Device +---------------------------------------------------------- + +UART device is a periphery device provided by ``sifive-blocks``. The UART offers a flexible means to perform Full-duplex data exchange with external devices. A very wide range of baud rates can be achieved through a fractional baud rate generator. The UART peripheral does not support hardware flow control or other modem control signals, or synchronous serial data transfers. + + +UART main features +~~~~~~~~~~~~~~~~~~~~~~~ + +* Full-duplex asynchronous communication + +* Baud rate generator systems + +* 16× Rx oversampling with 2/3 majority voting per bit + +* Two internal FIFOs for transmit and receive data with programmable watermark interrupts + +* A common programmable transmit and receive baud rate + +* Configurable stop bits (1 or 2 stop bits) + +* Separate enable bits for transmitter and receiver + +* Interrupt sources with flags + + +Including UART in the SoC +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: scala + + class ExampleChipConfig extends Config( + // ... + + // ================================== + // Set up Memory Devices + // ================================== + // ... + + // Peripheral section + new chipyard.config.WithUART(address = 0x10020000, baudrate = 115200) ++ + + // ... + ) + +Inter-Integrated Circuit (I2C) Interface Device +------------------------------------------------- + +I2C device is a periphery device provided by ``sifive-blocks``. The I2C (inter-integrated circuit) bus interface handles communications to the serial I2C bus. It provides multi-master capability, and controls all I2C bus-specific sequencing, protocol, arbitration and timing. It supports Standard-mode (Sm), Fast-mode (Fm) and Fast-mode Plus (Fm+). + + +I2C main features +~~~~~~~~~~~~~~~~~~~~~~~ + +* I2C bus specification compatibility: + + * Slave and master modes + + * Multimaster capability + + * Standard-mode (up to 100 kHz) + + * Fast-mode (up to 400 kHz) + + * Fast-mode Plus (up to 1 MHz) + + * 7-bit addressing mode + + +Including I2C in the SoC +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: scala + + class ExampleChipConfig extends Config( + // ... + + // ================================== + // Set up Memory Devices + // ================================== + // ... + + // Peripheral section + new chipyard.config.WithI2C(address = 0x10040000) ++ + + // ... + ) \ No newline at end of file From 2f7219d41be8de797200b8207ee4c599e5209b2c Mon Sep 17 00:00:00 2001 From: "-T.K.-" Date: Mon, 21 Aug 2023 15:27:09 -0700 Subject: [PATCH 2/3] ADD: add SPI documentation --- docs/Generators/SiFive-Generators.rst | 52 ++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/Generators/SiFive-Generators.rst b/docs/Generators/SiFive-Generators.rst index 37e659af..3a0997c3 100644 --- a/docs/Generators/SiFive-Generators.rst +++ b/docs/Generators/SiFive-Generators.rst @@ -161,4 +161,54 @@ Including I2C in the SoC new chipyard.config.WithI2C(address = 0x10040000) ++ // ... - ) \ No newline at end of file + ) + + +Serial Peripheral Interface (SPI) Device +------------------------------------------------- + +SPI device is a periphery device provided by ``sifive-blocks``. The SPI interface can be used to communicate with external devices using the SPI protocol. + +The serial peripheral interface (SPI) protocol supports half-duplex, full-duplex and simplex synchronous, serial communication with external devices. The interface can be configured as master and in this case it provides the communication clock (SCLK) to the external slave device. + + +SPI main features +~~~~~~~~~~~~~~~~~~~~~~~ + +* Master operation + +* Full-duplex synchronous transfers + +* 4 to 16-bit data size selection + +* Master mode baud rate prescalers up to fPCLK/2 + +* NSS management by hardware or software + +* Programmable clock polarity and phase + +* Programmable data order with MSB-first or LSB-first shifting + +* Dedicated transmission and reception flags with interrupt capability + +* Two 32-bit embedded Rx and Tx FIFOs with DMA capability + + +Including SPI in the SoC +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: scala + + class ExampleChipConfig extends Config( + // ... + + // ================================== + // Set up Memory Devices + // ================================== + // ... + + // Peripheral section + new chipyard.config.WithSPI(address = 0x10031000) ++ + + // ... + ) From f352ef46f4dd2f5b459b8371d6f267f1c63fb58f Mon Sep 17 00:00:00 2001 From: "-T.K.-" Date: Mon, 21 Aug 2023 15:33:07 -0700 Subject: [PATCH 3/3] ADD: minor fix on GPIO and UART description --- docs/Generators/SiFive-Generators.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Generators/SiFive-Generators.rst b/docs/Generators/SiFive-Generators.rst index 3a0997c3..73bb5b49 100644 --- a/docs/Generators/SiFive-Generators.rst +++ b/docs/Generators/SiFive-Generators.rst @@ -34,7 +34,7 @@ Finally, you add the relevant config fragment to the SoC config. For example: General Purpose I/Os (GPIO) Device ---------------------------------- -GPIO device is a periphery device provided by ``sifive-blocks``. Each general-purpose I/O port has five 32-bit configuration registers (GPIOx_INPUT_EN, GPIOx_OUTPUT_EN, GPIOx_PUE GPIOx_DS, and GPIOx_XOR), two 32-bit data registers (GPIOx_INPUT_VAL and GPIOx_OUTPUT_VAL) and eight 32-bit interrupt control/status register (GPIOx_RISE_IE, GPIOx_RISE_IP, GPIOx_FALL_IE, GPIOx_FALL_IP, GPIOx_HIGH_IE, GPIOx_HIGH_IP, GPIOx_LOW_IE, GPIOx_LOW_IP). In addition, all GPIOs can have two 32-bit alternate function selection registers (GPIOx_IOF_EN and GPIOx_IOF_SEL). +GPIO device is a periphery device provided by ``sifive-blocks``. Each general-purpose I/O port has five 32-bit configuration registers, two 32-bit data registers controlling pin input and output values, and eight 32-bit interrupt control/status register for signal level and edge triggering. In addition, all GPIOs can have two 32-bit alternate function selection registers. GPIO main features @@ -78,7 +78,7 @@ Including GPIO in the SoC Universal Asynchronous Receiver/Transmitter (UART) Device ---------------------------------------------------------- -UART device is a periphery device provided by ``sifive-blocks``. The UART offers a flexible means to perform Full-duplex data exchange with external devices. A very wide range of baud rates can be achieved through a fractional baud rate generator. The UART peripheral does not support hardware flow control or other modem control signals, or synchronous serial data transfers. +UART device is a periphery device provided by ``sifive-blocks``. The UART offers a flexible means to perform Full-duplex data exchange with external devices. A very wide range of baud rates can be achieved through a fractional baud rate generator. The UART peripheral does not support other modem control signals, or synchronous serial data transfers. UART main features @@ -100,6 +100,8 @@ UART main features * Interrupt sources with flags +* Configurable hardware flow control signals + Including UART in the SoC ~~~~~~~~~~~~~~~~~~~~~~~~~