Chapter 0: Welcome

Welcome to the PFCP Endpoint (PEP) microservice learning guide. PEP is the control-plane brain of the User Plane — it terminates PFCP from the SMF, manages associations and sessions, and pushes forwarding rules to the data-plane.

Repository at a Glance

pfcp-endpoint/
├── src/                    # Main application source
│   ├── pep_main.c          # Entry point
│   ├── pep.c               # Top-level PEP module
│   ├── pep_ctrl.c          # Controller module
│   ├── pfcp.c              # PFCP protocol codec
│   ├── pep_association_engine.c  # Association management (392K!)
│   ├── pep_session_engine.c     # Session management (661K!)
│   ├── pep_internal_session_engine.c  # Internal sessions
│   ├── gtp_path_supervisor.c    # GTP path monitoring
│   ├── path_supervisor.c        # PFCP path supervision
│   ├── lep_client_engine.c      # LEP (data-plane) client
│   ├── ext_adapter.c            # External adapter
│   ├── config/             # Configuration parsing
│   ├── network-instance/   # Network instance management
│   ├── pfdm/              # PFD Management
│   ├── pfcp-common/       # Shared PFCP utilities
│   ├── db-mux/            # Database multiplexer
│   ├── common/            # Common utilities
│   ├── session/           # Session client
│   ├── types/             # Type definitions
│   ├── pvtb/             # PVTB (buffering)
│   └── blocked-pools-manager/
├── libs/                   # Local libraries
│   ├── action/            # Action command framework
│   ├── cli/               # CLI agent
│   ├── cm/                # CM mediator/broker
│   ├── fen/               # FEN adapter
│   ├── fm/                # Fault Management
│   └── partitioner/       # Session partitioning
├── tests/                  # All tests
│   ├── ut/                # Unit tests
│   ├── sft/               # Signal Flow Tests
│   ├── fixture/           # SFT test fixtures/simulators
│   ├── mock/              # Mocks
│   ├── veto/              # System tests (VETO)
│   └── toads/             # TOADS integration tests
├── include/                # Public headers
├── flatbuffers/            # FlatBuffer schemas
├── up-common/              # Shared libraries (submodule)
├── Makefile                # Developer shortcuts (if exists)
├── CMakeLists.txt          # Build system
├── Jenkinsfile*            # CI/CD pipelines
└── ruleset2.0.yaml         # Bob build rules

Chapter 1: PFCP & the Control Plane

PFCP Recap (from the UPF perspective)

You already know PFCP from the data-plane guide. But PEP is the other side — it's the service that terminates PFCP messages from the SMF and translates them into data-plane configuration.

Key PFCP Concepts in PEP

Chapter 2: PEP's Role in PCG

Where PEP Sits

PEP's Responsibilities

• PFCP termination: Decode/encode PFCP messages (TS 29.244)
• Session lifecycle: Create, modify, delete PFCP sessions
• Association management: Handle SMF associations, heartbeats, recovery
• TEID/SEID allocation: Generate unique identifiers for tunnels and sessions
• Config push to DP: Translate PFCP rules into data-plane config (via LEP client)
• UE IP allocation: Request IP addresses from UE-IP Allocator service
• GTP path supervision: Monitor GTP-U path health (echo requests)
• Geo-redundancy: Persist session state to Redis for failover
• Load control: Report load to SMF, implement overload protection
• Metrics & OAM: Prometheus metrics, fault management, CLI

Chapter 3: Neighboring Services

Chapter 4: High-Level Architecture

Single-Threaded Event-Driven

Unlike the data-plane (multi-threaded, CPU-pinned), PEP is primarily single-threaded and event-driven using the EVL event loop. It handles thousands of PFCP messages per second without threads — all via async I/O and callbacks.

Key Source Files

Chapter 5: Association Engine

What is a PFCP Association?

Before an SMF can create sessions, it must establish a PFCP Association with the UPF. This is like a "handshake" that negotiates features and starts heartbeat monitoring.

SMF                              PEP (UPF)
 │                                │
 │── Association Setup Request ──►│  (features, node ID, recovery TS)
 │◄── Association Setup Response ─│  (accepted, UP features, TEID ranges)
 │                                │
 │── Heartbeat Request ──────────►│  (every N seconds)
 │◄── Heartbeat Response ─────────│
 │                                │
 │── Association Release Req ────►│  (graceful teardown)
 │◄── Association Release Resp ───│

