OrangeFS

OrangeFS의 성격과 역사

OrangeFS는 LGPL로 제공되는 사용자 공간 scale-out 병렬 스토리지 시스템입니다. HPC, BigData, 스트리밍 비디오, 유전체학과 생물정보학처럼 대규모 저장 문제를 다루는 환경에 적합합니다.

처음 이름은 PVFS였으며 Walt Ligon과 Eric Blumer가 1993년 NASA 연구 지원 아래 Parallel Virtual Machine(PVM)용 병렬 파일시스템으로 개발했습니다. 연구 목표는 병렬 프로그램의 I/O 패턴을 조사하는 것이었습니다. 이 역사 때문에 현재 사용자 공간 코드의 함수명과 변수명에도 `PVFS`가 남아 있습니다.

주요 특성은 여러 파일 서버에 파일 데이터를 분산하고, 여러 클라이언트의 동시 접근을 지원하며, 서버의 로컬 파일시스템과 접근 방법으로 데이터와 메타데이터를 저장한다는 점입니다. 사용자 공간 구현이라 설치와 유지보수가 쉽고, MPI를 직접 지원하며, 서버 측 프로토콜이 stateless 방식입니다.

원문은 개발 메일링 리스트 보관소, 제출 주소 `devel@lists.orangefs.org`, 공식 문서 사이트를 제공합니다.

.. SPDX-License-Identifier: GPL-2.0

========
ORANGEFS
========

OrangeFS is an LGPL userspace scale-out parallel storage system. It is ideal
for large storage problems faced by HPC, BigData, Streaming Video,
Genomics, Bioinformatics.

Orangefs, originally called PVFS, was first developed in 1993 by
Walt Ligon and Eric Blumer as a parallel file system for Parallel
Virtual Machine (PVM) as part of a NASA grant to study the I/O patterns
of parallel programs.

Orangefs features include:

  * Distributes file data among multiple file servers
  * Supports simultaneous access by multiple clients
  * Stores file data and metadata on servers using local file system
    and access methods
  * Userspace implementation is easy to install and maintain
  * Direct MPI support
  * Stateless


Mailing List Archives
=====================

http://lists.orangefs.org/pipermail/devel_lists.orangefs.org/


Mailing List Submissions
========================

devel@lists.orangefs.org


Documentation
=============

http://www.orangefs.org/documentation/

패키지로 단일 서버 구성

OrangeFS는 보통 여러 서버와 클라이언트가 있는 대규모 환경에서 실행하지만, 개발과 시험을 위해 한 시스템에서 완전한 파일시스템을 구성할 수 있습니다. Fedora에서는 `orangefs`와 `orangefs-server` 패키지를 설치합니다.

dnf -y install orangefs orangefs-server

예제 서버 설정은 `/etc/orangefs/orangefs.conf`에 있습니다. 필요하면 `localhost`를 실제 호스트 이름으로 바꿉니다. `/etc/pvfs2tab`에는 한 줄짜리 예제 클라이언트 설정이 있으며 주석을 해제하고 필요에 따라 호스트 이름을 수정합니다. 이 파일은 `libpvfs2`를 사용하는 클라이언트를 제어하지만 `pvfs2-client-core`는 제어하지 않습니다.

`pvfs2-server -f`로 파일시스템을 생성한 뒤 systemd로 서버를 시작하고 `pvfs2-ping`으로 확인합니다. 커널 모듈을 built-in으로 넣었거나 미리 적재한 상태에서 클라이언트를 시작하고, `pvfs2` 타입과 서버 URL을 지정하여 마운트합니다.

OrangeFS 2.9.3 이전 버전은 upstream 커널 클라이언트와 호환되지 않습니다. 사용자 공간 소스는 원문에 기재된 OrangeFS 다운로드 사이트에서 받을 수 있습니다.

Running ORANGEFS On a Single Server
===================================

OrangeFS is usually run in large installations with multiple servers and
clients, but a complete filesystem can be run on a single machine for
development and testing.

On Fedora, install orangefs and orangefs-server::

    dnf -y install orangefs orangefs-server

There is an example server configuration file in
/etc/orangefs/orangefs.conf.  Change localhost to your hostname if
necessary.

To generate a filesystem to run xfstests against, see below.

There is an example client configuration file in /etc/pvfs2tab.  It is a
single line.  Uncomment it and change the hostname if necessary.  This
controls clients which use libpvfs2.  This does not control the
pvfs2-client-core.

Create the filesystem::

    pvfs2-server -f /etc/orangefs/orangefs.conf

Start the server::

    systemctl start orangefs-server

Test the server::

    pvfs2-ping -m /pvfsmnt

Start the client.  The module must be compiled in or loaded before this
point::

    systemctl start orangefs-client

Mount the filesystem::

    mount -t pvfs2 tcp://localhost:3334/orangefs /pvfsmnt

