pw_router

Pigweed AI summary: The pw_router module provides classes for routing packets over network links. It includes common router interfaces such as PacketParser and Egress. The PacketParser interface is used to extract relevant packet data, while the Egress interface is used for sending packet data over a network link. The module also includes a StaticRouter class, which is a router with a static table of address to egress mappings. This class is suitable for basic networks with persistent links. The module can be enabled for Zephyr by adding

The pw_router module provides transport-agnostic classes for routing packets over network links.

Common router interfaces

Pigweed AI summary: The paragraph discusses two common router interfaces: PacketParser and Egress. The PacketParser interface is used by routers to extract relevant packet data, such as the destination. It is defined in pw_router/packet_parser.h and must be implemented for the packet framing format used by the network. The Egress interface is a virtual interface for sending packet data over a network link. Egress implementations provide a SendPacket function to transmit the raw packet data. Egresses are invoked with the PacketParser used to

PacketParser

Pigweed AI summary: The PacketParser module in the pw_router-packet_parser provides a common interface for routers to extract important packet data, such as the destination, from arbitrary packet formats. This interface, defined in pw_router/packet_parser.h, needs to be implemented for the specific packet framing format used by the network.

To work with arbitrary packet formats, routers require a common interface for extracting relevant packet data, such as the destination. This interface is pw::router::PacketParser, defined in pw_router/packet_parser.h, which must be implemented for the packet framing format used by the network.

Egress

Pigweed AI summary: The Egress class is a virtual interface used for sending packet data over a network link. It has a single function called SendPacket, which transmits the raw packet data. Egresses can extract additional information from each packet using the PacketParser, allowing them to make transmission decisions based on that information. For example, egresses can drop certain packets under heavy load to provide quality-of-service based on packet priority. The provided code snippet shows an example implementation of the SendPacket function, where custom

The Egress class is a virtual interface for sending packet data over a network link. Egress implementations provide a single SendPacket function, which takes the raw packet data and transmits it.

Egresses are invoked with the PacketParser used to process the packet. This allows additional information to be extracted from each packet to assist with transmitting decisions. For example, if packets in a project include a priority, egresses may use it to provide quality-of-service by dropping certain packets under heavy load.

Status MyEgress::SendPacket(
    ConstByteSpan packet, const PacketParser& parser) override {
  // Downcast the base PacketParser to the custom implementation that was
  // passed into RoutePacket().
  const CustomPacketParser& custom_parser =
      static_cast<const CustomPacketParser&>(parser);

  // Custom packet fields can now be accessed if necessary.
  if (custom_parser.priority() == MyPacketPriority::kHigh) {
    return SendHighPriorityPacket(packet);
  }

  return SendStandardPriorityPacket(packet);
}

Some common egress implementations are provided upstream in Pigweed.

StaticRouter

Pigweed AI summary: The StaticRouter is a router with a static table of address to egress mappings. It is suitable for basic networks with persistent links. The provided usage example shows how to define the router egresses and the routing table. The size report shows the cost of a StaticRouter with a simple PacketParser implementation and a single route using an EgressFunction. The size report indicates that the StaticRouter has a size increase of 1,044 bytes.

pw::router::StaticRouter is a router with a static table of address to egress mappings. Routes in a static router never change; packets with the same address are always sent through the same egress. If links are unavailable, packets will be dropped.

Static routers are suitable for basic networks with persistent links.

Usage example

Pigweed AI summary: This code defines a router with two egresses (UART and Bluetooth) and a routing table. It also includes a function to process packets using the router and a parser. The code is written in C++.

namespace {

// Define the router egresses.
UartEgress uart_egress;
BluetoothEgress ble_egress;

// Define the routing table.
constexpr pw::router::StaticRouter::Route routes[] = {{1, uart_egress},
                                                      {7, ble_egress}};
pw::router::StaticRouter router(routes);

}  // namespace

void ProcessPacket(pw::ConstByteSpan packet) {
  HdlcFrameParser hdlc_parser;
  router.RoutePacket(packet, hdlc_parser);
}

Size report

Pigweed AI summary: This section provides a size report for a StaticRouter with a simple PacketParser implementation and a single route using an EgressFunction. The report includes a table showing the label, segment, and delta for various functions and methods. The StaticRouter with a single route has a delta of +1,044.

The following size report shows the cost of a StaticRouter with a simple PacketParser implementation and a single route using an EgressFunction.

Label	Segment	Delta
Static router with a single route	FLASH +4 _ctype_ +44 main -2 pw::allocator::FreeList::RemoveChunk() +2 pw_log_tokenized_HandleLog +4 p05.0 NEW +216 pw::router::StaticRouter::RoutePacket() NEW +188 _GLOBAL__sub_I_main NEW +54 pw::router::StaticRouter::~StaticRouter() NEW +44 pw::router::EgressFunction::~EgressFunction() NEW +32 (anonymous namespace)::sys_io_egress::{lambda()#1}::_FUN() NEW +32 pw::intrusive_list_impl::List::insert_after() NEW +32 pw::metric::Metric::Increment() NEW +32 pw::router::EgressFunction::SendPacket() NEW +28 (anonymous namespace)::BasicPacketParser::Parse() NEW +28 __cxa_atexit NEW +26 pw::metric::Metric::Metric() NEW +24 (anonymous namespace)::BasicPacketParser NEW +24 fit::internal::target<>::invoke() NEW +20 fit::internal::null_target<>::ops NEW +20 fit::internal::target<>::ops NEW +20 pw::intrusive_list_impl::List::Item::unlist() NEW +20 pw::router::EgressFunction NEW +18 pw::metric::Group::Group() NEW +16 (anonymous namespace)::BasicPacketParser::~BasicPacketParser() NEW +16 __wrap_free NEW +14 pw::intrusive_list_impl::List::Item::previous() NEW +14 pw::intrusive_list_impl::List::Item::~Item() NEW +12 (anonymous namespace)::BasicPacketParser::GetDestinationAddress() NEW +10 __aeabi_atexit NEW +8 (anonymous namespace)::routes NEW +8 fit::internal::generic_function_base<>::destroy_target() NEW +8 operator delete() NEW +6 fit::internal::inline_trivial_target_move<>() NEW +6 fit::internal::null_target<>::invoke() NEW +4 fit::internal::inline_target_get() NEW +4 fit::internal::null_target_get() NEW +4 fit::internal::unshared_target_type_id() NEW +2 fit::internal::null_target_move() NEW +2 fit::internal::trivial_target_destroy()	+1,044

Zephyr

Pigweed AI summary: This paragraph provides instructions on how to enable pw_router for Zephyr by adding CONFIG_PIGWEED_ROUTER=y to the project's configuration. This will enable the Kconfig menu for pw_router.static_router, pw_router.egress, pw_router.packet_parser, and pw_router.egress_function, which can be individually enabled via their respective CONFIG_PIGWEED_ROUTER_* options.

To enable pw_router.* for Zephyr add CONFIG_PIGWEED_ROUTER=y to the project’s configuration. This will enable the Kconfig menu for the following:

• pw_router.static_router which can be enabled via CONFIG_PIGWEED_ROUTER_STATIC_ROUTER=y.

• pw_router.egress which can be enabled via CONFIG_PIGWEED_ROUTER_EGRESS=y.

• pw_router.packet_parser which can be enabled via CONFIG_PIGWEED_ROUTER_PACKET_PARSER=y.

• pw_router.egress_function which can be enabled via CONFIG_PIGWEED_ROUTER_EGRESS_FUNCTION=y.