path: root/data-ipa-cfg-mgr/hal/inc/IOffloadManager.h

/*
 * Copyright (c) 2017, The Linux Foundation. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above
 *      copyright notice, this list of conditions and the following
 *      disclaimer in the documentation and/or other materials provided
 *      with the distribution.
 *    * Neither the name of The Linux Foundation nor the names of its
 *      contributors may be used to endorse or promote products derived
 *      from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
#ifndef _I_OFFLOAD_MANAGER_H_
#define _I_OFFLOAD_MANAGER_H_

/* External Includes */
#include <sys/types.h>

/* Internal Includes */
#include "OffloadStatistics.h"


class IOffloadManager {
public:
    enum RET {
        FAIL_TOO_MANY_PREFIXES = -6,
        FAIL_UNSUPPORTED = -5,
        FAIL_INPUT_CHECK = -4,
        FAIL_HARDWARE = -3,
        FAIL_UNNEEDED = -2,
        FAIL_TRY_AGAIN = -1,
        SUCCESS = 0,
        SUCCESS_DUPLICATE_CONFIG = 1,
        SUCCESS_NO_OP = 2,
        SUCCESS_OPTIMIZED = 3
    }; /* RET */

    enum IP_FAM {
        V4 = 0,
        V6 = 1,
        INVALID = 2
    }; /* IP_FAM */

    /* Overloading to use for addresses as well */
    typedef struct Prefix {
        IP_FAM fam;
        uint32_t v4Addr;
        uint32_t v4Mask;
        uint32_t v6Addr[4];
        uint32_t v6Mask[4];
    } prefix_t;

    /* ---------------------------- LIFECYCLE ------------------------------- */
    virtual ~IOffloadManager(){}

    /* ---------------------- ASYNC EVENT CALLBACKS ------------------------- */
    class IpaEventListener {
    public:
        enum StoppedReason {
            /**
             * Offload was stopped due to the configuration being removed via
             * setUpstreamParameters/removeDownstream.
             */
            REQUESTED,
            /**
             * Offload was stopped due to an internal (to IPA or modem) error.
             *
             * Statistics may be temporarily unavailable.
             */
            ERROR,
            /**
             * Offload was stopped because the upstream connection has
             * migrated to unsupported radio access technology.
             *
             * Statistics will still be available.
             */
            UNSUPPORTED
        }; /* StoppedReason */
        virtual ~IpaEventListener(){}
        /**
         * Called when Offload first begins to occur on any upstream and
         * tether interface pair.  It should be paired with an onOffloadStopped
         * call.
         */
        virtual void onOffloadStarted(){}
        /**
         * Called when Offload stops occurring on all upstream and tether
         * interface pairs.  It comes after a call to onOffloadStarted.
         *
         * @param reason Reason that Offload was stopped
         */
        virtual void onOffloadStopped(StoppedReason /* reason */){}
        /**
         * Called when the hardware can support Offload again.
         *
         * Any statistics that were previously unavailable, may be queried
         * again at this time.
         */
        virtual void onOffloadSupportAvailable(){}
        /**
         * Called when the limit set via setQuota has expired.
         *
         * It is implied that Offload has been stopped on all upstream and
         * tether interface pairs when this callback is called.
         */
        virtual void onLimitReached(){}
    }; /* IpaEventListener */

    /**
     * Request notifications about asynchronous events that occur in hardware.
     *
     * The calling client must be able to handle the callback on a separate
     * thread (i.e. their implementation of IpaEventListener must be thread
     * safe).
     *
     * @return SUCCESS iff callback successfully registered
     *
     * Remarks: This can't really be allowed to fail.
     */
    virtual RET registerEventListener(IpaEventListener* /* listener */) = 0;
    /**
     * Unregister a previously registered listener.
     *
     * @return SUCCESS iff callback successfully unregistered
     *         FAIL_INPUT_CHECK if callback was never registered
     */
    virtual RET unregisterEventListener(IpaEventListener* /* listener */) = 0;