Userspace Filesystem Source
===========================

http://www.orangefs.org/download

Orangefs versions prior to 2.9.3 would not be compatible with the
upstream version of the kernel client.

소스에서 단일 서버 빌드

배포판 패키지로 OrangeFS를 설치할 수 없다면 소스에서 빌드할 수 있습니다. `--prefix`를 생략하면 여러 파일이 `/usr/local` 아래에 배치됩니다. OrangeFS 2.9.6 시점의 기본 데이터베이스는 Berkeley DB이지만, 원문은 기본값이 향후 LMDB로 바뀔 가능성을 설명합니다.

./configure --prefix=/opt/ofs --with-db-backend=lmdb --disable-usrint
make
make install

`pvfs2-genconfig`에 대상 설정 파일을 지정하여 서버 설정을 만듭니다. 대화형 질문은 대체로 기본값을 사용해도 되지만 호스트 이름 질문에는 `localhost` 대신 서버의 실제 hostname을 사용하는 것이 좋습니다.

/opt/ofs/bin/pvfs2-genconfig /etc/pvfs2.conf

`/etc/pvfs2tab`에는 `localhost`를 사용해도 됩니다. 탭 파일에 지정한 `/pvfsmnt` 마운트 지점을 만들고, `pvfs2-server -f`로 서버 저장소를 초기화한 뒤 일반 모드로 서버를 시작합니다. `pvfs2-ls`로 서버 동작을 간단히 확인합니다.

시험이 성공하면 커널 모듈을 적재하고 `pvfs2-client`가 `pvfs2-client-core`를 실행하도록 합니다. 마지막으로 현재 `hostname`을 포함한 `tcp://<host>:3334/orangefs` 주소를 `pvfs2` 타입으로 마운트합니다.

Building ORANGEFS on a Single Server
====================================

Where OrangeFS cannot be installed from distribution packages, it may be
built from source.

You can omit --prefix if you don't care that things are sprinkled around
in /usr/local.  As of version 2.9.6, OrangeFS uses Berkeley DB by
default, we will probably be changing the default to LMDB soon.

::

    ./configure --prefix=/opt/ofs --with-db-backend=lmdb --disable-usrint

    make

    make install

Create an orangefs config file by running pvfs2-genconfig and
specifying a target config file. Pvfs2-genconfig will prompt you
through. Generally it works fine to take the defaults, but you
should use your server's hostname, rather than "localhost" when
it comes to that question::

    /opt/ofs/bin/pvfs2-genconfig /etc/pvfs2.conf

Create an /etc/pvfs2tab file (localhost is fine)::

    echo tcp://localhost:3334/orangefs /pvfsmnt pvfs2 defaults,noauto 0 0 > \
        /etc/pvfs2tab

Create the mount point you specified in the tab file if needed::

    mkdir /pvfsmnt

Bootstrap the server::

    /opt/ofs/sbin/pvfs2-server -f /etc/pvfs2.conf

Start the server::

    /opt/ofs/sbin/pvfs2-server /etc/pvfs2.conf

Now the server should be running. Pvfs2-ls is a simple
test to verify that the server is running::

    /opt/ofs/bin/pvfs2-ls /pvfsmnt

If stuff seems to be working, load the kernel module and
turn on the client core::

    /opt/ofs/sbin/pvfs2-client -p /opt/ofs/sbin/pvfs2-client-core

Mount your filesystem::

    mount -t pvfs2 tcp://`hostname`:3334/orangefs /pvfsmnt

xfstests용 scratch 파일시스템

`xfstests`를 실행할 때는 별도의 scratch 파일시스템을 사용하는 것이 유용하며 단일 서버에서도 구성할 수 있습니다. `/etc/orangefs/orangefs.conf`의 `FileSystem` 구역을 하나 더 복사하고 이름을 `scratch`로 바꿉니다. 새 구역의 ID는 첫 파일시스템과 다른 값이어야 하며 보통 2가 적절합니다.

변경 뒤에는 `orangefs`와 `scratch` 두 `FileSystem` 구역이 존재합니다. 이 수정은 `pvfs2-server -f /etc/orangefs/orangefs.conf`로 파일시스템을 생성하기 전에 해야 합니다.

`/etc/xfsqa.config`에서 기본 시험 디렉터리와 장치를 `orangefs`에, scratch 마운트 지점과 장치를 `scratch`에 연결합니다. 그런 다음 `./check -pvfs2`로 xfstests를 실행합니다.

Running xfstests
================

It is useful to use a scratch filesystem with xfstests.  This can be
done with only one server.

Make a second copy of the FileSystem section in the server configuration
file, which is /etc/orangefs/orangefs.conf.  Change the Name to scratch.
Change the ID to something other than the ID of the first FileSystem
section (2 is usually a good choice).

Then there are two FileSystem sections: orangefs and scratch.

