radio/1.6/IRadio.hal

/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.radio@1.6;


import @1.0::CdmaSmsMessage;
import @1.0::Dial;
import @1.0::GsmSmsMessage;
import @1.1::CardPowerState;
import @1.2::DataRequestReason;
import @1.4::EmergencyCallRouting;
import @1.4::EmergencyServiceCategory;
import @1.4::RadioAccessFamily;
import @1.5::IRadio;
import @1.5::AccessNetwork;
import @1.5::DataProfileInfo;
import @1.5::LinkAddress;

/**
 * This interface is used by telephony and telecom to talk to cellular radio.
 * All the functions have minimum one parameter:
 * serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
 * duration of a method call. If clients provide colliding serials (including passing the same
 * serial to different methods), multiple responses (one for each method call) must still be served.
 * setResponseFunctions must work with @1.6::IRadioResponse and @1.6::IRadioIndication.
 */
interface IRadio extends @1.5::IRadio {
    /**
     * Toggle radio on and off (for "airplane" mode)
     * If the radio is turned off/on the radio modem subsystem
     * is expected return to an initialized state. For instance,
     * any voice and data calls must be terminated and all associated
     * lists emptied.
     *
     * When setting radio power on to exit from airplane mode to place an emergency call on this
     * logical modem, powerOn, forEmergencyCall and preferredForEmergencyCall must be true. In
     * this case, this modem is optimized to scan only emergency call bands, until:
     * 1) Emergency call is completed; or
     * 2) Another setRadioPower_1_5 is issued with forEmergencyCall being false or
     * preferredForEmergencyCall being false; or
     * 3) Timeout after 30 seconds if dial or emergencyDial is not called.
     * Once one of these conditions is reached, the modem should move into normal operation.
     *
     * @param serial Serial number of request.
     * @param powerOn To turn on radio -> on = true, to turn off radio -> on = false.
     * @param forEmergencyCall To indication to radio if this request is due to emergency call.
     *      No effect if powerOn is false.
     * @param preferredForEmergencyCall indicate whether the following emergency call will be sent
     *      on this modem or not. No effect if forEmergencyCall is false, or powerOn is false.
     *
     * Response callback is IRadioConfigResponse. setRadioPowerResponse_1_6.

     * Note this API is the same as the 1.5
     */
    oneway setRadioPower_1_6(int32_t serial, bool powerOn, bool forEmergencyCall,
            bool preferredForEmergencyCall);

    /**
     * Returns the data call list. An entry is added when a setupDataCall() is issued and removed
     * on a deactivateDataCall(). The list is emptied when setRadioPower()  off/on issued or when
     * the vendor HAL or modem crashes.
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.getDataCallListResponse_1_6()
     */
    oneway getDataCallList_1_6(int32_t serial);

