How to migrate the platform layer from v3 to v4.

The platform layer provides portability across different operating systems. Both v3 and v4 provide a POSIX port as an example. If you are running on a v3 application on a POSIX system, you can switch the to provided v4 POSIX port and skip this page. This guide is intended for applications running on other operating systems that would like to move their porting layer from v3 to v4.

Mutex

How to migrate the mutex type from v3 to v4.

The mutexes used in v3 and v4 implement the same interface. In v4, recursive mutexes must be supported.

The table below shows the equivalent mutex types for v3 and v4.

	Version 3	Version 4	Notes
Name	struct _IoT_Mutex_t	_IotSystemMutex_t	In v3, the mutex type must be a struct. In v4, the mutex type may be any type.
Declare in file	threads_platform.h	iot_config.h	In v3, the mutex type must be declared in a file called threads_platform.h. Link to sample In v4, we recommend declaring the mutex type in iot_config.h.

Interface

Equivalent functions of the mutex interface between v3 and v4.

The following functions should be implemented for the mutex type:

v3: See functions in threads_interface.h
v4: IotMutex functions in Thread Management

The table below shows the equivalent functions in v3 and v4.

Version 3	Version 4	Notes
aws_iot_thread_mutex_init	IotMutex_Create	The v4 function must support recursive mutexes.
aws_iot_thread_mutex_lock	IotMutex_Lock
aws_iot_thread_mutex_trylock	IotMutex_TryLock
aws_iot_thread_mutex_unlock	IotMutex_Unlock
aws_iot_thread_mutex_destroy	IotMutex_Destroy

Example

Example of migration between v3 and v4.

The table below provides examples of the equivalent mutex types and interfaces implemented on v3 and v4.

	Version 3	Version 4
Declaration	/* In threads_platform.h */ struct _IoT_Mutex_t { pthread_mutex_t lock; };	/* In iot_config.h */ typedef pthread_mutex_t _IotSystemMutex_t;
Sample implementation (POSIX)	threads_pthread_wrapper.c	iot_threads_posix.c

Timer

Differences between v3 and v4 timers.

The timers in v4 are more efficient than v3, but their interface is completely different. In v4, the timer interface is designed to be similar to the timer APIs provided by most operating systems.

Because of the differences between the timers in v3 and v4, it is not possible to migrate a v3 timer implementation to v4. Therefore, a new timer implementation will need to be written for v4. See Clock for the list of functions that need to be implemented.

Semaphores

Details about counting semaphores needed in v4.

Counting semaphores are a new addition to the platform layer in v4. They were not present in v3. See the IotSemaphore functions in Thread Management for the list of functions that need to be implemented.

Networking

How to migrate the network implementation from v3 to v4.

The networking functions are similar between v3 and v4. However, v4 requires some additional function to be implemented.

The networking component requires a type to provide credentials for secured connections. The table below shows the equivalent credentials type for v3 and v4.

	Version 3	Version 4	Notes
Name	TLSDataParams	_IotNetworkCredentials_t	v4 provides IotNetworkCredentials as a struct that satisfies most use cases.
Declare in file	network_platform.h	iot_config.h	In v3, the credentials type must be declared in a file called network_platform.h. Link to sample In v4, we recommend declaring the credentials type in iot_config.h.

Version 4 requires two additional types to be declared:

_IotNetworkServerInfo_t which provides data on the remote server. IotNetworkServerInfo should satisfy most use cases.
_IotNetworkConnection_t to represent the handle of a network connection. This should be an opaque handle.

Interface

Equivalent functions of the networking interface between v3 and v4.

The following functions should be implemented for networking:

v3: See functions in network_interface.h
v4: Functions in Networking

The table below shows the equivalent functions in v3 and v4.

Version 3	Version 4	Notes
iot_tls_init	Platform-specific init functions	The v4 networking interface does not define a function that must be implemented to initialize the network, as some network stacks do not require initialization. It may be implemented if needed. The parameters of iot_tls_init have been moved to IotNetworkInterface_t::create.
iot_tls_connect	IotNetworkInterface_t::create
iot_tls_write	IotNetworkInterface_t::send
iot_tls_read	IotNetworkInterface_t::receive
iot_tls_disconnect	IotNetworkInterface_t::close
iot_tls_destroy	IotNetworkInterface_t::destroy	In v3, this function destroys the entire network stack. In v4, this function only destroys the connection passed to it.

Version 4 has the following new functions that must be implemented:

Version 4 requires the networking functions to be given as an IotNetworkInterface_t. We recommend implementing a function that returns the IotNetworkInterface_t containing the networking functions.

Example

Example of migration between v3 and v4.

The table below provides examples of the equivalent networking types and interfaces implemented on v3 and v4.

	Version 3	Version 4
Credentials type declaration	/* In threads_platform.h / typedef struct _TLSDataParams { / Members omitted due to length. */ } TLSDataParams;	/* In iot_config.h / / Forward declare standard type from v4. / struct IotNetworkCredentials; typedef struct IotNetworkCredentials _IotNetworkCredentials_t;
Server info declaration	None	/* In iot_config.h / / Forward declare standard type from v4. / struct IotNetworkServerInfo; typedef struct IotNetworkServerInfo _IotNetworkServerInfo_t;
Opaque network type declaration	None	/* In iot_config.h / / Forward declare opaque struct. / struct _networkConnection; typedef struct _networkConnection _IotNetworkConnection_t;
Sample implementation (mbed TLS)	network_mbedtls_wrapper.c	iot_network_mbedtls.c