This change should be made before creating the filesystem.

::

    pvfs2-server -f /etc/orangefs/orangefs.conf

To run xfstests, create /etc/xfsqa.config::

    TEST_DIR=/orangefs
    TEST_DEV=tcp://localhost:3334/orangefs
    SCRATCH_MNT=/scratch
    SCRATCH_DEV=tcp://localhost:3334/scratch

Then xfstests can be run::

    ./check -pvfs2

마운트 옵션과 GOSSIP 디버깅

OrangeFS가 받는 마운트 옵션은 `acl`, `intr`, `local_lock`입니다. `acl`은 파일과 디렉터리에서 Access Control List 사용을 허용합니다. `intr`은 디버그 수준 변경이나 tunable parameter 설정처럼 커널 클라이언트와 사용자 공간 파일시스템 사이의 일부 작업을 중단 가능하게 합니다.

`local_lock`은 현재 커널 관점의 POSIX 잠금을 활성화합니다. 기본 `file_operations` 잠금 동작은 `ENOSYS`를 반환하지만 `-o local_lock`으로 마운트하면 POSIX 잠금이 동작합니다. 분산 잠금은 향후 기능으로 개발 중입니다.

특정 소스 파일의 GOSSIP 디버그 메시지를 syslog로 보내려면 `/sys/kernel/debug/orangefs/kernel-debug`에 키워드를 씁니다. `inode`는 `inode.c`, `inode,dir`은 여러 소스, `all`은 전체 디버깅을 활성화합니다. 기본값인 `none`은 디버깅을 끕니다. 지원 키워드 목록은 `/sys/kernel/debug/orangefs/debug-help`에서 읽습니다.

Options
=======

The following mount options are accepted:

  acl
    Allow the use of Access Control Lists on files and directories.

  intr
    Some operations between the kernel client and the user space
    filesystem can be interruptible, such as changes in debug levels
    and the setting of tunable parameters.

  local_lock
    Enable posix locking from the perspective of "this" kernel. The
    default file_operations lock action is to return ENOSYS. Posix
    locking kicks in if the filesystem is mounted with -o local_lock.
    Distributed locking is being worked on for the future.


Debugging
=========

If you want the debug (GOSSIP) statements in a particular
source file (inode.c for example) go to syslog::

  echo inode > /sys/kernel/debug/orangefs/kernel-debug

No debugging (the default)::

  echo none > /sys/kernel/debug/orangefs/kernel-debug

Debugging from several source files::

  echo inode,dir > /sys/kernel/debug/orangefs/kernel-debug

All debugging::

  echo all > /sys/kernel/debug/orangefs/kernel-debug

Get a list of all debugging keywords::

  cat /sys/kernel/debug/orangefs/debug-help

커널 모듈과 사용자 공간 프로토콜

OrangeFS는 사용자 공간 파일시스템과 연동 커널 모듈로 구성됩니다. 이하 설명에서 사용자 공간 부분은 `userspace`라고 부릅니다. OrangeFS는 PVFS에서 발전했기 때문에 사용자 공간 함수명과 변수명에는 여전히 `PVFS`가 사용됩니다.

사용자 공간은 중요한 구조체 다수에 typedef를 사용합니다. 커널 모듈의 함수명과 변수명은 `orangefs`로 전환되었고 Linux Coding Style은 typedef를 피하므로, 사용자 공간 구조체와 대응하는 커널 구조체는 typedef하지 않습니다.

커널 모듈은 사용자 공간이 읽고 쓸 수 있는 pseudo device를 구현합니다. 사용자 공간은 읽기와 쓰기 외에도 이 pseudo device에 `ioctl`을 호출하여 커널 모듈을 제어합니다.

Protocol between Kernel Module and Userspace
============================================

Orangefs is a user space filesystem and an associated kernel module.
We'll just refer to the user space part of Orangefs as "userspace"
from here on out. Orangefs descends from PVFS, and userspace code
still uses PVFS for function and variable names. Userspace typedefs
many of the important structures. Function and variable names in
the kernel module have been transitioned to "orangefs", and The Linux
Coding Style avoids typedefs, so kernel module structures that
correspond to userspace structures are not typedefed.

The kernel module implements a pseudo device that userspace
can read from and write to. Userspace can also manipulate the
kernel module through the pseudo device with ioctl.

Bufmap 메모리와 파티션 매핑

시작 시 userspace는 `posix_memalign`으로 page-size 정렬된 뒤 `mlock`된 메모리 버퍼 두 개를 할당합니다. 하나는 I/O, 다른 하나는 `readdir`용입니다. I/O 버퍼는 41,943,040(`41943040`)바이트이고 readdir 버퍼는 4,194,304(`4194304`)바이트입니다. 각 버퍼는 논리 chunk 또는 partition으로 나뉩니다.

