2 files changed, 37 insertions, 20 deletions
diff --git a/qemu_pipe/include/qemu_pipe.h b/qemu_pipe/include/qemu_pipe.h
index 098749899..16486c087 100644
--- a/qemu_pipe/include/qemu_pipe.h
+++ b/qemu_pipe/include/qemu_pipe.h
@@ -28,10 +28,8 @@ extern "C" {
 // This file descriptor can be used as a standard pipe/socket descriptor.
 //
 // 'pipeName' is the name of the emulator service you want to connect to,
-// and should begin with 'pipe:' (e.g. 'pipe:camera' or 'pipe:opengles').
-// For backward compatibility, the 'pipe:' prefix can be omitted, and in
-// that case, qemu_pipe_open will add it for you.
-
+// and must begin with 'pipe:' (e.g. 'pipe:camera' or 'pipe:opengles').
+//
 // On success, return a valid file descriptor, or -1/errno on failure. E.g.:
 //
 // EINVAL  -> unknown/unsupported pipeName
diff --git a/qemu_pipe/qemu_pipe.cpp b/qemu_pipe/qemu_pipe.cpp
index beeccb07f..ca3b79578 100644
--- a/qemu_pipe/qemu_pipe.cpp
+++ b/qemu_pipe/qemu_pipe.cpp
@@ -34,9 +34,29 @@ using android::base::WriteFully;
 #  define  QEMU_PIPE_DEBUG(...)   (void)0
 #endif
 
+// Try to open a new Qemu fast-pipe. This function returns a file descriptor
+// that can be used to communicate with a named service managed by the
+// emulator.
+//
+// This file descriptor can be used as a standard pipe/socket descriptor.
+//
+// 'pipeName' is the name of the emulator service you want to connect to,
+// and must begin with 'pipe:' (e.g. 'pipe:camera' or 'pipe:opengles').
+//
+// On success, return a valid file descriptor, or -1/errno on failure. E.g.:
+//
+// EINVAL  -> unknown/unsupported pipeName
+// ENOSYS  -> fast pipes not available in this system.
+//
+// ENOSYS should never happen, except if you're trying to run within a
+// misconfigured emulator.
+//
+// You should be able to open several pipes to the same pipe service,
+// except for a few special cases (e.g. GSM modem), where EBUSY will be
+// returned if more than one client tries to connect to it.
 int qemu_pipe_open(const char* pipeName) {
     // Sanity check.
-    if (!pipeName) {
+    if (!pipeName || memcmp(pipeName, "pipe:", 5) != 0) {
         errno = EINVAL;
         return -1;
     }
@@ -50,24 +70,18 @@ int qemu_pipe_open(const char* pipeName) {
 
     // Write the pipe name, *including* the trailing zero which is necessary.
     size_t pipeNameLen = strlen(pipeName);
-    if (WriteFully(fd, pipeName, pipeNameLen + 1U)) {
-        return fd;
-    }
-
-    // now, add 'pipe:' prefix and try again
-    // Note: host side will wait for the trailing '\0' to start
-    // service lookup.
-    const char pipe_prefix[] = "pipe:";
-    if (WriteFully(fd, pipe_prefix, strlen(pipe_prefix)) &&
-            WriteFully(fd, pipeName, pipeNameLen + 1U)) {
-        return fd;
+    if (!WriteFully(fd, pipeName, pipeNameLen + 1U)) {
+        QEMU_PIPE_DEBUG("%s: Could not connect to %s pipe service: %s",
+                        __FUNCTION__, pipeName, strerror(errno));
+        close(fd);
+        return -1;
     }
-    QEMU_PIPE_DEBUG("%s: Could not write to %s pipe service: %s",
-            __FUNCTION__, pipeName, strerror(errno));
-    close(fd);
-    return -1;
+    return fd;
 }
 
+// Send a framed message |buff| of |len| bytes through the |fd| descriptor.
+// This really adds a 4-hexchar prefix describing the payload size.
+// Returns 0 on success, and -1 on error.
 int qemu_pipe_frame_send(int fd, const void* buff, size_t len) {
     char header[5];
     snprintf(header, sizeof(header), "%04zx", len);
@@ -82,6 +96,11 @@ int qemu_pipe_frame_send(int fd, const void* buff, size_t len) {
     return 0;
 }
 
+// Read a frame message from |fd|, and store it into |buff| of |len| bytes.
+// If the framed message is larger than |len|, then this returns -1 and the
+// content is lost. Otherwise, this returns the size of the message. NOTE:
+// empty messages are possible in a framed wire protocol and do not mean
+// end-of-stream.
 int qemu_pipe_frame_recv(int fd, void* buff, size_t len) {
     char header[5];
     if (!ReadFully(fd, header, 4)) {