Virtual Accelerator Switchboard (VAS) userspace API

Virtual Accelerator Switchboard userspace API

이 문서는 POWER9 Virtual Accelerator Switchboard(VAS)를 통해 userspace가 NX GZIP hardware accelerator에 직접 request를 보내는 API를 설명합니다.

VAS와 NX 소개

POWER9의 VAS는 userspace와 kernel이 Nest Accelerator(NX) co-processor와 통신하도록 합니다. NX에는 842 compression, GZIP compression, encryption 같은 하나 이상의 hardware engine이 있습니다.

POWER9 userspace application은 현재 ZLIB 및 GZIP algorithm을 hardware로 처리하는 GZIP Compression engine만 사용할 수 있습니다.

Kernel은 NX와의 channel 또는 window를 먼저 설정합니다. 이후 request는 kernel 개입 없이 직접 제출할 수 있습니다. GZIP request는 co-processor Request Block(CRB) 형식이어야 하며 `COPY`/`PASTE` instruction으로 engine request queue에 대응하는 hardware address에 paste합니다.

GZIP engine은 Normal과 High 두 priority를 제공하지만 현재 userspace에서는 Normal request만 지원합니다.

이 API는 compression request를 NX accelerator에 직접 보낼 channel/window를 kernel과 설정하는 절차를 정의합니다.

Userspace 연결 lifecycle

Application은 VAS/NX driver가 제공하는 `/dev/crypto/nx-gzip`을 open해 file descriptor를 얻고, 그 fd로 `VAS_TX_WIN_OPEN` ioctl을 실행하여 process용 GZIP send window를 엽니다.

연결 뒤 `mmap()`으로 engine request queue의 hardware address를 application virtual address space에 mapping합니다. 반환된 `paste_address`에 CRB를 copy/paste하여 여러 request를 보냅니다.

`close(fd)` 또는 process exit로 window를 닫습니다. 같은 window로 여러 request를 보낼 수 있고 여러 window도 만들 수 있지만 file descriptor 하나에는 window 하나만 대응합니다.

NX-GZIP device node

System에는 `/dev/crypto/nx-gzip` node가 하나만 있으며 모든 GZIP engine에 접근합니다. Valid operation은 다음뿐이고 다른 file operation은 undefined입니다.

COPY/PASTE는 device node를 거치지 않고 hardware로 직접 갑니다. 세부 instruction은 COPY/PASTE 문서를 따라야 합니다.

P9 chip마다 NX instance가 있을 수 있지만 node는 하나입니다. Device open 시 kernel은 user process가 실행 중인 CPU와 그 CPU가 속한 chip을 확인해 적합한 NX instance에 send window를 엽니다. Application은 `VAS_TX_WIN_OPEN`의 `vas_id`로 특정 instance를 선택할 수도 있습니다.

개발 중인 `libnxz` userspace library를 사용하면 `inflate`/`deflate` application이 `libz` 대신 link하여 source 수정 없이 NX GZIP compression을 사용할 수 있습니다.

• libnxz development repositoryhttps://github.com/abalib/power-gzip

Device open

NX-GZIP device는 read/write로 open하며 특별한 privilege가 필요하지 않습니다. Window 하나가 fd 하나에 대응하므로 여러 window가 필요하면 여러 번 open해야 합니다.

Return value, error code와 restriction의 일반 사항은 `open(2)` man page를 따릅니다.

VAS_TX_WIN_OPEN ioctl

NX co-processor engine과 connection을 만들기 위해 다음 attribute structure와 ioctl을 사용합니다.

struct vas_tx_win_open_attr {
        __u32   version;
        __s16   vas_id; /* specific instance of vas or -1
                                for default */
        __u16   reserved1;
        __u64   flags;        /* For future use */
        __u64   reserved2[6];
};

`vas_id=-1`이면 kernel이 process에 optimal한 NX instance를 best-effort로 배정합니다. 특정 VAS 선택에는 아래 discovery 절차의 `ibm,vas-id` 값을 사용합니다.

#define VAS_MAGIC 'v'
#define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1,
                                struct vas_tx_win_open_attr)

struct vas_tx_win_open_attr attr;
rc = ioctl(fd, VAS_TX_WIN_OPEN, &attr);

`VAS_TX_WIN_OPEN`은 성공 시 0, 실패 시 -1을 반환하고 `errno`를 설정합니다.

