== MGCP Extensions

The MGCP protocol is extendable. The following non-standard extensions are
understood by OsmoMGW.

=== `X-Osmo-IGN`

`X-Osmo-IGN` indicates to OsmoMGW that specific items of an endpoint should be
ignored, so that it is lenient on mismatching values that would normally
indicate collisions or configuration errors.

==== `X-Osmo-IGN` Format

The value part of `X-Osmo-IGN` must be one or more items separated by one or more
spaces. Each item consists of one or more non-whitespace characters.

.Example: `X-Osmo-IGN` format with three ficticious items "X", "abc" and "123".
----
X-Osmo-IGN: X abc 123
----

`X-Osmo-IGN` must be issued in the MGCP header section (typically as its last item),
before the SDP section starts.

==== Supported `X-Osmo-IGN` Items

Currently, the following `X-Osmo-IGN` items are supported:

* `C`: ignore CallID mismatches, i.e. differing "C" values between connections
  on the same endpoint.

.Note:
`X-Osmo-IGN` does not support ignoring mismatches on the domain part of
an endpoint name, e.g. ignoring a mismatch on "example.com" in
`rtpbridge/123abc@example.com`. Instead, you may globally configure OsmoMGW
with `mgcp` / `domain *` to permit all domain parts.

===== `X-Osmo-IGN: C`

By default, OsmoMGW verifies that all CallIDs ("C" values) match for all
connections on any one given endpoint. To ignore CallID mismatches, pass a `C`
in the `X-Osmo-IGN` header, for the first or the second `CRCX` on an endpoint.
When the `X-Osmo-IGN: C` is sent for any one `CRCX` on an endpoint, CallID
mismatches will be ignored for that and all subsequent messages for that
endpoint. Hence this header only needs to be included once per endpoint, in any
`CRCX` message that precedes or coincides with a CallID mismatch.

This is particularly useful for a BSC that is connected to an A/SCCPlite MSC,
where the BSC and MSC each are expected to configure their respective own
connection on a shared endpoint. For A/SCCPlite, it is impossible for the BSC
to know the CallID that the MSC will use, so CallID mismatches are inevitable.
See also OsmoBSC, which will by default pass the `X-Osmo-IGN: C` header for
endpoints associated with an A/SCCPlite MSC.

.Example: `CRCX` message that instructs OsmoMGW to ignore CallID mismatches
----
CRCX 2 rtpbridge/123abc@mgw MGCP 1.0
M: recvonly
C: 2
L: p:20
X-Osmo-IGN: C

v=0
c=IN IP4 123.12.12.123
m=audio 5904 RTP/AVP 97
a=rtpmap:97 GSM-EFR/8000
a=ptime:40
----

=== `X-Osmux`

See <<mgcp-extension-osmux>>

=== Non-standard SDP codec parameters

CRCX command message normally includes an SDP block that specifies the RTP
address of the connecting peer and the list of codecs accepted by that entity.
Codec specifications may include optional parameters given via `a=fmtp` lines;
one well-known parameter is `octet-align`, defined for AMR and AMR-WB codecs.

In addition to standard (RFC-defined) codec parameters (of which the
just-mentioned `octet-align` parameter is the only one implemented so far),
OsmoMGW also understands some non-standard (Osmocom-private) codec parameters
as listed below.
These Osmocom-private codec parameters are meaningful only in the context
of OsmoBSC driving an E1 Abis MGW, which may be either OsmoMGW or a specialized
third-party replacement.

The MGCP extension described in this section is meaningful only for E1
endpoints - it has absolutely no effect on `rtpbridge` endpoints!

==== `tw-ts-001` parameter for FR and EFR codecs

GSM Full Rate codec is known in SDP as `GSM`; GSM Enhanced Full Rate codec
is known in SDP as `GSM-EFR`.
When either codec is to be transported in RTP, there is a choice between
two different payload formats: RFC 3551 or TW-TS-001.
RFC 3551 is the standard in non-GSM Internet applications, and it is the
format specified in later 3GPP releases for IP-based transport of
compressed speech - however, it exhibits functional regressions compared
to the original TRAU-UL frame format of GSM 08.60.
TW-TS-001 is an enhanced alternative payload format for the same codecs
that restores the original functionality and semantics of TRAU-UL frames.

In the context of CRCX or MDCX command messages from OsmoBSC to an E1 Abis MGW,
`tw-ts-001` codec parameter (attached to either `GSM` or `GSM-EFR` codec)
instructs the MGW whether or not it should emit the extended payload format
of TW-TS-001 for GSM uplink traffic converted to RTP.
In the absence of this parameter, IETF-standard and 3GPP-standard RFC 3551
format is emitted; if TW-TS-001 output is desired, please specify
`tw-ts-001=1` on the appropriate `a=fmtp` line.

.Example: `CRCX` message requesting EFR codec with TW-TS-001 extensions
----
CRCX 2 ds/e1-0/s-2/su16-2@mgw MGCP 1.0
M: recvonly
C: 2
L: p:20

v=0
c=IN IP4 123.12.12.123
m=audio 1234 RTP/AVP 110
a=rtpmap:110 GSM-EFR/8000/1
a=fmtp:110 tw-ts-001=1
----

==== `tw-ts-002` parameter for HR codec

GSM Half Rate codec is known in SDP as `GSM-HR-08`.
The same dichotomy that exists between RFC 3551 and TW-TS-001 RTP payload
formats for FR and EFR codecs also exists for HR codec, except that
the two opposing alternatives are now RFC 5993 and TW-TS-002.

In the context of CRCX or MDCX command messages from OsmoBSC to an E1 Abis MGW,
`tw-ts-002` codec parameter (attached to `GSM-HR-08` codec)
instructs the MGW whether or not it should emit the extended payload format
of TW-TS-002 for GSM uplink traffic converted to RTP.
In the absence of this parameter, IETF-standard and 3GPP-standard RFC 5993
format is emitted; if TW-TS-002 output is desired, please specify
`tw-ts-002=1` on the appropriate `a=fmtp` line.

.Example: `CRCX` message requesting HR codec with TW-TS-002 extensions
----
CRCX 2 ds/e1-0/s-2/su8-2@mgw MGCP 1.0
M: recvonly
C: 2
L: p:20

v=0
c=IN IP4 123.12.12.123
m=audio 1234 RTP/AVP 111
a=rtpmap:111 GSM-HR-08/8000/1
a=fmtp:111 tw-ts-002=1
----