각 버퍼 포인터는 별도의 `PVFS_dev_map_desc`에 들어가며 구조체에는 전체 크기, partition 크기와 개수도 기록됩니다. I/O 버퍼의 `PVFS_dev_map_desc` 포인터는 `ioctl`로 커널 매핑 루틴에 전달되고, `copy_from_user`로 복사된 정보가 커널의 `struct orangefs_bufmap`을 초기화합니다.

`refcnt`는 참조 카운터입니다. `desc_size`는 `PVFS2_BUFMAP_DEFAULT_DESC_SIZE`인 4,194,304바이트로 I/O partition 크기이자 파일시스템 block size이며 super block의 `s_blocksize`에 사용됩니다. `desc_count`는 `PVFS2_BUFMAP_DEFAULT_DESC_COUNT`인 10이고 `desc_shift`는 `log2(desc_size)`로 `s_blocksize_bits`에 쓰입니다.

`total_size`는 전체 I/O 버퍼 크기, `page_count`는 4,096바이트 page 개수입니다. `page_array`는 `page_count * sizeof(struct page *)` 크기로 `kcalloc`한 포인터 배열이며 `get_user_pages`로 I/O 버퍼의 각 page를 가리킵니다.

`desc_array`는 `desc_count * sizeof(struct orangefs_bufmap_desc)` 크기로 `kcalloc`합니다. `pages_per_desc = desc_size / PAGE_SIZE`이므로 기본값은 1,024입니다. descriptor 0은 page offset 0과 userspace 주소 `ptr + 0 * 1024 * 4096`, descriptor 9는 page offset 9,216과 주소 `ptr + 9 * 1024 * 4096`을 가리킵니다.

`buffer_index_array`는 `desc_count` 크기의 int 배열로 사용 가능한 I/O partition을 표시하고 `buffer_index_lock` spinlock이 갱신을 보호합니다. `readdir_index_array`는 `ORANGEFS_READDIR_DEFAULT_DESC_COUNT`인 5개 원소의 int 배열이며 readdir partition의 가용 상태를 표시합니다. `readdir_index_lock`이 이 배열의 갱신을 보호합니다.

The Bufmap
----------

At startup userspace allocates two page-size-aligned (posix_memalign)
mlocked memory buffers, one is used for IO and one is used for readdir
operations. The IO buffer is 41943040 bytes and the readdir buffer is
4194304 bytes. Each buffer contains logical chunks, or partitions, and
a pointer to each buffer is added to its own PVFS_dev_map_desc structure
which also describes its total size, as well as the size and number of
the partitions.

A pointer to the IO buffer's PVFS_dev_map_desc structure is sent to a
mapping routine in the kernel module with an ioctl. The structure is
copied from user space to kernel space with copy_from_user and is used
to initialize the kernel module's "bufmap" (struct orangefs_bufmap), which
then contains:

  * refcnt
    - a reference counter
  * desc_size - PVFS2_BUFMAP_DEFAULT_DESC_SIZE (4194304) - the IO buffer's
    partition size, which represents the filesystem's block size and
    is used for s_blocksize in super blocks.
  * desc_count - PVFS2_BUFMAP_DEFAULT_DESC_COUNT (10) - the number of
    partitions in the IO buffer.
  * desc_shift - log2(desc_size), used for s_blocksize_bits in super blocks.
  * total_size - the total size of the IO buffer.
  * page_count - the number of 4096 byte pages in the IO buffer.
  * page_array - a pointer to ``page_count * (sizeof(struct page*))`` bytes
    of kcalloced memory. This memory is used as an array of pointers
    to each of the pages in the IO buffer through a call to get_user_pages.
  * desc_array - a pointer to ``desc_count * (sizeof(struct orangefs_bufmap_desc))``
    bytes of kcalloced memory. This memory is further initialized:

      user_desc is the kernel's copy of the IO buffer's ORANGEFS_dev_map_desc
      structure. user_desc->ptr points to the IO buffer.

      ::

        pages_per_desc = bufmap->desc_size / PAGE_SIZE
        offset = 0

        bufmap->desc_array[0].page_array = &bufmap->page_array[offset]
        bufmap->desc_array[0].array_count = pages_per_desc = 1024
        bufmap->desc_array[0].uaddr = (user_desc->ptr) + (0 * 1024 * 4096)
        offset += 1024
                           .
                           .
                           .
        bufmap->desc_array[9].page_array = &bufmap->page_array[offset]
        bufmap->desc_array[9].array_count = pages_per_desc = 1024
        bufmap->desc_array[9].uaddr = (user_desc->ptr) +
                                               (9 * 1024 * 4096)
        offset += 1024

  * buffer_index_array - a desc_count sized array of ints, used to
    indicate which of the IO buffer's partitions are available to use.
  * buffer_index_lock - a spinlock to protect buffer_index_array during update.
  * readdir_index_array - a five (ORANGEFS_READDIR_DEFAULT_DESC_COUNT) element
    int array used to indicate which of the readdir buffer's partitions are
    available to use.
  * readdir_index_lock - a spinlock to protect readdir_index_array during
    update.

