xref: /FreeRTOS-Plus-TCP-v4.0.0/GettingStarted.md (revision 7681bb11f399b84f9ce34ddf79c304d0cc51c296) 
1Moving to 4.0.0 from 3.x.x:
2--------------------------------
3
4Version 4.0.0 adds new files to support IPv6 functionality, breaking each file into logically separated IPv4 and IPv6 files. The folder structure of FreeRTOS-Plus-TCP remains unchanged. Build separation is added to make the library modular, enabling users to compile and create a low-footprint binary with only the required functionalities. For more details on supported build combinations, see [History.txt](https://github.com/FreeRTOS/FreeRTOS-Plus-TCP/blob/main/History.txt) .
5
6Some of the APIs have changed which is illustrated in the section below. However, there is a backward compatibility mode provided as well.
7
8Backward Compatibility Mode:
9---------------------------
10   If you are moving your code from V3.x.x to V4.0.0, then set the "ipconfigIPv4_BACKWARD_COMPATIBLE" macro to 1 in “FreeRTOSIPConfigDefaults.h” to run the code in backward compatible mode.
11   The "Existing API's" defined in all the API changes below work only when the backward compatibility mode is enabled.
12
13API changes in 4.0.0:
14----------------------
15
16The changes mentioned below uses ipconfigIPv4_BACKWARD_COMPATIBLE flag to differentiate between old API and new API.
17
18Change 1:
19
20   - Existing API: FreeRTOS_IPInit
21      - Backward compatibility with the IPv4 FreeRTOS+TCP V3.x.x which only supports single network interface. This can be used for single  interface IPv4 systems.
22   - New API: FreeRTOS_IPInit_Multi
23      - Supports multiple interfaces. Before calling this function, at least 1 interface and 1 end-point must have been set-up. FreeRTOS_IPInit_Multi() replaces the earlier FreeRTOS_IPInit().
24
25Change 2:
26
27   - Existing API: FreeRTOS_GetAddressConfiguration/FreeRTOS_SetAddressConfiguration
28      - Get/Set the address configuration from the global variables initialised during FreeRTOS_IPInit
29   - New API: FreeRTOS_GetEndPointConfiguration/FreeRTOS_SetEndPointConfiguration
30      - Get/Set the same address configuration from/to the end point
31
32Change 3:
33
34   - Existing API:  FreeRTOS_GetUDPPayloadBuffer
35      - Backward compatibility with the IPv4 FreeRTOS+TCP V3.x.x. This can still be used for IPv4 use cases.
36   - New API:FreeRTOS_GetUDPPayloadBuffer_Multi
37      - A new argument (uint8_t ucIPType) to specify IP type to support both IPv4 and IPv6
38
39Change 4:
40
41   - Existing API: pxFillInterfaceDescriptor
42      - It is there for backward compatibility. The function FreeRTOS_IPInit() will call it to initialise the interface and end-point objects
43   - New API: prefix_pxFillInterfaceDescriptor
44      - where prefix = Network Interface Name
45      - E.g pxWinPcap_FillInterfaceDescriptor
46      - New function with the same functionality
47
48Change 5:
49
50   - Existing API: vApplicationIPNetworkEventHook
51   - New API: vApplicationIPNetworkEventHook_Multi
52      - New argument “struct xNetworkInterface * pxNetworkInterface” added.
53
54Change 6:
55
56   - Existing API: xApplicationDHCPHook
57   - New API: xApplicationDHCPHook_Multi
58      - New argument "struct xNetworkEndPoint * pxEndPoint" added.
59
60Change 7:
61
62   - Existing API: xApplicationDNSQueryHook
63   - New API: xApplicationDNSQueryHook_Multi
64      - New argument "struct xNetworkEndPoint * pxEndPoint" added.
65
66**NOTE** : We are NOT considering the APIs changes in FreeRTOS_IP_Private.h for backward compatibility as those are not part of published interface.
67
68Running Demos:
69-------------
70The demos can be found on [this page](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo).
71
72In all the demos, there is a backward compatibility mode which can be enabled by setting the flag “ipconfigIPv4_BACKWARD_COMPATIBLE” to 1 in the header file “FreeRTOSIPConfigDefaults.h”.
73This flag is by default set to zero.
74
75New IPv6 WinSim Demo can be found on [this page](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/FreeRTOS_Plus_TCP_IPv6_Demo/IPv6_Multi_WinSim_demo).
76