/* * 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 /* 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 must 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 may 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 not 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 exactly * 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_ */