api.md

NeoRAM: Intelligent Multi-Port Memory System API

This document describes the API for interacting with the NeoRAM system.

Top-level Module: neoram_controller

Parameters

• ADDR_WIDTH: Width of the address bus (default: 8)
• DATA_WIDTH: Width of the data bus (fixed: 32) - Note: As of v1.3.0, standardized to 32-bit for consistency
• NUM_PORTS: Number of ports for the NeoRAM system (default: 2)

Ports

Port Name	Direction	Width	Description
clk	input	1	System clock
rst_n	input	1	Active-low reset
addr	input	NUM_PORTS x ADDR_WIDTH	Address for each port
write_data	input	NUM_PORTS x DATA_WIDTH	Write data for each port
write_en	input	NUM_PORTS	Write enable for each port
read_data	output	NUM_PORTS x DATA_WIDTH	Read data for each port
ready	output	NUM_PORTS	Indicates when port is ready for new operation (properly initialized, no 'x' states)
error	output	1	Indicates an error in read data

Usage

1. Configure the NeoRAM system by setting the appropriate parameters during instantiation.
2. Connect the clock and reset signals to your system clock and reset.
3. To write data:
   • Set the addr for the desired port
   • Place the data to be written on the write_data bus for the desired port
   • Assert the corresponding write_en signal
   • Wait for the ready signal to be asserted, indicating the write operation is complete
4. To read data:
   • Set the addr for the desired port
   • Deassert the corresponding write_en signal
   • Wait for the ready signal to be asserted
   • Retrieve the data from the read_data port
5. Always check the error signal after each read operation to ensure data integrity

Error Handling

The NeoRAM system employs advanced error detection and correction mechanisms:

• If a single-bit error is detected during a read operation (indicated by the error signal), the system will automatically correct it and return the corrected data.
• In case of multi-bit (uncorrectable) errors, the system will return the best-effort corrected data, but the error signal will remain asserted.
• It is recommended to implement error logging and handling in your higher-level system to manage persistent or frequent errors.

Power Management

The NeoRAM system includes sophisticated power management features:

• The system automatically enters a low-power state when idle to conserve energy.
• No specific action is required from the user to enable this feature.
• For advanced power management, consider monitoring the system's power state and adjusting your access patterns accordingly.

Performance Considerations

• Round-Robin Arbitration: The system uses fair round-robin scheduling ensuring equal access opportunity for all ports
• Concurrent Access: Multi-port design allows simultaneous operations with proper conflict resolution
• Ready Signal Management: All ready signals are properly initialized and managed, eliminating undefined states
• Mode Selection: Choose between ECC mode (with error correction) and bypass mode (direct access) based on reliability vs. performance requirements
• Data Width: Optimized 32-bit data path provides consistent performance across all operations

Recent API Improvements (v1.3.0)

• Signal Reliability: All control signals now properly initialized, eliminating 'x' states
• Arbitration Fairness: Round-robin arbitration ensures no port starvation
• Data Consistency: Standardized 32-bit data width throughout the system
• Mode Support: Enhanced support for both ECC and bypass operational modes

---