Polling

This sample demonstrates how to communicate with an external flash by using SPI Polling mode.

The sample uses polling to read, erase, and write data to the external flash.

The example can select the communication mode of SPI as full duplex or EEPROM by configuring the macro SPI_MODE.

The example can select whether to use GPIO to simulate CS line communication by configuring macro SPI_CONFIG_GPIO_SIM_CS.

Requirements

The sample supports the following development kits:

Development Kits
Hardware Platforms	Board Name
RTL87x2G HDK	RTL87x2G EVB

For more requirements, please refer to Quick Start.

Wiring

EVB is connected to W25Q128 module: connect P4_0(SCK) to CLK, P4_1(MISO) to DO, P4_2(MOSI) to DI, P4_3(CS) to CS#.

Note

For module description of W25Q128, please refer to W25Q128 hardware introduction

Configurations

The example configurable macros are as follows:

SPI_MODE : select the SPI communication mode, the selectable values are as follows:
- SPI_MODE_FULLDUPLEX : SPI FullDuplex mode. In this mode, SPI receive and transmit operations are performed simultaneously.
- SPI_MODE_EEPROM : SPI EEPROM mode. In this mode, SPI does not perform a receive operation until the transmission is completed.
SPI_CONFIG_GPIO_SIM_CS : Select whether or not to use GPIO emulation of the CS line for communication. 1 means to use GPIO to simulate CS line communication, and 0 means not to use GPIO for simulation.

Note

The specific differences between FullDuplex and EEPROM mode can refer to Troubleshooting .

Building and Downloading

This sample can be found in the SDK folder:

Keil

Project file: samples\peripheral\spi\polling\proj\rtl87x2g\mdk

GCC

Project file: samples\peripheral\spi\polling\proj\rtl87x2g\gcc

To build and run the sample, follow the steps listed below:

Open sample project file.
To build the target, follow the steps listed on the Generating App Image in Quick Start.
After a successful compilation, the app bin app_MP_xxx.bin will be generated in the directory mdk\bin or gcc\bin.
To download app bin into EVB board, follow the steps listed on the MP Tool Download in Quick Start.
Press reset button on EVB board and it will start running.

Experimental Verification

When the IC resets, observe the following log within the Debug Analyzer.
```
Start spi polling test!
```
SPI transfer mode configuration:
1. If SPI_MODE is configured as SPI_MODE_FULLDUPLEX, print the following log
```
SPI is set to FullDuplex Mode!
```
2. If SPI_MODE is configured as SPI_MODE_EEPROM, print the following log
```
SPI is set to EEPROM Mode!
```

Read external flash ID.

Read DEVICE_ID, the first three bytes are dummy read, the last byte is DEVICE_ID.

flash id = 000000ff
flash id = 000000ff
flash id = 000000ff
flash id = 00000017

Read MF_DEVICE_ID, the first three bytes are dummy read, the last two bytes are DEVICE_ID.

flash id = 000000ff
flash id = 000000ff
flash id = 000000ff
flash id = 000000ef
flash id = 00000017

Read JEDEC_ID.

flash id = 000000ef
flash id = 00000040
flash id = 00000018

Erase the data at the specified address in the Flash, and read the erased data (all FF).

spi_demo: spi_flash_sector_erase done
spi_demo: after erase read_data[0] = 0x000000ff
...
spi_demo: after erase read_data[99] = 0x000000ff

Write data at the specified address in the Flash, and then read the data.

In Fullduplex mode, since four bytes of data are sent, the first four bytes of the received data are FF (invalid data), and the fifth byte onwards is valid data.

spi_demo: after write read_data[0] = 0x000000ff
spi_demo: after write read_data[1] = 0x000000ff
spi_demo: after write read_data[2] = 0x000000ff
spi_demo: after write read_data[3] = 0x000000ff
spi_demo: after write read_data[4] = 0x0000000a
...
spi_demo: after write read_data[99] = 0x00000069

