# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
---
name: gtp

protocol: genetlink-legacy

doc: |
  GPRS Tunnelling Protocol, user plane (GTP-U).

  The gtp netdevice encapsulates and decapsulates user plane packets in
  GTP-U tunnels (GTPv0 and GTPv1-U, see 3GPP TS 29.060 and TS 29.281).
  This family manages the PDP contexts that describe the tunnels and
  triggers GTP-U echo requests. It is driven by user space control planes
  such as those built on libgtpnl.

  The kernel registers the family with version 0, which the
  genetlink-legacy schema cannot express.

  The notifications multicast on the "gtp" group are not described: PDP
  context additions and deletions, and GTP-U echo responses, reuse the
  NEWPDP, DELPDP and ECHOREQ command values of the requests.

kernel-policy: global

definitions:
  -
    type: enum
    name: version
    name-prefix: gtp-
    enum-name: gtp-version
    header: linux/gtp.h
    entries: [v0, v1]

attribute-sets:
  -
    name: gtp
    name-prefix: gtpa-
    attributes:
      -
        name: link
        type: u32
        doc: ifindex of the gtp netdevice the context is attached to.
      -
        name: version
        type: u32
        enum: version
        doc: GTP version of the context, GTPv0 or GTPv1-U.
      -
        name: tid
        type: u64
        doc: Tunnel identifier, GTPv0 only.
      -
        name: peer-address
        type: u32
        byte-order: big-endian
        display-hint: ipv4
        doc: |
          IPv4 address of the remote GSN peer (GGSN or SGSN). Also known
          as GTPA_SGSN_ADDRESS, kept for legacy user space.
      -
        name: ms-address
        type: u32
        byte-order: big-endian
        display-hint: ipv4
        doc: IPv4 address of the mobile subscriber served by the context.
      -
        name: flow
        type: u16
        doc: Flow label, GTPv0 only.
      -
        name: net-ns-fd
        type: u32
        doc: File descriptor of the network namespace of the gtp netdevice.
      -
        name: i-tei
        type: u32
        doc: Ingress Tunnel Endpoint Identifier, GTPv1-U only.
      -
        name: o-tei
        type: u32
        doc: Egress Tunnel Endpoint Identifier, GTPv1-U only.
      -
        name: pad
        type: pad
      -
        name: peer-addr6
        type: binary
        checks:
          min-len: 16
        byte-order: big-endian
        display-hint: ipv6
        doc: IPv6 address of the remote GSN peer (GGSN or SGSN).
      -
        name: ms-addr6
        type: binary
        checks:
          min-len: 16
        byte-order: big-endian
        display-hint: ipv6
        doc: |
          IPv6 prefix of the mobile subscriber served by the context: a /64
          prefix, with the lower 64 bits set to zero.
      -
        name: family
        type: u8
        doc: |
          Address family (AF_INET or AF_INET6) of ms-address or ms-addr6,
          AF_INET when absent. The peer address uses the family of the
          tunnel socket.

operations:
  list:
    -
      name: newpdp
      doc: Create or update a PDP context.
      attribute-set: gtp
      value: 0
      dont-validate: [strict, dump]
      flags: [admin-perm]
      do:
        request: &pdp-attrs
          attributes:
            - link
            - version
            - tid
            - peer-address
            - peer-addr6
            - ms-address
            - ms-addr6
            - flow
            - i-tei
            - o-tei
            - family
            - net-ns-fd
    -
      name: delpdp
      doc: Delete a PDP context.
      attribute-set: gtp
      dont-validate: [strict, dump]
      flags: [admin-perm]
      do:
        request: &pdp-find
          attributes:
            - link
            - version
            - tid
            - ms-address
            - ms-addr6
            - i-tei
            - family
            - net-ns-fd
    -
      name: getpdp
      doc: Get or dump one or more PDP contexts.
      attribute-set: gtp
      dont-validate: [strict, dump]
      flags: [admin-perm]
      do:
        request: *pdp-find
        reply: &pdp-reply
          attributes:
            - link
            - version
            - tid
            - peer-address
            - peer-addr6
            - ms-address
            - ms-addr6
            - flow
            - i-tei
            - o-tei
            - family
      dump:
        reply: *pdp-reply
    -
      name: echoreq
      doc: |
        Send a GTP-U echo request to a peer. ms-address is not a mobile
        subscriber address here, but the local IPv4 address used as source
        of the request.
      attribute-set: gtp
      dont-validate: [strict, dump]
      flags: [admin-perm]
      do:
        request:
          attributes:
            - link
            - version
            - peer-address
            - ms-address
            - net-ns-fd

mcast-groups:
  list:
    -
      name: gtp