Svc::BufferManager Component

Svc::BufferManager

1 Introduction

BufferManager is a passive ISF component. It allocates and deallocates variable-sized buffers from a fixed-size store.

2 Requirements

Requirement	Description	Rationale	Verification Method
ISF-BM-001	BufferManager shall maintain a fixed-size store and shall provide a callee port on which another component may request and receive variable-size buffers allocated from the store.	This requirement provides variable-sized buffers that may be passed between components by reference. Such buffers are useful for transferring large data items of varying length, such as file packets and images. For such data items, a fixed-size buffer such as Fw::ComBuffer is not practical.	Test
ISF-BM-002	BufferManager shall provide an input port on which a component that has been given a buffer may return the buffer for deallocation.	Deallocation prevents the fixed-size store from becoming exhausted. Note that the component returning the buffer is generally the receiver, while the component requesting the buffer is generally the sender. See the sequence diagram below.	Test

3 Design

3.1 Assumptions

The design of BufferManager assumes the following:

1. BufferManager has some maximum number of outstanding allocations, set at component initialization, that is never exceeded.
2. The store maintained by BufferManager has a fixed size, set at component initialization. This fixed size is never exceeded by the outstanding allocations.
3. Buffers are freed in the same order that they were allocated.

3.2 Block Description Diagram (BDD)

3.3 Ports

3.3.1 Role Ports

Name	Type	Role
timeCaller	Fw::Time	TimeGet
tlmOut	Fw::Tlm	Telemetry
eventOut	Fw::LogEvent	LogEvent

3.3.2 Component-Specific Ports

Name	Type	Kind	Purpose
bufferSendIn	Fw::BufferSend	guarded input	Receives buffers for deallocation
bufferGetCallee	Fw::BufferGet	guarded input (callee)	Receives requests for allocated buffers and returns the buffers

3.4 Constants

BufferManager maintains the following constants, initialized when the component is instantiated:

• storeSize: The size of the store used to allocate buffers.
• allocationQueueDepth: The maximum number of buffers that may be allocated at any time.

3.5 State

BufferManager maintains the following state:

• store: A fixed allocation of storeSize bytes.
• allocationQueue: A doubly-ended queue of up to allocationQueueDepth entries that maintains, for each outstanding allocation, an entry E = (I, s) consisting of a unique identifier I and a size s.
• freeIndex: An index pointing to the first free byte of the store. The initial value is zero.

The identifiers I are 32-bit unsigned integers.

3.6 Port Behavior

3.6.1 bufferGetCallee

When BufferManager receives a request for a buffer of size s on bufferGetCallee, it carries out the following steps:

1. If freeIndex + s > storeSize, then issue a StoreSizeExceeded event and return an invalid buffer.

2. Otherwise

   a. Assert that the size s' of allocationQueue is less than or equal to allocationQueueDepth.

   b. If *s' = allocationQueueDepth*, then issue an *AllocationQueueFull*
   

   event and return an invalid buffer.

   c. Otherwise
   
     1. Create a fresh identifier *I*.
   
     2. Compute the pointer *P* that points to byte [*freeIndex*](#freeIndex) of [*store*](#store).
   
     3. Create an allocation queue entry *E = (I, s)*.
   
     4. Push *E* onto the front of [*allocationQueue*](#allocationQueue).
   
     5. Increase [*freeIndex*](#freeIndex) by *s*.
   
     6. Create and return a valid
   

   Fw::Buffer with managerID equal to the instance number of this component, bufferID equal to I, data equal to P, and size equal to s.

3.6.2 bufferSendIn

When BufferManager receives notification of a free buffer on bufferSendIn, it carries out the following steps:

1. If allocationQueue is empty, then issue an AllocationQueueEmpty event.

2. Otherwise

   a. Pull an entry *(I, s)* off the back of the queue.

   b. If I matches the identifier provided in the free notification, then decrease freeIndex by s.

   c. Otherwise issue an *IDMismatch* event.
   

3.7 Sequence Diagram

The following sequence diagram shows the procedure for sending a buffer from one component to another:

1. The sending component requests a buffer B on the bufferGetCallee port of BufferManager.
2. The sending component fills B with data and sends it to the receiving component.
3. The receiving component uses the data in B. When done, it sends B back to the bufferSendIn port of BufferManager for deallocation.

4 Dictionary

Dictionaries: HTML MD

5 Checklists

Document	Link
Design	Link
Code	Link
Unit Test	Link

6 Unit Testing

TODO