[libc] Add initial support for 'puts' and 'fputs' to the GPU

[jhuber6]

Summary

This patch adds the initial support required to support basic priting in
stdio.h via puts and fputs. This is done using the existing LLVM C
library File API. In this sense we can think of the RPC interface as
our system call to dump the character string to the file. We carry a
uintptr_t reference as our native "file descriptor" as it will be used
as an opaque reference to the host's version once functions like
fopen are supported.

For some unknown reason the declaration of the StdIn variable causes
both the AMDGPU and NVPTX backends to crash if I use the READ flag.
This is not used currently as we only support output now, but it needs
to be fixed

[jhuber6]

Fix the issue with stdin. This requires removing constexpr from this function and I'm unsure why it's problematic, maybe someone can help me understand why it would caue an infinite reference and crash the GPU backend.

Overall, the precense of all the buffering code in this implementation is detrimental to implementing this on the GPU. The register usage for puts is currently ~70 registers while the basic write_to_stderr is only ~25. There could be some discussions on how to best optionally disable the buffering, but as it stands I don't think the runtime configuration is enough. A templated class would be ideal, but then we'd have a hard time keeping compatibility with user's custom streams for the Linux case. Worst case scenario we have a separate implementation just for GPUs to use. It would be very short and unlikely to change so it might be the easiest solution rather than to force the other targets into this very specific mold.

[jhuber6]

Add the standard stream entrypoints

[jhuber6]

Updating. I decided that the most painless method would be to make a constexpr
function that the GPU can use to disable buffering features. This is a little
ugly, but not unreasonable I don't think. Previously a lot of buffering code was
either causing errors or leading to very inefficient implementations on the GPU.
Hopefully this is an acceptable amount of ugliness to implement these in
general.

For reference, the GPU doesn't support buffering for a few reasons. First, the
buffer is a global shared resource. This would require a functioning mutex which
the GPU does not have. In general locks on the GPU cannot be safely implemented
due to lack of forward progress guaruntees. I.e. one thread cannot depend on
another reliably. Even if they were to be implemented it would be undesireable
as the GPU is highly parallel with thousands of threads running at the same
time. Second, even if we did have a reliable lock, it would likely add a
significant amount of register pressure to the GPU kernel. It is quite easy to
run out of resources so we need to be sparse if possible.

Buffering in theory would be nice on the GPU as it could prevent us from
performing an RPC call in situations where the user needs to send less than 64
bits, but the rest of the cost is unlikely to make up for it.

[jhuber6]

A little uglier, need to completely suppress the custom destructor as making a no-op.

[tra]

In general locks on the GPU cannot be safely implemented due to lack of forward progress guaruntees.

I think sm_70+ does provide forward progress guarantees. This was one of the major architectural changes introduced on Volta.
https://docs.nvidia.com/cuda/volta-tuning-guide/index.html#independent-thread-scheduling

[jhuber6]

In D151282#4376876, @tra wrote:

In general locks on the GPU cannot be safely implemented due to lack of forward progress guaruntees.

I think sm_70+ does provide forward progress guarantees. This was one of the major architectural changes introduced on Volta.
https://docs.nvidia.com/cuda/volta-tuning-guide/index.html#independent-thread-scheduling

So, I believe what Volta added was forward progress guarantees within a warp. E.g. a warp cannot deadlock on itself because the threads within a warp can make independent progress. The OpenCL model is extremely pessimistic and offers absolutely zero forward progress guarantees. As far as I understand the underlying hardware is a different story. I haven't heard of any vendors guaranteeing forward progress, or a fair scheduler on the GPU globally. However, I think that Nvidia in general is on firmer ground here than AMD so it's less likely to be an issue there. The typical way to bypass this is to provide enough locks in parallel that an active warp / wavefront won't get blocked on any other active one. It's very wasteful but it's "safe". At least for the AMD case.

[lntue]

libc/src/__support/File/file.h

24

