NAME

libzz9k, zz9k_inflate, zz9k_pool - ZZ9000-family board services, with a software fallback

SYNOPSIS

#include <zz9k/amix.h>

int zz9k_inflate(uint32_t algorithm, uint32_t flags,
    const void *src, uint32_t src_length,
    void *dst, uint32_t dst_capacity, int how,
    ZZ9KDecompressResult *result, int *ran);

void zz9k_inflate_threshold(uint32_t bytes);

int zz9k_pool(const ZZ9KAmixBoard **boards);
int zz9k_pool_codec(uint32_t flags);
void zz9k_pool_timeout(uint32_t ms);
void zz9k_pool_close(void);

int zz9k_open_unit(ZZ9KContext **ctx, int unit);

cc ... -I/opt/amix/include ... -Wl,--gc-sections -L/opt/amix/lib -lzz9k -lz

DESCRIPTION

A Z3660, and a ZZ9000 whose firmware has the services runtime, can do work for a program on the board's second ARM core. The kernel reaches each such board through zz9ksvc(7), /dev/zz9ksvc0 and /dev/zz9ksvc1. libzz9k is the program's side: the ZZ9000 SDK version 2 host interface (<zz9k/host.h>) over those channels, and calls that run on a board when one offers the service and in software when none does, with the same result either way.

zz9k_inflate decompresses src_length bytes at src into at most dst_capacity bytes at dst. algorithm is ZZ9K_COMPRESSION_DEFLATE_RAW, ZZ9K_COMPRESSION_ZLIB or ZZ9K_COMPRESSION_GZIP; the other algorithms of the SDK run on a board only. flags is 0 or ZZ9K_DECOMPRESS_FLAG_EXPECT_END (a stream that does not end is an error). how is ZZ9K_INFLATE_AUTO (a board that offers it, else software; see below), ZZ9K_INFLATE_BOARD or ZZ9K_INFLATE_SOFT. The status is a ZZ9K_STATUS_* code; ZZ9K_STATUS_OK fills result (bytes consumed and written, the CRC-32 of the output, the algorithm, the result flags), and the status, the result and the bytes at dst are the same on a board and in software: in ZZ9K_INFLATE_AUTO only a board's ZZ9K_STATUS_OK is taken, and any other answer of the board is decided again in software, so every stream has one answer; ZZ9K_INFLATE_BOARD returns the board's own status. ZZ9K_STATUS_NO_MEMORY means dst is too small, ZZ9K_STATUS_BAD_REQUEST a stream that cannot be decoded or a bad argument. In ZZ9K_INFLATE_AUTO, a source shorter than the threshold runs in software, since the board's round trip would cost more: ZZ9K_INFLATE_BOARD_MIN (1024) bytes, or what zz9k_inflate_threshold set for the process. An algorithm only a board can do goes to the board whatever its size.

*ran (when ran is not null) says where it ran. With ZZ9K_INFLATE_BOARD and no board offering it, the status is ZZ9K_STATUS_NOT_FOUND when there is no board and ZZ9K_STATUS_UNSUPPORTED when none has the service.

The pool opens every /dev/zz9ksvcN once per process, at the first call, and reads each board's capability catalogue (QUERY_CAPS, and the CODEC service's flags by QUERY_SERVICE). A node that gives ENXIO (no board, or no runtime on it) is left out. zz9k_pool gives the boards and their number; zz9k_pool_codec the unit of the first board whose CODEC service has every flag in flags, or -1. zz9k_pool_timeout bounds each board request (ms, 0 for the kernel's 10 seconds); a call that times out runs in software, and that board is left out of ZZ9K_INFLATE_AUTO calls for 30 seconds. zz9k_pool_close closes every channel.

zz9k_open takes the first unit that answers, zz9k_open_unit a given one, for the SDK's own calls. On Amix a buffer of zz9k_alloc_shared is mapped with mmap(2); the kernel passes on only the requests it knows (see zz9ksvc(7)); zz9k_submit, zz9k_poll and the interrupt calls give ZZ9K_STATUS_UNSUPPORTED.

NOTES

The library has a section per function: -Wl,--gc-sections keeps only the calls a program makes (the whole SDK host interface is about 50 KB of text).

The kernel gives a freed buffer that was mapped back to the board only when the channel closes, so the pool keeps two buffers per board and reuses them, and opens its channel again when growing them runs out of handles.

The library is not safe for threads.

LICENCE

libzz9k is GPL-3.0-or-later: it is the ZZ9000 SDK's host code, which is GPL-3.0-or-later with no linking exception. A program that links it is a combined work under the GPL, version 3 or later, as a whole. The licence is /opt/amix/doc/libzz9k/LICENSE.

FILES

/opt/amix/lib/libzz9k.a

the library

/opt/amix/include/zz9k

its headers

/dev/zz9ksvc0, /dev/zz9ksvc1

the channels

SEE ALSO

zz9k-test(1), zz9ksvc(7), mmap(2)