    /**
     * Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
     * the data connection must be added to data calls and a unsolDataCallListChanged() must be
     * sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
     * lost due to many factors, including deactivateDataCall() being issued, the radio powered
     * off, reception lost or even transient factors like congestion. This data call list is
     * returned by getDataCallList() and dataCallListChanged().
     *
     * The Radio is expected to:
     *   - Create one data call context.
     *   - Create and configure a dedicated interface for the context.
     *   - The interface must be point to point.
     *   - The interface is configured with one or more addresses and is capable of sending and
     *     receiving packets. The format is IP address with optional "/" prefix length
     *     (The format is defined in RFC-4291 section 2.3). For example, "192.0.1.3",
     *     "192.0.1.11/16", or "2001:db8::1/64". Typically one IPv4 or one IPv6 or one of each. If
     *     the prefix length is absent, then the addresses are assumed to be point to point with
     *     IPv4 with prefix length 32 or IPv6 with prefix length 128.
     *   - Must not modify routing configuration related to this interface; routing management is
     *     exclusively within the purview of the Android OS.
     *   - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
     *     in the response of getDataRegistrationState.
     *
     * The differences relative to the 1.5 version of the API are:
     *   - The addition of new parameters pduSessionId, sliceInfo, trafficDescriptor, and
     *     matchAllRuleAllowed.
     *   - If an existing data call should be used for the request, that must be indicated in the
     *     response by setting SetupDataCallResult::cid to the context id of that call.
     *
     * @param serial Serial number of request.
     * @param accessNetwork The access network to setup the data call. If the data connection cannot
     *     be established on the specified access network then it should be responded with an error.
     * @param dataProfileInfo Data profile info.
     * @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
     * @param reason The request reason. Must be DataRequestReason:NORMAL or
     *     DataRequestReason:HANDOVER.
     * @param addresses If the reason is DataRequestReason:HANDOVER, this indicates the list of link
     *     addresses of the existing data connection. This parameter must be ignored unless reason
     *     is DataRequestReason:HANDOVER.
     * @param dnses If the reason is DataRequestReason:HANDOVER, this indicates the list of DNS
     *     addresses of the existing data connection. The format is defined in RFC-4291 section 2.2.
     *     For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless reason
     *     is DataRequestReason:HANDOVER.
     * @param pduSessionId The pdu session id to be used for this data call.  A value of 0 means
     *     no pdu session id was attached to this call.
     *     Reference: 3GPP TS 24.007 section 11.2.3.1b
     * @param sliceInfo SliceInfo to be used for the data connection when a handover occurs from
     *     EPDG to 5G.  It is valid only when accessNetwork is AccessNetwork:NGRAN.  If the slice
     *     passed from EPDG is rejected, then the data failure cause must be
     *     DataCallFailCause:SLICE_REJECTED.
     * @param trafficDescriptor TrafficDescriptor for which data connection needs to be
     *     established. It is used for URSP traffic matching as described in TS 24.526
     *     Section 4.2.2. It includes an optional DNN which, if present, must be used for traffic
     *     matching -- it does not specify the end point to be used for the data call. The end
     *     point is specified by DataProfileInfo.apn; DataProfileInfo.apn must be used as the end
     *     point if one is not specified through URSP rules.
     * @param matchAllRuleAllowed bool to indicate if using default match-all URSP rule for this
     *     request is allowed. If false, this request must not use the match-all URSP rule and if
     *     a non-match-all rule is not found (or if URSP rules are not available) it should return
     *     failure with cause DataCallFailCause:MATCH_ALL_RULE_NOT_ALLOWED. This is needed as some
     *     requests need to have a hard failure if the intention cannot be met, for example, a
     *     zero-rating slice.
     *
     * Response function is IRadioResponse.setupDataCallResponse_1_6()
     *
     * Note this API is the same as the 1.5
     */
    oneway setupDataCall_1_6(int32_t serial, AccessNetwork accessNetwork,
            DataProfileInfo dataProfileInfo, bool roamingAllowed,
            DataRequestReason reason, vec<LinkAddress> addresses, vec<string> dnses,
            int32_t pduSessionId, OptionalSliceInfo sliceInfo,
            OptionalTrafficDescriptor trafficDescriptor, bool matchAllRuleAllowed);

    /**
     * Send an SMS message
     *
     * @param serial Serial number of request.
     * @param message GsmSmsMessage as defined in types.hal
     *
     * Response function is IRadioResponse.sendSmsResponse_1_6()
     *
     * Note this API is the same as the 1.0
     *
     * Based on the return error, caller decides to resend if sending sms
     * fails. RadioError:SMS_SEND_FAIL_RETRY means retry (i.e. error cause is 332)
     * and RadioError:GENERIC_FAILURE means no retry (i.e. error cause is 500)
     */
    oneway sendSms_1_6(int32_t serial, GsmSmsMessage message);