Since most of the usage of this constexpr function is kind of double-negative form if ( !buffer_disabled() ), I think it is better to define this as a static constexpr member of class File, and change the name to positive form like File::USE_BUFFER, File::ENABLE_BUFFER or something like that.

[jhuber6]

libc/src/__support/File/file.h

24

Yeah that might make it more readable. Is @sivachandra okay with this somewhat hacky workaround? We cannot compile otherwise due to the GPU backend's not allowing circular references, i.e. initializers that use offsets from itself. Also this gets the resource usage within acceptable levels.

[jhuber6]

Changing to a constexpr member variable with a positive check.

[lntue]

libc/src/__support/File/file.cpp

345

Shouldn't this be !ENABLE_BUFFER?

[jhuber6]

libc/src/__support/File/file.cpp

345

You're right, I'll fix it.

[jhuber6]

Fix

[sivachandra]

libc/src/__support/File/file.cpp

28

Can we repeat the order of conditionals so that the ENABLE_BUFFER is checked only once:

if (!ENABLE_BUFFER || bufmode == _IONBF) {
  ...
} else if (bufmode =_ _IOFBF) {
  ...
} else { // if (bufmode == _IOLBF)
  ...
}

327

Can we do an early return:

if constexpr (!ENABLE_BUFFER)
  return;

341

Same here:

if constexpr (!ENABLE_BUFFER)
  return;

libc/src/__support/File/gpu/dir.cpp

17

If they are just erroring out, why are they required?

[sivachandra]

libc/src/__support/File/file.h

54

Sorry, forgot to mention this in the earlier post: Just pointing out that files opened even with fopencookie will become unbuffered.

That we have new switch means we should add tests for it on non-GPU platforms also. So, one way would be to do something like this:

1. Add a compile option, say LIBC_COPT_UNBUFFERED_FILE and update this conditional to:

#if defined(LIBC_TARGET_ARCH_IS_GPU) || defined(LIBC_COPT_UNBUFFERED_FILE)

2. The above flag will allow to setup up a separate platform independent test only target for unbuffered files.
3. Add a test for unbuffered files which depends on the ubuffered file target.

[jhuber6]

libc/src/__support/File/file.h

54

It would be fine to have other users of unbuffered IO, maybe for a more minimal implementation.

libc/src/__support/File/gpu/dir.cpp

17

Wasn't sure if this was required for linking somewhere.

[jhuber6]

Addressing comments

[sivachandra]

libc/src/__support/File/file.cpp

39

line buffered

libc/src/__support/File/file.h

54

I agree that it is fine to have this switch. My comment about fopencookie was just FYI. But, to protect accidental regressions around this switch, I am suggesting that you should add a test for it even for non-GPU platforms.

188

Can you add a comment why?

libc/src/__support/File/gpu/dir.cpp

17

You are seeing some linker error if you don't add this file?

[jhuber6]

libc/src/__support/File/file.h

54

I'm not sure how to add a test on a non-GPU platform since it's a build-time thing.

libc/src/__support/File/gpu/dir.cpp

17

The CMake expects it currently so I just provide an empty file.

[jhuber6]

Address comments

libc/config/gpu/api.td

let Types = [
     "size_t",
     "__atexithandler_t",
   ];
 }
 
 def FenvAPI: PublicAPI<"fenv.h"> {
   let Types = ["fenv_t"];
 }
+
+def StdIOAPI : PublicAPI<"stdio.h"> {
+  let Macros = [
+    SimpleMacroDef<"_IOFBF", "0">,
+    SimpleMacroDef<"_IOLBF", "1">,
+    SimpleMacroDef<"_IONBF", "2">,
+    SimpleMacroDef<"EOF", "-1">,
+  ];
+  let Types = ["size_t", "FILE"];
+}

libc/config/gpu/entrypoints.txt