Association Engine Responsibilities

• Accept/reject association setup requests
• Track multiple simultaneous SMF associations
• Monitor heartbeats (detect dead SMFs)
• Handle recovery timestamp changes (SMF restart → clean stale sessions)
• Report UP features and capabilities to SMF
• Manage association-level counters and metrics

Chapter 6: Session Engine

Session Lifecycle

Key Concepts

• SEID Generator (pfcp-common/src/pep_seid_generator.c) — Generates unique 64-bit Session Endpoint IDs
• TEID Generator (pfcp-common/src/pep_teid_generator.c) — Generates unique 32-bit Tunnel Endpoint IDs
• Session Client (session/src/pep_session_client.c) — Interface to data-plane for session config
• Session Cleanup (pep_session_cleanup.c) — Handles stale session removal
• UE-IP Allocator Client (ueip_allocator_client.c) — Requests IPs from pool service

Chapter 7: Path Supervision

PFCP Path Supervision

PEP monitors the PFCP path to each SMF using heartbeat messages. If heartbeats fail, the association is considered dead and sessions are cleaned up.

// path_supervisor.c handles:
// - Sending heartbeat requests on timer
// - Tracking response timeouts
// - Declaring path failure after N retries
// - Triggering association cleanup on failure

GTP Path Supervision

PEP also monitors GTP-U paths (to gNBs) using GTP Echo Request/Response. This detects transport failures between the UPF and radio access network.

Chapter 8: PFCP Protocol Handling

The PFCP Codec

src/pfcp.c (185K) implements the PFCP message encoder/decoder per 3GPP TS 29.244. It handles:

• Message type dispatch (Association, Session, Heartbeat, Node Report)
• IE (Information Element) parsing and validation
• Grouped IE handling (nested structures)
• Error response generation

PFCP Resource Encoder

src/pfcp_resource_encoder.c (64K) encodes PFCP resources (TEIDs, network instance info) into the format expected by the data-plane.

Chapter 9: Network Instances

The src/network-instance/ module manages network instances (DNNs/APNs). Each network instance has:

• A unique NWID (network instance ID)
• Associated IP pools
• GTP access selectors
• Routing configuration

Key files: nw_instance_engine.c (108K), nw_instance_id_engine.c (69K), nw_instance_id_allocator.c, nw_instance_id_cache.c.

Chapter 10: PFD Management

The src/pfdm/ module handles Packet Flow Description Management — the SMF can provision application detection rules (PFDs) that the UPF uses for DPI-less traffic classification.

Key components: pfdm_engine.c, pfdm_provision_handler.c, pfdm_delete_handler.c, pfdm_request_handler.c, pfdm_state_data.c.

Chapter 11: DB Mux & Geo-Redundancy

DB Multiplexer

The src/db-mux/ module abstracts database operations, allowing PEP to work with multiple Redis instances for geo-redundancy.

Geo-Redundancy

PEP persists session state to Redis so that if a PEP pod dies, another can take over. The common/src/db_module.c and common/src/db_tracker_adapter.c handle this.

Sequence Number Allocator

common/src/seqno_allocator.c — Generates unique sequence numbers for PFCP messages, persisted across restarts via Redis.

Chapter 12: Module Lifecycle

PEP follows the same module lifecycle pattern as data-plane (create → start → stop → delete). See the data-plane guide Chapter 12 for the full pattern. The same rules apply: start must not fail, stop must be callable before start completes, on_stopped_cb means safe to delete.

// PEP module example (from pep.h)
pep_t* pep_create(pep_options_t* options, evl_t* evl, ...);
void   pep_start(pep_t* pep, on_started_cb, ctx);
void   pep_stop(pep_t* pep, on_stopped_cb, ctx);
void   pep_delete(pep_t* pep);

Chapter 13: Config Handling

Configuration Sources

• CM Mediator (JSON) — Runtime config via REST (config/pep_config_json_parser.c, 195K)
• XML (EPG mode) — Legacy config (config/pep_config_xml_parser.c, 70K)
• Environment variables — Startup options (config/pep_config_env_parser.c)
• Command-line options — (pep_options.c, 90K)

Config Flow

Chapter 14: LEP Client & Ext Adapter

LEP Client

The LEP (Local Endpoint) Client (lep_client_engine.c, 59K) is how PEP pushes session configuration to the data-plane. It serializes rules into FlatBuffers and sends them over an internal connection.

