Extra FD Circular Buffer

Example Path: examples/FileDescriptor/ExtraFdCircularBuffer

NetBurner Extra File Descriptor Circular Buffer

Overview

This application demonstrates how to implement a custom I/O device using NetBurner's Extra File Descriptor system. The example creates a circular buffer that can be accessed using standard file operations like read() and write(), making it behave like any other file descriptor in the system. The Extra File Descriptors are defined in the 'iointernal.h' header file.

Note

If you have an I/O device and wish to use interrupts, after adding the appropriate interrupt code that is specific to your device, you would use USER_ENTER_CRITICAL and USER_EXIT_CRITICAL to protect the internal data structures.

Key Features

• Custom I/O Device: Implements a circular buffer as a file descriptor
• Thread-Safe Operations: Uses critical sections for multi-task safety
• Overwrite Mode: Configurable buffer overflow handling
• Terminator-Based Flushing: Intelligent buffer management for line-based data
• Standard File Operations: Compatible with read(), write(), and fdprintf()

Architecture

Core Components

1. CircularBufferObject: Main data structure containing:
   • Read/write indices for buffer management
   • Data buffer pointer and size
   • Critical section for thread safety
   • Overwrite configuration settings
2. I/O Functions:
   • CircularBufferRead(): Reads data from the circular buffer
   • CircularBufferWrite(): Writes data to the circular buffer
   • CircularBufferClose(): Cleanup when closing the file descriptor
3. Utility Functions:
   • CircularBufferInit(): Initializes the buffer and returns a file descriptor
   • CircularBufferFlushBytes(): Flushes data up to a terminator byte
   • CircularBufferRawPrint(): Debug function to display raw buffer contents

Buffer Management

The circular buffer uses two indices:

• Read Index: Points to the next byte to be read

• Write Index: Points to the next position for writing

  Buffer States**:

• Empty: readIndex == writeIndex
• Full: (writeIndex + 1) % bufferSize == readIndex

Configuration Options

Overwrite Mode

• Enabled: When buffer is full, old data is automatically overwritten
• Disabled: Write operations fail when buffer is full

Terminator Byte

When overwrite mode is enabled, you can specify a terminator byte (e.g., '
' for line-based data). When the buffer becomes full, data is flushed up to this terminator instead of byte-by-byte, making it ideal for line-oriented protocols.

Usage Example

// Initialize buffer
const uint32_t bufferSize = 256;
char dataBuffer[bufferSize];
CircularBufferObject circBuffer;
 
// Create file descriptor with overwrite enabled and newline terminator
int fd = CircularBufferInit(&circBuffer, dataBuffer, bufferSize, true, '\n');
 
// Write data
fdprintf(fd, "Hello World\n");
 
// Read data
char readBuffer[100];
int bytesRead = read(fd, readBuffer, sizeof(readBuffer));

Test Functions

The application includes two test functions:

TestBufferFull()

Demonstrates buffer overflow behavior by writing more data than the buffer can hold, then reading it back to show how the system handles full buffer conditions.

TestBufferLineMode()

Tests the terminator-based flushing feature by sending line-terminated messages and displaying the raw buffer contents to show how data is managed.

File Descriptor Status Management

The implementation uses NetBurner's file descriptor status functions:

• SetDataAvail(fd) / ClrDataAvail(fd): Indicates data ready for reading
• SetWriteAvail(fd) / ClrWriteAvail(fd): Indicates space available for writing
• SetHaveError(fd) / ClrHaveError(fd): Error status management

These functions are interrupt-safe and integrate with NetBurner's I/O system.

Thread Safety

All buffer operations are protected by critical sections using NetBurner's OS_CRIT class, ensuring safe operation in multi-task environments.

Debug Features

• Compile-time debug flag (circBufDebug) for detailed operation logging
• Raw buffer print function for visualizing buffer contents
• Detailed status reporting during read/write operations

Configuration

Key configuration parameters in main.cpp:

• dataBufferSize: Buffer size (set to 10 for testing, increase for production)
• enableOverwrite: Set to true for automatic overwrite mode
• overwriteTermByte: Terminator character for intelligent flushing

Integration Notes

This example demonstrates the NetBurner Extra File Descriptor system defined in iointernal.h. The same pattern can be used to create custom I/O devices for:

• Serial communication protocols
• Custom data logging
• Inter-task communication buffers
• Hardware device abstraction

Files

• main.cpp: Main application and test functions
• ExtraFdCircBuffer.h: Header file with structure definitions
• ExtraFdCircBuffer.cpp: Implementation of circular buffer operations