set(TARGET_LIBC_ENTRYPOINTS
     # Only implemented in the test suite
     libc.src.stdlib.malloc
     libc.src.stdlib.aligned_alloc
     libc.src.stdlib.realloc
     libc.src.stdlib.free
 
     # errno.h entrypoints
     libc.src.errno.errno
+
+    # stdio.h entrypoints
+    libc.src.stdio.puts
+    libc.src.stdio.fputs
+    libc.src.stdio.stdin
+    libc.src.stdio.stdout
+    libc.src.stdio.stderr
 )
 
 set(TARGET_LLVMLIBC_ENTRYPOINTS
   ${TARGET_LIBC_ENTRYPOINTS}
 )
 

libc/config/gpu/headers.txt

 set(TARGET_PUBLIC_HEADERS
     libc.include.ctype
     libc.include.string
     libc.include.fenv
     libc.include.errno
     libc.include.stdlib
+    libc.include.stdio
 )

libc/src/__support/File/file.h

 #include "src/__support/error_or.h"
 #include "src/__support/threads/mutex.h"
 
 #include <stddef.h>
 #include <stdint.h>
 
 namespace __llvm_libc {
 
+// Some platforms like the GPU build cannot support buffering due to extra
+// resource usage or hardware constraints. This function allows us to optimize
+// out the buffering portions of the code in the general implementation.
+constexpr bool buffer_disabled() {
+#if defined(LIBC_TARGET_ARCH_IS_GPU)
+  return true;
+#else
+  return false;
+#endif
+}
+
 struct FileIOResult {
   size_t value;
   int error;
 
   constexpr FileIOResult(size_t val) : value(val), error(0) {}
   constexpr FileIOResult(size_t val, int error) : value(val), error(error) {}
 
   constexpr bool has_error() { return error != 0; }
 
   constexpr operator size_t() { return value; }
 };
 
 // This a generic base class to encapsulate a platform independent file data
 // structure. Platform specific specializations should create a subclass as
 // suitable for their platform.
 class File {
 public:
   static constexpr size_t DEFAULT_BUFFER_SIZE = 1024;
 
   using LockFunc = void(File *);
   using UnlockFunc = void(File *);
 
   using WriteFunc = FileIOResult(File *, const void *, size_t);
   using ReadFunc = FileIOResult(File *, void *, size_t);
   // The SeekFunc is expected to return the current offset of the external
   // file position indicator.
   using SeekFunc = ErrorOr<long>(File *, long, int);
   using CloseFunc = int(File *);
   using FlushFunc = int(File *);
   // CleanupFunc is a function which does the equivalent of this:
   //
return mode & (static_cast<ModeFlags>(OpenMode::WRITE) |
                    static_cast<ModeFlags>(OpenMode::PLUS));
   }
 
   constexpr bool read_allowed() const {
     return mode & (static_cast<ModeFlags>(OpenMode::READ) |
                    static_cast<ModeFlags>(OpenMode::PLUS));
   }
 
   ~File() {
+    if constexpr (!buffer_disabled())
       if (own_buf)
         delete buf;
   }
 
 public:
   // We want this constructor to be constexpr so that global file objects
   // like stdout do not require invocation of the constructor which can
   // potentially lead to static initialization order fiasco. Consequently,
   // we will assume that the |buffer| and |buffer_size| argument are
   // meaningful - that is, |buffer| is nullptr if and only if |buffer_size|
   // is zero. This way, we will not have to employ the semantics of
   // the set_buffer method and allocate a buffer.
   constexpr File(WriteFunc *wf, ReadFunc *rf, SeekFunc *sf, CloseFunc *cf,
                  FlushFunc *ff, CleanupFunc *clf, uint8_t *buffer,
                  size_t buffer_size, int buffer_mode, bool owned,
                  ModeFlags modeflags)
       : platform_write(wf), platform_read(rf), platform_seek(sf),
         platform_close(cf), platform_flush(ff), platform_cleanup(clf),
         mutex(false, false, false), ungetc_buf(0), buf(buffer),
         bufsize(buffer_size), bufmode(buffer_mode), own_buf(owned),
         mode(modeflags), pos(0), prev_op(FileOp::NONE), read_limit(0),
         eof(false), err(false) {
+    if constexpr (!buffer_disabled())
       adjust_buf();
   }
 
   // Close |f| and cleanup resources held by it.
   // Returns the non-zero error value if an error occurs when closing the
   // file.
   static int cleanup(File *f) {
     int close_result = f->close();
     if (close_result != 0)

libc/src/__support/File/file.cpp

 FileIOResult File::write_unlocked(const void *data, size_t len) {
   if (!write_allowed()) {
     err = true;
     return {0, EBADF};
   }
 
   prev_op = FileOp::WRITE;
 
-  if (bufmode == _IOFBF) { // fully buffered
+  if (!buffer_disabled() && bufmode == _IOFBF) { // fully buffered
     return write_unlocked_fbf(static_cast<const uint8_t *>(data), len);
-  } else if (bufmode == _IOLBF) { // line buffered
+  } else if (!buffer_disabled() && bufmode == _IOLBF) { // line buffered
     return write_unlocked_lbf(static_cast<const uint8_t *>(data), len);
   } else /*if (bufmode == _IONBF) */ { // unbuffered
     size_t ret_val =
         write_unlocked_nbf(static_cast<const uint8_t *>(data), len);
     flush_unlocked();
     return ret_val;
   }
 }
 
 FileIOResult File::write_unlocked_nbf(const uint8_t *data, size_t len) {
-  if (pos > 0) { // If the buffer is not empty
+  if (!buffer_disabled() && pos > 0) { // If the buffer is not empty
     // Flush the buffer
     const size_t write_size = pos;
     auto write_result = platform_write(this, buf, write_size);
     pos = 0; // Buffer is now empty so reset pos to the beginning.
     // If less bytes were written than expected, then an error occurred.
     if (write_result < write_size) {
       err = true;
       // No bytes from data were written, so return 0.
ErrorOr<long> File::tell() {
   if (prev_op == FileOp::READ)
     return platform_offset - (read_limit - pos);
   else if (prev_op == FileOp::WRITE)
     return platform_offset + pos;
   else
     return platform_offset;
 }
 
 int File::flush_unlocked() {
-  if (prev_op == FileOp::WRITE && pos > 0) {
+  if (!buffer_disabled() && prev_op == FileOp::WRITE && pos > 0) {
     auto buf_result = platform_write(this, buf, pos);
     if (buf_result.has_error() || buf_result.value < pos) {
       err = true;
       return buf_result.error;
     }
     pos = 0;
     return platform_flush(this);
   }
   // TODO: Add POSIX behavior for input streams.
   return 0;
 }
 
 int File::set_buffer(void *buffer, size_t size, int buffer_mode) {
   // We do not need to lock the file as this method should be called before
   // other operations are performed on the file.
 
-  if (buffer != nullptr && size == 0)
+  if ((buffer != nullptr && size == 0) || buffer_disabled())
     return EINVAL;
 
   switch (buffer_mode) {
   case _IOFBF:
   case _IOLBF:
   case _IONBF:
     break;
   default:

libc/src/__support/File/gpu/CMakeLists.txt

+add_object_library(
+  gpu_file
+  SRCS
+    file.cpp
+  DEPENDS
+    libc.include.stdio
+    libc.src.errno.errno
+    libc.src.__support.CPP.new
+    libc.src.__support.error_or
+    libc.src.__support.File.file
+)
+
+add_object_library(
+  gpu_dir
+  SRCS
+    dir.cpp
+  DEPENDS
+    libc.src.errno.errno
+    libc.src.__support.error_or
+    libc.src.__support.File.dir
+)

libc/src/__support/File/gpu/dir.cpp

+//===--- GPU implementation of the Dir helpers ----------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/__support/File/dir.h"
+
+#include "src/__support/error_or.h"
+
+namespace __llvm_libc {
+
+ErrorOr<int> platform_opendir(const char *name) {
+  return __llvm_libc::Error(-1);
+}
+
+ErrorOr<size_t> platform_fetch_dirents(int fd, cpp::span<uint8_t> buffer) {
+  return __llvm_libc::Error(static_cast<int>(-1));
+}
+
+int platform_closedir(int fd) { return -1; }
+
+} // namespace __llvm_libc

libc/src/__support/File/gpu/file.cpp

+//===--- GPU specialization of the File data structure --------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/__support/File/file.h"
+
+#include "src/__support/RPC/rpc_client.h"
+#include "src/errno/libc_errno.h" // For error macros
+
+#include <stdio.h>
+
+namespace __llvm_libc {
+
+namespace {
+
+FileIOResult write_func(File *, const void *, size_t);
+FileIOResult read_func(File *, void *, size_t) { return -1; }
+ErrorOr<long> seek_func(File *, long, int) { return 0; }
+void cleanup_file(File *) { return; }
+int close_func(File *) { return -1; }
+int flush_func(File *) { return -1; }
+
+} // namespace
+
+class GPUFile : public File {
+  uintptr_t file;
+
+public:
+  constexpr GPUFile(uintptr_t file, File::ModeFlags modeflags)
+      : File(&write_func, &read_func, &seek_func, &close_func, flush_func,
+             &cleanup_file, nullptr, 0, _IONBF, false, modeflags),
+        file(file) {}
+
+  uintptr_t get_file() const { return file; }
+};
+
+namespace {
+
+int write_to_stdout(const void *data, size_t size) {
+  int ret = 0;
+  rpc::Client::Port port = rpc::client.open<rpc::WRITE_TO_STDOUT>();
+  port.send_n(data, size);
+  port.recv([&](rpc::Buffer *buffer) {
+    ret = reinterpret_cast<int *>(buffer->data)[0];
+  });
+  port.close();
+  return ret;
+}
+
+int write_to_stderr(const void *data, size_t size) {
+  int ret = 0;
+  rpc::Client::Port port = rpc::client.open<rpc::WRITE_TO_STDERR>();
+  port.send_n(data, size);
+  port.recv([&](rpc::Buffer *buffer) {
+    ret = reinterpret_cast<int *>(buffer->data)[0];
+  });
+  port.close();
+  return ret;
+}
+
+int write_to_stream(uintptr_t file, const void *data, size_t size) {
+  int ret = 0;
+  rpc::Client::Port port = rpc::client.open<rpc::WRITE_TO_STREAM>();
+  port.send([&](rpc::Buffer *buffer) {
+    reinterpret_cast<uintptr_t *>(buffer->data)[0] = file;
+  });
+  port.send_n(data, size);
+  port.recv([&](rpc::Buffer *buffer) {
+    ret = reinterpret_cast<int *>(buffer->data)[0];
+  });
+  port.close();
+  return ret;
+}
+
+FileIOResult write_func(File *f, const void *data, size_t size) {
+  auto *gpu_file = reinterpret_cast<GPUFile *>(f);
+  int ret = 0;
+  if (gpu_file == stdout)
+    ret = write_to_stdout(data, size);
+  else if (gpu_file == stderr)
+    ret = write_to_stderr(data, size);
+  else
+    ret = write_to_stream(gpu_file->get_file(), data, size);
+  if (ret < 0)
+    return {0, -ret};
+  return ret;
+}
+
+} // namespace
+
+static GPUFile StdIn(0UL, File::ModeFlags(File::OpenMode::READ));
+File *stdin = &StdIn;
+
+static GPUFile StdOut(0UL, File::ModeFlags(File::OpenMode::APPEND));
+File *stdout = &StdOut;
+
+static GPUFile StdErr(0UL, File::ModeFlags(File::OpenMode::APPEND));
+File *stderr = &StdErr;
+
+} // namespace __llvm_libc

libc/src/__support/RPC/rpc.h

 #include <stdint.h>
 
 namespace __llvm_libc {
 namespace rpc {
 
 /// A list of opcodes that we use to invoke certain actions on the server.
 enum Opcode : uint16_t {
   NOOP = 0,
-  PRINT_TO_STDERR = 1,
-  EXIT = 2,
-  TEST_INCREMENT = 3,
-  TEST_INTERFACE = 4,
-  TEST_STREAM = 5,
+  EXIT = 1,
+  WRITE_TO_STDOUT = 2,
+  WRITE_TO_STDERR = 3,
+  WRITE_TO_STREAM = 4,
+
+  // TODO: These should be internal and not exported.
+  PRINT_TO_STDERR = 5,
+  TEST_INCREMENT = 6,
+  TEST_INTERFACE = 7,
+  TEST_STREAM = 8,
 };
 
 /// A fixed size channel used to communicate between the RPC client and server.
 struct Buffer {
   uint64_t data[8];
 };
 static_assert(sizeof(Buffer) == 64, "Buffer size mismatch");
 

libc/test/src/stdio/CMakeLists.txt

add_libc_unittest(
   SRCS
     sscanf_test.cpp
   DEPENDS
     libc.src.stdio.sscanf
   LINK_LIBRARIES
     LibcFPTestHelpers
 )
 
-add_libc_unittest(
+add_libc_test(
   puts_test
   SUITE
     libc_stdio_unittests
   SRCS
     puts_test.cpp
   DEPENDS
     libc.src.stdio.puts
 )

libc/utils/gpu/loader/Server.h

void handle_server() {
 
   // Continue servicing the client until there is no work left and we return.
   for (;;) {
     auto port = server.try_open();
     if (!port)
       return;
 
     switch (port->get_opcode()) {
+    case rpc::Opcode::WRITE_TO_STREAM:
+    case rpc::Opcode::WRITE_TO_STDERR:
+    case rpc::Opcode::WRITE_TO_STDOUT: {
+      uint64_t sizes[rpc::MAX_LANE_SIZE] = {0};
+      void *strs[rpc::MAX_LANE_SIZE] = {nullptr};
+      FILE *files[rpc::MAX_LANE_SIZE] = {nullptr};
+      if (port->get_opcode() == rpc::Opcode::WRITE_TO_STREAM)
+        port->recv([&](rpc::Buffer *buffer, uint32_t id) {
+          files[id] = reinterpret_cast<FILE *>(buffer->data[0]);
+        });
+      port->recv_n(strs, sizes, [&](uint64_t size) { return new char[size]; });
+      port->send([&](rpc::Buffer *buffer, uint32_t id) {
+        FILE *file = port->get_opcode() == rpc::Opcode::WRITE_TO_STDOUT
+                         ? stdout
+                         : (port->get_opcode() == rpc::Opcode::WRITE_TO_STDERR
+                                ? stderr
+                                : files[id]);
+        int ret = fwrite(strs[id], sizes[id], 1, file);
+        reinterpret_cast<int *>(buffer->data)[0] = ret >= 0 ? sizes[id] : ret;
+      });
+      for (uint64_t i = 0; i < rpc::MAX_LANE_SIZE; ++i) {
+        if (strs[i])
+          delete[] reinterpret_cast<uint8_t *>(strs[i]);
+      }
+      break;
+    }
     case rpc::Opcode::PRINT_TO_STDERR: {
       uint64_t sizes[rpc::MAX_LANE_SIZE] = {0};
       void *strs[rpc::MAX_LANE_SIZE] = {nullptr};
       port->recv_n(strs, sizes, [&](uint64_t size) { return new char[size]; });
       port->send([](rpc::Buffer *) { /* void */ });
       for (uint64_t i = 0; i < rpc::MAX_LANE_SIZE; ++i) {
         if (strs[i]) {
           fwrite(strs[i], sizes[i], 1, stderr);