Define CAN bus HAL.
Bug: 135918744
Test: VTS (separate new change)
Change-Id: Ia4de5ee441834c7870e33481e982960a1593de28
diff --git a/automotive/can/1.0/Android.bp b/automotive/can/1.0/Android.bp
new file mode 100644
index 0000000..fe2a2be
--- /dev/null
+++ b/automotive/can/1.0/Android.bp
@@ -0,0 +1,20 @@
+// This file is autogenerated by hidl-gen -Landroidbp.
+
+hidl_interface {
+ name: "android.hardware.automotive.can@1.0",
+ root: "android.hardware",
+ vndk: {
+ enabled: true,
+ },
+ srcs: [
+ "types.hal",
+ "ICanBus.hal",
+ "ICanController.hal",
+ "ICanMessageListener.hal",
+ "ICloseHandle.hal",
+ ],
+ interfaces: [
+ "android.hidl.base@1.0",
+ ],
+ gen_java: true,
+}
diff --git a/automotive/can/1.0/ICanBus.hal b/automotive/can/1.0/ICanBus.hal
new file mode 100644
index 0000000..6ed89f3
--- /dev/null
+++ b/automotive/can/1.0/ICanBus.hal
@@ -0,0 +1,60 @@
+/*
+ * 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;
+
+import ICanMessageListener;
+import ICloseHandle;
+
+/**
+ * Represents a CAN bus interface that's up and configured.
+ *
+ * Configuration part is done in ICanController.
+ */
+interface ICanBus {
+ /**
+ * Send CAN message.
+ *
+ * @param message CAN message to send out
+ * @return result OK in the case of success
+ * PAYLOAD_TOO_LONG if the payload is too long
+ * INTERFACE_DOWN if the bus is down
+ * TRANSMISSION_FAILURE in case of transmission failure
+ */
+ send(CanMessage message) generates (Result result);
+
+ /**
+ * Requests HAL implementation to listen for specific CAN messages.
+ *
+ * HAL is responsible for maintaining listener set and sending out messages
+ * to each listener that matches given filter against received message.
+ *
+ * Empty filter list means no filtering. If two or more listeners requested
+ * different filters, HAL server must merge these to fulfill the superset of
+ * these filters. HAL must not send out a message to a listener which filter
+ * doesn't match given message id.
+ *
+ * If filtering is not supported at the hardware level (what's strongly
+ * recommended), it must be covered in the HAL.
+ *
+ * @param filter The set of requested filters
+ * @param listener The interface to receive the messages on
+ * @return result OK in the case of success
+ * INTERFACE_DOWN if the bus is down
+ * @return close A handle to call in order to remove the listener
+ */
+ listen(vec<CanMessageFilter> filter, ICanMessageListener listener)
+ generates (Result result, ICloseHandle close);
+};
diff --git a/automotive/can/1.0/ICanController.hal b/automotive/can/1.0/ICanController.hal
new file mode 100644
index 0000000..2c7494a
--- /dev/null
+++ b/automotive/can/1.0/ICanController.hal
@@ -0,0 +1,190 @@
+/*
+ * 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, a mean to express the domain of device address.
+ */
+ enum InterfaceType : uint8_t {
+ /**
+ * Virtual SocketCAN interface.
+ *
+ * The address is an interface name, such as vcan0. If the interface
+ * doesn't exist, HAL server must create it.
+ *
+ * Valid InterfaceIdentifier types:
+ * - address.
+ */
+ VIRTUAL,
+
+ /**
+ * Native SocketCAN interface.
+ *
+ * The address is an interface name, such as can0.
+ *
+ * Valid InterfaceIdentifier types:
+ * - address;
+ * - serialno.
+ */
+ SOCKETCAN,
+
+ /**
+ * Serial-based interface.
+ *
+ * The address is a patch to a device, such as /dev/ttyUSB0.
+ *
+ * Valid InterfaceIdentifier types:
+ * - address;
+ * - serialno.
+ */
+ SLCAN,
+
+ /**
+ * Proprietary interface, specific to the hardware system Android
+ * is running on. Instead of using address field, the interface is
+ * addressed with 0-based index.
+ *
+ * Valid InterfaceIdentifier types:
+ * - index
+ */
+ 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 address (interface name, device path) doesn't exist or there
+ * is no device with a given serial no.
+ */
+ BAD_ADDRESS,
+
+ /** Provided baud rate is not supported by the hardware. */
+ BAD_BAUDRATE,
+ };
+
+ /**
+ * Configuration of the (physical or virtual) CAN bus.
+ *
+ * ISO TP and CAN FD are currently not supported.
+ */
+ struct BusConfiguration {
+ /**
+ * 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.
+ */
+ string name;
+
+ /**
+ * Type of the hardware (or virtual) CAN interface.
+ */
+ InterfaceType iftype;
+
+ /**
+ * Identification of hardware interface to configure.
+ */
+ safe_union InterfaceIdentifier {
+ /**
+ * Interface name or other mean of identification of the specific
+ * interface port. Syntax depends on {@see iftype}, for details
+ * {@see InterfaceType}.
+ */
+ string address;
+
+ /**
+ * Numerical identifier of interface, used for InterfaceType#INDEXED.
+ */
+ uint8_t index;
+
+ /**
+ * Alternatively to providing {@see address}, 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,
+ * it gets selected.
+ *
+ * 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;
+ } interfaceId;
+
+ /**
+ * Baud rate for CAN communication.
+ *
+ * Typical baud rates are: 100000, 125000, 250000, 500000.
+ *
+ * For virtual interfaces this value is ignored.
+ */
+ uint32_t baudrate;
+ };
+
+ /**
+ * 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(BusConfiguration 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 BusConfiguration#name} to
+ * bring down
+ * @return success true in case of success, false otherwise
+ */
+ downInterface(string name) generates (bool success);
+};
diff --git a/automotive/can/1.0/ICanMessageListener.hal b/automotive/can/1.0/ICanMessageListener.hal
new file mode 100644
index 0000000..992d1c7
--- /dev/null
+++ b/automotive/can/1.0/ICanMessageListener.hal
@@ -0,0 +1,40 @@
+/*
+ * 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;
+
+/**
+ * CAN message listener.
+ */
+interface ICanMessageListener {
+ /**
+ * Called on received CAN message.
+ *
+ * The timestamp field of message struct is set to time when the message
+ * was received by the hardware. If it's not possible to fetch exact
+ * hardware time, this field should be set as early as possible to decrease
+ * potential time delta.
+ *
+ * @param message Received CAN message
+ */
+ onReceive(CanMessage message);
+
+ /**
+ * Called on error event.
+ *
+ * @param error Error type
+ */
+ onError(ErrorEvent error);
+};
diff --git a/automotive/can/1.0/ICloseHandle.hal b/automotive/can/1.0/ICloseHandle.hal
new file mode 100644
index 0000000..924c58b
--- /dev/null
+++ b/automotive/can/1.0/ICloseHandle.hal
@@ -0,0 +1,33 @@
+/*
+ * 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 generic close handle to remove a callback that doesn't need
+ * active interface.
+ *
+ * When close() is called OR when the interface is released, the underlying
+ * resources must be freed.
+ */
+interface ICloseHandle {
+ /**
+ * Closes the handle.
+ *
+ * The call must not fail and must be issued by the client at most once.
+ * Otherwise, the server must ignore subsequent calls.
+ */
+ close();
+};
diff --git a/automotive/can/1.0/types.hal b/automotive/can/1.0/types.hal
new file mode 100644
index 0000000..37877c6
--- /dev/null
+++ b/automotive/can/1.0/types.hal
@@ -0,0 +1,112 @@
+/*
+ * 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;
+
+/**
+ * CAN message ID.
+ *
+ * Does not include any flags like RTR nor ERR, only a plain 11-bit
+ * or 29-bit identifier, as defined in CAN 1.x/2.0x.
+ *
+ * Unused bits must be set to zero.
+ */
+typedef uint32_t CanMessageId;
+
+/**
+ * CAN message being sent or received.
+ */
+struct CanMessage {
+ CanMessageId id;
+
+ /**
+ * CAN message payload, as defined in CAN 1.x and CAN 2.x standards.
+ *
+ * The length of the payload vector directly translates to the length
+ * of the data frame (i.e. includes any padding bytes), so it may be in
+ * a range of:
+ * - 0-8 bytes for standard CAN;
+ * - up to 64 bytes for CAN FD.
+ * ISO TP is not supported directly for now.
+ */
+ vec<uint8_t> payload;
+
+ /**
+ * Time in nanoseconds since boot.
+ *
+ * Ignored for outgoing messages.
+ */
+ uint64_t timestamp;
+
+ /**
+ * A request to proactively pull certain data from other ECU in CAN network.
+ *
+ * For details please refer to CAN standard.
+ *
+ * If this flag is set, payload must be empty.
+ */
+ bool remoteTransmissionRequest;
+};
+
+/**
+ * Single filter rule for CAN messages.
+ *
+ * A filter is satisfied if:
+ * ((receivedId & mask) == (id & mask)) == !inverted
+ *
+ * In order for set of filters to match, at least one non-inverted filters must match (if there is
+ * one) and all inverted filters must match. In other words:
+ * - a single matching non-inverted filter makes the whole set matching;
+ * - a single non-matching inverted filter makes the whole set non-matching.
+ */
+struct CanMessageFilter {
+ CanMessageId id;
+ uint32_t mask;
+ bool inverted;
+};
+
+enum Result : uint8_t {
+ OK,
+ UNKNOWN_ERROR,
+ PAYLOAD_TOO_LONG,
+ INTERFACE_DOWN,
+ TRANSMISSION_FAILURE,
+ INVALID_ARGUMENTS,
+};
+
+/**
+ * @see ICanMessageListener#onError
+ */
+enum ErrorEvent : uint8_t {
+ UNKNOWN_ERROR,
+
+ /** A problem with CAN interface HW. */
+ HARDWARE_ERROR,
+
+ /** TX buffer overflow: client is sending too many packets. */
+ TX_OVERFLOW,
+
+ /** RX buffer overflow: client is not reading packets fast enough. */
+ RX_OVERFLOW,
+
+ /** Received malformed input. */
+ MALFORMED_INPUT,
+
+ /** Bus overload: there is too much traffic on the bus. */
+ BUS_OVERLOAD,
+
+ /** Bus error: shorted Hi/Lo line, bus off etc. */
+ BUS_ERROR,
+};