Software Library Documentation
Overview
This documentation provides an overview and usage guide for the software library designed to manage peripherals and handle ELF file parsing for embedded system simulations. The library is structured to support easy integration and extension, with components dedicated to different aspects of system emulation, such as memory management, peripheral interfacing, and file handling.
Features
Peripheral Management: Manages a variety of simulated peripherals.
Memory Simulation: Simulates different memory scenarios and behaviors.
File Parsing: Supports reading and interpreting ELF files.
Getting Started
Prerequisites
A modern C++ compiler supporting C++17 or later.
Basic understanding of computer architecture and peripheral management.
Familiarity with the PicoNut project and its components.
Library Components
The library is divided into several key components, each handling a specific aspect of system simulation. Detailed documentation for each component is provided in the following sections.
c_soft_peripheral
The c_soft_peripheral
class is the base class for all peripherals in the software library. It provides a common interface for peripheral operations and is designed to be extended for specific peripheral implementations.
Usage Example
class my_peripheral : public c_soft_peripheral {
public:
my_peripheral(uint32_t base_address) : c_soft_peripheral(base_address) {}
uint8_t read(uint32_t address) override {
// Read from the peripheral
}
void write(uint32_t address, uint8_t data) override {
// Write to the peripheral
}
};
Refer to existing peripherals such as c_soft_memory
and c_soft_uart
for further examples.
c_soft_memory
The c_soft_memory
class simulates memory within the software library. It supports basic read and write operations to access memory locations.
Usage Example
c_soft_memory memory(1024, 0x40000000);
memory.write(0x40000000, 0x12);
uint8_t data = memory.read(0x40000000);
The constructor takes the memory size and base address as parameters. It also provides methods to dump the memory contents to a file.
c_soft_uart
The c_soft_uart
class simulates a UART interface. It allows data transmission and reception over a simulated UART connection and supports setting the baud rate, checking for data availability, and reading/writing data.
Usage Example
c_soft_uart uart(0x40001000);
uart.set_baud_rate(9600);
uart.write(0x40001000, 'A');
uint8_t data = uart.read(0x40001000);
Peripheral Interface
The c_soft_peripheral_container
class manages the peripherals in a simulation-only environment. It allows adding, interacting with, and managing peripherals, typically used within a m_soft_memu
or similar module.
Class: c_soft_peripheral_container
Public Methods
void add_peripheral(uint64_t base_address, std::unique_ptr<c_soft_peripheral> peripheral)
Description: Adds a new peripheral to the system at the specified base address.
Parameters:
base_address
(uint64_t): The base address of the peripheral.peripheral
(std::unique_ptr<c_soft_peripheral>): A unique pointer to the peripheral.
Usage Example:
auto my_peripheral = std::make_unique<my_peripheral>();
peripheral_interface.add_peripheral(0x1000, std::move(my_peripheral));
c_soft_peripheral* find_peripheral(uint64_t address)
Description: Finds a peripheral by its memory address.
Parameters:
address
(uint64_t): The memory address to search for.
Returns:
A pointer to the peripheral if found, otherwise
nullptr
.
Usage Example:
c_soft_peripheral* peripheral = peripheral_interface.find_peripheral(0x1000);
if (peripheral != nullptr) {
// Peripheral found
}
void write_peripheral(uint64_t address, uint32_t data, uint8_t bsel)
Description: Writes data to a peripheral at the specified address, using the byte-select value.
Parameters:
address
(uint64_t): The peripheral address.data
(uint32_t): Data to write.bsel
(uint8_t): Byte-select value.
Usage Example:
peripheral_interface.write_peripheral(0x1000, 0xFF00FF00, 0x0F);
uint32_t read_peripheral(uint64_t address, uint8_t bsel)
Description: Reads data from a peripheral at the specified address, using the byte-select value.
Parameters:
address
(uint64_t): The address of the peripheral.bsel
(uint8_t): Byte-select value.
Returns:
The data read from the peripheral.
Usage Example:
uint32_t data = peripheral_interface.read_peripheral(0x1000, 0x01);
ELF Reader
The elf_reader
class provides methods for reading and parsing ELF files in the software library. It reads the contents of an ELF file, extracts important information such as entry points and program headers, and supports symbol parsing for debugging purposes.
Example Usage
elf_reader elf("my_program.elf");
elf.initialize_from_file();
char* memory = elf.get_memory();
The ELF reader loads ELF files into memory and provides access to symbols for debugging and memory dumping.
Troubleshooting
Common issues and solutions:
Peripheral not found: Ensure the peripheral’s base address is correctly added to the system.
Is also intended to show up whenever a new peripheral is added to declare that there is not already a existing one at that address range.
Invalid memory access: Check that the memory address falls within the bounds of the initialized memory.