    /**
     * Send an SMS message. Identical to sendSms_1_6,
     * except that more messages are expected to be sent soon. If possible,
     * keep SMS relay protocol link open (eg TS 27.005 AT+CMMS command)
     *
     * @param serial Serial number of request.
     * @param message GsmSmsMessage as defined in types.hal
     *
     * Response function is IRadioResponse.sendSMSExpectMoreResponse_1_6()
     *
     * Note this API is the same as the 1.0
     *
     * Based on the return error, caller decides to resend if sending sms
     * fails. RadioError:SMS_SEND_FAIL_RETRY means retry (i.e. error cause is 332)
     * and RadioError:GENERIC_FAILURE means no retry (i.e. error cause is 500)
     */
    oneway sendSMSExpectMore_1_6(int32_t serial, GsmSmsMessage message);

    /**
     * Send a CDMA SMS message
     *
     * @param serial Serial number of request.
     * @param sms Cdma Sms to be sent described by CdmaSmsMessage in types.hal
     *
     * Response callback is IRadioResponse.sendCdmaSmsResponse_1_6()
     *
     * Note this API is the same as the 1.0
     *
     */
    oneway sendCdmaSms_1_6(int32_t serial, CdmaSmsMessage sms);

    /**
     * Send an SMS message. Identical to sendCdmaSms_1_6,
     * except that more messages are expected to be sent soon.
     *
     * @param serial Serial number of request.
     * @param sms Cdma Sms to be sent described by CdmaSmsMessage in types.hal
     *
     * Response callback is IRadioResponse.sendCdmaSMSExpectMoreResponse_1_6()
     *
     * Note this API is the same as the 1.5
     *
     */
    oneway sendCdmaSmsExpectMore_1_6(int32_t serial, CdmaSmsMessage sms);

    /**
     * Set SIM card power state.
     * Request is used to power off or power on the card. It should not generate
     * a CardState.CARDSTATE_ABSENT indication, since the SIM is still physically
     * inserted.
     *
     * @param serial Serial number of request
     * @param powerUp POWER_DOWN if powering down the SIM card,
     *                POWER_UP if powering up the SIM card,
     *                POWER_UP_PASS_THROUGH if powering up the SIM card in
     *                                      pass through mode.
     *
     * When SIM card is in POWER_UP_PASS_THROUGH, the modem does not send
     * any command to it (for example SELECT of MF, or TERMINAL
     * CAPABILITY), and the SIM card is controlled completely by Telephony
     * sending APDUs directly. The SIM card state must be
     * RIL_CARDSTATE_PRESENT and the number of card apps will be 0.
     * No new error code is generated. Emergency calls are supported in
     * the same way as if the SIM card is absent.
     * Pass-through mode is valid only for the specific card session where
     * it is activated, and normal behavior occurs at the next SIM
     * initialization, unless POWER_UP_PASS_THROUGH is requested again.
     *
     * The device is required to power down the SIM card before it can
     * switch the mode between POWER_UP and POWER_UP_PASS_THROUGH.
     * At device power up, the SIM interface is powered up automatically.
     * Each subsequent request to this method is processed only after the
     * completion of the previous one.
     *
     * When the SIM is in POWER_DOWN, the modem should send an empty vector of
     * AppStatus in CardStatus.applications. If a SIM in the POWER_DOWN state
     * is removed and a new SIM is inserted, the new SIM should be in POWER_UP
     * mode by default. If the device is turned off or restarted while the SIM
     * is in POWER_DOWN, then the SIM should turn on normally in POWER_UP mode
     * when the device turns back on.
     *
     * Response callback is IRadioResponse.setSimCardPowerResponse_1_6().
     * Note that this differs from setSimCardPower_1_1 in that the response
     * callback should only be sent once the device has finished executing
     * the request (the SIM has finished powering on or off).
     */
    oneway setSimCardPower_1_6(int32_t serial, CardPowerState powerUp);

