/*
 * Copyright (C) 2019 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.automotive.can@1.0;

/**
 * Represents a CAN controller that's capable of configuring CAN bus interfaces.
 *
 * The goal of this service is to configure CAN interfaces and bring up HIDL
 * server instances of ICanBus for each one that's up.
 *
 * Providing an ICanController interface to configure CAN buses is optional.
 * A system can elect to publish only ICanBus if the hardware is hardcoded
 * for a specific application.
 */
interface ICanController {
    /**
     * Type of an interface, an equivalent to BusConfig::InterfaceId
     * union discriminator. Defines a number of specific standard hardware
     * families and a generic catch-all type of {@see INDEXED}.
     */
    enum InterfaceType : uint8_t {
        /** Virtual SocketCAN interface. */
        VIRTUAL,

        /** Native SocketCAN interface. */
        SOCKETCAN,

        /** Serial line CAN interface. */
        SLCAN,

        /** Proprietary, device-specific interface. */
        INDEXED,
    };

    enum Result : uint8_t {
        OK,

        /**
         * General error class, if others are not applicable.
         */
        UNKNOWN_ERROR,

        /**
         * Up request was called out of order (i.e. trying to up the
         * interface twice).
         */
        INVALID_STATE,

        /** Interface type is not supported. */
        NOT_SUPPORTED,

        /**
         * Provided interface ID (index, name, device path) doesn't exist or
         * there is no device with a given serial number.
         */
        BAD_INTERFACE_ID,

        /** Provided bit rate is not supported by the hardware. */
        BAD_BITRATE,

        /**
         * Provided service name ({@see BusConfig#name}) either has invalid
         * format or is not listed in device manifest file.
         */
        BAD_SERVICE_NAME,
    };

    /**
     * Configuration of the (physical or virtual) CAN bus.
     *
     * ISO TP and CAN FD are currently not supported.
     */
    struct BusConfig {
        /**
         * Name under which ICanBus HIDL service should be published.
         *
         * It must consist of only alphanumeric characters and underscore
         * (a-z, A-Z, 0-9, '_'), at least 1 and at most 32 characters long.
         *
         * This field is *not* meant to distinguish between hardware interfaces
         * nor preselect parameters like bitrate. The only intended side-effect
         * of changing it should be a different ICanBus HIDL service name and
         * the HIDL service should make no assumptions on its contents.
         */
        string name;

        /**
         * Hardware interface configuration.
         *
         * This union's discriminator has an equivalent enum
         * {@see InterfaceType} to express compatibility via
         * getSupportedInterfaceTypes().
         */
        safe_union InterfaceId {
            /** Virtual SocketCAN interface. */
            struct Virtual {
                /** Interface name, such as vcan0. If the interface doesn't
                 * exist, HAL server must create it.
                 */
                string ifname;
            } virtualif;

            /** Native SocketCAN interface. */
            safe_union Socketcan {
                /** Interface name, such as can0. */
                string ifname;
                /**
                 * Alternatively to providing {@see ifname}, one may provide a
                 * list of interface serial number suffixes. If there happens to
                 * be a device (like USB2CAN) with a matching serial number
                 * suffix, the HAL service will have to select it.
                 *
                 * Client may utilize this in two ways: by matching against the
                 * entire serial number, or the last few characters (usually
                 * one). The former is better for small-scale test deployments
                 * (with just a handful of vehicles), the latter is good for
                 * larger scale (where a small suffix list may support large
                 * test fleet).
                 */
                vec<string> serialno;
            } socketcan;

            /** Serial line CAN interface. */
            safe_union Slcan {
                /** Path to a device, such as /dev/ttyUSB0. */
                string ttyname;
                /**
                 * List of interface serial number suffixes.
                 * {@see Socketcan::serialno}
                 */
                vec<string> serialno;
            } slcan;

            /**
             * Proprietary, device-specific interface.
             *
             * Non-SocketCAN interfaces should use this variant.
             */
            struct Indexed {
                /** Interface number, 0-based. */
                uint8_t index;
            } indexed;
        } interfaceId;

        /**
         * Bit rate for CAN communication.
         *
         * Typical bit rates are: 100000, 125000, 250000, 500000.
         *
         * For {@see interfaceId#virtual} and pre-configured
         * {@see interfaceId#indexed} interfaces this value is ignored.
         */
        uint32_t bitrate;
    };

    /**
     * Fetches the list of interface types supported by this HAL server.
     *
     * @return iftypes The list of supported interface types.
     */
    getSupportedInterfaceTypes() generates (vec<InterfaceType> iftypes);

    /**
     * Bring up the CAN interface and publish ICanBus server instance.
     *
     * @param config Configuration of the CAN interface.
     * @return result OK if the operation succeeded; error code otherwise.
     */
    upInterface(BusConfig config) generates (Result result);

    /**
     * Unpublish ICanBus server instance and bring down the CAN interface.
     *
     * In case of failure, at least the ICanBus server instance must be
     * unpublished and resources freed on best-effort basis.
     *
     * @param name Name of the interface (@see BusConfig#name} to
     * bring down.
     * @return success true in case of success, false otherwise.
     */
    downInterface(string name) generates (bool success);
};