Application Note

embOS/IP Migration
Guide

Document: AN07001
Revision: 9
Date: June 30, 2016

A product of SEGGER Microcontroller GmbH & Co. KG

www.segger.com
2

Disclaimer
Specifications written in this document are believed to be accurate, but are not guar-
anteed to be entirely free of error. The information in this manual is subject to
change for functional or performance improvements without notice. Please make sure
your manual is the latest edition. While the information herein is assumed to be
accurate, SEGGER Microcontroller GmbH & Co. KG (SEGGER) assumes no responsibil-
ity for any errors or omissions. SEGGER makes and you receive no warranties or con-
ditions, express, implied, statutory or in any communication with you. SEGGER
specifically disclaims any implied warranty of merchantability or fitness for a particu-
lar purpose.
Copyright notice
You may not extract portions of this manual or modify the PDF file in any way without
the prior written permission of SEGGER. The software described in this document is
furnished under a license and may only be used or copied in accordance with the
terms of such a license.
© 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG, Hilden / Germany

Trademarks
Names mentioned in this manual may be trademarks of their respective companies.
Brand and product names are trademarks or registered trademarks of their respec-
tive holders.

Manual versions
This manual describes the current software version. If any error occurs, inform us
and we will try to assist you as soon as possible.
Contact us for further information on topics or routines not yet specified.
Print date: June 30, 2016

Revision Date By Description

9 160630 OO Added migration information for V3.08 (IP_BSP_API).
8 160511 OO Added migration information for V3.06 .
7 160419 OO Minor corrections on text.
Added missing information regarding moved IP/OS layer for V3.00a .
6 151124 OO
Added migration information for V3.02 .
5 151007 OO Added migration information for V3.00a .
4 150813 OO Added migration information for V3.00 .
3 141002 OO Added migration information for V2.20b .
2 140430 OO Added migration information for V2.20 .
1 130312 OO Added migration information for V2.12 .
0 120511 OO First version.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 3

Table of Contents

1 Migrating from a previous version....................................................................................5

1.1 Migrating from embOS/IP V1.......................................................................6
1.1.1 Changes to the configuration file..................................................................6
1.2 Migrating to embOS/IP V2.12 ......................................................................7
1.2.1 Changes regarding checksum calculation ......................................................7
1.2.2 Changes regarding VFile hooks ....................................................................7
1.3 Migrating to embOS/IP V2.20 ......................................................................8
1.3.1 Changes regarding PPP and BSP_UART.c module ...........................................8
1.3.2 Changes regarding the file system application layer........................................8
1.4 Migrating to embOS/IP V2.20b ....................................................................9
1.4.1 New files added .........................................................................................9
1.4.2 Files changed ............................................................................................9
1.4.3 Other changes...........................................................................................9
1.5 Migrating to embOS/IP V3.00 .................................................................... 10
1.5.1 New files added ....................................................................................... 10
1.5.2 Files changed .......................................................................................... 10
1.6 Migrating to embOS/IP V3.00a .................................................................. 11
1.6.1 Util folder moved ..................................................................................... 11
1.6.2 Assembler files moved.............................................................................. 11
1.6.3 OS abstraction layer moved ...................................................................... 11
1.7 Migrating to embOS/IP V3.02 .................................................................... 12
1.7.1 Changes regarding PHY drivers.................................................................. 12
1.7.2 RX BSP_ETH_* changes ........................................................................... 12
1.8 Migrating to embOS/IP V3.06 .................................................................... 13
1.8.1 Changes regarding file/folder structure ....................................................... 13
1.9 Migrating to embOS/IP V3.08 .................................................................... 14
1.9.1 IP_BSP_API has been added ..................................................................... 14

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
4

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 5

Chapter 1

Migrating from a previous version

This chapter provides a guideline on how to migrate to the latest embOS/IP software
version from a previously used older version. Although trying to provide a minimum
of changes that need to be applied for new versions this can not be guaranteed in
any case. This chapter shall provide step by step instructions about the necessary
changes that need to be applied in case there was a change in embOS/IP not com-
patible with a previous version.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
6 CHAPTER 1 Migrating from a previous version

1.1 Migrating from embOS/IP V1

One of the new features of embOS/IP V2 is that the user now can save ROM and RAM
by not including modules that are not needed for the users functionality.
For this to achieve embOS/IP V2 now allows to add only those protocols that you plan
to use in your project. For this the customer will have to apply minimal changes to
their previously used configuration. The steps necessary are explained in more detail
in the next sections.

