Merge remote-tracking branch 'GuidoCasati/nr-paging' into integration_2026_w25

Complete NR L2/L3 Paging path from F1AP to NAS (gNB and UE) (#151)

This MR wires a 5G‑NR paging flow across the stack, from F1AP Paging on
the DU down to PCCH scheduling in MAC/RLC, RRC/ASN encode/decode, and
UE‑side NAS Service Request triggering, including the NR UE changes in
L1/L2.

It centralises paging PF/PO computation and PCCH scheduling in MAC,
using shared SSB/Type0‑PDCCH and common PDSCH helpers that are also
reused by SIB1. On the UE, it enables decoding of NR PCCH messages,
matching ng‑5G‑S‑TMSI/fullI‑RNTI, and conditionally initiating a
network‑triggered Service Request when 5GMM state allows it. The change
set includes focused refactors and ASN.1 tests to validate the new
paging encode/decode path.

Changes:
- MAC gNB common helpers: Move SSB/Type0‑PDCCH utilities from the
  BCH scheduler into shared MAC primitives and introduce a reusable 
Type0‑occasion helper and common PDSCH RB/MCS/TBS sizing
- MAC paging PF/PO responsibility: Add a dedicated PCCH scheduler module
  that implements TS 38.304 §7 PF/PO computation (defaultPagingCycle,
nAndPagingFrameOffset, Ns, SFN‑based PF formula and PO slot mapping)
and owns the “is this (frame,slot) a paging occasion for UE_ID?”
decision.
- F1AP -> MAC -> RLC PCCH path (gNB/DU): Have the DU decode F1AP Paging
  with CN UE identity, build an NR RRC Paging message (PCCH) in MAC, and
hand it to RLC as a dedicated PCCH SDU together with UE_ID (5G‑S‑TMSI
mod 1024), using per‑module PCCH storage. RAN UE paging identity
is explicitly rejected.
- Direct CU to DU paging path: Implement direct F1 Paging handling
  in the NR RRC DL direct interface for RLC PCCH storage for later 
scheduling.
- PCCH scheduling and NFAPI integration (gNB MAC): Integrate 
  schedule_nr_pcch() into the DL scheduler so that when a stored PCCH
SDU exists and the current (frame,slot) is a paging occasion, MAC 
resolves the paging search space and CORESET, selects a beam (from SSB),
allocates CCEs and PDSCH resources, builds NFAPI DL_TTI PDUs 
(PDCCH + PDSCH with P‑RNTI, DCI 1_0), and populates the matching
TX_DATA PDU, then clears the cached PCCH.
- DCI handling for P‑RNTI paging: Adjust DCI payload preparation
  to treat P‑RNTI specially, returning after setting DMRS and antenna 
ports and skipping HARQ and UE scheduling state that do not exist for
paging, so paging DCIs no longer touch UE HARQ data structures.
- PHY UE RX Chain: DCI handling for P‑RNTI on UE, monitor DCI on Paging
  Occasions, process DCI 1_0 with CRC scrambled by P‑RNTI on the paging 
search space, trigger PDSCH decoding for PCCH based on that DCI, deliver
decoded PCCH to upper layers from the PHY/MAC side
- RRC/ASN paging encode API: Replace the legacy buffer‑based do_NR_Paging 
with a nr_paging_params_t‑based API returning a byte_array_t,
supporting both ng‑5G‑S‑TMSI and fullI‑RNTI identities, and optional IEs
(e.g. accessType non‑3GPP and pagingCause v17), and encoding via 
uper_encode_to_new_buffer, with ownership and failure semantics clearly 
defined for callers.
- UE‑side PCCH reception and matching: Add UE MAC to RRC logic
  to deliver PCCH SDUs to RRC, decode NR PCCH via a new nr_pcch_decode() 
helper into an array of nr_paging_params_t, iterate PagingRecordList on 
the UE, compare M‑TMSI/fullI‑RNTI against local identity, and log whether 
a paging match was found.
- NAS integration for network‑triggered Service Request: On a UE paging
  match, send a NAS_PAGING_IND from RRC to NAS and, when the UE has a
GUTI, is 5GMM‑REGISTERED and in 5GMM‑IDLE, generate and send a Service
Request uplink NAS message
- Tests and validation helpers: Extend nr_asn1 paging tests
  to encode Paging via do_NR_Paging, decode it via nr_pcch_decode,
and verify round‑trips for multiple ng‑5G‑S‑TMSI values, accessType,
and fullI‑RNTI bit patterns, using a shared encode/decode helper that 
exercises the same decoder path used by the UE.

Notes:
Paging handling currently supports CN UE paging
identity (5G‑S‑TMSI) only. RAN UE paging identity is logged and ignored.
A paging match triggers a Service Request only when the UE has a GUTI,
is 5GMM‑REGISTERED, and in 5GMM‑IDLE. T3346 and suspend‑indication
handling are documented as future work and not implemented here.

Testing:
Tested with Open5gs. How to trigger Paging in Open5GS lab setup:

- Use gNB telnet to request NGAP UE Context Release: `rrc ctx_rel_req
  <RRC_UE_ID>`
- Wait until AMF reports CM-IDLE (for example gNB-UEs is now 0).
- Generate downlink data from the Linux host to the UE IP: `ping
  <UE_IP>`
- Host-originated downlink data will trigger paging.

Closes #74

Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Reviewed-by: Francesco Mani <email@francescomani.it>

CMakeLists.txt

@@ -1206,6 +1206,7 @@ set (MAC_NR_SRC
   ${NR_GNB_MAC_DIR}/gNB_scheduler_uci.c
   ${NR_GNB_MAC_DIR}/gNB_scheduler_srs.c
   ${NR_GNB_MAC_DIR}/gNB_scheduler_RA.c
+  ${NR_GNB_MAC_DIR}/gNB_scheduler_pcch.c
   ${NR_GNB_MAC_DIR}/mac_rrc_dl_handler.c
   ${NR_GNB_MAC_DIR}/mac_rrc_ul_direct.c
   ${NR_GNB_MAC_DIR}/mac_rrc_ul_f1ap.c