    class ConntrackTimeoutUpdater {
    public:
        enum L4Protocol {
            TCP = 0,
            UDP = 1
        }; /* L4Protocol */
        typedef struct IpAddrPortPair {
            uint32_t ipAddr;
            uint16_t port;
        } ipAddrPortPair_t;
        typedef struct NatTimeoutUpdate {
            IpAddrPortPair src;
            IpAddrPortPair dst;
            L4Protocol proto;
        } natTimeoutUpdate_t;
        virtual ~ConntrackTimeoutUpdater(){}
        virtual void updateTimeout(NatTimeoutUpdate /* update */) {}
    }; /* ConntrackTimeoutUpdater */

    /**
     * Register a callback that may be called if the OffloadManager wants to
     * update the timeout value in conntrack of kernel.
     *
     * The calling client must be able to handle the callback on a separate
     * thread (i.e. their implementation of ConntrackTimeoutUpdater must be
     * thread safe)
     *
     * @return SUCCESS iff callback successfully registered
     *
     * Remarks: This can't really be allowed to fail
     */
    virtual RET registerCtTimeoutUpdater(ConntrackTimeoutUpdater* /* cb */) = 0;
    /**
     * Unregister a previously registered callback.
     *
     * @return SUCCESS iff callback successfully unregistered
     *         FAIL_INPUT_CHECK if callback was never registered
     */
    virtual RET unregisterCtTimeoutUpdater(ConntrackTimeoutUpdater* /* cb */) = 0;

    /* ----------------------------- CONFIG --------------------------------- */
    /**
     * Provide a file descriptor for use with conntrack library
     *
     * @param fd File Descriptor that has been opened and bound to groups
     * @param groups Groups (bit mask) that fd has been bound to
     *
     * @return SUCCESS iff IOffloadManager needed this file descriptor and
     *                 it was properly bound.
     *         FAIL_INPUT_CHECK if IOffloadManager needed this file descriptor
     *                          but it was found to not be properly bound
     *         FAIL_UNNEEDED if IOffloadManager determined that it does not need
     *                       a file descriptor bound to these groups.
     */
    virtual RET provideFd(int /* fd */, unsigned int /* group */) = 0;
    /**
     * Indicate that IOffloadManager <b>must</b> cease using all file
     * descriptors passed via provideFd API.
     *
     * After this call returns, the file descriptors will likely be closed by
     * the calling client.
     *
     * @return SUCCESS iff IOffloadManager has stopped using all file
     *                 descriptors
     *         FAIL_TRY_AGAIN if IOffloadManager needs more time with these
     *                        file descriptors before it can release them
     *
     * Remarks: Currently, it would be very difficult to handle a FAIL_TRY_AGAIN
     *          because HAL serivce does not own a thread outside of RPC
     *          Threadpool to reschedule this call.
     */
    virtual RET clearAllFds() = 0;
    /**
     * Query whether STA+AP offload is supported on this device.
     *
     * @return true if supported, false otherwise
     */
    virtual bool isStaApSupported() = 0;

