CoreControl.h Source File¶

Simu5G: CoreControl.h Source File
Simu5G
//
//                  Simu5G
//
// Authors: Andras Varga (OpenSim Ltd)
//
// This file is part of a software released under the license included in file
// "license.pdf". Please read LICENSE and README files before using it.
// The above files and the present reference are part of the software itself,
// and cannot be removed from it.
//
 
#ifndef _CORECONTROL_H_
#define _CORECONTROL_H_
 
#include <map>
#include <set>
#include <string>
#include <vector>
 
#include <inet/common/ModuleRefByPar.h>
 
#include "simu5g/common/LteCommon.h"
#include "simu5g/common/binder/Binder.h"
#include "simu5g/corenetwork/gtp/GtpTunnel.h"
 
namespace simu5g {
 
class BearerConfigurator;
class ConnectionControlEnb;
class UserPlaneNodeControl;
class CoreControl : public omnetpp::cSimpleModule, public omnetpp::cListener
{
  public:
    // A session the core network establishes for a UE (see sessionsToEstablish()): its
    // id (1..15, unique among the UE's sessions), its type, and the UE addresses that
    // belong to it (empty: every address of the UE)
    struct SessionPlan {
        SessionId id = SessionId(0);
        SessionType type = IP_V4;
        std::vector<AddressPrefix> addresses;
    };
 
  protected:
    inet::ModuleRefByPar<Binder> binder_;
    inet::ModuleRefByPar<BearerConfigurator> bearerConfigurator_;
 
    // A node of the network that ends tunnels (see takeGtpEndpoints()), through its
    // control-plane entry point: the UserPlaneNodeControl of a user plane node (a UPF/PGW or a
    // MEC host's UPF), or the connection control of a base station. Each allocates
    // its node's TEIDs itself, and is programmed through its calls.
    struct GtpEndpoint {
        omnetpp::cModule *node = nullptr;     // the network node
        UserPlaneNodeControl *userPlaneNode = nullptr;  // user plane nodes only
        ConnectionControlEnb *bs = nullptr;   // base stations only
        CoreNodeType type = ENB;
        MacNodeId bsId = NODEID_NONE;         // base stations only
        std::string gateway;                  // the core network gateway of a base station connected to the core network, or of a MEC host's UPF; empty otherwise
    };
    std::vector<GtpEndpoint> gtpEndpoints_;       // the user plane nodes, then the base stations
    std::map<MacNodeId, int> bsGtpEndpoints_;     // base station id -> index into gtpEndpoints_
 
    // A UE's session (a PDN connection of an EPC, a PDU session of a 5G core, TS 23.501
    // 5.6), as the core network keeps it: established when the UE first has a serving
    // node, as sessionsToEstablish() says, released when the UE leaves (see
    // establishSessions()). The
    // anchor (the PGW, or the PDU session anchor UPF) is chosen at establishment and
    // kept for the lifetime of the session (SSC mode 1): a handover only moves the
    // downlink end of the tunnel (see updateDownlinkPath()). The tunnel ends are told
    // about every change through their nodes' control-plane entry points.
    struct CoreSession {
        omnetpp::cModule *ueModule = nullptr;
        SessionRef ref;                          // the UE's node ids and the session id
        SessionType type = IP_V4;                   // the session's type
        std::vector<AddressPrefix> addresses;       // the UE addresses that belong to the session; empty: every address of the UE
        inet::L3Address n6Address;                  // Unstructured sessions only: the session's address on the anchor's N6 tunnel, allocated from the anchor's prefix
        uint32_t n6Suffix = 0;                      // the host part of n6Address within the prefix (0: none)
        int anchor = -1;                            // the anchor UPF/PGW, index into gtpEndpoints_
        FTeid ulAnchor;                             // uplink F-TEID at the anchor
        std::map<int, FTeid> ulMecHosts;            // uplink F-TEIDs at the MEC host UPFs of the anchor's core network, by index into gtpEndpoints_
        MacNodeId dlBaseStation = NODEID_NONE;      // where the downlink enters the RAN; NODEID_NONE while the UE is attached nowhere
        MacNodeId lastDlBaseStation = NODEID_NONE;  // where the downlink last entered the RAN, kept while the UE is attached nowhere
        FTeid dl;                                   // downlink F-TEID at dlBaseStation
        std::map<MacNodeId, FTeid> dlTunnels;       // the downlink F-TEID at each base station the UE has been attached through, kept until release
    };
    typedef std::pair<int, SessionId> CoreSessionKey;     // the UE module's id, and the session id
    std::map<CoreSessionKey, CoreSession> sessions_;
    std::map<MacNodeId, std::vector<CoreSessionKey>> sessionsOfNode_;   // UE node id (either stack) -> the UE's sessions, in establishment order
    std::map<int, SessionType> requestedTypes_;   // UE module id -> the session type the UE requests
 
    // The host parts of the N6 addresses allocated from each anchor's prefix to the
    // Unstructured sessions it anchors, by index into gtpEndpoints_
    std::map<int, std::set<uint32_t>> n6AddressesInUse_;
 
  protected:
    void initialize(int stage) override;
    int numInitStages() const override { return inet::NUM_INIT_STAGES; }
    void handleMessage(omnetpp::cMessage *msg) override { throw omnetpp::cRuntimeError("This module does not process messages"); }
    void receiveSignal(omnetpp::cComponent *source, omnetpp::simsignal_t signalID, long nodeId, omnetpp::cObject *details) override;
 
