eclipse-iceoryx / eclipse-iceoryx/iceoryx
Simplify platform abstraction
- 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
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