    /**
     * Enable or disable E-UTRA-NR dual connectivity. If disabled then UE will not connect
     * to secondary carrier.
     *
     * @param serial Serial number of request.
     * @param nrDualConnectivityState expected NR dual connectivity state.
     * 1. Enable NR dual connectivity {NrDualConnectivityState:ENABLE}
     * 2. Disable NR dual connectivity {NrDualConnectivityState:DISABLE}
     * 3. Disable NR dual connectivity and force secondary cell to be released
     * {NrDualConnectivityState:DISABLE_IMMEDIATE}

     * Response callback is IRadioResponse.setNRDualConnectivityStateResponse()
     */
    oneway setNrDualConnectivityState(int32_t serial,
            NrDualConnectivityState nrDualConnectivityState);

    /**
     * Is E-UTRA-NR Dual Connectivity enabled
     *
     * @param serial Serial number of request.
     * Response callback is IRadioResponse.isNRDualConnectivityEnabledResponse()
     */
    oneway isNrDualConnectivityEnabled(int32_t serial);

    /**
     * Reserves an unallocated pdu session id from the pool of ids.
     *
     * The allocated id is returned in the response.
     *
     * When the id is no longer needed, call releasePduSessionId to
     * return it to the pool.
     *
     * Reference: 3GPP TS 24.007 section 11.2.3.1b
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.allocatePduSessionIdResponse()
     */
    oneway allocatePduSessionId(int32_t serial);

    /**
     * Releases a pdu session id that was previously allocated using
     * allocatePduSessionId.
     *
     * Reference: 3GPP TS 24.007 section 11.2.3.1b
     * @param serial Serial number of request.
     * @param id Pdu session id to release.
     *
     * Response function is IRadioResponse.releasePduSessionIdResponse()
     */
    oneway releasePduSessionId(int32_t serial, int32_t id);

    /**
     * Indicates that a handover to the IWLAN transport has begun.
     *
     * Any resources being transferred to the IWlan transport cannot be released while a
     * handover is underway. For example, if a pdu session id needs to be
     * transferred to IWlan, then, the modem should not release the id while
     * the handover is in progress.
     *
     * If a handover was unsuccessful, then the framework calls IRadio::cancelHandover.
     * The modem retains ownership over any of the resources being transferred to IWlan.
     *
     * If a handover was successful, the framework calls IRadio::deactivateDataCall with reason
     * HANDOVER. The IWlan transport now owns the transferred resources and is responsible for
     * releasing them.
     *
     * @param serial Serial number of request.
     * @param id callId The identifier of the data call which is provided in SetupDataCallResult
     *
     * Response function is IRadioResponse.startHandoverResponse()
     */
    oneway startHandover(int32_t serial, int32_t callId);

    /**
     * Indicates that a handover was cancelled after a call to IRadio::startHandover.
     *
     * Since the handover was unsuccessful, the modem retains ownership over any of the resources
     * being transferred and is still responsible for releasing them.
     *
     * @param serial Serial number of request.
     * @param id callId The identifier of the data call which is provided in SetupDataCallResult
     *
     * Response function is IRadioResponse.cancelHandoverResponse()
     */
    oneway cancelHandover(int32_t serial, int32_t callId);

    /**
     * Requests to set the network type for searching and registering.
     *
     * Instruct the radio to *only* accept the types of network provided. This
     * is stronger than setPreferredNetworkType which is a suggestion.
     *
     * In case of an emergency call, the modem is authorized to bypass this
     * restriction.
     *
     * @param serial Serial number of request.
     * @param networkTypeBitmap a 32-bit bearer bitmap of RadioAccessFamily
     *
     * Response callback is IRadioResponse.setNetworkTypeBitmapResponse()
     */
    oneway setAllowedNetworkTypeBitmap(
            uint32_t serial, bitfield<RadioAccessFamily> networkTypeBitmap);

