eclipse-iceoryx / eclipse-iceoryx/iceoryx

Simplify platform abstraction

Open
#2,107 1 comment 0 reactions 0 assignees View on GitHub
refactoring
Dominant language
C++
Stars
2.2k
Forks
492
Avg merge
18h 57m
Merged PRs (30d)
1

Description

## Brief feature description

Currently one needs to provide all headers for all platform, even if they are simply forwarding to the system header. This can be simplified by the C++17 feature `__has_include`

## Detailed information

The platform would provide a generic implementation of the header. If the specific platform does not provide a custoom header, the generic one would be used.

This is an example for `iceoryx_platform/include/iox/platform/semaphor.hpp`
```cpp
#ifndef IOX_PLATFORM_SEMAPHORE_HPP
#define IOX_PLATFORM_SEMAPHORE_HPP

#if __has_include("iox/platform/override/semaphore.hpp")
#include "iox/platform/override/semaphore.hpp"
#else
#include "iox/platform/generic/semaphore.hpp"
#endif // __has_include

#endif // IOX_PLATFORM_SEMAPHORE_HPP
```

The generic implementation in `iceoryx_platform/generic/include/iox/platform/generic/semaphore.hpp` would look like this
```cpp
#ifndef IOX_PLATFORM_GENERIC_SEMAPHORE_HPP
#define IOX_PLATFORM_GENERIC_SEMAPHORE_HPP

#include
#include
#include

using iox_sem_t = sem_t;

#define IOX_SEM_FAILED SEM_FAILED
constexpr uint32_t IOX_SEM_VALUE_MAX = SEM_VALUE_MAX;

#ifndef IOX_PLATFORM_OVERRIDE_SEM_GETVALUE
inline int iox_sem_getvalue(iox_sem_t* sem, int* sval)
{
return sem_getvalue(sem, sval);
}
#endif

#ifndef IOX_PLATFORM_OVERRIDE_SEM_POST
inline int iox_sem_post(iox_sem_t* sem)
{
return sem_post(sem);
}
#endif

// ...

#ifndef IOX_PLATFORM_OVERRIDE_SEM_UNLINK
inline int iox_sem_unlink(const char* name)
{
return sem_unlink(name);
}
#endif

#endif // IOX_PLATFORM_GENERIC_SEMAPHORE_HPP
```

For Linux, Unix, QNX and potentially other POSIX operating systems it would work out of the box.

FreeRTOS would specify a `iceoryx_platform/freertos/include/iox/platform/override/semaphore.hpp` header and partially reuse the generic header
```cpp
#ifndef IOX_PLATFORM_FREERTOS_SEMAPHORE_HPP
#define IOX_PLATFORM_FREERTOS_SEMAPHORE_HPP

#define SEM_FAILED nullptr
#define IOX_PLATFORM_OVERRIDE_SEM_UNLINK

#include "iox/platform/generic/semaphore.hpp"

inline int iox_sem_unlink(const char*)
{
// Named semaphores are not supported in FreeRTOS+POSIX
configASSERT(false);
return 0;
}

#endif // IOX_PLATFORM_FREERTOS_SEMAPHORE_HPP
```

Windows (and macOS) would have a full re-implementation in `iceoryx_platform/windows/iox/platform/override/semaphore.hpp`
```cpp
#ifndef IOX_PLATFORM_WINDOWS_SEMAPHORE_HPP
#define IOX_PLATFORM_WINDOWS_SEMAPHORE_HPP

// fully custom implementation without using the generic header

#endif // IOX_PLATFORM_WINDOWS_SEMAPHORE_HPP
```

To use an out-of-tree platform one just needs to specify the path to `iceoryx_platform/os/` like it is nowadays but it would be much simpler to add an maintain a platform which is mostly compatible with the generic platform.

## Tasks

- [ ] Design document
- [ ] Implementation
- [ ] Update `website/advanced/custom-iceoryx-platform.md`

Contributor guide

Open the contributing guide

Research direction

Start with iceoryx_platform/include/iox/platform/semaphor.hpp and iceoryx_platform/generic/include/iox/platform/generic/semaphore.hpp to understand the proposed generic and override structure. Review the platform-specific headers and website/advanced/custom-iceoryx-platform.md before defining the design. Done means the abstraction is implemented across the relevant platforms and the custom-platform documentation is updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.