    // Take the nodes that end tunnels from the Binder: the user plane nodes' control-
    // plane entry points, registered there at INITSTAGE_LOCAL, in registration order, then the
    // base stations' connection controls, through the node directory, in node id
    // order. Before the first tunnel is set up.
    virtual void takeGtpEndpoints();
 
    // Deliver the QFI classification rules the BearerConfigurator holds to their
    // evaluation sites: the downlink rules to each user plane node, the uplink rules
    // to each SDAP UE's classifier through the
    // UE's RRC (the QoS rules NAS signaling installs into a UE at PDU session
    // establishment, TS 23.501 5.7.1.4). The sites never author rules of their own.
    virtual void deliverQfiRules();
 
    // The node a gateway parameter names, or nullptr
    virtual omnetpp::cModule *findGatewayNode(const std::string& gateway);
 
    // The UPF/PGW endpoint the gateway parameter of the given endpoint names; throws if
    // there is none
    virtual int findGatewayEndpoint(const std::string& gateway, const GtpEndpoint& from);
 
    // The base station a downlink packet for the UE enters the RAN at: the master of the
    // serving node of the stack the core network addresses the UE by, the LTE one while
    // it is attached and else the NR one (as Binder::getMacNodeId() resolves a UE
    // address); NODEID_NONE if the UE is attached nowhere
    virtual MacNodeId findDlBaseStation(MacNodeId lteNodeId, MacNodeId nrNodeId);
 
    // The policy: the sessions to establish for a UE that requests a session of the
    // given type. One session per UE, of the requested type, with every address of
    // the UE: a UE has one session in this model, a deliberate simplification of 3GPP
    // (where a UE may have several, each with its own type and address). The protocol
    // modules keep their state per session, so a subclass may return several.
    virtual std::vector<SessionPlan> sessionsToEstablish(omnetpp::cModule *ueModule, SessionType requestedType);
 
    // Establish the sessions of the UE with the given node id (see
    // sessionsToEstablish()), each anchored at the gateway of the UE's downlink base
    // station: its uplink tunnels at the anchor and the MEC host UPFs. Does nothing if
    // the UE is attached nowhere yet, or its base station is not connected to a core
    // network; throws if the anchor's core network cannot carry a session of the
    // type (an EPC carries the IP types only). The RAN end of the sessions is set up
    // separately (initialUeMessage(), pathSwitchRequest()).
    virtual void establishSessions(MacNodeId ueNodeId, SessionType requestedType);
 
    // If the base station the UE's downlink enters the RAN at has changed, the downlink
    // end of the tunnel moves there (the path switch, TS 23.502 4.9.1.2.2), and that
    // base station is told (ConnectionControlEnb::downlinkPathSwitched())
    virtual void updateDownlinkPath(CoreSession& session);
 
    // Set up the session's tunnels at a base station the UE is attached through, unless
    // they are there already (see registerRanTunnel())
    virtual void setUpRanTunnels(CoreSession& session, MacNodeId bsId);
 
    // Record the session's downlink tunnel at a base station. The base stations of the
    // session learn each other's downlink TEIDs, to forward the downlink over X2 with.
    virtual void registerRanTunnel(CoreSession& session, MacNodeId bsId, const FTeid& dl);
 
    // The session's uplink tunnels, as a base station uses them
    virtual UplinkTunnels getUplinkTunnels(const CoreSession& session);
 
    // Allocate the N6 address of an Unstructured session from its anchor's prefix (the
    // SMF's allocation of TS 29.561 9.2, one address per session): the lowest free one
    // after the prefix itself; and free it at the session's release
    virtual void allocateN6Address(CoreSession& session);
    virtual void freeN6Address(const CoreSession& session);
 
    // Release the sessions of the UE with the given node id, if it has any
    virtual void releaseSessions(MacNodeId ueNodeId);
 
    // Release one session
    virtual void releaseSession(const CoreSession& session);
 
  public:
    // INITIAL UE MESSAGE (S1AP/NGAP), and the registration and session establishment that
    // follow: a leg of a UE has connected at the given base station, requesting a
    // session of the given type (the NAS message the INITIAL UE MESSAGE carries). The
    // UE's sessions are established once, at its first leg's registration; the other
    // leg of a dual-stack UE requests the same type. Each session's RAN resources are
    // set up at every base station the UE attaches through, once
    // (ConnectionControlEnb::sessionResourceSetup()); and the downlink paths are
    // settled.
    virtual void initialUeMessage(MacNodeId legId, ConnectionControlEnb *bs, SessionType sessionType);
 
    // PATH SWITCH REQUEST (S1AP/NGAP), from the base station a leg arrived at by handover: the
    // UE's sessions now enter the RAN at that base station (the master of it, under
    // dual connectivity), with the downlink F-TEIDs the handover preparation set up
    // there (the session resources "to be switched in downlink"); a base station the
    // preparation gave no tunnels (a secondary node's source has none to transfer)
    // gets them now. The downlink path is switched if the base station the downlink
    // enters at changed.
    virtual void pathSwitchRequest(MacNodeId legId, ConnectionControlEnb *bs, const std::vector<SessionResource>& sessions);
 
    // UE CONTEXT RELEASE REQUEST (S1AP/NGAP), from the base station a leg left without a
    // handover: the leg is attached nowhere; the downlink paths follow the UE's
    // remaining attachment, if any. The UE's sessions stay until the UE leaves the
    // simulation (nodeUnregistered).
    virtual void ueContextReleaseRequest(MacNodeId legId);
};
 
} //namespace
 
#endif