Buffers & Memory Model

1. Overview

OpenSRBuffers.h

#pragma once
#include "OpenSROutSimData.h"
#include "OpenSRInSimData.h"
#include "OpenSRBlobData.h"

// Buffers visible to IN plugins
typedef struct OpenSRBuffersIN {
    OutSimData* outSimDataIN;   // plugin writes telemetry here
    BlobData* blobData;         // plugin writes custom data struct (optional)
} OpenSRBuffersIN;

// Buffers visible to OUT plugins
typedef struct OpenSRBuffersOUT {
    InSimData* inSimData;            // plugin writes input signals
    OutSimData* outSimDataOUT; // plugin reads telemetry
    BlobData* blobData;              // plugin reads custom data struct (optional)
} OpenSRBuffersOUT;

OpenSR uses a shared buffer model to exchange data between:

• IN plugins (telemetry producers)
• OUT plugins (consumers + input producers)
• Host (validator and dispatcher)

The system is designed to be:

• zero-copy
• lock-free in practice
• safe under continuous access

2. Memory Ownership

Rule:

All buffers are owned and managed by the host.

Plugins:

• must NOT allocate
• must NOT free
• must NOT reallocate

Host guarantees:

• Buffers remain valid for the entire lifetime of the plugin
• No pointer invalidation during runtime

3. Buffer Access Model

IN plugins receive:

OpenSRBuffersIN
- OutSimData*   // write telemetry
- BlobData*     // write custom data

OUT plugins receive:

OpenSRBuffersOUT
- InSimData*    // write inputs
- OutSimData*   // read telemetry
- BlobData*     // read custom data

4. Pointer Lifetime & Caching

Allowed:

Plugins can safely cache buffer pointers:

m_pBufferIn = static_cast<OpenSRBuffersIN*>(inBuf);

Guarantee:

• Cached pointers remain valid until:
  • Stop() / Shutdown()
  • plugin unload

5. Access Safety Rules

General rule:

Buffers are designed for continuous, unsynchronized access.

IN plugins:

• Write-only on:
  • OutSimData
  • BlobData

OUT plugins:

• Read:
  • OutSimData
  • BlobData
• Write:
  • InSimData

Thread safety model:

• No explicit locking required
• Safe to:
  • read anytime
  • write anytime (within role boundaries)

Important:

Each buffer is logically dedicated:

• no concurrent write conflicts between plugins

6. Runtime Safety Expectations

Plugins must still ensure:

• No access after:
  • Stop()
  • Shutdown()
• Proper thread termination before:
  • releasing references

Typical safety pattern:

while (!m_stopRequested) {
    if (!IsProcessAlive() || !m_pContext->isAppRunning) {
        break;
    }

    // safe buffer access here
}

7. BlobData (Custom Data Channel)

Purpose:

Provide a generic extension channel for:

• custom telemetry
• third-party integrations
• advanced device data

Structure:

OpenSRBlobData.h

#include "OpenSROutSimData.h"
#include <cstdint>

#pragma pack(push, 1)

typedef struct Blob_t {
	// Extension blob
    size_t  blobSize /* = 0 */;     // effective buffer size in bytes (optional)
	uint8_t blob[32768];            // opaque binary data buffer for custom usage (third party struct)
} Blob_t;

typedef struct BlobData {
	PacketHeader_t	mPacketHeader;	// size 32 bytes
	Blob_t			mBlobData;		// size 32K
} BlobData;

/*
--------------
PacketHeader 32
-------------
BlobData 32808
*/

#pragma pack(pop)

Key properties:

• Total size ≈ 32 KB payload
• Fixed-size buffer
• Binary opaque data (no imposed format)

Usage Rules:

IN plugins:

• Can write:
  • custom structured data into blob
  • set blobSize accordingly

OUT plugins:

• Can read:
  • interpret data based on agreed format

Constraints:

• No dynamic allocation inside buffer
• No resizing
• Must respect: blobSize <= 32768

8. PacketHeader Integration

Each BlobData includes:

PacketHeader_t mPacketHeader; // see OpenSROutSimData.h

This ensures:

• consistency with telemetry packets
• synchronization with frame submission

9. Design Philosophy

• Host owns memory → plugins stay simple
• Fixed buffers → no fragmentation
• Direct access → maximum performance
• Role separation → no write conflicts

10. Common Mistakes

Plugins must avoid:

• Writing outside assigned buffers
• Assuming ownership of memory
• Accessing buffers after shutdown
• Ignoring blobSize
• Using blob without defining a format contract (structure)

11. Usage Model

• Buffers = shared memory owned by host
• IN plugins = writers (telemetry)
• OUT plugins = readers + input writers
• Blob = custom channel