Document OSAL Integration

[LeStarch]

F´ Version
Affected Component

---

Feature Description

Document how to add an OSAL layer, and select it in CMake.

[rithvikrajraapeti]

ok fine

[rithvikrajraapeti]

F´ Version
Affected Component

---

Feature Description

Document how to add an OSAL layer, and select it in CMake.

Already saved a file called osal documentation

[thomas-bc]

@rithvikrajraapeti Thanks for contributing!
I believe we will want this specific issue to be handled by our team. If you would like to contribute more to F´ you can search for issues that have been tagged with the Help Wanted or Easy first issue labels 🚀

[matt392code]

Adding and Configuring OSAL Layers in F Prime

Overview

This guide explains how to:

1. Create a new OSAL implementation
2. Configure it in CMake
3. Select between different OSAL implementations

Directory Structure

Add your OSAL implementation in the Os directory:

fprime/Os/
├── MyNewOsal/
│   ├── CMakeLists.txt
│   ├── File.cpp
│   ├── Task.cpp
│   ├── Queue.cpp
│   ├── Mutex.cpp
│   └── ...
├── Linux/
├── FreeRTOS/
└── CMakeLists.txt

1. Implementing OSAL Files

Task Implementation Example (Task.cpp)

#include <Os/Task.hpp>

namespace Os {

    Task::Task() :
        m_handle(0),
        m_identifier(0),
        m_started(false) {
    }

    Task::TaskStatus Task::start(const Fw::StringBase &name,
                                NATIVE_INT_TYPE identifier,
                                NATIVE_INT_TYPE priority,
                                NATIVE_INT_TYPE stackSize,
                                taskRoutine routine,
                                void* arg,
                                NATIVE_INT_TYPE cpuAffinity) {
        // Your RTOS-specific implementation here
        return TASK_OK;
    }

    Task::TaskStatus Task::delay(NATIVE_UINT_TYPE milliseconds) {
        // Your RTOS-specific delay implementation
        return TASK_OK;
    }

    // Implement other required methods...
}

Queue Implementation Example (Queue.cpp)

#include <Os/Queue.hpp>

namespace Os {

    Queue::Queue() :
        m_handle(nullptr),
        m_size(0),
        m_maxMsgSize(0) {
    }

    Queue::QueueStatus Queue::create(const Fw::StringBase &name,
                                   NATIVE_INT_TYPE depth,
                                   NATIVE_INT_TYPE msgSize) {
        // Your RTOS-specific queue creation
        return QUEUE_OK;
    }

    // Implement other required methods...
}

2. CMake Configuration

OSAL Directory CMakeLists.txt

# MyNewOsal/CMakeLists.txt

# Create library for your OSAL implementation
add_fprime_library(
    MyNewOsal
    SOURCES
        Task.cpp
        Queue.cpp
        Mutex.cpp
        File.cpp
    LINK_LIBRARIES
        Fw_Types
)

Main Os CMakeLists.txt

# Os/CMakeLists.txt

# Add OSAL selection option
set(FPRIME_OSAL "Linux" CACHE STRING "Select OSAL implementation")
set_property(CACHE FPRIME_OSAL PROPERTY STRINGS "Linux" "FreeRTOS" "MyNewOsal")

# Configure based on selection
if(${FPRIME_OSAL} STREQUAL "MyNewOsal")
    add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/MyNewOsal")
    set(OSAL_SELECTED_BUILD TRUE)
endif()

3. Required OSAL Implementations

Your OSAL must implement these core classes:

1. Os::Task - Thread/Task Management
2. Os::Queue - Message Queues
3. Os::Mutex - Mutual Exclusion
4. Os::File - File Operations
5. Os::Timer - System Timing
6. Os::InterruptLock - Interrupt Management

4. Selecting Your OSAL

Command Line

fprime-util generate -DFPRIME_OSAL=MyNewOsal

CMake Configuration

# In your project's CMakeLists.txt
set(FPRIME_OSAL "MyNewOsal" CACHE STRING "Use custom OSAL")

5. OSAL Interface Requirements

Task Interface

class Task {
public:
    virtual TaskStatus start(
        const Fw::StringBase &name,
        NATIVE_INT_TYPE identifier,
        NATIVE_INT_TYPE priority,
        NATIVE_INT_TYPE stackSize,
        taskRoutine routine,
        void* arg,
        NATIVE_INT_TYPE cpuAffinity = -1
    ) = 0;

    virtual TaskStatus delay(NATIVE_UINT_TYPE milliseconds) = 0;
    // Other required methods...
};

Queue Interface

class Queue {
public:
    virtual QueueStatus create(
        const Fw::StringBase &name,
        NATIVE_INT_TYPE depth,
        NATIVE_INT_TYPE msgSize
    ) = 0;

    virtual QueueStatus send(
        const U8* buffer,
        NATIVE_INT_TYPE size,
        NATIVE_INT_TYPE timeout
    ) = 0;

    // Other required methods...
};

6. Testing Your OSAL

Create unit tests in Os/test:

// MyNewOsalTest.cpp
#include <gtest/gtest.h>
#include <Os/Task.hpp>

TEST(MyNewOsal, TaskCreation) {
    Os::Task task;
    
    Os::Task::TaskStatus status = task.start(
        "TestTask",
        0,
        100,
        1024,
        someTaskRoutine,
        nullptr
    );
    
    ASSERT_EQ(status, Os::Task::TASK_OK);
}

7. Best Practices

1. Error Handling

   • Implement robust error checking
   • Use appropriate status returns
   • Log critical errors

2. Resource Management

   • Clean up resources in destructors
   • Handle out-of-memory conditions
   • Implement proper threading cleanup

3. Configuration

   • Make thread priorities configurable
   • Allow stack size customization
   • Support different queue depths

4. Testing

   • Test all OSAL interfaces
   • Verify resource cleanup
   • Test error conditions

8. Example Platform Configuration

# platform/MyPlatform/CMakeLists.txt

set(FPRIME_OSAL "MyNewOsal" CACHE STRING "Platform OSAL selection")
set(FPRIME_OSAL_DEFINES
    -DFPRIME_CUSTOM_OS_DEFINES
    -DSTACK_SIZE=4096
    -DMAX_PRIORITY=255
)

add_definitions(${FPRIME_OSAL_DEFINES})

9. Common Issues and Solutions

1. Thread Priority Mapping

   • Map F Prime priorities to OS priorities
   • Handle priority inheritance
   • Consider real-time requirements

2. Resource Limits

   • Check stack size limits
   • Monitor queue depths
   • Handle memory constraints

3. Timing Issues

   • Implement precise delays
   • Handle timer resolution
   • Consider clock synchronization

4. Platform Specifics

   • Handle endianness
   • Consider alignment requirements
   • Support platform debug features