    /**
     * Requests bitmap representing the currently allowed network types.
     *
     * Requests the bitmap set by the corresponding method
     * setAllowedNetworkTypeBitmap, which sets a strict set of RATs for the
     * radio to use. Differs from getPreferredNetworkType and getPreferredNetworkTypeBitmap
     * in that those request *preferences*.
     *
     * @param serial Serial number of request.
     *
     * Response callback is IRadioResponse.getNetworkTypeBitmapResponse()
     */
    oneway getAllowedNetworkTypeBitmap(uint32_t serial);

    /**
     * Control data throttling at modem.
     *   - DataThrottlingAction:NO_DATA_THROTTLING should clear any existing
     *     data throttling within the requested completion window.
     *   - DataThrottlingAction:THROTTLE_SECONDARY_CARRIER: Remove any existing
     *     throttling on anchor carrier and achieve maximum data throttling on
     *     secondary carrier within the requested completion window.
     *   - DataThrottlingAction:THROTTLE_ANCHOR_CARRIER: disable secondary
     *     carrier and achieve maximum data throttling on anchor carrier by
     *     requested completion window.
     *   - DataThrottlingAction:HOLD: Immediately hold on to current level of
     *     throttling.
     *
     * @param serial Serial number of request.
     * @param dataThrottlingAction DataThrottlingAction as defined in types.hal
     * @param completionDurationMillis window, in milliseconds, in which the
     *     requested throttling action has to be achieved. This must be 0 when
     *     dataThrottlingAction is DataThrottlingAction:HOLD.
     *
     * Response function is IRadioResponse.setDataThrottlingResponse()
     */
    oneway setDataThrottling(int32_t serial,
            DataThrottlingAction dataThrottlingAction,
            int64_t completionDurationMillis);

    /**
     * Initiate emergency voice call, with zero or more emergency service category(s), zero or
     * more emergency Uniform Resource Names (URN), and routing information for handling the call.
     * Android uses this request to make its emergency call instead of using @1.0::IRadio.dial
     * if the 'address' in the 'dialInfo' field is identified as an emergency number by Android.
     *
     * In multi-sim scenario, if the emergency number is from a specific subscription, this radio
     * request can still be sent out on the other subscription as long as routing is set to
     * @1.4::EmergencyNumberRouting#EMERGENCY. This radio request will not be sent on an inactive
     * (PIN/PUK locked) subscription unless both subscriptions are PIN/PUK locked. In this case,
     * the request will be sent on the primary subscription.
     *
     * Some countries or carriers require some emergency numbers that must be handled with normal
     * call routing if possible or emergency routing. 1) if the 'routing' field is specified as
     * @1.4::EmergencyNumberRouting#NORMAL, the implementation must try the full radio service to
     * use normal call routing to handle the call; if service cannot support normal routing, the
     * implementation must use emergency routing to handle the call. 2) if 'routing' is specified
     * as @1.4::EmergencyNumberRouting#EMERGENCY, the implementation must use emergency routing to
     * handle the call. 3) if 'routing' is specified as @1.4::EmergencyNumberRouting#UNKNOWN,
     * Android does not know how to handle the call.
     *
     * If the dialed emergency number does not have a specified emergency service category, the
     * 'categories' field is set to @1.4::EmergencyServiceCategory#UNSPECIFIED; if the dialed
     * emergency number does not have specified emergency Uniform Resource Names, the 'urns' field
     * is set to an empty list. If the underlying technology used to request emergency services
     * does not support the emergency service category or emergency uniform resource names, the
     * field 'categories' or 'urns' may be ignored.
     *
     * In the scenarios that the 'address' in the 'dialInfo' field has other functions besides the
     * emergency number function, if the 'hasKnownUserIntentEmergency' field is true, the user's
     * intent for this dial request is emergency call, and the modem must treat this as an actual
     * emergency dial; if the 'hasKnownUserIntentEmergency' field is false, Android does not know
     * user's intent for this call.
     *
     * If 'isTesting' is true, this request is for testing purpose, and must not be sent to a real
     * emergency service; otherwise it's for a real emergency call request.
     *
     * Reference: 3gpp 22.101, Section 10 - Emergency Calls;
     *            3gpp 23.167, Section 6 - Functional description;
     *            3gpp 24.503, Section 5.1.6.8.1 - General;
     *            RFC 5031
     *
     * @param serial Serial number of request.
     * @param dialInfo the same @1.0::Dial information used by @1.0::IRadio.dial.
     * @param categories bitfield<@1.4::EmergencyServiceCategory> the Emergency Service Category(s)
     *     of the call.
     * @param urns the emergency Uniform Resource Names (URN)
     * @param routing @1.4::EmergencyCallRouting the emergency call routing information.
     * @param hasKnownUserIntentEmergency Flag indicating if user's intent for the emergency call
     *     is known.
     * @param isTesting Flag indicating if this request is for testing purpose.
     *
     * Response function is IRadioResponse.emergencyDialResponse()
     */
    oneway emergencyDial_1_6(int32_t serial, Dial dialInfo,
            bitfield<EmergencyServiceCategory> categories, vec<string> urns,
            EmergencyCallRouting routing, bool hasKnownUserIntentEmergency, bool isTesting);