    /* ------------------------------ ROUTE --------------------------------- */
    /**
     * Add a downstream prefix that <i>may</i> be forwarded.
     *
     * The Prefix may be an IPv4 or IPv6 address to signify which family can be
     * offloaded from the specified tether interface.  If the given IP family,
     * as determined by the Prefix, has a corresponding upstream configured,
     * then traffic should be forwarded between the two interfaces.
     *
     * Only traffic that has a downstream address within the specified Prefix
     * can be forwarded.  Traffic from the same downstream interface that falls
     * outside of the Prefix will be unaffected and can be forwarded iff it was
     * previously configured via a separate addDownstream call.
     *
     * If no upstream has been configured, then this information must be cached
     * so that offload may begin once an upstream is configured.
     *
     * This API does <b>not</b> replace any previously configured downstreams
     * and must be explicitly removed by calling removeDownstream or by clearing
     * the entire configuration by calling stopAllOffload.
     *
     * @return SUCCESS The new information was accepted
     *         FAIL_TOO_MANY_PREFIXES The hardware has already accepted the max
     *                                number of Prefixes that can be supported.
     *                                If offload is desired on this Prefix then
     *                                another must be removed first.
     *         FAIL_UNSUPPORTED The hardware cannot forward traffic from this
     *                          downstream interface and will never be able to.
     */
    virtual RET addDownstream(const char* /* downstream */,
            const Prefix& /* prefix */) = 0;
    /**
     * Remove a downstream Prefix that forwarding was previously requested for.
     *
     * The Prefix may be an IPv4 or IPv6 address.  Traffic outside of this
     * Prefix is not affected.
     *
     * @return SUCCESS iff forwarding was previously occurring and has been
     *                 stopped
     *         SUCCESS_NO_OP iff forwarding was not previously occurring and
     *                       therefore no action needed to be taken
     */
    virtual RET removeDownstream(const char* /* downstream */,
            const Prefix& /* prefix */) = 0;
    /**
     * Indicate that hardware should forward traffic from any configured
     * downstreams to the specified upstream.
     *
     * When iface is non-null and non-empty and v4Gw is valid, then any
     * currently configured or future configured IPv4 downstreams should be
     * forwarded to this upstream interface.
     *
     * When iface is non-null and non-empty and v6Gw is valid, then any
     * currently configured or future configured IPv6 downstreams should be
     * forwarded to this upstream interface.
     *
     * @param iface Upstream interface name.  Only one is needed because IPv4
     *              and IPv6 interface names are required to match.
     * @param v4Gw The address of the IPv4 Gateway on the iface
     * @param v6Gw The address of one of the IPv6 Gateways on the iface
     *
     * @return SUCCESS iff the specified configuration was applied
     *         SUCCESS_DUPLICATE_CONFIG if this configuration <i>exactly</i>
     *                                  matches a previously provided
     *                                  configuration.  This means that no
     *                                  action has to be taken, but, the
     *                                  configuration was previously accepted
     *                                  and applied.
     *         FAIL_UNSUPPORTED if hardware cannot support forwarding to this
     *                          upstream interface
     *
     * Remarks: This overrides any previously configured parameters
     */
    virtual RET setUpstream(const char* /* iface */, const Prefix& /* v4Gw */,
            const Prefix& /* v6Gw */) = 0;
    /**
     * All traffic must be returned to the software path and all configuration
     * (including provided file descriptors) must be forgotten.
     *
     * @return SUCCESS If all offload was successfully stopped and provided
     *                 file descriptors were released.
     *
     * Remarks: This can't really fail?
     */
    virtual RET stopAllOffload() = 0;

    /* --------------------------- STATS/POLICY ----------------------------- */
    /**
     * Instruct hardware to stop forwarding traffic and send a callback after
     * limit bytes have been transferred in either direction on this upstream
     * interface.
     *
     * @param upstream Upstream interface name that the limit should apply to
     * @param limit Bytes limit that can occur before action should be taken
     *
     * @return SUCCESS If the limit was successfully applied
     *         SUCCESS_OPTIMIZED If the limit was sufficiently high to be
     *                           interpreted as "no quota".
     *         FAIL_HARDWARE If the limit was rejected by the hardware
     *         FAIL_UNSUPPORTED If metering is not supported on this interface
     *         FAIL_TRY_AGAIN If this upstream has not been previously
     *                        configured to allow offload
     *                        (via setUpstreamParameters)
     */
    virtual RET setQuota(const char* /* upstream */, uint64_t /* limit */) = 0;
    /**
     * Query for statistics counters in hardware.
     *
     * This returns an aggregate of all hardware accelerated traffic which
     * has occurred on this upstream interface.
     *
     * @param upstream Interface on which traffic entered/exited
     * @param reset Whether hardware counters should reset after returning
     *              current statistics
     * @param ret Output variable where statistics are returned
     *
     * @return SUCCESS If the statistics were successfully populated in ret and
     *                 were successfully reset if requested.
     *         FAIL_TRY_AGAIN If the statistics are not currently available but
     *                        may be available later.  This may occur during
     *                        a subsystem restart.
     *         FAIL_UNSUPPORTED If statistics are not supported on this upstream
     */
    virtual RET getStats(const char* /* upstream */, bool /* reset */,
            OffloadStatistics& /* ret */) = 0;
}; /* IOffloadManager */
#endif /* _I_OFFLOAD_MANAGER_H_ */