1/*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package [email protected];
17
18/**
19 * Represents a CAN controller that's capable of configuring CAN bus interfaces.
20 *
21 * The goal of this service is to configure CAN interfaces and bring up HIDL
22 * server instances of ICanBus for each one that's up.
23 *
24 * Providing an ICanController interface to configure CAN buses is optional.
25 * A system can elect to publish only ICanBus if the hardware is hardcoded
26 * for a specific application.
27 */
28interface ICanController {
29    /**
30     * Type of an interface, an equivalent to BusConfig::InterfaceId
31     * union discriminator. Defines a number of specific standard hardware
32     * families and a generic catch-all type of {@see INDEXED}.
33     */
34    enum InterfaceType : uint8_t {
35        /** Virtual SocketCAN interface. */
36        VIRTUAL,
37
38        /** Native SocketCAN interface. */
39        SOCKETCAN,
40
41        /** Serial line CAN interface. */
42        SLCAN,
43
44        /** Proprietary, device-specific interface. */
45        INDEXED,
46    };
47
48    enum Result : uint8_t {
49        OK,
50
51        /**
52         * General error class, if others are not applicable.
53         */
54        UNKNOWN_ERROR,
55
56        /**
57         * Up request was called out of order (i.e. trying to up the
58         * interface twice).
59         */
60        INVALID_STATE,
61
62        /** Interface type is not supported. */
63        NOT_SUPPORTED,
64
65        /**
66         * Provided interface ID (index, name, device path) doesn't exist or
67         * there is no device with a given serial number.
68         */
69        BAD_INTERFACE_ID,
70
71        /** Provided bit rate is not supported by the hardware. */
72        BAD_BITRATE,
73
74        /**
75         * Provided service name ({@see BusConfig#name}) either has invalid
76         * format or is not listed in device manifest file.
77         */
78        BAD_SERVICE_NAME,
79    };
80
81    /**
82     * Configuration of the (physical or virtual) CAN bus.
83     *
84     * ISO TP and CAN FD are currently not supported.
85     */
86    struct BusConfig {
87        /**
88         * Name under which ICanBus HIDL service should be published.
89         *
90         * It must consist of only alphanumeric characters and underscore
91         * (a-z, A-Z, 0-9, '_'), at least 1 and at most 32 characters long.
92         *
93         * This field is *not* meant to distinguish between hardware interfaces
94         * nor preselect parameters like bitrate. The only intended side-effect
95         * of changing it should be a different ICanBus HIDL service name and
96         * the HIDL service should make no assumptions on its contents.
97         */
98        string name;
99
100        /**
101         * Hardware interface configuration.
102         *
103         * This union's discriminator has an equivalent enum
104         * {@see InterfaceType} to express compatibility via
105         * getSupportedInterfaceTypes().
106         */
107        safe_union InterfaceId {
108            /** Virtual SocketCAN interface. */
109            struct Virtual {
110                /** Interface name, such as vcan0. If the interface doesn't
111                 * exist, HAL server must create it.
112                 */
113                string ifname;
114            } virtualif;
115
116            /** Native SocketCAN interface. */
117            safe_union Socketcan {
118                /** Interface name, such as can0. */
119                string ifname;
120                /**
121                 * Alternatively to providing {@see ifname}, one may provide a
122                 * list of interface serial number suffixes. If there happens to
123                 * be a device (like USB2CAN) with a matching serial number
124                 * suffix, the HAL service will have to select it.
125                 *
126                 * Client may utilize this in two ways: by matching against the
127                 * entire serial number, or the last few characters (usually
128                 * one). The former is better for small-scale test deployments
129                 * (with just a handful of vehicles), the latter is good for
130                 * larger scale (where a small suffix list may support large
131                 * test fleet).
132                 */
133                vec<string> serialno;
134            } socketcan;
135
136            /** Serial line CAN interface. */
137            safe_union Slcan {
138                /** Path to a device, such as /dev/ttyUSB0. */
139                string ttyname;
140                /**
141                 * List of interface serial number suffixes.
142                 * {@see Socketcan::serialno}
143                 */
144                vec<string> serialno;
145            } slcan;
146
147            /**
148             * Proprietary, device-specific interface.
149             *
150             * Non-SocketCAN interfaces should use this variant.
151             */
152            struct Indexed {
153                /** Interface number, 0-based. */
154                uint8_t index;
155            } indexed;
156        } interfaceId;
157
158        /**
159         * Bit rate for CAN communication.
160         *
161         * Typical bit rates are: 100000, 125000, 250000, 500000.
162         *
163         * For {@see interfaceId#virtual} and pre-configured
164         * {@see interfaceId#indexed} interfaces this value is ignored.
165         */
166        uint32_t bitrate;
167    };
168
169    /**
170     * Fetches the list of interface types supported by this HAL server.
171     *
172     * @return iftypes The list of supported interface types.
173     */
174    getSupportedInterfaceTypes() generates (vec<InterfaceType> iftypes);
175
176    /**
177     * Bring up the CAN interface and publish ICanBus server instance.
178     *
179     * @param config Configuration of the CAN interface.
180     * @return result OK if the operation succeeded; error code otherwise.
181     */
182    upInterface(BusConfig config) generates (Result result);
183
184    /**
185     * Unpublish ICanBus server instance and bring down the CAN interface.
186     *
187     * In case of failure, at least the ICanBus server instance must be
188     * unpublished and resources freed on best-effort basis.
189     *
190     * @param name Name of the interface (@see BusConfig#name} to
191     * bring down.
192     * @return success true in case of success, false otherwise.
193     */
194    downInterface(string name) generates (bool success);
195};
196