Build A Protocol Stack With No Hardware
Build Your First Rogue Application reached registers through
rogue.interfaces.memory.Emulate, which stands in for a memory space
directly. Real systems rarely look like that. Between a host and a board sit
several protocol layers, each solving one problem: framing requests, recovering
from packet loss, multiplexing channels over one link.
This tutorial builds that stack in three stages, adding one layer at a time so you can see what each contributes. Every stage runs on one machine with no hardware and no network interface beyond loopback.
Note
No hardware required. Rogue ships software endpoints for each protocol
layer — most importantly SrpV3Emulation, which answers register requests
from an internal store. That lets you develop and test a complete transport
stack before a board exists.
Prerequisites
Finish Build Your First Rogue Application first. You should be comfortable with
Root, Device, and RemoteVariable.
Every stage below uses the same one-register device, so the only thing changing between stages is the transport underneath it:
class ScratchDevice(pr.Device):
"""One read/write register, used to prove each transport works."""
def __init__(self, **kwargs):
super().__init__(description='Register map reached over a protocol stack',
**kwargs)
self.add(pr.RemoteVariable(
name = 'ScratchPad',
description = 'Read/write test register',
offset = 0x04,
bitSize = 32,
base = pr.UInt,
mode = 'RW',
disp = '{:#010x}'))
Stage 1: SRP Without A Network
SRP (Streaming Register Protocol) is how Rogue turns register reads and
writes into stream frames. SrpV3 is the host-side master: it accepts memory
transactions from a Device and emits SRP request frames.
Something has to answer those frames. On real hardware that is firmware; here
SrpV3Emulation plays the role, servicing requests from its own memory store:
class SrpRoot(pr.Root):
"""Stage 1: SRPv3 talking to a software SRP endpoint.
``SrpV3Emulation`` answers SRP requests from an internal memory store, so
the whole register path is exercised with no transport and no hardware.
"""
def __init__(self, **kwargs):
super().__init__(description='SRP over emulation', timeout=2.0, **kwargs)
self._srp = rogue.protocols.srp.SrpV3()
self._emu = rogue.protocols.srp.SrpV3Emulation()
# Bi-directional: requests flow to the emulator, responses come back.
self._srp == self._emu
self.addInterface(self._srp)
self.addInterface(self._emu)
self.add(ScratchDevice(name='Dev', memBase=self._srp, offset=0x0))
Two details matter. The == operator makes a bi-directional connection,
which SRP needs because every request expects a response — >> would only
wire the outbound half. And memBase=self._srp points the Device at the
SRP master rather than at a memory space, so its transactions become SRP frames.
ScratchPad = 0xcafebabe
The register round-trips through a real protocol implementation. No emulated
memory space is involved this time: Emulate is gone, replaced by an
endpoint that speaks SRP.
Stage 2: Cross A Process Boundary
SRP frames are still moving inside one process. The TCP bridge changes that:
TcpServer exposes a local memory slave on a socket, and TcpClient
forwards a Device’s transactions to it.
class TcpBridgeRoot(pr.Root):
"""Stage 2: the same register path crossing a TCP socket.
``TcpServer`` fronts the memory slave and ``TcpClient`` feeds the Device.
In a real system these two halves live in different processes, or on
different machines; here both ends run locally so the example is runnable.
"""
def __init__(self, port=11000, **kwargs):
super().__init__(description='Registers over a TCP bridge',
timeout=5.0, **kwargs)
self._sim = rogue.interfaces.memory.Emulate(4, 0x1000)
# Server side: bridge -> emulated memory space.
self._server = rogue.interfaces.memory.TcpServer('127.0.0.1', port)
self._server >> self._sim
# Client side: Device -> bridge.
self._client = rogue.interfaces.memory.TcpClient('127.0.0.1', port)
for interface in (self._sim, self._server, self._client):
self.addInterface(interface)
self.add(ScratchDevice(name='Dev', memBase=self._client, offset=0x0))
Note the connection direction: self._server >> self._sim. The bridge is the
master here — it receives transactions from the network and drives them into the
memory slave. Writing << raises TypeError.
ScratchPad = 0xabcd1234
Both halves run in one process here so the example is a single file. In practice the point of this bridge is that they need not: the server can run on an embedded CPU next to the hardware while the client runs on a workstation. See Memory TCP Bridge for the two-process form.
Stage 3: The Full Transport Stack
Real links are lossy and carry more than one kind of traffic. Three layers
handle that, and UdpRssiPack bundles them:
UDP moves datagrams. Fast, and makes no delivery guarantee.
RSSI adds reliability on top — sequence numbers, acknowledgements, retransmission. This is what makes a dropped register write recoverable.
Packetizer multiplexes several logical channels over the single link, so register access and bulk data can share one connection.
Instantiating UdpRssiPack twice, once with server=True, gives a complete
link with no firmware at either end:
class NetworkRoot(pr.Root):
"""Stage 3: UDP + RSSI + packetizer + SRP, client and server on loopback.
``UdpRssiPack`` bundles the three transport layers that normally sit
between a host and a board. Running it twice -- once with ``server=True``
-- gives a complete link with no NIC or firmware involved.
"""
def __init__(self, port=8192, **kwargs):
super().__init__(description='Registers over UDP + RSSI + packetizer',
timeout=10.0, **kwargs)
# Firmware side: server transport with an SRP endpoint behind it.
self._server = pr.protocols.UdpRssiPack(
name='Server', host='127.0.0.1', port=port,
server=True, jumbo=False, wait=False, packVer=2)
self.add(self._server)
self._emu = rogue.protocols.srp.SrpV3Emulation()
self.addInterface(self._emu)
self._server.application(0) == self._emu
# Host side: client transport driving an SRP master.
self._client = pr.protocols.UdpRssiPack(
name='Client', host='127.0.0.1', port=port,
server=False, jumbo=False, wait=False, packVer=2)
self.add(self._client)
self._srp = rogue.protocols.srp.SrpV3()
self.addInterface(self._srp)
self._client.application(0) == self._srp
self.add(ScratchDevice(name='Dev', memBase=self._srp, offset=0x0))
def waitForLink(self, timeout=15.0):
"""Block until RSSI reports the link open.
RSSI performs a handshake, so the link is not usable the instant the
tree starts. Poll rather than guessing a sleep duration.
"""
deadline = time.time() + timeout
while time.time() < deadline:
if self.Client.rssiOpen.get():
return True
time.sleep(0.25)
return False
application(0) selects packetizer channel 0 and connects it to the SRP
endpoint. Other channels are free for data streams — that is the multiplexing
the packetizer provides.
RSSI performs a handshake, so the link is not usable the instant the tree starts. Poll for it rather than guessing a sleep:
def waitForLink(self, timeout=15.0):
"""Block until RSSI reports the link open.
RSSI performs a handshake, so the link is not usable the instant the
tree starts. Poll rather than guessing a sleep duration.
"""
deadline = time.time() + timeout
while time.time() < deadline:
if self.Client.rssiOpen.get():
return True
time.sleep(0.25)
return False
rssi link open: True
ScratchPad = 0xfeedface
Running All Three
python3 protocol_stack.py
--- Stage 1: SRP over emulation
ScratchPad = 0xcafebabe
--- Stage 2: registers over a TCP bridge
ScratchPad = 0xabcd1234
--- Stage 3: registers over UDP + RSSI + packetizer
rssi link open: True
ScratchPad = 0xfeedface
The Device code never changed. That is the point of the layering: a
RemoteVariable does not know or care whether its transactions end up in an
emulator, cross a socket, or traverse UDP with retransmission. Swapping the
transport is a change to the Root, not to the register map.
Choosing A Stack
Situation |
Reasonable choice |
|---|---|
Unit tests, CI, register-map development |
|
Hardware on an embedded CPU, control from a workstation |
TCP bridge, or |
Ethernet-attached FPGA |
|
Local PCIe or DMA hardware |
No protocol stack; see Hardware |
Where To Go Next
Protocols — every protocol module, with options this tutorial did not use.
SRP Protocol — SRP versions and when each applies.
RSSI Protocol — RSSI tuning: buffer counts, timeouts, retransmission.
Memory Interface — the transaction model underneath all of this.
Commands, Blocks, And Groups — continue with commands, blocks, and groups.
Hardware-Based Walkthroughs
To point this stack at a real board, replace UdpRssiPack(server=True) with
actual firmware and give the client the board’s IP address — the host-side code
is otherwise unchanged. See
Simple-PGPv4-KCU105 Example
for a complete hardware bring-up.