Operation 구조와 상태

커널 모듈이 userspace와 통신해야 할 때 `struct orangefs_kernel_op_s`인 `op`를 만듭니다. op의 `upcall` 부분은 userspace에 보내는 요청이고, 나중에 채워지는 `downcall` 부분은 요청 결과입니다. slab allocator는 op 구조체 cache를 유지하여 빠르게 재사용합니다.

초기화 시 커널 모듈은 전송 중인 모든 op를 추적하기 위해 `request_list`와 `in_progress` hash table을 정의하고 초기화합니다.

op는 상태를 가집니다. `unknown`은 막 초기화된 상태, `waiting`은 위쪽으로 전달될 `request_list` 대기 상태, `inprogr`는 downcall을 기다리는 진행 상태입니다. `serviced`는 일치하는 downcall을 받아 정상 완료한 상태입니다. `purged`는 client-core가 처리 전에 비정상 종료하여 timer를 시작해야 하는 상태이고, `given up`은 제출자가 기다리기를 포기한 상태입니다.

Operations
----------

The kernel module builds an "op" (struct orangefs_kernel_op_s) when it
needs to communicate with userspace. Part of the op contains the "upcall"
which expresses the request to userspace. Part of the op eventually
contains the "downcall" which expresses the results of the request.

The slab allocator is used to keep a cache of op structures handy.

At init time the kernel module defines and initializes a request list
and an in_progress hash table to keep track of all the ops that are
in flight at any given time.

Ops are stateful:

 * unknown
            - op was just initialized
 * waiting
            - op is on request_list (upward bound)
 * inprogr
            - op is in progress (waiting for downcall)
 * serviced
            - op has matching downcall; ok
 * purged
            - op has to start a timer since client-core
              exited uncleanly before servicing op
 * given up
            - submitter has given up waiting for it

Upcall·downcall 수명주기와 watchdog

임의의 userspace 프로그램이 `readdir`, I/O, create 같은 OrangeFS 작업을 요청하면 커널은 op를 초기화하고 고유 tag ID를 붙입니다. upcall을 채운 뒤 `service_operation`에 전달합니다.

`service_operation`은 상태를 `waiting`으로 바꾸고 op를 `request_list`에 넣은 뒤 wait queue를 통해 `file_operations.poll`을 깨웁니다. pseudo device를 poll하던 userspace는 읽어야 할 upcall을 알게 됩니다.

`file_operations.read`가 실행되면 처리 가능한 op를 목록에서 찾아 제거하고 tag와 upcall을 `copy_to_user`로 userspace에 복사합니다. 이 복사 또는 관련 프로토콜 복사가 실패하면 상태를 다시 `waiting`으로 바꾸고 요청 목록에 되돌립니다. 성공하면 상태를 `in progress`로 바꾸고 tag를 hash하여 `in_progress` table의 해당 목록 끝에 넣습니다.

userspace는 응답과 tag를 여러 `io_vec`으로 pseudo device에 씁니다. `file_operations.write_iter`가 같은 tag의 op를 찾아 `in_progress` table에서 제거합니다. 상태가 `canceled`나 `given up`이 아니면 `serviced`로 바꿉니다. 이후 대기 중인 VFS와 `wait_for_matching_downcall`을 거쳐 `service_operation`으로 돌아가며, 호출자는 채워진 downcall을 받습니다.

`client-core`는 커널 모듈과 userspace 사이의 daemon bridge이며 별도의 watchdog daemon이 감시합니다. client-core가 종료 신호를 받으면 watchdog이 즉시 다시 시작하지만 잠시 죽어 있는 구간이 생깁니다. 이때 poll 통지가 전달되지 않아 wait queue의 op가 timeout될 수 있으며 한 번 재활용을 시도합니다.

client-core가 너무 오래 중단되면 OrangeFS를 사용하는 프로세스가 영향을 받습니다. 처리할 수 없는 waiting op는 `request_list`에서, in-progress op는 `in_progress` hash table에서 제거되고 둘 다 `given up` 상태가 됩니다.

When some arbitrary userspace program needs to perform a
filesystem operation on Orangefs (readdir, I/O, create, whatever)
an op structure is initialized and tagged with a distinguishing ID
number. The upcall part of the op is filled out, and the op is
passed to the "service_operation" function.

Service_operation changes the op's state to "waiting", puts
it on the request list, and signals the Orangefs file_operations.poll
function through a wait queue. Userspace is polling the pseudo-device
and thus becomes aware of the upcall request that needs to be read.