In EEPROM mode, data is not received when it is sent, so all data received is valid information.

spi_demo: after write read_data[0] = 0x0000000a
spi_demo: after write read_data[1] = 0x0000000b
...
spi_demo: after write read_data[99] = 0x0000006d

Code Overview

This chapter will be introduced according to the following several parts:

Source Code Directory.
Peripheral initialization will be introduced in chapter Initialization .
Functional implementation after initialization will be introduced in chapter Functional Implementation .

Source Code Directory

Project Directory: sdk\samples\peripheral\spi\polling\proj
Source Code Directory: sdk\samples\peripheral\spi\polling\src

Source files are currently categorized into several groups as below.

└── Project: polling
    └── secure_only_app
        └── Device                   includes startup code
            ├── startup_rtl.c
            └── system_rtl.c
        ├── CMSIS                    includes CMSIS header files
        ├── CMSE Library             Non-secure callable lib
        ├── Lib                      includes all binary symbol files that user application is built on
            └── rtl87x2g_io.lib
        ├── Peripheral               includes all peripheral drivers and module code used by the application
            ├── rtl_rcc.c
            ├── rtl_pinmux.c
            ├── rtl_gpio.c
            └── rtl_spi.c
        └── APP                      includes the ble_peripheral user application implementation
            ├── main_ns.c
            ├── spi_flash.c          includes a wrapper implementation of functions to communicate with external flash
            └── io_spi.c

Initialization

The initialization process includes board_spi_init and driver_spi_init .

board_spi_init contains the PAD and PINMUX settings:

Config PAD: Set pin as PINMUX mode, PowerOn, internal Pull-Up.
Config PINMUX: Assign pins for SPI0_CLK_MASTER, SPI0_MO_MASTER, SPI0_MI_MASTER, SPI0_CSN_0_MASTER functions respectively.
1. If set SPI_CONFIG_GPIO_SIM_CS to 1, SPI_CS_PIN needs to be assigned to the DWGPIO function.

driver_spi_init contains the initialization of SPI peripheral:

Enable PCC clock.
Configure the corresponding SPI transfer mode according to the SPI_MODE configuration.
In EEPROM transfer mode, the NDF value needs to be configured.
Configure the transfer data width.
Configure the clock to high level during idle state, with data captured on the second clock edge.
Set the clock division factor to 100.
Set the receive data length threshold and data transfer format.

Note

The minimum value of the clock division factor for SPI is 2 and can only be an even number.

RCC_PeriphClockCmd(APBPeriph_SPI0, APBPeriph_SPI0_CLOCK, ENABLE);
...
#if (SPI_MODE_FULLDUPLEX == SPI_MODE)
  SPI_InitStruct.SPI_Direction   = SPI_Direction_FullDuplex;
       DBG_DIRECT("SPI is set to FullDuplex Mode!");
#elif (SPI_MODE_EEPROM == SPI_MODE)
       SPI_InitStruct.SPI_Direction   = SPI_Direction_EEPROM;
       /* SPI_Direction_EEPROM mode read data lenth. */
       SPI_InitStruct.SPI_NDF         = 1;
       DBG_DIRECT("SPI is set to EEPROM Mode!");
#endif
...

Functional Implementation

Loop spi_flash_read_id function three times to read the external flash DEVICE_ID/MF_DEVICE_ID/JEDEC_ID information respectively.
1. Depending on the different ID types that need to be read, change the different instructions corresponding to the first byte of the sent data with the length of the data that needs to be received.
2. If SPI_MODE is configured as SPI_MODE_EEPROM:
  1. Execute SPI_SetReadLen() before sending data to set the length of the data to be read.
  2. After setting the receive length, only need to execute SPI_SendBuffer() to send one byte of instruction data, and then loop the SPI_ReceiveData() function to receive the data.
