User Tools

Site Tools


IoTivity Platform Support Project

1 Platforms

For documentation purposes, “platform” is defined in terms of:

  • OS (with version)
  • CPU architecture
  • Toolchain (with version)

Platform dependencies such as operating systems or toolchains should be “released” versions (not beta) at least 1 month prior to the expected IoTivity release. Unless platform support is dropped, the expectation is that support would continue to move forward as the platform evolves (for instance, as new OS versions are released).

1.1 Fully Supported Platforms

A fully-supported platform:

  • Is actively maintained and tested prior to release
  • Is included in automated testing and builds
  • Has sub-maintainer(s) that will address issues that arise
  • Has sample code
  • Has a “Getting Started Guide” that includes build instructions

A fully supported platform is one where all non-experimental features work, and you cannot commit a feature that is enabled by default unless it works with all fully supported platforms. You can commit a new feature that is enabled by default if it works with all such platforms, but it need not work with preview/deprecated platforms.

1.2 Preview/Deprecated Platforms

There may be additional platforms that are not fully supported, due to lacking one or more of the above criteria. Other platforms or variations may be included in the code base and still build and run, but are not verified. For example, older compiler versions or newer versions of the OS may work fine. Bug fixes and feature porting may be on a best-effort basis from committers or contributors.

2 Features

2.1 Core Features

A core feature is supported on all fully-supported platforms, where (at the time of an IoTivity release) it:

  • Is actively maintained and tested (on each fully supported platform) prior to release
  • Has a maintainer that will address issues that arise
  • If there is public API surface area, then sample code exists
  • If there is public API surface area, then API documentation exists
  • For any registry managed by IANA, only uses registered values
  • For any codepoints whose behavior is specified by some standard specification, the specification is stable (e.g., an implementation of an Internet-Draft is not stable)
  • Is compiled and enabled by default
  • Can have API additions but not breaking changes across releases

2.2 Optional Features

An optional feature has the same criteria as a Core Feature, with the following exceptions:

  • It may be disabled, or not compiled in, by default.

2.3 Experimental Features

There may be additional features that are not core or optional features, due to lacking one or more of the above criteria (e.g., not being available on all fully supported platforms). Experimental features shall not be enabled by default. They may or may not be compiled in by default.

API breaking changes can be made to experimental features.

3 Coding Guidelines

Any platform-specific functions should be in files under the Platform Abstraction Layer (PAL) subtree (currently resource\c_common\platformname\).

New code should not duplicate functionality of a POSIX-compliant function that is available. If a given posix compliant function is not available on a given platform, then there are two choices:

  1. If the POSIX-compliant function still makes sense, then a function should be written and only compiled for platforms without the native function, so that callers use the POSIX-compliant function name independent of platform. Example: snprintf doesn’t exist when using Visual Studio versions earlier than 2015; IoTivity #define’s snprintf to vs12_snprintf on that platform and compiles vs12_snprintf() only in such a case.
  2. If a platform provides more detailed functionality that is desirable but is not available in a POSIX-compliant function, then a function with a new (IoTivity-specific) name should be written that abstracts the platform. That is, the implementation should be platform-specific, and might call a POSIX-compliant function on some platforms that do not provide the more detailed functionality. Example: converting an ifindex to a sin6_scope_id usable with a link-local address varies by platform and there is no standard function to do so, so an IoTivity-specific API name should be used which has different implementations on different platforms.

The general principle is to not duplicate code and functionality in IoTivity when it exists natively on a given platform.

3.1 Use of os.path.join in SConscript files

The path separator differs across platforms ('/' vs '\'). There has been some confusion about when to use os.path.join in SConscript files. In short:

  1. Use os.path.join when constructing paths passed as arguments to a compiler, such as when constructing CPPPATH or LIBS
  2. Don't use os.path.join when constructing paths interpreted by Python itself, such as via an env.SConscript() call

3.2 Use of target_os in SConscript files

Often there are things that do not apply to all target OS's and so an SConscript file needs to put some functionality under an 'if' test against target_os. The following applies when deciding when to use an inclusion test (i.e., “==” or “in”) vs an exclusion list (i.e., “!=” or “not in”):

  1. Use exclusion when the functionality ought to apply but doesn't yet because some porting work has not yet been done.
  2. Use inclusion when the functionality is inherently specific to one or more specific OS's

3.3 Use of OS-specific ifdefs in code

#ifdefs in code outside the PAL subtree should not be platform checks, but may be feature checks (e.g., #ifdef HAVE_SNPRINTF). In most cases, however, ifdefs that vary by platform should be placed within the PAL subtree rather than in other code.

Sometimes there are ifdefs in Test code due to platform-specific issues. Ideally any #ifdef's in Test code should also be feature checks. If this is not practical, then the same rule for target_os in SConscript files applies to ifdef checks for platform-specific defines:

  1. Use exclusion when the functionality ought to apply but doesn't yet because some porting work has not yet been done or some bug currently exists.
  2. Use inclusion when the functionality is inherently specific to one or more specific OS's
platform_support.txt · Last modified: 2017/07/06 01:21 by Dave Thaler