External Adapter

ext_adapter.c (56K) handles communication with external services (UE-IP allocator, routing agent, etc.).

Chapter 15: up-common & EVL

PEP uses the same up-common submodule as data-plane. Key libraries: EVL (event loop), timers, mbox, RCU, HTTP, Redis client, TLS, logging, metrics. See data-plane guide Chapters 15-17 for details.

Chapter 16: Local Libraries

PEP has its own libs/ directory with service-specific libraries:

Chapter 17: Flatbuffers & PFCP Codec

FlatBuffers

PEP uses FlatBuffers (Google's zero-copy serialization) to communicate with the data-plane. Schemas are in flatbuffers/. This is more efficient than JSON for high-frequency session updates.

PFCP Codec Libraries

The src/pfcp-common/ module contains shared PFCP utilities:

• pep_seid_generator.c — SEID allocation (43K)
• pep_teid_generator.c — TEID allocation (24K)
• load_ctrl.c — Load control reporting to SMF (40K)
• recovery_timestamp.c — Recovery timestamp management (27K)
• pep_uetrace_ctrl.c / pep_uetrace_engine.c — UE tracing

Chapter 18: Build System

Same as data-plane: CMake + Bob + up-common 3PP system. The top-level CMakeLists.txt builds the pfcp-endpoint executable and links all modules.

# Key build commands (similar to data-plane)
$ bob/bob init-dev
$ bob/bob generate:3pp          # Download 3PP dependencies
$ bob/bob -p build-dir=builds/san generate:cmake
$ bob/bob -p build-dir=builds/san build:cpp test:cpp

Build variants: builds/san (sanitizers), builds/assert, builds/debug, builds/release, builds/cov.

Chapter 19: Unit & SFT Tests

Test Organization

tests/
├── ut/                 # Unit tests (test single modules with mocks)
│   ├── pep_ut_session_engine.c      (725K!)
│   ├── pep_ut_association_engine.c  (216K)
│   ├── pep_ut_pfcp.c               (64K)
│   └── ...
├── sft/                # Signal Flow Tests (multi-module integration)
│   ├── pep_sft_sessions.c          (273K)
│   ├── pep_sft_associations.c      (98K)
│   ├── pep_sft_pfdm.c             (470K!)
│   └── ...
├── fixture/            # SFT simulators
│   ├── pep_sft_fix.c              (165K - main fixture)
│   ├── pep_sft_sim_data_plane.c   (simulates DP)
│   ├── pep_sft_sim_control_plane.c (simulates SMF)
│   └── pep_sft_sim_lep.c          (simulates LEP)
├── mock/               # Mock implementations
└── utils/              # Test utilities

Uses the same ET test framework from up-common.

Chapter 20: VETO & TOADS

VETO (System Test)

tests/veto/ contains Python-based system tests that run against a real PCG deployment. They use TRex traffic generator and test end-to-end PFCP flows.

TOADS

tests/toads/ is a container-based integration test framework (similar to data-plane's contest). It runs PEP in a Docker container with simulated peers.

Chapter 21: CI Pipelines

Same pipeline structure as data-plane:

• JenkinsfilePreCodeReview — Runs on every Gerrit push (build, test, lint)
• JenkinsfileDrop — Produces versioned artifacts on merge
• JenkinsfilePra — Release pipeline with full VA/compliance
• JenkinsfileVA2.0 — Vulnerability scanning
• JenkinsfileSoC — Security of Code
• JenkinsfileReadinessCheck — ADP readiness verification

Chapter 22: Docker & Helm

PEP is deployed as eric-pc-up-pfcp-endpoint in Kubernetes. The Dockerfile builds a minimal image with the pfcp-endpoint binary. Helm chart is in charts/.

Key differences from data-plane: PEP does NOT need DPDK, SR-IOV, or hugepages. It's a standard network service using regular kernel sockets (UDP for PFCP).

Chapter 23: Day-to-Day Workflow

Same Gerrit workflow as data-plane. Key commands:

# Build and test
$ bob/bob -p build-dir=builds/san generate:cmake
$ bob/bob -p build-dir=builds/san build:cpp test:cpp

# Run specific test
$ bob/bob -p build-dir=builds/san -p cpp-target=pep_ut_session_engine_SUITE test:cpp

# Build image
$ bob/bob -p build-dir=builds/release build image package