1.1.1 Changes to the configuration file

Adding one or more protocols to the IP stack is fairly easy. At the moment the follow-
ing protocols can be added:
• TCP
• UDP
• ICMP
The following table shows the API that is needed to be added to your config file to
add protocols.

Function Description
IP_ICMP_Add() Adds ICMP to the stack.
IP_TCP_Add() Adds TCP to the stack.
IP_UDP_Add() Adds UDP to the stack.
Table 1.1: embOS/IP protocol API function overview

To add one or more of these protocols to the IP stack follow these steps:
1. Open your configuration file which is typically called IP_Config_*.c in a text edi-
tor or the editor of your IDE.
2. Add one or more protocols to the routine IP_X_Config()

IP_TCP_Add();
IP_UDP_Add();
IP_ICMP_Add();

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 7

1.2 Migrating to embOS/IP V2.12

The changes in this version are kept to a minimum and may not apply to you depend-
ing on what MCU you are using. The following changes are necessary to know when:
• You are using an assembler routine for checksum calculation.
• You are using VFile hooks as they are used with the UPnP add-on.

1.2.1 Changes regarding checksum calculation

In previous releases the checksum calculation as it was used for e.g. TCP did not fol-
low recommendations in RFC 1624 . RFC 1624 describes a case where a network par-
ticipant may send a TCP checksum of 0xFFFF due to an older RFC and how to handle
it as 0xFFFF is not treated a valid value for a TCP checksum.
In order to support RFC 1624 the assembler routines for checksum calculation now
get a third parameter Sum which is the start checksum.
The following changes need to be applied to your IP_Conf.h for each compiler. For
demonstrational purposes the ARM branch is shown:
Old
U32 ARM_IP_cksum(void *ptr, unsigned NumHWords);
#define IP_CKSUM(p, NumItems) ARM_IP_cksum((p), (NumItems))

New
U32 ARM_IP_cksum(void *ptr, unsigned NumHWords, U32 Sum);
#define IP_CKSUM(p, NumItems, Sum) ARM_IP_cksum((p), (NumItems), (Sum))

1.2.2 Changes regarding VFile hooks

VFile hooks have been introduced to support an easy way of serving a small dynami-
cally built config file such as an XML file for UPnP that does not need further parsing.
As UPnP does not seem to be able to handle chunked encoding the XML file needs to
be served in RAW encoding for UPnP. In previous releases all VFile hooks were serv-
ing RAW encoded content. However this is not always desired as with larger files
being served by VFile hooks it might be desired to have chunked encoding.
For this to achieve VFile hooks will now as with regular web site requests by a
browser try to serve chunked encoding when possible. To support UPnP which needs
to use RAW encoding the VFile hook function has been changed to get another
parameter to force RAW encoding.
The following changes need to be applied where VFile hooks have been used:
Using a VFile hook for a web page
IP_WEBS_AddVFileHook( &_UPnP_VFileHook,
&_UPnP_VFileAPI,
0);

Using a VFile hook for UPnP XML file

IP_WEBS_AddVFileHook( &_UPnP_VFileHook,
&_UPnP_VFileAPI,
HTTP_ENCODING_RAW);

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
8 CHAPTER 1 Migrating from a previous version

1.3 Migrating to embOS/IP V2.20

The changes in this version are kept to a minimum and may not apply to you depend-
ing on what configuration you are using. The following changes are necessary to
know when:
• You are using the PPP add-on.
• You are using the FTP Server add-on.

1.3.1 Changes regarding PPP and BSP_UART.c module

To allow the BSP_UART.c module to be used with several other middleware the API of
the BSP_UART_* routines has been extended. Basically the old routines can be easily
extended by wrapping the old functions with the new API.
A sample of the new API is shipped in the BSP folder that comes with the PPP / PPPoE
add-on shipment.

1.3.2 Changes regarding the file system application layer

To allow moving files and folders when accessing the FTP server add-on the function
IP_FS_API structure has been extended by two function pointers.

Function pointer Description

pfIsFolder Checks if the given path is a folder.
pfMove Moves a file or folder.
Table 1.2: embOS/IP file system application layer API function overview

The new functionality is optional but not implementing these functionality means that
the FTP server will not be able to successfully check if the given path is really a folder
(which might be necessary for batch operations) or moving files and folders.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 9

1.4 Migrating to embOS/IP V2.20b

The following changes need to be addressed when migrating from a previous version.

1.4.1 New files added

