readme.md
1This is a FreeeRTOS+TCP driver that works for STM32Fxx parts.
2
3
4CONFIGURATION AND RUNNING
5=========================
6
7The code of stm32fxx_hal_eth.c is based on the ETH drivers as provided by ST.
8
9These modules should be included:
10- portable/NetworkInterface/STM32Fxx/NetworkInterface.c
11- portable/NetworkInterface/STM32Fxx/stm32fxx_hal_eth.c
12
13When initialising the EMAC, the driver will call the function `HAL_ETH_MspInit()`, which should do the following:
14
15- Enable the Ethernet interface clock using:
16```cpp
17 __HAL_RCC_ETHMAC_CLK_ENABLE();
18 __HAL_RCC_ETHMACTX_CLK_ENABLE();
19 __HAL_RCC_ETHMACRX_CLK_ENABLE();
20```
21
22- Initialize the related GPIO clocks
23
24- Configure Ethernet pin-out
25 Please check the schematic of your hardware to see which pins are used.
26 Also check if either MII or RMII is used ( define `ipconfigUSE_RMII`
27 as 0 or 1 ).
28
29- Configure Ethernet NVIC interrupt (IT mode)
30 Choose a proper interrupt priority, defined in FreeRTOSIPConfig.h as e.g. :
31
32```cpp
33 #define ipconfigMAC_INTERRUPT_PRIORITY ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY )
34```
35
36The function `HAL_ETH_MspInit()` must be provided by the application. Make sure that your copy of the function is called,
37and not a dummy defined as "weak".
38
39It is assumed that one of these macros is defined at the highest level:
40
41 STM32F1xx
42 STM32F2xx
43 STM32F4xx
44 STM32F7xx
45
46For instance, you can pass it to the compiler with the `-D` option:
47
48 gcc ... -D STM32F4xx=1
49
50And sub-models may also be indicated, such as `STM32F401xC` or `STM32F407xx`.
51
52The driver has been tested on both Eval and Discovery boards with STM32F1, STM32F2, STM32F4 and STM32F7. The F1 and F2 boards
53have only be tested by customers who reported about it on the FreeRTOS forum.
54
55Note that it is required to define `HAL_ETH_MODULE_ENABLED` in your STM32 configuration file. The name of this file is one out
56of:
57
58 stm32f1xx_hal_conf.h
59 stm32f2xx_hal_conf.h
60 stm32f4xx_hal_conf.h
61 stm32f7xx_hal_conf.h
62
63This configuration file defines the HAL modules that will be used. Here are some examples of the module macros:
64~~~c
65#define HAL_MODULE_ENABLED
66#define HAL_ETH_MODULE_ENABLED /* <= this one is needed to get Ethernet. */
67#define HAL_SRAM_MODULE_ENABLED
68#define HAL_RNG_MODULE_ENABLED
69#define HAL_RTC_MODULE_ENABLED
70/* etc. */
71~~~
72
73Recommended settings for STM32Fxx Network Interface:
74
75
76**Defined in FreeRTOSIPConfig.h**
77```cpp
78#define ipconfigETHERNET_DRIVER_FILTERS_FRAME_TYPES 1
79#define ipconfigDRIVER_INCLUDED_TX_IP_CHECKSUM 1
80#define ipconfigDRIVER_INCLUDED_RX_IP_CHECKSUM 1
81#define ipconfigZERO_COPY_RX_DRIVER 1
82#define ipconfigZERO_COPY_TX_DRIVER 1
83#define ipconfigUSE_LINKED_RX_MESSAGES 1
84#define ipconfigSUPPORT_NETWORK_DOWN_EVENT 1
85```
86
87**Defined in stm32f4xx_hal_conf.h**
88```cpp
89#define ETH_RXBUFNB 3 or 4
90#define ETH_TXBUFNB 1 or 2
91#define ETH_RX_BUF_SIZE ( ipconfigNETWORK_MTU + 36 )
92#define ETH_TX_BUF_SIZE ( ipconfigNETWORK_MTU + 36 )
93```
94
95The best size for `ETH_RXBUFNB` and `ETH_TXBUFNB` depends on the speed of the CPU. These macro's define the number of DMA buffers
96for reception and for transmission. In general, if the CPU is very fast, you will need less buffers. You can obtain an estimate
97empirically.
98
99The optimal value of `ETH_RX_BUF_SIZE` and `ETH_TX_BUF_SIZE` depends on the actual value of `ipconfigNETWORK_MTU`.
100When MTU is 1500, MTU+36 becomes a well-aligned buffer of 1536 bytes ( 0x600 ).
101When MTU is 1200, MTU+48 will make 1248 ( 0x4E0 ), which is also well aligned.
102
103Having well aligned buffers is important for CPU with memory cache. Often the caching system divides memory in blocks of 32 bytes.
104When two buffers share the same cache buffer, you are bound to see data errors.
105
106Without memory caching, let the size be at least a multiple of 8 ( for DMA ), and make it at least "ipconfigNETWORK_MTU + 14".
107
108STM32F7xx only:
109
110NetworkInterface.c will place the 2 DMA tables in a special section called 'first_data'.
111In case 'BufferAllocation_1.c' is used, the network packets will also be declared in this section 'first_data'.
112As long as the part has no caching, this section can be placed anywhere in RAM.
113On an STM32F7 with an L1 data cache, it shall be placed in the first 64KB of RAM, which is always uncached.
114The linker script must be changed for this, for instance as follows:
115
116```assembly
117 .data :
118 {
119 . = ALIGN(4);
120 _sdata = .; // create a global symbol at data start
121+ *(.first_data) // .first_data sections
122 *(.data) // .data sections
123 *(.data*) // .data* sections
124
125 . = ALIGN(4);
126 _edata = .; // define a global symbol at data end
127 } >RAM AT> FLASH
128```
129
130The driver contains these files:
131- NetworkInterface.c
132- stm32fxx_hal_eth.c
133- stm32f2xx_hal_eth.h
134- stm32f4xx_hal_eth.h
135- stm32f7xx_hal_eth.h
136- stm32fxx_hal_eth.h
137
138These files are copied from ST's HAL library. These work both for STM32F4 and STM32F7.
139Please remove or rename these files from the HAL distribution that you are using.
140
141
