1
2FreeRTOS+TCP driver for STM32H7xx.
3
4Some STM32 network settings are stored in 'stm32h7xx_hal_conf.h'.
5
6Number of DMA descriptors, for transmission and for reception.
7
8The descriptors for transmission are protected with a counting semaphore.
9By the time that a packet has been sent, the other TX descriptor becomes
10available already.
11The number of descriptors has an incluence on the performance.  But that also depends on the size
12of the TCP buffers and TCP window sizes.
13
14When ETH_RX_DESC_CNT is too low, the adapter may miss incoming packets, they will be dropped.
15When ETH_RX_DESC_CNT is low, sending packets becomes slower.
16
17Here are settings give a high performance for iperf3:
18
19~~~
20/* ########################### Ethernet Configuration ######################### */
21#define ETH_TX_DESC_CNT         14U /* number of Ethernet Tx DMA descriptors */
22#define ETH_RX_DESC_CNT         8U  /* number of Ethernet Rx DMA descriptors */
23~~~
24
25Two more defines that are needed:
26
27~~~
28#define HAL_ETH_MODULE_ENABLED
29#define USE_HAL_ETH_REGISTER_CALLBACKS     0U /* ETH register callback disabled     */
30~~~
31
32The following macro's are **not** used by the FreeRTOS driver:
33
34    #define ETH_MAC_ADDR0    ((uint8_t)0x02)
35    #define ETH_MAC_ADDR1    ((uint8_t)0x00)
36    ...
37
38All memory that is shared between the CPU and the DMA ETH peripheral, should be
39located in special RAM area called ".ethernet_data". This shall be declared in
40the linker file (.ld).
41
42It is possible to use the AXI SRAM for this, but RAM{1,2,3} are also connected
43to the Ethernet MAC.
44
45Here is an example of the changes to the linker file:
46
47	RAM_D1 (xrw)   : ORIGIN = 0x24000000, LENGTH = 512K	/* should already exist in MEMORY section */
48
49	.ethernet_data : /* inside SECTIONS section, before /DISCARD/ */
50	{
51		PROVIDE_HIDDEN (__ethernet_data_start = .);
52		KEEP (*(SORT(.ethernet_data.*)))
53		KEEP (*(.ethernet_data*))
54		PROVIDE_HIDDEN (__ethernet_data_end = .);
55	} >RAM_D1
56
57Here is a table of 3 types of STH32H7 :
58
59|RAM area   |H747|H743|H742|Location  |
60|-----------|----|----|----|----------|
61|DTCM       |128k|128k|128k|0x20000000|
62|AXI-SRAM   |511k|511k|384k|0x24000000|
63|SRAM1      |128k|128k|32k |0x30000000|
64|SRAM2      |128k|128k|16k |0x30020000|
65|SRAM3      |32k | 32k| -  |0x30040000|
66|SRAM4      |64k |64k |64k |0x38000000|
67|Backup SRAM|4k  |4k  |4k  |0x38800000|
68
69
70Please make sure that the addresses and lengths are correct for your model of STM32H7xx.
71If you use a memory that is not supported, it will result in a DMA errors.
72
73Don't redefine a new memory area (like AXI-SRAM, RAM_D1) if it already exists in the
74MEMORY section, just take note of it's name for defining the section .ethernet_data later
75in that same file.
76
77In FreeRTOSIPConfig.h :
78
79Define the total number of network buffer descriptors, e.g. 64:
80
81~~~
82    #define ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS    ( 64 )
83~~~
84
85It is recommended to use the zero-copy method for both reception and transmission:
86
87~~~
88    #define ipconfigZERO_COPY_RX_DRIVER            ( 1 )
89    #define ipconfigZERO_COPY_TX_DRIVER            ( 1 )
90~~~
91
92The copy-method also works well, may just a little slower.
93
94Checksum cal be calculated in the Ethernet MAC, which is faster than doing manual calculations:
95
96~~~
97	/* The checksums will be checked and calculated by the STM32F4x ETH peripheral. */
98	#define ipconfigDRIVER_INCLUDED_TX_IP_CHECKSUM		( 1 )
99	#define ipconfigDRIVER_INCLUDED_RX_IP_CHECKSUM		( 1 )
100~~~
101
102The most important DMAC registers, along with their names which are used in the reference manual:
103
104    __IO uint32_t DMAMR;           // ETH_DMAMR         DMA mode register
105    __IO uint32_t DMAISR;          // ETH_DMAISR        DMA Interrupt status register
106    __IO uint32_t DMADSR;          // ETH_DMADSR        DMA Debug status register
107    __IO uint32_t DMACCR;          // ETH_DMACCR        DMA Channel control register
108    __IO uint32_t DMACTCR;         // ETH_DMACTXCR      Channel Tx transmit control register
109    __IO uint32_t DMACRCR;         // ETH_DMACRXCR      Channel Rx receive control register
110    __IO uint32_t DMACTDLAR;       // ETH_DMACTXDLAR    Channel Tx descriptor list address register
111    __IO uint32_t DMACRDLAR;       // ETH_DMACRXDLAR    Channel Rx descriptor list address register
112    __IO uint32_t DMACTDTPR;       // ETH_DMACTXDTPR    Channel TX tail pointer
113    __IO uint32_t DMACRDTPR;       // ETH_DMACRXDTPR    Channel RX tail pointer
114    __IO uint32_t DMACTDRLR;       // ETH_DMACTXRLR     Channel Tx descriptor ring length register
115    __IO uint32_t DMACRDRLR;       // ETH_DMACRXRLR     Channel Rx descriptor ring length register
116    __IO uint32_t DMACIER;         // ETH_DMACIER       Channel interrupt enable register
117    __IO uint32_t DMACRIWTR;       // ETH_DMACRXIWTR    Channel Rx interrupt watchdog timer register
118    __IO uint32_t DMACCATDR;       // ETH_DMACCATXDR    Channel Tx current application transmit descriptor register
119    __IO uint32_t DMACCARDR;       // ETH_DMACCARXDR    Channel Rx current application receive descriptor register
120    __IO uint32_t DMACCATBR;       // ETH_DMACCATXBR    Channel Tx current application transmit buffer register
121    __IO uint32_t DMACCARBR;       // ETH_DMACCARXBR    Channel Rx current application receive buffer register
122    __IO uint32_t DMACSR;          // ETH_DMACSR        Channel status register
123
124
125As most EMAC's, the STM32H7 EMAC is able to put packets in multiple linked DMA segments.
126FreeRTOS+TCP never uses this feature. Each packet is stored in a single buffer called
127`NetworkBufferDescriptor_t`.
128