When the Orangefs file_operations.read function is triggered, the
request list is searched for an op that seems ready-to-process.
The op is removed from the request list. The tag from the op and
the filled-out upcall struct are copy_to_user'ed back to userspace.

If any of these (and some additional protocol) copy_to_users fail,
the op's state is set to "waiting" and the op is added back to
the request list. Otherwise, the op's state is changed to "in progress",
and the op is hashed on its tag and put onto the end of a list in the
in_progress hash table at the index the tag hashed to.

When userspace has assembled the response to the upcall, it
writes the response, which includes the distinguishing tag, back to
the pseudo device in a series of io_vecs. This triggers the Orangefs
file_operations.write_iter function to find the op with the associated
tag and remove it from the in_progress hash table. As long as the op's
state is not "canceled" or "given up", its state is set to "serviced".
The file_operations.write_iter function returns to the waiting vfs,
and back to service_operation through wait_for_matching_downcall.

Service operation returns to its caller with the op's downcall
part (the response to the upcall) filled out.

The "client-core" is the bridge between the kernel module and
userspace. The client-core is a daemon. The client-core has an
associated watchdog daemon. If the client-core is ever signaled
to die, the watchdog daemon restarts the client-core. Even though
the client-core is restarted "right away", there is a period of
time during such an event that the client-core is dead. A dead client-core
can't be triggered by the Orangefs file_operations.poll function.
Ops that pass through service_operation during a "dead spell" can timeout
on the wait queue and one attempt is made to recycle them. Obviously,
if the client-core stays dead too long, the arbitrary userspace processes
trying to use Orangefs will be negatively affected. Waiting ops
that can't be serviced will be removed from the request list and
have their states set to "given up". In-progress ops that can't
be serviced will be removed from the in_progress hash table and
have their states set to "given up".

readdir·I/O payload와 downcall 공통 필드

`readdir`와 I/O op는 payload 처리 방식이 일반 op와 다릅니다. readdir는 미리 할당하고 partition한 두 버퍼 중 작은 버퍼를 사용하며 이 버퍼는 userspace에서만 접근합니다. 커널 모듈은 op를 시작하기 전에 빈 partition index를 얻고, userspace가 결과를 그 partition에 쓴 뒤 pvfs device로 다시 전달합니다.

read와 write I/O op는 큰 I/O 버퍼를 사용하며 userspace와 커널 모듈 모두 접근할 수 있습니다. 커널은 op 시작 전에 빈 partition index를 얻습니다. write에서는 커널이 partition에 데이터를 넣고 userspace가 직접 소비하며, read에서는 userspace가 요청 결과를 넣고 커널이 직접 소비합니다.

커널 요청에 대한 모든 응답은 `pvfs2_downcall_t`로 포장합니다. 이 구조체에는 응답 종류별 구조체 union과 공통 필드가 있습니다. `int32_t type`은 작업 종류, `int32_t status`는 반환 코드입니다. `int64_t trailer_size`는 readdir가 아니면 0이고, `char *trailer_buf`는 처음 `NULL`이며 readdir 작업에서 사용됩니다.

Readdir and I/O ops are atypical with respect to their payloads.

  - readdir ops use the smaller of the two pre-allocated pre-partitioned
    memory buffers. The readdir buffer is only available to userspace.
    The kernel module obtains an index to a free partition before launching
    a readdir op. Userspace deposits the results into the indexed partition
    and then writes them to back to the pvfs device.

  - io (read and write) ops use the larger of the two pre-allocated
    pre-partitioned memory buffers. The IO buffer is accessible from
    both userspace and the kernel module. The kernel module obtains an
    index to a free partition before launching an io op. The kernel module
    deposits write data into the indexed partition, to be consumed
    directly by userspace. Userspace deposits the results of read
    requests into the indexed partition, to be consumed directly
    by the kernel module.

Responses to kernel requests are all packaged in pvfs2_downcall_t
structs. Besides a few other members, pvfs2_downcall_t contains a
union of structs, each of which is associated with a particular
response type.

The several members outside of the union are:

 ``int32_t type``
    - type of operation.
 ``int32_t status``
    - return code for the operation.
 ``int64_t trailer_size``
    - 0 unless readdir operation.
 ``char *trailer_buf``
    - initialized to NULL, used during readdir operations.

The appropriate member inside the union is filled out for any
particular response.

응답 union과 writev 전달

각 응답은 `pvfs2_downcall_t` union 안의 해당 멤버를 채웁니다. `PVFS2_VFS_OP_FILE_IO`는 `pvfs2_io_response_t`, LOOKUP·CREATE·SYMLINK·MKDIR은 `PVFS_object_kref`, GETATTR는 `PVFS_sys_attr_s`와 symlink 대상 문자열을 채웁니다.

