binder: Add AIDL interfaces/parcelables for iorapd

Bug: 72170747
Change-Id: Icd3feebcd2342e66b63fbb0c0e8f08bade618c76
Test: atest frameworks/base/startop/iorap

12 files changed, 414 insertions, 0 deletions

diff --git a/Android.bp b/Android.bp
new file mode 100644
index 0000000..481cd33
--- /dev/null
+++ b/Android.bp
@@ -0,0 +1,26 @@
+// Copyright (C) 2018 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.
+
+filegroup {
+    name: "iorap-aidl",
+    srcs: [
+        // note: using **/* doesn't work, so list each file one by one:
+        // see also b/70046217
+
+        // note: list only 'interface' aidl files, otherwise
+        // aidl generates an error "Refusing to generate code with unstructured parcelables."
+        "binder/com/google/android/startop/iorap/IIorap.aidl",
+        "binder/com/google/android/startop/iorap/ITaskListener.aidl",
+    ],
+}
diff --git a/binder/com/google/android/startop/iorap/AppIntentEvent.aidl b/binder/com/google/android/startop/iorap/AppIntentEvent.aidl
new file mode 100644
index 0000000..dbf1d02
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/AppIntentEvent.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable AppIntentEvent cpp_header "binder/app_intent_event.h";
diff --git a/binder/com/google/android/startop/iorap/IIorap.aidl b/binder/com/google/android/startop/iorap/IIorap.aidl
new file mode 100644
index 0000000..2b58905
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/IIorap.aidl
@@ -0,0 +1,114 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+import com.google.android.startop.iorap.ITaskListener;
+
+import com.google.android.startop.iorap.PackageEvent;
+import com.google.android.startop.iorap.AppIntentEvent;
+import com.google.android.startop.iorap.SystemServiceEvent;
+import com.google.android.startop.iorap.SystemServiceUserEvent;
+import com.google.android.startop.iorap.RequestId;
+
+/**
+* IIOrap is a client interface to the input/output readahead and pin daemon (iorapd).
+*
+* The aim is to speed-up the cold start-up time of certain use-cases like application startup
+* by utilizing trace-based pinning or readahead.
+*
+* Programatically, the behavior of iorapd should be treated like a black box. There is no
+* "correctness", but only performance. By sending the right events at the appropriate time,
+* we can squeeze more performance out of the system.
+*
+* If some events are not appropriately wired up, system performance may (temporarily) degrade.
+*
+* {@hide} */
+oneway interface IIorap {
+   /**
+    * Set an ITaskListener which will be used to deliver notifications of in-progress/completition
+    * for the onXEvent method calls below this.<br /><br />
+    *
+    * iorapd does all the work asynchronously and may deliver one or more onProgress events after
+    * the event begins to be processed. It will always send back one onComplete that is considered
+    * terminal.<br /><br />
+    *
+    * onProgress/onComplete are matched to the original event by the requestId. Once an onComplete
+    * occurs for any given requestId, no further callbacks with the same requestId will occur.
+    * It is illegal for the caller to reuse the same requestId on different invocations of IIorap.
+    * <br /><br />
+    *
+    * onXEvent(id1) must be well-ordered w.r.t. onXEvent(id2), the assumption is that later
+    * calls happen-after earlier calls and that id2 > id1. Decreasing request IDs will
+    * immediately get rejected.
+    * <br /><br />
+    *
+    * Sequence diagram of stereotypical successful event delivery and response notification:
+    *
+    * <pre>
+    *
+    *           ┌─────────────┐                ┌──────┐
+    *           │system_server│                │iorapd│
+    *           └──────┬──────┘                └──┬───┘
+    *                  Request [01]: onSomeEvent ┌┴┐
+    *                  │────────────────────────>│ │
+    *                  │                         │ │
+    *                  │                         │ │  ╔════════════════════════╗
+    *                  │                         │ │  ║start processing event ░║
+    *                  │                         │ │  ╚════════════════════════╝
+    *                  │                         │ │
+    * ╔═══════╤════════╪═════════════════════════╪═╪══════════════════════════════╗
+    * ║ LOOP  │  1 or more times                 │ │                              ║
+    * ╟───────┘        │                         │ │                              ║
+    * ║                │Request [01]: onProgress │ │                              ║
+    * ║                │<────────────────────────│ │                              ║
+    * ║                │                         │ │                              ║
+    * ║                │                         │ │────┐                         ║
+    * ║                │                         │ │    │ workload in progress    ║
+    * ║                │                         │ │<───┘                         ║
+    * ╚════════════════╪═════════════════════════╪═╪══════════════════════════════╝
+    *                  │                         └┬┘
+    *                  .                          .
+    *                  .                          .
+    *                  .                          .
+    *                  .                          .
+    *                  .                          .
+    *                  │                         ┌┴┐  ╔═════════════════════════╗
+    *                  │                         │ │  ║finish processing event ░║
+    *                  │                         │ │  ╚═════════════════════════╝
+    *                  │Request [01]: onComplete │ │
+    *                  │<────────────────────────│ │
+    *           ┌──────┴──────┐                ┌─└┬┘──┐
+    *           │system_server│                │iorapd│
+    *           └─────────────┘                └──────┘
+    *
+    * </pre> <!-- system/iorap/docs/binder/IIorap_setTaskListener.plantuml -->
+    */
+    void setTaskListener(ITaskListener listener);
+
+    // All callbacks will be done via the ITaskListener.
+    // The RequestId passed in is the same RequestId sent back via the ITaskListener.
+    // See above for more details.
+
+    // Note: For each ${Type}Event, see the ${Type}Event.java for more documentation
+    // in frameworks/base/startop/src/com/google/android/startop/iorap/${Type}Event.java
+
+    // void onActivityHintEvent(in RequestId request, in ActivityHintEvent event);
+    void onPackageEvent(in RequestId request, in PackageEvent event);
+    void onAppIntentEvent(in RequestId request, in AppIntentEvent event);
+    void onSystemServiceEvent(in RequestId request, in SystemServiceEvent event);
+    void onSystemServiceUserEvent(in RequestId request, in SystemServiceUserEvent event);
+}
diff --git a/binder/com/google/android/startop/iorap/ITaskListener.aidl b/binder/com/google/android/startop/iorap/ITaskListener.aidl
new file mode 100644
index 0000000..0b5f4a6
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/ITaskListener.aidl
@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+import com.google.android.startop.iorap.TaskResult;
+import com.google.android.startop.iorap.RequestId;
+
+/**
+* Provide callbacks to the {@code IIorap} client in response to method invocations.<br /><br />
+*
+* @see com.google.android.startop.iorap.IIorap
+*
+* {@hide} */
+oneway interface ITaskListener {
+    void onProgress(in RequestId requestId, in TaskResult result);
+    void onComplete(in RequestId requestId, in TaskResult result);
+}
+
+// TODO: we can probably delete the multiple methods. one is likely sufficient?
diff --git a/binder/com/google/android/startop/iorap/PackageEvent.aidl b/binder/com/google/android/startop/iorap/PackageEvent.aidl
new file mode 100644
index 0000000..8f9d18e
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/PackageEvent.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable PackageEvent cpp_header "binder/package_event.h";
diff --git a/binder/com/google/android/startop/iorap/RequestId.aidl b/binder/com/google/android/startop/iorap/RequestId.aidl
new file mode 100644
index 0000000..895af87
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/RequestId.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable RequestId cpp_header "binder/request_id.h";
diff --git a/binder/com/google/android/startop/iorap/SystemServiceEvent.aidl b/binder/com/google/android/startop/iorap/SystemServiceEvent.aidl
new file mode 100644
index 0000000..005676f
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/SystemServiceEvent.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable SystemServiceEvent cpp_header "binder/system_service_event.h";
diff --git a/binder/com/google/android/startop/iorap/SystemServiceUserEvent.aidl b/binder/com/google/android/startop/iorap/SystemServiceUserEvent.aidl
new file mode 100644
index 0000000..c165dc4
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/SystemServiceUserEvent.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable SystemServiceUserEvent cpp_header "binder/system_service_user_event.h";
diff --git a/binder/com/google/android/startop/iorap/TaskResult.aidl b/binder/com/google/android/startop/iorap/TaskResult.aidl
new file mode 100644
index 0000000..76cce8f
--- /dev/null
+++ b/binder/com/google/android/startop/iorap/TaskResult.aidl
@@ -0,0 +1,20 @@
+/*
+ * Copyright (C) 2018 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 com.google.android.startop.iorap;
+
+/** @hide */
+parcelable TaskResult cpp_header "binder/task_result.h";
diff --git a/docs/binder/ActivityHint.dot b/docs/binder/ActivityHint.dot
new file mode 100644
index 0000000..94b5a84
--- /dev/null
+++ b/docs/binder/ActivityHint.dot
@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2018 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.
+ */
+
+/**
+ * Convert with `graph-easy --as=boxart` to get textual rendering.
+ */
+digraph finite_state_machine {
+rankdir=LR;
+size="8,5"
+node [shape = circle ]; STARTED;
+node [shape = doublecircle];
+
+"" -> STARTED;
+STARTED -> CANCELLED;
+STARTED -> COMPLETED;
+COMPLETED -> POST_COMPLETED;
+COMPLETED -> CANCELLED;
+}
diff --git a/docs/binder/IIorap_setTaskListener.plantuml b/docs/binder/IIorap_setTaskListener.plantuml
new file mode 100644
index 0000000..5cdfac7
--- /dev/null
+++ b/docs/binder/IIorap_setTaskListener.plantuml
@@ -0,0 +1,53 @@
+@startuml
+' Copyright (C) 2018 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.
+
+' Compile with PlantUML:
+' http://www.plantuml.com/plantuml/uml/
+
+
+'hide footbox
+
+participant "system_server" as ss
+participant iorapd
+
+autonumber 1 0 "Request [00]:"
+
+ss -\ iorapd : onSomeEvent
+activate iorapd
+note right of iorapd
+  start processing event
+end note
+
+loop 1 or more times
+iorapd -\ ss : onProgress
+
+autonumber stop
+iorapd -> iorapd : workload in progress
+autonumber resume
+
+end
+
+' some time later...
+... ...
+
+note right of iorapd
+  finish processing event
+end note
+
+
+iorapd -\ ss : onComplete
+
+deactivate iorapd
+@enduml
diff --git a/docs/binder/TaskResult.dot b/docs/binder/TaskResult.dot
new file mode 100644
index 0000000..28d7819
--- /dev/null
+++ b/docs/binder/TaskResult.dot
@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2018 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.
+ */
+
+/**
+ * Convert with `graph-easy --as=boxart` to get textual rendering.
+ */
+digraph finite_state_machine {
+rankdir=LR;
+size="8,5"
+node [shape = circle ]; BEGAN ONGOING;
+node [shape = doublecircle];
+
+// graph-easy does not support multiple state syntax {}, write one-by-one
+
+"" -> BEGAN;
+"" -> ERROR;
+BEGAN -> ERROR;
+ONGOING -> ERROR;
+
+BEGAN -> ONGOING;
+BEGAN -> COMPLETED;
+ONGOING -> COMPLETED;
+
+}