User Tools

Site Tools


platform_support

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. You can use os.path.join when constructing paths interpreted by Python itself, these will then be correct for the system it is running on. Especially necessary if Python is being asked to check for existence of a resource before doing something (os.path.isfile, os.path.isdir, os.path.exists).
  2. For paths that will be interpreted by SCons, there is no need to use os.path.join as SCons understands its own context and will do the right thing. An example is adding to CPPPATH, which is always interpreted in the context of the directory of the SConscript doing the work (unless an explicit change directory has taken place). It is fine to use POSIX-style paths here.
  3. For paths that will be passed directly to an external tool, use os.path.join. An example of this case is resource/csdk/security/unittest/SConscript, which builds a path to be passed to the compiler inside a define (SECURITY_BUILD_UNITTEST_DIR).

3.1.1 Use of relative and absolute paths

Early iterations of the build scripts used copies of paths saved in the construction environment (SRC_DIR and BUILD_DIR) to help build paths to things. This is not wrong, but led to a number of places where building was accidentally done in the source directory instead of the variant directory, which in turn causes problems for concurrent builds with different parameters. The normal approach should be to use a relative path first, if that gets to looking compilacted, a topdir-relative path (starts with #) can be used. Both will be adjusted for the variant directory in effect. If you REALLY need to have the source directory, like for certain checks to be done by Python code, it can be obtained this way: #/some/path.srcdir().path (or .abspath, but avoid using abspath unless it is absolutely needed).

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. Try to avoid long inclusion / exclusion lists, that usually means the “special case” was not so special, and the target check possibly should be inverted. With over 200 build scripts, it becomes a pain to find and modify all the places if something changes like a new platform or state change in existing platform.

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/10/30 18:50 by Mats Wichmann