3. If SPI_MODE is configured as SPI_MODE_FULLDUPLEX:
  1. Since Fullduplex mode communication is simultaneous sending and receiving, it is necessary to send recv_len + 1 length of data.
  2. After sending the data, the SPI_ReceiveData() function is executed once, i.e., a dummy read is performed to read the invalid data that corresponds to the reply of the command byte sent.
  3. Loop execute SPI_ReceiveData() function for remaining data reception.

void spi_flash_read_id(Flash_ID_Type vFlashIdType, uint8_t *pFlashId)
{
#if (SPI_CONFIG_GPIO_SIM_CS == 1)
        GPIO_ResetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif
   uint8_t send_buf[4] = {SPI_FLASH_JEDEC_ID, 0, 0, 0};
   uint8_t recv_len = 3;

   switch (vFlashIdType)
   {
   ...
   }

#if (SPI_MODE_EEPROM == SPI_MODE)
   SPI_SetReadLen(FLASH_SPI, recv_len);
   SPI_SendBuffer(FLASH_SPI, send_buf, 1);
#elif (SPI_MODE_FULLDUPLEX == SPI_MODE)
   SPI_SendBuffer(FLASH_SPI, send_buf, recv_len + 1);
   while (SPI_GetFlagState(FLASH_SPI, SPI_FLAG_RFNE) == RESET){}
   SPI_ReceiveData(FLASH_SPI);//dummy read data
#endif

   *pFlashId++ = recv_len;
   uint8_t idx = 1;
   while (recv_len--)
   {
      while (RESET == SPI_GetFlagState(FLASH_SPI, SPI_FLAG_RFNE)){}
         *pFlashId++ = SPI_ReceiveData(FLASH_SPI);
   }

#if (SPI_CONFIG_GPIO_SIM_CS == 1)
   GPIO_SetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif
}

Execute spi_flash_sector_erase, erase data at the specified address.
1. Edit the data to be sent. The first byte is the erase command and the second, third, and fourth bytes are the address to be specified.
2. Before writing the data, execute spi_flash_write_enable to enable the write operation.
3. If SPI_MODE is configured as SPI_MODE_EEPROM:
  1. When the write operation is executed, only the data to be sent and not the data to be received is required. In this case, the communication mode of EEPROM cannot support the use of this scenario, so it is necessary to switch the mode to Tx Only mode to send data.
  2. Before cutting back to EEPROM mode, it is necessary to wait for the BUSY status bit to return to RESET.
4. If SPI_MODE is configured as SPI_MODE_FULLDUPLEX:
  1. In FullDuplex mode, it is necessary to loop SPI_GetRxFIFOLen() to read the data in the RX FIFO empty after sending the first buffer.
5. Execute spi_flash_busy_check to check the status of external flash.

void spi_flash_sector_erase(uint32_t vAddress)
{
#if (SPI_CONFIG_GPIO_SIM_CS == 1)
   GPIO_ResetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif

   uint8_t send_buf[4] = {SPI_FLASH_SECTOR_ERASE, 0, 0, 0};
   uint8_t recv_len = 0;

   send_buf[1] = (vAddress >> 16) & 0xff;
   send_buf[2] = (vAddress >> 8) & 0xff;
   send_buf[3] = vAddress & 0xff;

   /* enable write */
   spi_flash_write_enable();
   /* erase data */
#if (SPI_MODE_EEPROM == SPI_MODE)
   SPI_ChangeDirection(FLASH_SPI, SPI_Direction_TxOnly);
   SPI_SendBuffer(FLASH_SPI, send_buf, 4);
   while (SPI_GetFlagState(FLASH_SPI, SPI_FLAG_BUSY) == SET){}
   SPI_ChangeDirection(FLASH_SPI, SPI_Direction_EEPROM);
#elif (SPI_MODE_FULLDUPLEX == SPI_MODE)
   SPI_SendBuffer(FLASH_SPI, send_buf, 4);
   while (SPI_GetFlagState(FLASH_SPI, SPI_FLAG_BUSY) == SET){}
   recv_len = SPI_GetRxFIFOLen(FLASH_SPI);
   while (recv_len--)
   {
      SPI_ReceiveData(FLASH_SPI);
   }
#endif

#if (SPI_CONFIG_GPIO_SIM_CS == 1)
   GPIO_SetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif

   spi_flash_busy_check();
}

