Documentation

Mistake on this page? Email us
Docs › Porting devices › Porting Device Management Client

Porting Pelion Device Management Client

This section begins by giving an overview of the tasks needed to port the Platform Abstraction Layer (PAL) platform APIs to a new target platform. It explains the PAL modules and layers, as well as their porting order. It then discusses the basic configurations for PAL porting and gives instructions for porting the following PAL modules: the RTOS, networking, Crypto, FileSystem and TLS/DTLS modules. Each instruction set explains the module scope, prerequisites for the porting stage, and the porting result, while providing porting notes and reference implementations.

Internally, PAL consists of two layers:

  • The Service API layer provides the PAL APIs and target-independent APIs for Device Management Client code. These APIs are identical for all targets and operating systems, and you should not modify them.
  • The Platform API layer provides standard baseline target required functionality. To run Device Management Client on your target, implement the required APIs in this porting layer by using the APIs and functionality of your own target. The implementation may be different for each target operating system or library; we provide reference implementations of the PAL layer for several operating systems, including Mbed OS and Linux. You can view the Platform API layer header files and the reference implementations (found in the Source/Port/Reference-Impl folder).

PAL structure

PAL modules and their porting order

This list defines the recommended order for porting PAL modules, to ensure the correct dependency relation:

  1. RTOS.
  2. Networking.
  3. Entropy.
  4. Crypto.
  5. RoT.
  6. Secure Storage.
  7. FileSystem.
  8. TLS/DTLS.
  9. Update.

Porting in this order allows you to test the already-ported modules using the PAL test suite running only the applicable tests. For example, once you implement the RTOS porting module, you can test it using the RTOS tests. Once you also implement the network module, you can test it by running both the RTOS and network tests. See the testing section for more information.

Secure storage dependencies

To port Device Management Client successfully, you need secure storage. Device Management Client offers secure storage for targets without their own. See Secure storage.

PAL configurations

PAL includes the following configuration files:

  • A general (OS independent) configuration header file:
  • OS or library specific configuration files for the reference implementations:
    • mbedOS_default.h: default Mbed OS configuration for PAL.
    • Linux_default.h: default Linux configuration for PAL.
    • mbedTLSConfig_mbedOS.h: default Mbed OS configuration for the Mbed TLS library.
    • mbedTLSConfig_mbedOS_SW_TRNG.h: default Mbed OS (version 5.10 or older) configuration of the Mbed TLS library for targets onto which entropy is injected in the factory (targets that do not use a TRNG).
    • mbedTLSConfig_mbedOS_SW_TRNG_PSA.h: default Mbed OS (version 5.11 or newer) configuration of the Mbed TLS library for targets onto which entropy is injected in the factory (targets that do not use a TRNG).
    • mbedTLSConfig_Linux.h: default Linux configuration for the Mbed TLS library.

These files contain the default values for the PAL configuration options at the service layer. They also include defines, which you can configure when porting, either in the file itself or with compilation flags. These configurations have a direct effect on the code's behavior: some of them disable or enable a feature, while others define the number of threads that can be created and used. Together, they provide robust implementation for different targets.

When porting, we recommend you start with the default values for your target or the closest reference implementation. Make changes as needed to match the abilities and requirements of your target.

Warning: Modify parameter default values only when necessary and with extra caution.

Warning: Do not rename or delete any of the definitions.

PAL errors

Note: The pal_errors.h file should not be included directly. It will be included when you include pal.h.

The PAL errors file pal_errors.h lists all the different error codes that you might encounter when calling PAL functions. The errors are divided into modules that match the PAL modules, and all the error values are negative.

In your target porting code, make sure that the Platform API layer translates errors into the proper PAL error. When an error is returned by an implementation of the PAL Platform API, please make sure to map it to the appropriate PAL error code based on the cause of the error, and return the mapped error.

The reference ports for Mbed OS and Linux can serve as a guide for translating the error codes.

For more information, see the pal_errors.h file.

Testing your port

When you have completed all the implementation, you need to test your port. You may find it easier to test after implementing each module, rather than all at once.

Next