hipFile file registration

Before performing any I/O on a file, the file must be registered with hipFile through hipFileHandleRegister().

File registration is required before any call to hipFileRead() or hipFileWrite(). hipFileHandleRegister() takes a descriptor of type hipFileDescr_t that specifies the handle type. It returns a file handle that is then passed to hipFileRead() and hipFileWrite().

For example, the roundtrip-verify.cpp example first calls open_file() from examples_common.cpp before calling hipFileWrite():

if (open_file(created_path, O_WRONLY | O_CREAT | O_TRUNC | O_DIRECT,
      S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH, &fd, &handle)) {
    goto deregister_buf;

    [...]

    nbytes = hipFileWrite(handle, devbuf, alloc_size, /*file_offset=*/0, /*buf_offset=*/0);

open_file() calls hipFileHandleRegister():

int open_file(const char *path, int flags, mode_t mode, int *fd, hipFileHandle_t *handle)
{
  *fd = open(path, flags, mode);
  if (-1 == *fd) {
      fprintf(stderr, "Could not open %s (%s)\n", path, strerror(errno));
      return 1;
  }

  hipFileDescr_t descr{};
  descr.type      = hipFileHandleTypeOpaqueFD;
  descr.handle.fd = *fd;

  hipFileError_t hipfile_err = hipFileHandleRegister(handle, &descr);
  if (hipFileSuccess != hipfile_err.err) {
      fprintf(stderr, "Could not register %s (%s)\n", path, hipFileGetOpErrorString(hipfile_err.err));
      close(*fd);
      return 1;
  }

  return 0;
}

Two file descriptors, a buffered file descriptor and an unbuffered file descriptor, are kept for the registered file. The unbuffered descriptor is used by the fastpath backend and the buffered descriptor is used by the fallback backend.

If the file doesn’t support direct I/O and was not opened with O_DIRECT, the unbuffered descriptor will not be available and fastpath will decline the I/O request. For more information on backend selection, see hipFile fastpath and fallback backends.

When the file handle is no longer needed, hipFileHandleDeregister() must be called to release the associated resources.