Execute the spi_flash_read function to read the data of the specified length at the specified address of the flash.
1. Edit the data to be sent. The first byte is the read command and the second, third, and fourth bytes are the address to be specified.
2. If SPI_MODE is configured as SPI_MODE_EEPROM:
  1. It needs to execute SPI_SetReadLen() to set the length of the data to be read to the specified length before sending the data.
  2. Execute SPI_SendBuffer() function to send the read command to the specified address.
  3. Loop SPI_GetRxFIFOLen() to read the data sent back by flash.
3. If SPI_MODE is configured as SPI_MODE_FULLDUPLEX:
  1. After sending instruction+address data, it needs to loop SPI_GetRxFIFOLen() to read the invalid data in RX FIFO empty.
  2. In receive data phase: every time before receiving data, need to send a dummy data to flash before receiving data.

void spi_flash_read(uint8_t vReadCmd, uint32_t vReadAddr, uint8_t *pBuffer, uint16_t vLength)
{
#if (SPI_CONFIG_GPIO_SIM_CS == 1)
   GPIO_ResetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif

   ...

#if (SPI_MODE_EEPROM == SPI_MODE)
   SPI_SetReadLen(FLASH_SPI, vLength);
   SPI_SendBuffer(FLASH_SPI, send_buf, send_len);
#elif (SPI_MODE_FULLDUPLEX == SPI_MODE)
   SPI_SendBuffer(FLASH_SPI, send_buf, send_len);
   while (SPI_GetFlagState(FLASH_SPI, SPI_FLAG_RFNE) == RESET){}
   for (uint8_t i = 0; i < send_len; i++)
   {
      SPI_ReceiveData(FLASH_SPI);//dummy read data
   }
#endif

   recv_len = vLength;
   while (recv_len--)
   {
#if (SPI_MODE_FULLDUPLEX == SPI_MODE)
      SPI_SendBuffer(FLASH_SPI, &send_buf[9], 1);
#endif
      while (SPI_GetFlagState(FLASH_SPI, SPI_FLAG_RFNE) == RESET){}
      *pBuffer++ = SPI_ReceiveData(FLASH_SPI);
   }

#if (SPI_CONFIG_GPIO_SIM_CS == 1)
   GPIO_SetBits(GPIO_GetPort(SPI_CS_PIN), GPIO_GetPin(SPI_CS_PIN));
#endif
}

Execute spi_flash_page_write function to write the specified data to the specified address in the flash. (logic similar to spi_flash_sector_erase)
Execute spi_flash_read function to read the data content under the address after writing the data, and check whether it is correct or not.
When setting up GPIO simulate CS line, execute GPIO_ResetBits() function to pull down the CS line before each communication starts, and execute GPIO_SetBits() function to pull up the CS line after the communication ends.

Troubleshooting

SPI Four Communication Methods Introduction

FullDuplex In FullDuplex communication mode, both transmit and receive logic are active. Data transmission proceeds normally according to the selected frame format (serial protocol).

Transmit Only In Transmit Only communication mode, the logic for receiving data is invalid and is not stored in the FIFO.

Receive Only In Receive Only communication mode, transmit data is invalid. The output remains at a constant logic level during transmission.

EEPROM In the EEPROM communication mode, generally used for sending data, the opcode and address are sent to the EEPROM device. During the transmission of the opcode and address, the receive logic is disabled and no receive data is performed. The master continues to send data until the transmit FIFO is empty. When the transmit FIFO is empty, data on the receive line is valid and stored in the receive FIFO. Transmission continues until the master receives the same amount of data as the NDF value configured in initialization.