The following files have been added to allow better handling of CPUs with cache.
• IP_CACHE.c

1.4.2 Files changed

The following files that reside outside of the IP folder have been changed and need to
be updated as well.
• SEGGER.h

1.4.3 Other changes

If multicast support is enabled with IP_SUPPORT_MULTICAST == 1 (default) the file
IP_IGMP.c now needs to be included into the project as well.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
10 CHAPTER 1 Migrating from a previous version

1.5 Migrating to embOS/IP V3.00

The following changes need to be addressed when migrating from a previous version.

1.5.1 New files added

The following files have been added:
• IP_ETH.c

1.5.2 Files changed

The following files that reside outside of the IP folder have been changed and need to
be updated as well.
• SEGGER.h
• Global.h

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 11

1.6 Migrating to embOS/IP V3.00a

The following changes need to be addressed when migrating from a previous version.

1.6.1 Util folder moved

The files from the Util folder have been moved into the SEGGER folder to match their
prefix.

1.6.2 Assembler files moved

Assembler files have been moved up one folder into ASM folders to make it clear that
these are special optimized versions of the default C-routines. Overwriting the
default C-routines is typically done by a macro that can be found in the file
\Config\IP_Conf.h . This applies to the following folders:
• IP\ASM
• SEGGER\ASM

1.6.3 OS abstraction layer moved

The OS abstraction layer and espacially the file IP_OS_embOS.c can now be found in
the folder \Sample\IP\OS. Exactly one IP/OS layer has to be used at the same time.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
12 CHAPTER 1 Migrating from a previous version

1.7 Migrating to embOS/IP V3.02

The following changes need to be addressed when migrating from a previous version.

1.7.1 Changes regarding PHY drivers

With embOS/IP V3.02 PHY driver support has been added. The previously fixed
generic PHY driver is now an exchangeable PHY driver that has been moved into the
new file IP_PHY_GENERIC.c and has to be added to your project.

1.7.2 RX BSP_ETH_* changes

The Renesas RX Ethernet driver now supports RX64M and RX71M in general as well
as dual MAC support. For this change the call to BSP_ETH_InstallISR() is exchanged
with BSP_ETH_InstallISR_Ex().
The conversion is shown in the following example:
Before
/*********************************************************************
*
* BSP_ETH_InstallISR()
*/
void BSP_ETH_InstallISR(void (*pfISR)(void)){
_pfEthISRHandler = pfISR;
}

After
/*********************************************************************
*
* BSP_ETH_InstallISR_Ex()
*/
void BSP_ETH_InstallISR_Ex(int ISRIndex, void (*pfISR)(void), int Prio){
(void)ISRIndex;
(void)Prio;

_pfEthISRHandler = pfISR;
}

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 13

1.8 Migrating to embOS/IP V3.06

The following changes need to be addressed when migrating from a previous version.

1.8.1 Changes regarding file/folder structure

Some files that provide functionality not directly related to the IP stack itself or not
necessary for running the stack have been moved into a “Shared” folder. Examples
for these files are connection layers between IP and FS as well as sample code that is
shared between more than one sample like the “Webserver_DynContent.c“ that con-
tains most of the sample code used by various web server samples that basically only
differ in the setup phase.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
14 CHAPTER 1 Migrating from a previous version

1.9 Migrating to embOS/IP V3.08

The following changes need to be addressed when migrating from a previous version.

1.9.1 IP_BSP_API has been added

In previous versions hardware specific setup that the driver can not handle in a
generic way was located in BSP_ETH_* functions in the file BSP.c that was shipped
for different eval boards in the “\BSP” folder of the embOS/IP shipment.
As this file might be shipped in different versions with different middleware compo-
nents the BSP.c that contained routines for several middlewares has been split up
into middleware specific BSP_<MW>.c files like BSP_IP.c .
Drivers will be switched from the old BSP.c implementation to the new IP_BSP_API
structure over time. Such a change will be announced in the release notes and will
not be mentioned in the migration guide again.
Drivers that have been changed to the IP_BSP_API will be shipped with matching
sample BSP.c and BSP_IP.c in the “\BSP“ folder for your reference and are easy to
adopt to the new API.
The main difference is that for each driver added the following line now needs to be
added to the IP_X_Config():
IP_BSP_SetAPI(IFaceId, &BSP_IP_Api); // Set BSP callbacks for hardware access.

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
 15

Index

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG
16 Index

AN07001 Migration Guide for embOS/IP © 2007 - 2016 SEGGER Microcontroller GmbH & Co. KG