Jump to main content

##

# 1.4.1 How The Library Works

Abstraction Model

The common interface can easily be ported to many host Real-Time Operating Systems (RTOS) by third parties and the set of functions provides a basic level of RTOS compatibility. Where a specific RTOS does not implement a given architectural feature (e.g., events), the OSAL port for that RTOS should endeavor to imitate that feature using the constructs that are available. Although it is recognized that this may have a detrimental effect on the performance of that system it does allow MPLAB Harmony developers the broadest scope for using RTOS features in their designs.

The following diagram illustrates the OSAL Abstraction model.

Library Overview

The OSAL Library provides a defined interface such that driver and middleware developers will be able to create MPLAB Harmony code that can safely operate in a multi-threaded environment when a supported RTOS is present yet will still compile and function correctly when MPLAB Harmony is being used in a non-RTOS environment with an interrupt or non-interrupt driven application model.

At the application layer, the developer is encouraged to use the specific features of a chosen RTOS once it has been selected since this is likely to provide a more effective and rich programming environment.

The OSAL Library is deliberately designed to be a thin layer over an underlying RTOS, which presents a predefined interface to the common features used by the majority of Real-Time Operating Systems, which includes:

Library Interface Section | Description
--- | ---
Semaphore Functions | Binary and counting semaphores
Mutex Functions | Thread and resource locking mechanism
Critical Section Functions | Application and scheduler locking mechanism
Memory Allocation Functions | Memory allocation primitives or wrappers
OSAL Control Functions | OSAL initialization

One of the primary design guidelines is that a host operating system may not be present and so any operations that the OSAL presents are designed to compile out to safe default implementations if no RTOS is present. This can mean the following:

- Implementing a dummy function that mimics typical RTOS behavior

- Implementing a #define or inline function that returns a 'safe' generic return value, such as 'true' or a 'call succeeded' status

- Returning a OSAL_RESULT_NOT_IMPLEMENTED value to indicate an unsupported operation

- Throwing an OSAL_ASSERT failure to indicate a terminal error that prevents operation under specific circumstances