    /**
     * Get which bands the modem's background scan is acting on.
     *
     * @param serial Serial number of request.
     *
     * Response callback is IRadioResponse.getSystemSelectionChannelsResponse()
     */
    oneway getSystemSelectionChannels(int32_t serial);

   /**
     * Request all of the current cell information known to the radio. The radio
     * must return list of all current cells, including the neighboring cells. If for a particular
     * cell information isn't known then the appropriate unknown value will be returned.
     * This does not cause or change the rate of unsolicited cellInfoList().
     *
     * This is identical to getCellInfoList in V1.0, but it requests updated version of CellInfo.
     *
     * @param serial Serial number of request.
     *
     * Response callback is IRadioResponse.getCellInfoListResponse()
     */
    oneway getCellInfoList_1_6(int32_t serial);

    /**
     * Request current voice registration state.
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.getVoiceRegistrationStateResponse_1_6()
     */
    oneway getVoiceRegistrationState_1_6(int32_t serial);

    /**
     * Requests current signal strength and associated information.  Must succeed if radio is on.
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.getSignalStrengthResponse_1_6()
     */
    oneway getSignalStrength_1_6(int32_t serial);

    /**
     * Request current data registration state.
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.getDataRegistrationStateResponse_1_6()
     */
    oneway getDataRegistrationState_1_6(int32_t serial);

    /**
     * Requests current call list
     *
     * @param serial Serial number of request.
     *
     * Response function is IRadioResponse.getCurrentCallsResponse_1_6()
     */
    oneway getCurrentCalls_1_6(int32_t serial);

    /**
     * Request to get the current slicing configuration including URSP rules and
     * NSSAIs (configured, allowed and rejected).
     * URSP stands for UE route selection policy and is defined in 3GPP TS 24.526
     * Section 4.2.
     * An NSSAI is a collection of network slices. Each network slice is identified by
     * an S-NSSAI and is represented by the struct SliceInfo. NSSAI and S-NSSAI
     * are defined in 3GPP TS 24.501.
     *
     * Response function is IRadioResponse.getSlicingConfigResponse()
     */
    oneway getSlicingConfig(int32_t serial);

    /**
     * Provide Carrier specific information to the modem that must be used to
     * encrypt the IMSI and IMPI. Sent by the framework during boot, carrier
     * switch and everytime the framework receives a new certificate.
     *
     * @param serial Serial number of request.
     * @param imsiEncryptionInfo ImsiEncryptionInfo as defined in types.hal.
     *
     * Response callback is
     * IRadioResponse.setCarrierInfoForImsiEncryptionResponse()
     *
     * Note this API is the same as the 1.1 version except using the 1.6 ImsiEncryptionInfo
     * as the input param.
     */
    oneway setCarrierInfoForImsiEncryption_1_6(int32_t serial, @1.6::ImsiEncryptionInfo imsiEncryptionInfo);
};