`PVFS2_VFS_OP_STATFS`는 분산 네트워크 파일시스템의 통계를 제때 정확히 알기 어렵지만 `pvfs2_statfs_response_t`를 채웁니다. FS_MOUNT는 필드 순서가 다르고 `__pad1` 대신 `id`를 둔 `pvfs2_fs_mount_response_t`를 사용합니다.

GETXATTR, LISTXATTR, PARAM, PERF_COUNT, FSKEY는 각각 `pvfs2_getxattr_response_t`, `pvfs2_listxattr_response_t`, `pvfs2_param_response_t`, `pvfs2_perf_count_response_t`, `pvfs2_fs_key_response_t`를 채웁니다. READDIR는 upcall이 지정한 readdir buffer descriptor에 `pvfs2_readdir_response_t` 표현에 필요한 모든 데이터를 넣습니다.

userspace는 `/dev/pvfs2-req`에 `writev()`를 호출하여 커널 요청의 응답을 전달합니다. `buffer_list`에는 준비된 `struct pvfs2_downcall_t` 포인터가 들어가고, readdir 요청이면 대상 디렉터리 object descriptor를 담은 버퍼 포인터도 추가됩니다. 이 목록은 실제 `writev`를 수행하는 `PINT_dev_write_list`로 전달됩니다.

  PVFS2_VFS_OP_FILE_IO
    fill a pvfs2_io_response_t

  PVFS2_VFS_OP_LOOKUP
    fill a PVFS_object_kref

  PVFS2_VFS_OP_CREATE
    fill a PVFS_object_kref

  PVFS2_VFS_OP_SYMLINK
    fill a PVFS_object_kref

  PVFS2_VFS_OP_GETATTR
    fill in a PVFS_sys_attr_s (tons of stuff the kernel doesn't need)
    fill in a string with the link target when the object is a symlink.

  PVFS2_VFS_OP_MKDIR
    fill a PVFS_object_kref

  PVFS2_VFS_OP_STATFS
    fill a pvfs2_statfs_response_t with useless info <g>. It is hard for
    us to know, in a timely fashion, these statistics about our
    distributed network filesystem.

  PVFS2_VFS_OP_FS_MOUNT
    fill a pvfs2_fs_mount_response_t which is just like a PVFS_object_kref
    except its members are in a different order and "__pad1" is replaced
    with "id".

  PVFS2_VFS_OP_GETXATTR
    fill a pvfs2_getxattr_response_t

  PVFS2_VFS_OP_LISTXATTR
    fill a pvfs2_listxattr_response_t

  PVFS2_VFS_OP_PARAM
    fill a pvfs2_param_response_t

  PVFS2_VFS_OP_PERF_COUNT
    fill a pvfs2_perf_count_response_t

  PVFS2_VFS_OP_FSKEY
    file a pvfs2_fs_key_response_t

  PVFS2_VFS_OP_READDIR
    jamb everything needed to represent a pvfs2_readdir_response_t into
    the readdir buffer descriptor specified in the upcall.

Userspace uses writev() on /dev/pvfs2-req to pass responses to the requests
made by the kernel side.

A buffer_list containing:

  - a pointer to the prepared response to the request from the
    kernel (struct pvfs2_downcall_t).
  - and also, in the case of a readdir request, a pointer to a
    buffer containing descriptors for the objects in the target
    directory.

... is sent to the function (PINT_dev_write_list) which performs
the writev.

PINT_dev_write_list iovec 배치

`PINT_dev_write_list`는 로컬 `struct iovec io_array[10]`을 가집니다. 모든 응답에서 첫 네 원소를 같은 방식으로 초기화합니다. `io_array[0]`은 로컬 `int32_t proto_ver`, `[1]`은 전역 `int32_t pdev_magic`, `[2]`는 매개변수 `PVFS_id_gen_t tag`, `[3]`은 전역 `vfs_request`의 `pvfs2_downcall_t out_downcall`을 가리킵니다. 각 `iov_len`은 대응 형식의 `sizeof`입니다.

readdir 응답은 다섯 번째 원소도 초기화합니다. `io_array[4].iov_base`는 `vfs_request.out_downcall.trailer_buf`의 내용이고, `iov_len`은 같은 downcall의 `trailer_size` 값입니다. 이 배열 배치는 프로토콜 버전과 magic, 요청 tag, 고정 downcall, 선택적 가변 readdir trailer 순서를 명시합니다.

PINT_dev_write_list has a local iovec array: struct iovec io_array[10];

The first four elements of io_array are initialized like this for all
responses::

  io_array[0].iov_base = address of local variable "proto_ver" (int32_t)
  io_array[0].iov_len = sizeof(int32_t)

  io_array[1].iov_base = address of global variable "pdev_magic" (int32_t)
  io_array[1].iov_len = sizeof(int32_t)

  io_array[2].iov_base = address of parameter "tag" (PVFS_id_gen_t)
  io_array[2].iov_len = sizeof(int64_t)

  io_array[3].iov_base = address of out_downcall member (pvfs2_downcall_t)
                         of global variable vfs_request (vfs_request_t)
  io_array[3].iov_len = sizeof(pvfs2_downcall_t)

Readdir responses initialize the fifth element io_array like this::

  io_array[4].iov_base = contents of member trailer_buf (char *)
                         from out_downcall member of global variable
                         vfs_request
  io_array[4].iov_len = contents of member trailer_size (PVFS_size)
                        from out_downcall member of global variable
                        vfs_request

dcache, inode 갱신과 jiffy timeout

OrangeFS는 userspace로 중복 요청을 보내지 않도록 dcache를 활용합니다. `orangefs_inode_getattr`은 object inode 속성을 최신 상태로 유지하며 `new`와 `bypass` 두 인자로 갱신 여부를 결정합니다. inode의 private data에는 짧은 timeout인 `getattr_time`이 있어 마지막 갱신 후 경과 시간을 판단합니다.

object가 새 것이 아니고 `new == 0`, bypass도 설정되지 않아 `bypass == 0`일 때 `getattr_time`이 아직 만료되지 않았다면 inode를 갱신하지 않고 반환합니다. inode를 실제로 갱신할 때마다 `getattr_time`도 갱신합니다.

새 file, directory, symbolic link를 만들 때 pathname 평가 결과는 처음에 negative dentry입니다. Linux의 `new_inode()`로 새 inode를 할당하고 `d_instantiate()`로 inode와 dentry를 연결하면 정상적인 positive dentry가 됩니다.

기존 object의 pathname은 대응 dentry로 해석됩니다. dentry가 없으면 dcache에 새로 만듭니다. OrangeFS가 dentry를 수정하거나 검증할 때 짧은 timeout을 `d_time`에 저장하고 그 시간 동안 dentry를 신뢰합니다.

OrangeFS는 네트워크 파일시스템이므로 특정 커널 모듈 인스턴스가 모르는 사이 서버의 object가 바뀔 수 있어 dentry 신뢰에는 위험이 있습니다. 그러나 매번 userspace, 최소한 client-core와 경우에 따라 서버까지 왕복하는 비용은 dentry 조회보다 훨씬 큽니다. 이 비용 차이가 제한된 시간 동안 dentry를 사용하는 이유입니다.

`d_time`과 `getattr_time`은 jiffy 기반이며 코드는 jiffy wrap 문제를 피하도록 설계되었습니다. 시계가 여러 번 wrap했을 가능성이 있으면 경과 시간을 알 수 없지만, 두 시각 `t1`, `t2`가 충분히 가깝다는 전제에서는 중간 wrap 가능성을 반영해 차이를 안정적으로 계산할 수 있습니다. 원문은 Andy Wang 강의 노트를 이 설명의 출처로 밝힙니다.

Orangefs exploits the dcache in order to avoid sending redundant
requests to userspace. We keep object inode attributes up-to-date with
orangefs_inode_getattr. Orangefs_inode_getattr uses two arguments to
help it decide whether or not to update an inode: "new" and "bypass".
Orangefs keeps private data in an object's inode that includes a short
timeout value, getattr_time, which allows any iteration of
orangefs_inode_getattr to know how long it has been since the inode was
updated. When the object is not new (new == 0) and the bypass flag is not
set (bypass == 0) orangefs_inode_getattr returns without updating the inode
if getattr_time has not timed out. Getattr_time is updated each time the
inode is updated.

Creation of a new object (file, dir, sym-link) includes the evaluation of
its pathname, resulting in a negative directory entry for the object.
A new inode is allocated and associated with the dentry, turning it from
a negative dentry into a "productive full member of society". Orangefs
obtains the new inode from Linux with new_inode() and associates
the inode with the dentry by sending the pair back to Linux with
d_instantiate().

The evaluation of a pathname for an object resolves to its corresponding
dentry. If there is no corresponding dentry, one is created for it in
the dcache. Whenever a dentry is modified or verified Orangefs stores a
short timeout value in the dentry's d_time, and the dentry will be trusted
for that amount of time. Orangefs is a network filesystem, and objects
can potentially change out-of-band with any particular Orangefs kernel module
instance, so trusting a dentry is risky. The alternative to trusting
dentries is to always obtain the needed information from userspace - at
least a trip to the client-core, maybe to the servers. Obtaining information
from a dentry is cheap, obtaining it from userspace is relatively expensive,
hence the motivation to use the dentry when possible.

The timeout values d_time and getattr_time are jiffy based, and the
code is designed to avoid the jiffy-wrap problem::

    "In general, if the clock may have wrapped around more than once, there
    is no way to tell how much time has elapsed. However, if the times t1
    and t2 are known to be fairly close, we can reliably compute the
    difference in a way that takes into account the possibility that the
    clock may have wrapped between times."

from course notes by instructor Andy Wang