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

SrpV3 + SrpV3Emulation

Hardware on an embedded CPU, control from a workstation

TCP bridge, or UdpRssiPack if the link is lossy

Ethernet-attached FPGA

UdpRssiPack — the usual production choice

Local PCIe or DMA hardware

No protocol stack; see Hardware

Where To Go Next

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.