추가 ioctl 제약은 `ioctl(2)` man page를 따릅니다.

NX-GZIP mmap

NX-GZIP fd의 `mmap()`은 CRB를 hardware engine에 copy/paste할 `paste_address`를 반환합니다.

paste_addr = mmap(addr, size, prot, flags, fd, offset);

일반 `mmap(2)` error 외에 다음 NX-GZIP-specific `EINVAL` 조건이 있습니다.

사용 가능한 VAS engine discovery

각 VAS instance에는 `/proc/device-tree/vas@*` 또는 `/proc/device-tree/xscom@*/vas@*` 형태의 device-tree node가 있습니다. Chip/VAS instance를 찾고 node의 `ibm,vas-id` property를 `vas_id`에 사용합니다.

COPY/PASTE operation

Application은 COPY와 PASTE instruction으로 CRB를 NX에 보냅니다. 자세한 instruction은 PowerISA section 4.4를 참고합니다.

• Power ISA version 3.0https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0

CRB specification

Co-processor request는 CRB 형식으로 작성해야 합니다. CRB format, userspace request 제출과 status 확인은 NX-GZIP user's manual을 따릅니다.

NX fault handling

Application은 NX request를 보내고 co-processor Status Block(CSB) flag를 polling합니다. NX는 request 처리 뒤 CSB status를 update합니다.

CSB address나 request buffer에서 translation error, 즉 NX page fault가 발생하면 NX가 CPU interrupt를 올립니다. Invalid address를 전달했거나 request buffer가 memory에 없을 때 발생할 수 있습니다.

OS가 CSB에 기록하는 fault data는 다음과 같습니다.

csb.flags = CSB_V;
csb.cc = CSB_CC_FAULT_ADDRESS;
csb.ce = CSB_CE_TERMINATION;
csb.address = fault_address;

Application이 translation error를 받으면 fault address page를 touch하여 memory에 올린 뒤 request를 NX에 다시 제출할 수 있습니다.

Invalid CSB address 때문에 OS가 CSB를 update할 수 없으면 send window를 연 process에 `SIGSEGV`를 보냅니다.

siginfo.si_signo = SIGSEGV;
siginfo.si_errno = EFAULT;
siginfo.si_code = SEGV_MAPERR;
siginfo.si_addr = CSB address;

Multithread application에서는 NX send window를 모든 thread가 share할 수 있습니다. CSB address가 valid하면 다른 thread의 request도 OS fault handling과 함께 성공합니다.

Invalid CSB request의 signal은 window를 연 child thread로 갑니다. 그 thread가 window를 닫지 않고 exit한 뒤 request가 발행되면 thread-group leader(`tgid`)에게 signal을 보냅니다. Signal을 무시하거나 처리할지는 application 책임입니다.

• NX-GZIP User's Manualhttps://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf

Simple example

다음 원문 예제는 device open, attribute 초기화, ioctl, mmap, CRB copy/paste, CSB polling과 close의 전체 흐름을 보여 줍니다.

int use_nx_gzip()
{
        int rc, fd;
        void *addr;
        struct vas_setup_attr txattr;

        fd = open("/dev/crypto/nx-gzip", O_RDWR);
        if (fd < 0) {
                fprintf(stderr, "open nx-gzip failed\n");
                return -1;
        }
        memset(&txattr, 0, sizeof(txattr));
        txattr.version = 1;
        txattr.vas_id = -1
        rc = ioctl(fd, VAS_TX_WIN_OPEN,
                        (unsigned long)&txattr);
        if (rc < 0) {
                fprintf(stderr, "ioctl() n %d, error %d\n",
                                rc, errno);
                return rc;
        }
        addr = mmap(NULL, 4096, PROT_READ|PROT_WRITE,
                        MAP_SHARED, fd, 0ULL);
        if (addr == MAP_FAILED) {
                fprintf(stderr, "mmap() failed, errno %d\n",
                                errno);
                return -errno;
        }
        do {
                //Format CRB request with compression or
                //uncompression
                // Refer tests for vas_copy/vas_paste
                vas_copy((&crb, 0, 1);
                vas_paste(addr, 0, 1);
                // Poll on csb.flags with timeout
                // csb address is listed in CRB
        } while (true)
        close(fd) or window can be closed upon process exit
}

• libnxz tests and exampleshttps://github.com/libnxz/power-gzip