fbpf_rus.txt

! This file/gist was reflecting thinking/design process (in mix of English &
! Russian) and is now in HISTORIC status - selected variants are moved to
! http://github.com/nuclight/bpf64/bpf64spec.md (see there for actual version)

04.07.24 14:09:03
возникла идея, как можно расширить классический BPF без верификатора - всё равно в нашем BSD-коде он ходит в mbuf, а в eBPF по факту нужны проверки указателя на каждый чих, поэтому оставить доступ к пакету как и было, добавить BPF_CALL и BPF_RET, stack frame на 16 слов по 64 бита, среди них read only Loop Counter для BPF_LOOP, который только декрементит счетчик и единственный разрешенный jump назад - все остальные только вперёд; ну еще BPF_SYSCALL добавить для внешних функций, подумать насчёт дополнительных областей памяти и деталей реализации BPF_LOOP (да, только один nested на функцию, но break/continue/jump изнутри что делать?), а также exception handlers (за пределы пакета, stack overflow и т.д.) - и всё, сложный верификатор не нужен, программа гарантировано завершится и имеет доступ только к разрешенным областям памяти. А поскольку это виртуальная машина, то JIT тоже имеет доступ только туда
===
12.07.24
в продолжение идеи про расширение BPF, смотрел, как устроены по числу регистров ARM, MIPS, SPARC - этот интереснее всего, register window
также в NetBSD посмотрел: там в BPF_MISC есть BPF_COP, типа coprocessor - это вызов внешней функции¸ используется их файрволом NPF, там еще BPF_MEMWORDS  расширены до extwords, и одна из внешних функций этого файрвола кладёт в три слова в MEM параметры пакета типа l4 offset, а другая делает лукап по таблице - ну вот он, зачаток eBPF maps
===
13.07.24
снова расширение fBPF - читал про Itanium, там переменное регистровое окно, вот это похоже то, что нужно
https://devblogs.microsoft.com/oldnewthing/20150729-00/?p=90801
===
14.07.24
для ALU в старший байт надо: 5 бит override register и флаги - бит DW, бит Signed, бит Three_regs для взятия jt и jf, например:
BPF_ALU+BPF_ADD+BPF_X      A <- A + X
при override=3 это         D <- D + X
override=3 T=1 jt=5 jf=6   F <- G + D

а может несколько loop counter на stack frame держать? и назвать I,J,K как в Fortran
ну да, если на ARM64 только 31 регистр, плюс если один всегда zero, плюс надо где-то держать X, то остается только 29 general purpose регистров, а если JIT-коду надо держать указатели на стек, на пакет, на что там еще...
===
16.07.24
читал про ассемблер ARM64, мало того что FP и LR заняты, так еще и X18 под Platform... и режимом адресации всего ничего, [регистр+регистр*shift] по сути, то есть на каждый чих - пакет, shared, контекст, стэк основной, стэк спрятанный - надо держать по регистру, а то и по два, на смещение, и еще временные регистры для загрузки оттуда могут понадобиться?..

а может, не мапить тогда стэк на регистры, а сделать его явным в BPF_MODE типа BPF_IND? тогда и Z <- I[k] и L[k] и O[k] можно раздельные
===
17.07.24
в RISC-V вместо MOV просто частный случай ADD - похоже с BPF_ALU выходит так же
инструкция на alloc таки нужна - иначе это в каждом call повторять придётся; плюс для main тоже позволит задать регистры - чтобы не инициализировать лишние
===
18.07.24
инструкции расширенной длины в BPF_MISC - флаг M и оффсет (как IP fragments), в каждой из инструкций - на случай случайного джампа
можно использовать, например, в аппаратной реализации в сетевухах для загрузки IPv6 в 128-битный регистр
а первое применение - строковый литерал, и старший байт code в промежуточных - битовая маска, перед какими символами вставить %

https://www.usenix.org/legacy/events/bsdcon02/full_papers/lidl/lidl.pdf :
<<
5.5 Stackable Filters
Each filtering point in the kernel is actually the attachment point for a stack of filter programs. Filter programs
can easily be pushed onto the stack, popped off the stack,
or inserted into the middle of the stack for each filtering
point. Individual filters each have a priority (a signed 32
bit number) that determines where the in the stack the
filter is actually placed. Multiple filters installed at the
same priority, at the same filtering location, operate as a
traditional stack.

Filters may also have a symbolic tag to aid in their
identification, replacement, or deletion.

5.6 Flexibility of Actions

After classifying a packet according to whatever rules
are in place, a packet filtering system has to perform an
operation on the packet. A simple packet filtering system has just two operations, “accept” and “reject.” The
BSD/OS IPFW system has three additional operations.
The `log` action takes a specified amount of the packet
and copies it to the IPFW kernel socket. The `call` action allows the current packet to be passed to a different
named filter for further processing. The `next` action
calls the next filter in the stack of filters installed at the
current filter location. In addition, the BSD/OS IPFW
system allows packets to be modified explicitly by the
filter program, or as the consequence of calling another
filter program. The classic “accept” and “reject” actions
have been extended so they can also optionally log the
packet to the kernel socket.

5.7 Filter Pool

In addition to the explicit filtering points in the kernel
a pool of filter programs can be installed into the kernel, not associated with a particular filtering point. This
allows common filter programs to be installed into the
filter pool and then be referenced from any of the other
filters installed in the running system. Currently only
BPF based filters have the ability to call a filter from the
pool. The filter called may delete the packet or return a
value associated with the packet. Typically this value is
boolean. The called filter might also be used to record
some state that can later be accessed.
Unlike BPF programs, it is possible to create an infinite loop of called filters. There is no loop detection
in the filter software, which could be considered a flaw.
Users of the IPFW system are obligated to understand
the interactions between all their filter programs.

5.8 Circuit Cache

Although BPF filters themselves are stateless, by using custom coded filters, such as the circuit cache, the
filters can access saved state about a connection. The
circuit cache provides the system with two features. The
first is the ability of a BPF program to request the circuit
described by a packet be added to the cache. A circuit is
defined as the combination of the source and destination
addresses, along with the source and destination ports
for the upper level protocol, if relevant. The second is
the ability to pass a packet to the cache for it to determine
if that session has been seen before. For example, TCP
packets can be divided into “Initial `SYN`” packets and
“Established” packets. Initial SYN packets are subject
to potentially complicated rules to determine if the session should be allowed. If the packet is to be accepted,
it is passed to the circuit cache asking for an entry to
be added for its circuit. Any Established packet is simply passed to the circuit cache for query. If the packet
does not match an existing session, it is rejected. The
circuit cache understands the TCP protocol and when
caching TCP circuits it can optionally monitor FIN and
`RST` packets and automatically terminate a circuit when
the TCP session is shut down. Circuits may also automatically be timed out to reclaim kernel resources after
a configuration period of inactivity.

7 BPF Language Overview

The most used and most flexible filter type in IPFW is the BPF filter. As mentioned earlier, this type of filter uses the BPF pseudo-machine. The BPF pseudo-machine has been enhanced for use with IPFW. Only one totally new BPF instruction was added for IPv4 packet processing. A new memory type was added, as well asthe ability to modify the packet being processed. IPv6 enhancements have been added and are discussed at the end of this section.

The new BPF instruction, `CCC`, enables the calling of a filter on the “call filter chain.” While it might seem that the acronym stands for “Call Call Chain,” it was actually derived from “Call Circuit Cache.” The circuit cache was the reason for the creation of the call chain. The CCC instruction returns the result of the call in the `A` register.

The new memory type is called ROM and is an additional memory area to the original BPF memory spaces.
The original memory spaces included the packet contents as well as the scratch memory arena. While the first
implementation did in fact store read only information, the term ROM is now a misnomer as the ROM locations can be modified by the filter. This space, called “prom” in the source code, is used to pass ancillary information in and out of the BPF filter.

While the `bpf_filter()` function does not have any innate knowledge of the meaning of these memory locations, IPFW assigns meanings to several locations:
0 IPFWM_AUX An auxiliary return value (for errors)
1 IPFWM_SRCIF The index of the source interface (if known)
2 IPFWM_DSTIF The index of the destination interface (if known)
3 IPFWM_SRCRT The index of the interface for return packets
4 IPFWM_MFLAGS The mbuf flags
5 IPFWM_EXTRA Bytes of wrapper that preceeded this packet
6 IPFWM_POINT What filter point was used
7 IPFWM_DSTADDR New address to use for routing to destination
The BPF filter is intelligent about setting these values. As some of these values, such as `IPFWM_SRCRT`,
can be expensive to calculate, the filter is examined when passed into the kernel. A bitmap is built of all ROM locations referenced by the program and only those locations are initialized.

In order to support the ROM memory space, the calling convention of the `bpf_filter()` function was changed to pass three additional parameters:

int32_t *prom; /* ptr to ROM memory */
int promlen; /* count of valid bytes */
/* in the memory space */
int modify; /* boolean to indicate */
/* whether packet */
/* can be modified */
/* by bpf_filter() */

All existing calls to `bpf_filter()` were modified to pass NULL, 0, 0 for these three values.

IPFW has been adapted for use with IPv6. This work was implemented with the NRL version of IPv6. More recent releases of BSD/OS use the KAME IPv6 implementation. The changes to support IPFW in the KAME IPv6 stack have not yet been written.

In order to support IPv6, several other new enhancements were made to the BPF pseudo-machine. Triple
length instructions were added. A “classic” BPF instruction is normally 64 bits in size: 16 bits of opcode, two
8 bit jump fields, and a 32 bit immediate field. A triple
length instruction has 128 bits of additional immediate
data (the length of an IPv6 address). A new register,
`A128`, was also added. The load, store, and jump instructions now have 128 bit versions. The scratch memory locations have been expanded to 128 bits, though
traditional programs only use the lower 32 bits of each
location. An instruction to zero out a scratch memory
location (`ZMEM`) was added. Because BPF was not extended to handle 128 bit arithmetic, a new jump instruction was created that allowed for the comparison of the
`A` register to a network address, subject to a netmask.
The netmask must be specified as a CIDR style netmask,
specifically a count of the number of significant bits in
the netmask.

ROM locations only have 32 bit values and it is in the
ROM that a new destination routing address is passed.
Currently it is not possible to use the next-hop routing
capability with IPv6.
>>


для других областей памяти вводим номер сгемента - и помещаем его в jf, "from"; BPF_LEN становится параметром лимита каждого сегмента
вообще, можно попробовать обойтись без бита Little Endian в BPF_LD/BPF_ST - ведь он актуален только для packet, т.е. нулевого сегмента; в других сегментах зато нужен atomic, правда набор функций разный на фре и линуксе
но вообще BPF_ATOMIC в eBPF есть только в BPF_STX, а там меньше модов - нет работы с пакетом...
а нужно ли тратить на BPF_MEMSX	и movsx? может это можно сделать отдельной операцией в ALU?


BPF_LOOP_NEXT и BPF_LOOP_LAST - как джампы, off указывают вперёд на закрывающую скобку
может совместить их? типа в last будет k=0, иначе величина инкремента
BPF_LOOP_DO - инициализация, off указывает вперёд на закрывающую скобку
BPF_LOOP_END - единственный собственно (условный) джамп назад, off указывает на открывающую скобку

так как BPF_RVAL(code)  ((code) & 0x18) то мало бит, логично в BPF_RET разместить только BPF_LOOP_END и другие типа BPF_CALL - как те, кто могут возвращаться *назад*
а остальные BPF_LOOP_* в классе BPF_JMP

эдак на I,J,K,L не хватит бит...
хотя там же еще старший байт, разве что его для регистра инициализации
===
19.07.24
назвать для общей длины _OPEN и _BACK и _SKIP мож?
засунуть BPF128 в BPF_MISC?
===
20.07.24
Поскольку в JIT на популярных RISC всё равно регистров не хватит, то фиг
с ним, пусть будет например платформенный #define скажем на 4 регистра из
каждого типа, а остальные держит в памяти (и сохраняет туда при вызовах
внешних функций чтоб выглядеть как и интерпретатор VM) - но сейчас время
ускорителей вместо CPU общего назначения, поэтому можно проектировать это как
ассемблер некоей машины, которая будет сделана в железе. Например, offload
в сетевую карту - еще и поэтому общие указатели в ядре не годятся (как
в линуксе), ибо у железки могут отмаплены только определенные буферы хоста.

с сего момента редактируемый черновик спеки, без отдельных записей дат по дням

To: freebsd-arch, freebsd-hackers, tcpdump-workers, TBD@netbsd.org, XXX
Subject: BPF64: proposal of platform-independent hardware-friendly eBPF alternative

Hello!

                                         We don't need ELF relocations!
                                         We like language with foreach!
                       Lie on beach, just add other case in the switch.
                                                          -- Ping Floyd

I've recently had some experience with Linux's ePBF in it's XDP, and this left
quite negative impression. I was following via https://github.com/xdp-project/xdp-tutorial
and after 3rd lesson was trying to create a simple program for searching TCP
timestamp option and incrementing it by one. As you know, eBPF tool stack
consists of at least clang and eBPF verifier in the kernel, and after two dozen
tries eBPF verifier still didn't accept my code. I was digging into verifier
sources, and the abysses opened in front of me! Carefully and boringly going
via disassembler and verifier output, I've found that clang optimizer ignores
just checked register - patching one byte in assembler sources (and target .o)
did help. I've filed https://github.com/iovisor/bcc/issues/5062 with details
if one curious.

So, looking at eBPF ecosystem, I must say it's a Frankenstein. Sewn from good,
sometimes brilliant parts, it's a monster in outcome. Verifier is in it's own
right, compiler/optimizer is in it's own right... But at the end you even
don't have a high-level programming language! You must write in C, relatively
low-level C, and restricted subset of C. This requires very skilled
professionals - it's far from something not even user-friendly, but at least
sysadmin-friendly, like `ipfw` or `iptables` firewall rules.

Thus I looked at the foundation of eBPF architecture, with which presuppositions
in mind it was created with. In fact, it tries to be just usual programming
after checks - that is, with all that pointers. It's too x86-centric and
Linux-centric - number of registers was added just ten. So if you look at the
GitHub ticket above, when I tried to add debug to program - you know, just
specific `printf()`s - it failed verifier checks again because compiler now
had to move some variables between registers and memory, as there is limit on
just 5 arguments to call due to limit of 5 registers! And verifier, despite
being more than 20,000 lines of code, still was not smart enough to track info
between registers and stack.

So, if we'd started from beginning, what should we do? Remember classic BPF:
it has very simple validator due to it's Virtual Machine design - only forward
jumps, checks for packet boundaries at runtime, etc. You'd say eBPF tries for
performance if verifier's checks were passed? But in practice you have to toss
in as much packet boundary checks as near to actual access as possible, or
verifier may "forget" it, because of compiler optimizer. So this is not of
much difference for checking if access is after packet in classic BPF - the
same CMP/JUMP in JIT if buffer is linear, and if your OS has put packet in
several buffers, like *BSD or DPDK `mbuf`'s, the runtime check overhead is
negligible in comparison.

Ensuring kernel stability? Just don't allow arbitrary pointers, like original BPF.
Guaranteed termination time? It's possible if you place some restrictions. For
example, don't allow backward jumps but allow function calls - in case of
stack overflow, terminate program. Really need backward jumps? Let's analyze
for what purpose. You'll find these are needed for loops on packet contents.
Solve it but supporting loops in "hardware"-controlled loops, which can's be
infinite.

Finally, platforms. It's beginning of sunset of x86 era now - RISC is coming.
ARM is now not only on mobiles, but on desktops and servers. Moreover, it's
era of specialized hardware accelerators - e.g. GPU, neural processors. Even
general purpose ARM64 has 31 register, and specialized hardware can
implement much more. Then, don't tie to Linux kernel - BPF helpers are very
rigid interface, from ancient era, like syscalls.

So, let's continue *Berkeley* Packet Filter with Berkeley RISC design - having
register window idea, updated by SPARC and then by Itanium (to not waste
registers). Take NetBSD's coprocessor functions which set is passed with
a context, instead of hardcoded enums of functions - for example, BPF maps is
not something universal, both NetBSD and FreeBSD have their own tables in
firewall.

Add more features actually needed for *network* processor - e.g. 128-bit
registers for IPv6 (eBPF axed put even BPF_MSH!). And do all of this in fully
backwards-compatible way - new language should allow to run older programs
from e.g. `tcpdump` to run without any modifications, binary-compatible
(again, eBPF does not do this)

TODO

very complex ELF infrastructure which may be not suitable for every network
card - having pc-addressed literals, as in RISC processors allows for much
simpler format: just BLOB of instructions



> First, a BPF program using bpf_trace_printk() has to have a GPL-compatible license.
> Another hard limitation is that bpf_trace_printk() can accept only up to 3 input arguments (in addition to fmt and fmt_size). This is quite often pretty limiting and you might need to use multiple bpf_trace_printk() invocations to log all the data. This limitation stems from the BPF helpers ability to accept only up to 5 input arguments in total.
> Previously, bpf_trace_printk() allowed the use of only one string (%s) argument, which was quite limiting. Linux 5.13 release lifts this restriction and allows multiple string arguments, as long as total formatted output doesn't exceed 512 bytes. Another annoying restriction was the lack of support for width specifiers, like %10d or %-20s. This restriction is gone now as well

> enum bpf_func_id___x { BPF_FUNC_snprintf___x = 42 /* avoid zero */ };

Ancient syscall-like way of global constant, instead of context


> Helper function bpf_snprintf
> Outputs a string into the str buffer of size str_size based on a format string stored in a read-only map pointed by fmt.
>
> Each format specifier in fmt corresponds to one u64 element in the data array. For strings and pointers where pointees are accessed, only the pointer values are stored in the data array. The data_len is the size of data in bytes - must be a multiple of 8.
>
> Formats %s and %p{i,I}{4,6} require to read kernel memory. Reading kernel memory may fail due to either invalid address or valid address but requiring a major memory fault. If reading kernel memory fails, the string for %s will be an empty string, and the ip address for %p{i,I}{4,6} will be 0. Not returning error to bpf program is consistent with what bpf_trace_printk() does for now.
>
> Returns
>
> The strictly positive length of the formatted string, including the trailing zero character. If the return value is greater than str_size, str contains a truncated string, guaranteed to be zero-terminated except when str_size is 0.
>
> Or -EBUSY if the per-CPU memory copy buffer is busy.
>
> static long (* const bpf_snprintf)(char *str, __u32 str_size, const char *fmt, __u64 *data, __u32 data_len) = (void *) 165;




1. in BPF_LD and BPF_LDX

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | Register number N |MSX|    BPF_EXTMODE    |PF_SIZE| BPF_CLASS |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |       jt = atomic op/reg      |        jf = from segment      |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                    2                   1

BPF_EXTMODE:

#define	BPF_IMM 	0x000	// 0 0 0 0 0 regs[N] <- k
#define	BPF_ABS		0x020	// 0 0 0 0 1 regs[N[ <- P[k:BPF_SIZE]
#define	BPF_IND		0x040	// 0 0 0 1 0 regs[N] <- P[X+k:BPF_SIZE]
#define	BPF_MEM		0x060	// 0 0 0 1 1 regs[N] <- M[k]
#define	BPF_LEN		0x080	// 0 0 1 0 0 regs[N] <- pkt.len
#define	BPF_MSH		0x0a0	// 0 0 1 0 1 X <- 4*(P[k:1]&0xf)
// BPF_IND+BPF_MSH	0x0e0	// 0 0 1 1 1 X <- 4*(P[X+k:1]&0xf) # when DLT unknown
#define	BPF_RODATA	0x0c0	// 0 0 1 1 0 regs[N] <- C[8*pc+imm:BPF_SIZE]
/* reserved		0x100	   0 1 0 0 0 */
#define	BPF_ABS_SEG	0x120	// 0 1 0 0 1 regs[N[ <- seg[jf]->P[k:BPF_SIZE]
#define	BPF_IND_SEG_X	0x140	// 0 1 0 1 0 regs[N[ <- seg[jf]->P[X+k:BPF_SIZE]
#define	BPF_IND_SEG_Y	0x160	// 0 1 0 1 1 regs[N[ <- seg[jf]->P[Y+k:BPF_SIZE]
#define	BPF_LEN_SEG	0x180	// 0 1 1 0 0 regs[N] <- seg[jf].len
#define	BPF_ABS_PKT_LE	0x1a0	// 0 1 1 0 1 regs[N[ <- from_leSIZE(P[k:BPF_SIZE])
#define	BPF_IND_PKT_LE	0x1b0	// 0 1 1 1 0 regs[N[ <- from_leSIZE(P[X+k:BPF_SIZE])
/* reserved		0x1e0	   0 1 1 1 1 */
/* reserved		0x200	   1 0 0 0 0 */
#define	BPF_ABS_CPU	0x220	// 1 0 0 0 1 regs[N[ <- perCPU(seg[jf], k, BPF_SIZE)
#define	BPF_IND_CPU_X	0x240	// 1 0 0 1 0 regs[N[ <- perCPU(seg[jf], X+k, BPF_SIZE)
#define	BPF_IND_CPU_X1	0x260	// 1 0 0 1 1 regs[N[ <- perCPU(seg[jf], X1+k, BPF_SIZE)
#define	BPF_ATOMIC	0x6e0	// 1 1 x x x mask for atomic operations

from_leSIZE() loads specified BPF_SIZE bytes which are little-endian. For
example, on little-endian platform loading BPF_H requires `ntohs()` but
`from_leH()` is no-op, on big-endian platform ordinary load do not require
conversion (it's already network byte order), but *_PKT_LE modes will require.
These modes defined only for packet access because other memory segment are
expected to be in native machine byte order. For rare cases when this is not
true, there is BPF_ENDIAN instruction in BPF_ALU class.

BPF_RODATA is for generic literal, addressing mode around `pc` in code
segment, see BPF_DATA_LITERAL instruction

22.07.24 need a way to pass not just words but *address* to cop-functions, e.g.
address of literal to `printf()` or structure addresses in shared segment for
complex table/map lookup functions
- похоже нет, нельзя, это принципиально дыра в безопасности - для cop-функций
  хватит индекса в сегменте
- но блин, а когда надо, для того же `printf()` ?..

TBD заюзать регистр 26 как kernptr, запретив на нём ALU ? но чем это
кардинально отличается от вычисления адреса из сегмента в самой cop-функции?..
а в не-ядре (железке) в таком регистре один фиг будет записан BPF_EMODE||jf||k
- имеет смысл для литерала из RODATA, если залочить регистр после записи
  (отлочивается в cop-функции) - ведь непосредственно в вызове можно только
  регистры передавать, а для RODATA там в каждой инструкции своё смещение

TBD может вообще режимы переделать? сунуть их все в jf например, а то 256
сегментов многовато, да и не ортогональный какой-то enum получается...

это же еще возможен NULL на сегмент / загрузка сегмента в результате функции,
типа lookup_dyn_rule() какой-нибудь

продумывать механизм сигналов/исключений? типа сегмент NULL, хэндлер инсталлит
сгемент, повторяем операцию?

23.07.24 23:59 а как системы с managed-памятью? вот в перле ссылка - не адрес
а может, перловый скаляры передавать в kernel cop-функции? типа вот инструкция
сказала newSVpvn() "на две трети этого литерала", и теперь в cop-функции можно
передавать номер скаляра и индекс в нём; скаляр содержит тип, так что не
будет создан новый при передаче тех же параметров, а вернут существующий, etc.

the answer lies in the managed-memory languages

получатся скаляры как fd-дескрипторы - часть environment

тогда может и сегменты переделать на скаляры? вопрос со статикой-динамикой,
они же в jf, а регистров - мало, и аллокации памяти во время работы тормозно

не, ну можно ввести разделение по диапазону - вот статические, вот (регистр)
динамические, и для статических затребовать в инструкции конкретный номер

если можно новый скаляр создавать из другого, тогда между ними нужно вести
бухгалтетрию
- хотя это проблемы ядра/машины, а не программы

можно в каждом скаляре хранить его OFFSET как сохранённое значение для X и
загружать в X с помощью BPF_MSH
- тогда его туда как-то и сохранять надо

25.07.24
по аналогии с селекторами 386, младшие 2 бита jf - тип операции,
обычный/atomic/perCPU, остальное - номер сегмента; если номер на 0xf то 2 бита
на номер сегментного регистра

вообще нужно-то что... BPF_ABS, BPF_LEN и BPF_IND расширить сегментом,
BPF_IND расширить как можно больше индексных регистров, BPF_ABS и BPF_IND
расширить PKT_LE для пакета, но не для сегмента, и где-то еще прилепить RODATA

		classic		PKT_LE		segment		X regs
BPF_ABS:	1		1		1		0
BPF_IND:	1		1		1		* N
BPF_LEN:	1		0		1		MSH?

BPF_RODATA можно вынести как BPF_IMM в спец. сегменте 0, тогда его код
0xc0 = BPF_IND+BPF_LEN можно сделать как P[Y+k:BPF_SIZE], а в старшие 2 бита
уже выбор: 0 - обычный, 1 - PKT_LE, 2 - сегмент в jf
- не, под PKT_LE его, модификатор - точнее BPF_L

кстати, BPF_MSH = BPF_ABS+BPF_LEN, есть логика - тогда надо BPF_IND+BPF_LEN
для X <- 4*(P[X+k:1]&0xf)
BPF_MSH разрешен же только в LDX для самого X <- т.е. можно реюзнуть в LD ?
а вообще всего два индексных регистра хватит, надо оставить для расширения

в LDX всего 4 режима, BPF_IND среди них нет, значит таки BPF_IND+BPF_MSH
а в LD реюзать BPF_MSH нельзя - вдруг ошибка программиста? в валидатор можно сунуть
значит таки 0xc0 = BPF_IND+BPF_LEN идёт как P[Y+k:BPF_SIZE]

=== variant 2:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | Register number N |SIG|    BPF_EXTMODE    |PF_SIZE| BPF_CLASS |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |  jt = atomic op   |WID|A/B/C/D|    jf = from segment  | Type  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                    2                   1

BPF_EXTMODE:

#define	BPF_IMM 	0x000	// 0 0 0 0 0 regs[N] <- k
#define	BPF_ABS		0x020	// 0 0 0 0 1 regs[N[ <- P[k:BPF_SIZE]
#define	BPF_IND		0x040	// 0 0 0 1 0 regs[N] <- P[X+k:BPF_SIZE]
#define	BPF_MEM		0x060	// 0 0 0 1 1 regs[N] <- M[k]
#define	BPF_LEN		0x080	// 0 0 1 0 0 regs[N] <- pkt.len
#define	BPF_MSH		0x0a0	// 0 0 1 0 1 X <- 4*(P[k:1]&0xf)
#define	BPF_IND_Y	0x0c0	// 0 0 1 1 0 regs[N] <- P[Y+k:BPF_SIZE]
// BPF_IND+BPF_MSH	0x0e0	// 0 0 1 1 1 X <- 4*(P[X+k:1]&0xf) # when DLT unknown

#define BPF_SIGN	0x400

#define BPF_L		0x100
#define BPF_SEG		0x200

#define	BPF_RODATA (BPF_L|BPF_IMM) // 0 1 0 0 0 regs[N] <- C[8*pc+imm:BPF_SIZE]

#define BPF_PERCPU	0x01
#define	BPF_ATOMIC	0x02
/* type 03 reserved */

BPF_SEG|BPF_MEM may be used in future for additional segment attributes

for atomic operations requiring 3 arguments, only registers A or B or C or
D are allowed as third operand, and returned (boolean) value from such
functions is always placed in A

TBD this is 5 bits for register, loop counters are prohibited to LD - use
128-bit instead? if so, ignore BPF_SIZE, or reserve it for possible 256-bit?
and address - for mem use M[k] & M[k+1] ? in which order?
- what to do in BPF_ST? do we allow saving loop registers, IPv6 to pkt?
- use 2 instrs in LDX/STX for M[k] in 128: hi and lo
- 06.09.24 treat this 5 bits as 6 with upper set (see this day in ALU), M[]
  will be treated as "bytes" for extended registers, and we don't need to
  refer to 32 bit registers here - there's sign extend bit if loading B/H/W;
  rethink Z() to MASK() counting from right extending to infinity - for future
  registers wider than 128 bits
  - 07.09 what if bit/byte vector strings instead? then IPv6 (128) is just
    fixed width particular case and any strings can be used (e.g. for text
    protocols) by special SVs, but how to load then? cur++ ? and Z() be
    rethought to even more generic... OZm/a (e.g. OZ128/48), ZO-35 ?
  - 07.09 SIGN/MSX bit do not match it's place with BPF_ALU/BPF_JMP, but we
    don't need 6 bits here as BPF_SIZE tells it already, what to do? in ane
    case put a note (rationale) to spec
    - eBPF has `is_sdiv_smod() insn->off == 1`, `is_movsx() off == 8/16/32`
      and BPF_MEMSX as bit in BPF_MODE 

TBD which mode for loading address to KERN, and which for types to KERN?
- what if both at the same time? possible if it's k/imm only; so impl
  remembers address and then uses either address or operand depending on
  using instruction

TODO let's `jt` be all related aTomicity per platform, including per-CPU etc.,
with zero value "no such special things", and `jf` just segment number
- 18.08 or not: counter(9), their array, magic... may be 4 bits for type
  (system-dependent), 0xf0..f9 for RODATA segments, 0xfa..0xff selectors?
  - 19.08 if add ipfw tables like %HV, then just 15 segs is too small
    - but get_sv() is possible, just will need to error check every time...
    - however, ipfw tables are external to bpf64, they are not in sysctl
    - well, generic %map can include type and accessor funcs ("tied HV"), so
      code from ipfw tables could be reused to be independent space in sysctl
- 07.09 for extended (IPv6/string) registers, `jt` may be load offset, see
  also this day for SIGN/MSX problem, may be also here - name it as `Type`?
  universal name, as atomicity is also type, and atomicity can't be for
  extended registers as they are more than native word size

TBD naming: global? extern?

TODO make distinguishable from CBOR: 0xd9 is in BPF_LDX class
d9 d9f7                       # tag(55799)
with BPF_MODE 0xc0 and BPF_B size
so don't use 0xc0 ? seems ERR here...

2. in BPF_ST

Here existing implementations check just BPF_ST or BPF_STX, that is, BPF_IMM
is treated like BPF_MEM. However, new code need not be defined, because there
is no point to store in 'k' of instruction - self-modifying code can't be
verified.

TBD

4. in BPF_ALU

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | Register number N |MSX|WID|XFK|     BPF_OP    |SRC| BPF_ALU=4 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |      jt - "to" register       |     jf - "from" register      |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

WID=0 - 32-bit registers, WID=1 - 64-bit registers

#define	BPF_ADD		0x00
#define	BPF_SUB		0x10
#define	BPF_MUL		0x20
#define	BPF_DIV		0x30
#define	BPF_OR		0x40
#define	BPF_AND		0x50
#define	BPF_LSH		0x60
#define	BPF_RSH		0x70
#define	BPF_NEG		0x80
#define	BPF_MOD		0x90
#define	BPF_XOR		0xa0
/*			0xb0	reserved */
#define	BPF_ARSH	0xc0	/* sign extending arithmetic shift right */
#define	BPF_ENDIAN	0xd0	/* byteswap/endianness change */
#define	BPF_SDIV	0xe0	/* signed division */
#define	BPF_SMOD	0xf0	/* signed %= */

TBD two new opcodes sdiv/smod or MSX bit? BPF_NOT is missing, and if put it to
0xb0 then no reserved left if sdiv/smod used
TBD also, are we guaranteed that jt and jf will always be 0 in cBPF ? if yes,
then regs[jt] and regs[jf] could be used, if no, then need J bit for using them!
BPF_STMT macro sets them to 0, tcpdump also emits 0, but what if
non-conformant compilers exist?..

or do 'jt' as 'third' ? e.g. X, Y, or CIDR with counts of 1's and 0's in k
- 06.09.24 yes, third: the register in `code` is always lvalue (left to `=`)
  - 07.09 well, what if BPF_K ? may be unify with BPF_JMP variant 2 ?
    - and when "k is just k" also, use BPF_SIGN to extend k to 64 bits, so now
      sign bit is not for ARSH/SDIV/SMOD only, but more broad
    - so `jt` is now reserved and MUST be 0 for future extensions, and R() and
      Z() encodings may use full 32 bits of `k`

`Z(k)` means "zero-ones pseudo-register" described as follows - take low byte
of `k` and interpret it as:

      MSB      6       5       4       3       2       1       0
    +-------+-------+-------+-------+-------+-------+-------+-------+
    |Starts |Number of 'Starts' bit, then it's inversion bits to 128|
    +-------+-------+-------+-------+-------+-------+-------+-------+

That is, it is used not only as "zero" register, but for CIDR operations:
netmask and hostmask. For example, /48 netmask will be 0xb0 and mean 48 1's
and then 80 zeroes; hostmask for /48 will be 0x30 - starts with 0, so 48
zeroes and 80 ones.

Note that filling is from MSB to LSB, but application for smaller register
widths is from right - e.g. 0xf0 is /112 for IPv6, mask 0xffff_ffff_ffff_0000
for 64-bit registers, and 0xffff0000 i.e. /16 for IPv4 / 32-bit registers.

`R(k)` is `Z(k)` with part of values taken to be register identifier, based on
fact that hostmasks for very large IPv6 subnets are rarely used - however, if
provided `k` has more than 8 bits width (it's really `k` and not e.g. `jt`/`jf`),
then such values are still available - e.g. `R(0x106)` is equal to `Z(6)`.

The beginning of value space is number of register and/or it's width. In some
classes only 5 bits are available, for that 0-31 are "generic", sometimes with
separate width bit, or implied by context. If not, and more bits are
available, width from table below is used.

   Num | Name | Bits | Type            | Visible | Comments
   ====+======+======+=================+=========+=======================
    0  |   A  |  32  | General-purpose | Global  | Accumulator
    1  |   B  |  32  | General-purpose | Global  | 
    2  |   C  |  32  | General-purpose | Global  | 
    3  |   D  |  32  | General-purpose | Global  | 
    4  |   E  |  32  | General-purpose | Global  | 
    5  |   F  |  32  | General-purpose | Global  | 
    6  |   G  |  32  | General-purpose | Global  | 
    7  |   H  |  32  | General-purpose | Global  | 
    8  |   W0 |  32  | Rotated/renamed | Local   | usually 1st arg to func
    9  |   W1 |  32  | Rotated/renamed | Local   | 2nd arg to func
    10 |   W2 |  32  | Rotated/renamed | Local   | and so on
    11 |   W3 |  32  | Rotated/renamed | Local   | 
    12 |   W4 |  32  | Rotated/renamed | Local   | some of them is first
    13 |   W5 |  32  | Rotated/renamed | Local   | local variable
    14 |   W6 |  32  | Rotated/renamed | Local   | 
    15 |   W7 |  32  | Rotated/renamed | Local   | some for input/output
    16 |   W8 |  32  | Rotated/renamed | Local   | with next callee
    17 |   W9 |  32  | Rotated/renamed | Local   | 
    18 |  W10 |  32  | Rotated/renamed | Local   | 
    19 |  W11 |  32  | Rotated/renamed | Local   | 
    20 |  W12 |  32  | Rotated/renamed | Local   | 
    21 |  W13 |  32  | Rotated/renamed | Local   | 
    22 |  W14 |  32  | Rotated/renamed | Local   | 
    23 |  W15 |  32  | Rotated/renamed | Local   | 
    24 |  W16 |  32  | Rotated/renamed | Local   | 
    25 |  W17 |  32  | Rotated/renamed | Local   | 
    26 | KERN | N/A  | Special: k-addr | Opaque  | W.O.R.K.
    27 |Reserved for future use as flags & trap jump condition
    28 |   I  |  32  | Special: loop 0 | Local   | read-only, most outer loop
    29 |   J  |  32  | Special: loop 1 | Local   | read-only 
    30 |   K  |  32  | Special: loop 2 | Local   | read-only 
    31 |   L  |  32  | Special: loop 3 | Local   | read-only, most inner loop 
   ----+------+------+-----------------+---------+-----------------------
    32 |  Ad  |  64  | General-purpose | Global  | A is low 32 bits of Ad
    33 |  Bd  |  64  | General-purpose | Global  | B is low 32 bits of Bd
    34 |  Cd  |  64  | General-purpose | Global  | and so on
    35 |  Dd  |  64  | General-purpose | Global  | 
    36 |  Ed  |  64  | General-purpose | Global  | 
    37 |  Fd  |  64  | General-purpose | Global  | 
    38 |  Gd  |  64  | General-purpose | Global  | 
    39 |  Hd  |  64  | General-purpose | Global  | 
    40 |  R0  |  64  | Rotated/renamed | Local   | usually 1st arg to func
    41 |  R1  |  64  | Rotated/renamed | Local   | 2nd arg to func
    42 |  R2  |  64  | Rotated/renamed | Local   | and so on
    43 |  R3  |  64  | Rotated/renamed | Local   | 
    44 |  R4  |  64  | Rotated/renamed | Local   | some of them is first
    45 |  R5  |  64  | Rotated/renamed | Local   | local variable
    46 |  R6  |  64  | Rotated/renamed | Local   | 
    47 |  R7  |  64  | Rotated/renamed | Local   | some for input/output
    48 |  R8  |  64  | Rotated/renamed | Local   | with next callee
    49 |  R9  |  64  | Rotated/renamed | Local   | 
    50 |  R10 |  64  | Rotated/renamed | Local   | 
    51 |  R11 |  64  | Rotated/renamed | Local   | 
    52 |  R12 |  64  | Rotated/renamed | Local   | 
    53 |  R13 |  64  | Rotated/renamed | Local   | 
    54 |  R14 |  64  | Rotated/renamed | Local   | 
    55 |  R15 |  64  | Rotated/renamed | Local   | 
    56 |  R16 |  64  | Rotated/renamed | Local   | 
    57 |  R17 |  64  | Rotated/renamed | Local   | 
    58 |   X  |  32  | Special: index  | Global  | 
    59 |   Y  |  32  | Special: index  | Global  | 
    60 |   Z0 | 128  | Special: IPv6   | Global  | no ALU except AND/OR
    61 |   Z1 | 128  | Special: IPv6   | Global  | no ALU except AND/OR
    62 |   Z2 | 128  | Special: IPv6   | Global  | no ALU except AND/OR
    63 |   Z3 | 128  | Special: IPv6   | Global  | no ALU except AND/OR

TBD more index registers? shadow / bank switching registers? scalar selector register?
- no bank-switching, there's BPF_MEM for it

TBD 06.09.24 VL0.., BPF_B for 64 bit; X & Y to 26/27;
5 selectors - last (F) reserved;
just 6 bit var instead of WID in ALU?

TBD

5. in BPF_JMP

This class retains forward jumps only, so includes only two of three loop opcodes.

				// SRC = BPF_K or BPF_X
#define	BPF_JA		0x00	// pc += k
#define	BPF_JEQ		0x10	// pc += (A == SRC) ? jt : jf
#define	BPF_JGT		0x20	// pc += (A > SRC) ? jt : jf
#define	BPF_JGE		0x30	// pc += (A >= SRC) ? jt : jf
#define	BPF_JSET	0x40	// pc += (A & SRC) ? jt : jf
#define BPF_JNE		0x50	/* jump != */
#define BPF_JSGT	0x60	/* SGT is signed '>', GT in x86 */
#define BPF_JSGE	0x70	/* SGE is signed '>=', GE in x86 */
#define	BPF_LOOP_NEXT	0x80	/* loop 'continue' / 'break' */
#define	BPF_LOOP_OPEN	0x90	/* loop start' */
#define BPF_JLT		0xa0	/* LT is unsigned, '<' */
#define BPF_JLE		0xb0	/* LE is unsigned, '<=' */
#define BPF_JSLT	0xc0	/* SLT is signed, '<' */
#define BPF_JSLE	0xd0	/* SLE is signed, '<=' */
#define BPF_JEXT	0xe0	/* extended operation in BPF_JMPMODE */
/*			0xf0	reserved */

The codes 0x50-0x70 and 0xa0-0xd0 are taken from eBPF with the same meaning
and reason - classic BPF always had `jt` and `jf` fields so only half of
instructions were needed - in case of needing '<=' instead of '>' one could
always just swap true and false branch destinations. By extending `jt` to
`off16` and `jf` always 0, this is no longer possible.

ну тут всё понятно, интереснее расширения / зе луп

Extended format for all except loops:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | Register number N |BPF_JMPMODE|    BPF_OP     |SRC| BPF_JMP=5 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |               jt              |               jf              |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

When BPF_JMPMODE is zero, opcodes behave almost as in cBPF - 32-bit registers
and unsigned `jt`, `jf` are used, except that unsigned `k` in unsigned opcodes
but signed `imm` in signed variants, and non-A general-purpose register,
if it is non-zero.

Otherwise, BPF_SRC bit is not used directly but as high bit together with
BPF_JMPMODE forming nibble of mode with meanings:

   SRC | MODE  | Hex | Meaning:
   ====+=======+=====+=======================================================
    0  | 0 0 0 |  0  | unusable - classic BPF
   ----+-------+------+------------------------------------------------------
    0  | 0 0 1 |  1  | regs[N] OP k
    0  | 0 1 0 |  2  | regs[N] OP R(k)
    0  | 0 1 1 |  3  | W=1 k
    0  | 1 0 0 |  4  | W=1 R(k)
    0  | 1 0 1 |  5  | 
    0  | 1 1 0 |  6  | 
    0  | 1 1 1 |  7  | 
   ----+-------+-----+------------------------------------------------------
    1  | 0 0 0 |  8  | unusable - classic BPF
   ----+-------+-----+------------------------------------------------------
    1  | 0 0 1 |  9  | 
    1  | 0 1 0 |  a  | AAAA=1 k
    1  | 0 1 1 |  b  | AAAA=1 Z(k)
    1  | 1 0 0 |  c  | AAAA=1 R(k)
    1  | 1 0 1 |  d  | 
    1  | 1 1 0 |  e  | 
    1  | 1 1 1 |  f  | 

=== variant 2 (24.07.24)

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |          R(N)         |OFF|Rk |    BPF_OP     |SRC| BPF_JMP=5 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |               jt              |               jf              |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

if off=1, then 16 bit unsigned `off` field is used instead of `jt` and `jf` is
implicitly zero

if SRC=BPF_X then it is X if Rk=0, otherwise R320(k) is used
validator must check for permitted combinations e.g. different width 32/64/128

TBD Rk is not enough for extended op - ranges, table...

=== /variant 2

TBD do we really need 16-bit offset insead of jt/jf given 32-bit BPF_JA ?
in eBPF it's needed because backward jumps are allowed (and they can't use
`imm` there), but we have them only for loops - which may be rethought,
and restoring jt/jf allows to free more opcodes in BPF_JMP again

TBD 07.09 see ALU: Rk rename to XFk, no OFF, SIGN bit instead
- or no sign bit: adding just BPF_JSGT and BPF_JSGE is not such waste as '<'
  and '<=' and their signed versions

TBD

BPF_LOOP_OPEN:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |     Reserved      |SUB|LoopVar| BPF_OP = 0x90 |SRC| BPF_JMP=5 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |           MUST point to corresponding BPF_LOOP_BACK           |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |     Start value: imm (signed) if BPF_K or R26(k) if BPF_X     |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

TODO `while` flag for `while(){}` / `do{}while()` - do test in BPF_LOOP_BACK
immediately after load or execute body at least once

BPF_LOOP_NEXT:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |     Reserved      |SUB|LoopVar| BPF_OP = 0x80 |SRC| BPF_JMP=5 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |           MUST point to corresponding BPF_LOOP_BACK           |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |      abs(increment_value): k if BPF_K or R26(k) if BPF_X      |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

if BPF_LOOP_LAST (0), then loop is terminated early - "break"

validator MUST strictly check that there is no NEXT I inside loop on j, k, l
and no NEXT J or NEXT I in loops on k, l, etc. - that is, that nesting is
proper

TBD


6. in BPF_RET

Opcodes in this class are altering control flow graph program in a
possibly non-forward way - e.g. BPF_JMP allows only forward jumps, but BPF_RET
allows to jump backwards or even terminate current program.

The first is BPF_EXIT, the only instruction in this class in classic BPF.
It returns from current function or entire program, yielding return value in
register A for caller, if it was a procedure. Here for BPF_RVAL allowed values
are BPF_A, BPF_K and BPF_X. If more parameters were needed by calling
procedure, they are passed in input section of rotated registers.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |                               |BPF_EXIT=0 | _RVAL | BPF_RET=6 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

If a return was to previous function in the stack, register window is
automatically restored as it was in previous function.


* BPF_CALL:

Call a function. Backward address is allowed. Return address is placed in
shadow (back) stack. From the register window point of view, call is two-part
process - first, calling procedure advances window, hiding it's own input and
local registers from callee. Then, simple callee may choose to not do anything
at all, but if callee plans to call another functions, the rest of window must
be set up with BPF_PROLOG instruction.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |RegWindow shift| 0/BPF_L/BPF_S |BPF_CALL=1 | _RVAL | BPF_RET=6 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                imm (signed): pc += imm                        |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

TODO different calling conventions - to function by pc+imm if 0, to BPF
machine if BPF_L and external kernel functiond when SV/segment-wrapped,
also think about simple `k` resolving like in NetBSD bpf_ctx_t and with
run-time (may be each call) resolving by ASCII name; SV/segment-wrapped
means arguments are *not* in registers so they must be prepared before
call in some temporary space - pushtr/pushtv? Perl's ST(n) ?

<<
The question remains on when the SVs which are targets for opcodes are created. The answer is that they are created when the current unit--a subroutine or a file (for opcodes for statements outside of subroutines)--is compiled. During this time a special anonymous Perl array is created, which is called a scratchpad for the current unit.
>>

TODO jt != 0 & jf != 0 - it's `catch` (pairs like 'error => labelname' in awc)
TBD or not in `call`? where to capture other [trappable] exceptions?
- loop meta-body (with call(s) inside) seems like natural catch{} block


* BPF_PROLOG:

  Usually the first instruction of called function. Advances register window,
  declaring how many local and output registers will be used.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | # input regs  | # to max regs |     2     | _RVAL | BPF_RET=6 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                   Offset to end of function                   |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

  Caller reserves it's output registers number to maximum of any called
  function can accept. Thus every called function must declare how many
  it has input registers actually - and reserves rest of space for both local
  and it's own output registers. Then, when it's time to do it's own call,
  it knows how many local registers it has and advances window by this number
  in BPF_CALL.

  As it can be seen from field sizes, both `(input+local) <= 15` and
  `(local+output)` <= 15` (that's not a big restriction given small number of
  available rotating registers). Limiting output registers is two-purpose: to
  not overdo zero initialization of those registers on call and to check for
  errors - an exception will be thrown on access to register after declared.

  Also note that this scheme allows caller to have different number of local
  registers for different callees - e.g. if between child calls some local
  registers became no longer needed temporaries, it can advance window for
  lesser number, leaving more space for output parameters for next call.

  The `k` points to last instruction of function body - used by validator to
  check that within these boundaries there are no jumps outside of the
  function.

TBD is this needed? e.g. if optimizing compiler decides to split

TBD 02.08 вообще loop какой-то некрасивый, в Tcl у return есть дополнительные
коды ok/error/return/break/continue - вот и генерализованные exceptions заодно

* BPF_LOOP_BACK:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |  BPF_J*       |   |SUB|LoopVar|     3     | _RVAL | BPF_RET=6 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |           MUST point to corresponding BPF_LOOP_OPEN           |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |               Final LoopVar value: always constant            |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

If this instruction was reached by "natural" means, operates on LoopVar like
BPF_LOOP_NEXT, otherwise it was jump here from BPF_LOOP_NEXT which did t his already.
Then checks LoopVar by corresponding code from BPF_JMP class and if true,
`off` is used for jump backwards to first instruction after corresponding
BPF_LOOP_OPEN. If result of test was false, or instruction reached by jump
from BPF_LOOP_LAST, the loop is terminated, marked internally as reset, and
control is passed to next instruction after BPF_LOOP_BACK.

TBD 02.08.24 what if combine loop and call, to have "blocks" instead, with
only one loop counter per frame and accessing others as "uplevel var"? This
would give much higher limit on loop nesting, would allow "next J" and local
variables in block (that is, like Perl context stack); also equivalent to
tail recursion (hello, factorial :)

TBD 08.08.24 if make BPF_LOOP for only one next instruction, like REP in x86,
then it would be for e.g. memory clear (if X++ added) or CALL to body

TBD 18.08.24 seems that OPEN/BACK will be a special catch block, but with
scanning till finding BPF_LOOP_BACK in case of return next/last, which are
the Tcl's way, so there will LC0..LC3 for upper stack frames - and
"short simple" loop form (without call) is the only which utilizes LC0; and
so syntax must be changed: {} are [prolog] blocks of stack frames, so loop
do/done and if/then/fi instead of braces, highlighting the fact labels are
local to block; so no NEXT/LAST opcodes - move them to BPF_EXIT, and rethink
syntax of variable declarations as they can now be in every block (even
somewhat like to closures and anon/nested subs?)
- 19.08 here problem with jumps out of the loop - on exception it will scan
  a lot and won't find BPF_LOOP_BACK (see parse_ipv6() in nuc_ts_incr.baw)
  - so again call-block only which is slow? or can we optimize it somehow?

TBD let's try how this look in code...

#define RETURN(x) if (caller_arg!=NULL) *caller_arg=retcode; return (x);
#define DIE ... //similar
	while (1) {
		++pc;
		switch (pc->code & 0x00ff) {
		case BPF_RET|BPF_K:
			A = ((u_int)pc->k);
		case BPF_RET|BPF_A:
			retcode = pc->code >> 8;
			if (bsp == 0)
				RETURN ((u_int)A);
			pc = backstack[bsp]->ret;
			bsp--;
			if (pc->code == BPF_LOOP &&
			    backstack[bsp]->flags == BPF_BSFLAG_LOOP_DESC) {
				/*
				 * Optimization for loop body - reuse frame.
				 */
				if (retcode >= BPF_RETURN) {
					/* As if it was on this level */
					pc = backstack[bsp]->ret;
					bsp--;
					/* TODO -level and error handling /
				 }
				 else {
					/* Loop continuation. */
					int decr = retcode == BPF_NEXT ? A : 1;
					if (decr == 0 && retcode == BPF_NEXT)
						DIE(INFINITE_LOOP);
					/* Handle both do/while and next too big */
					if (decr >= backstack[bsp]->loop_counter)
						backstack[bsp]->loop_counter = 0;
					else
						backstack[bsp]->loop_counter -= decr;
					if (retcode == BPF_LAST ||
					    backstack[bsp]->loop_counter == 0) {
						backstack[bsp]->flags |= BPF_BSFLAG_LOOP_DONE;
						/* Leave bsp/counter as is */
					} else {
						/* Return to loop body. */
						pc += pc->jt; // XXX
						bsp++;
					}
				 }
			}
			continue;
		...
		case BPF_JMP|BPF_JA:
			pc += pc->k;
			continue;
		case BPF_JMP|BPF_JGT|BPF_K:
			pc += (A > pc->k) ? pc->jt : pc->jf;
			continue;
		...
		case BPF_RET|BPF_CALL:
			if (bsp >= BPF_MAX_BACKSTACK)
				DIE(BACKSTACK_OVERFLOW);
			int shft = (pc->code >> 12) + backstack[bsp]->reg_shift;
			if (shft > 255)
				DIE(REGSTACK_OVERFLOW);
			bsp++;
			backstack[bsp]->ret = pc;
			backstack[bsp]->ctx = whatever_callee_ctx(pc);
			backstack[bsp]->reg_shift = shft;
			backstack[bsp]->reg_input = 0; /* XXX if no prolog? */
			backstack[bsp]->reg_local = 0;
			backstack[bsp]->flags = 0;
			backstack[bsp]->loop_counter = 0;
			... //adjust & other checks by cmd flags etc.
			pc += (int)pc->k; // actuall get by flags
			continue;
		...
		case BPF_LOOP:
			if (bsp >= BPF_MAX_BACKSTACK)
				DIE(BACKSTACK_OVERFLOW);
			if (backstack[bsp]->flags == BPF_BSFLAG_LOOP_DESC)
				DIE(LOOP_ALREADY_ACTIVE);
			backstack[bsp]->flags = BPF_BSFLAG_LOOP_DONE;
			backstack[bsp]->loop_counter = get_reg_or_k(pc);
			if (backstack[bsp]->loop_counter == 0)
				continue; // XXX do/while flag
			backstack[bsp]->flags = BPF_BSFLAG_LOOP_DESC;
			bsp++;
			backstack[bsp]->ret = pc;
			backstack[bsp]->ctx = backstack[bsp-1]->ctx;
			// TODO prolog
			backstack[bsp]->reg_shift = backstack[bsp-1]->reg_shift;
			backstack[bsp]->reg_input = get_prolog_input(pc);
			backstack[bsp]->reg_local = get_prolog_local(pc);
			backstack[bsp]->flags = BPF_BSFLAG_PROLOGSEEN;
			backstack[bsp]->loop_counter = 0;
			... //adjust & other checks by cmd flags etc.
			pc += (int)pc->jt; // XXX
			continue;

TBD ok, it's single instruction now, then why 3 states? they are now impossible?

TBD 07.09 what if we'll have more registers, and even if not, it's better for
JITs to know which registers are local, so need decoupling local+out thus:
1) space for it in backstack frame (at least 5 bits for each possible in 16)
2) in BPF_LOOP/BPF_RET optimization above, probably decouple BPF_PROLOG from
   BPF_LOOP (too little space in upper `code` + `jf`) - e.g. check by seen
   flag in body? or check `jt` points to BPF_PROLOG ?


TBD 31.08.24 if verifier is simple, but having killed by timeout is too ugly for solution, may be statistical approach: if program consumed too much time on a first few launches, mark it as bad?

#define BPF_BSFLAG_LOOP_MASK	0x03	/* loop state bits */
#define BPF_BSFLAG_LOOP_NONE	0	/* not started, throw on LC access */
#define BPF_BSFLAG_LOOP_ASC	1	/* counter incrementing \ die on   */
#define BPF_BSFLAG_LOOP_DESC	2	/* counter decrementing / new loop */
#define BPF_BSFLAG_LOOP_DONE	3	/* finished, l.counter accessible */
#define BPF_BSFLAG_PROLOGSEEN	0x04	/* BPF_PROLOG was issued */
#define BPF_BSFLAG_CATCHING	0x08	/* return will be to BPF_CATCH */

struct bpf_backstack_frame {
	struct bpf_insn *ret; // XXX what for C functions?
	bpf_ctx_t	*ctx;		/* where we live in? */
	uint8_t		reg_shift;	/* base for input registers */
	uint8_t		reg_input;	/* locals after reg_shift+this */
	uint8_t		reg_local;	/* local+out: reg_shift+input */
	uint8_t		flags;		/* is loop active & other */
	uint16_t	start_tick;	/* profiling/kill: time entered */
	uint16_t	loop_counter;	/* value for loop counter */
};

#define BPF_MAX_MEMWORDS	128
#define BPF_MAX_BACKSTACK	32
#define BPF_MAX_REGWINDOW	264

/* typed args, e.g. for printf(), 256 bytes */
struct bpf_argv {
	uint8_t		argc;		/* # args, 0..15 */
	uint8_t		argtypes[15];	/* their types as in bpf_sv */
	bpf_sv_union_t	argvalues[15];	/* and actual values like in bpf_sv */
};

/* Entire "process" and "CPU" memory - fit on 4 Kb page */
struct bpf_process_mem {
	STAILQ_ENTRY ...		/* XXX other housekeeping */
	uint64_t	start_tick;	/* do we run too much? base for bsp */
	struct bpf_insn *kreg_pc;	/* pc when KERN register written */
	uint16_t	ds, es;		/* segment selector registers */
	uint32_t	X, Y;		/* index registers */
	uint8_t		bsp;		/* backstack pointer */
	uint8_t		kreg_flags;	/* KERN reg locked? */
	uint8_t		__align[26];	/* to 64 bytes from beginning */
	uint64_t	g_regs[8];	/* A..H (64 bytes) */
	struct in6_addr Z[4];		/* 128-bit registers (64 bytes) */
	struct bpf_backstack_frame backstack[BPF_MAX_BACKSTACK]; /* 768 bytes */
	uint64_t	reg_window[BPF_MAX_REGWINDOW];	/* 2112 bytes */
	uint64_t	mem[BPF_MAX_MEMWORDS];	/* 1024 bytes * */
};

TODO bpf_argv, *input_argv, scalar_table[], space for exception handlers

in accepting programs, references to SVs are first created in local table and
then numbers are converted in argv
TBD so inside of caller's bpf_process_mem? then need some prevention for
caller to read it back to avoid real pointers leak
- better to place pointer so program will create SV only if/when needed,
  but this requires 12 bytes / unaligned ptr in argdwords

There is limit on bpf_argv to fit on page (to avoid malloc's for individual
SV's) but cheat is possible by passing AV in args
TBD should bpf_printf() flatten such arrays as in Perl?

* BPF_TAILCALL:

#define BPF_TAILCALL 0x80

  Like `execve()` - replaces current running BPF program with another one. The
  stack is rewinded - current output registers become input registers at
  offset 0, all loops are reset. All other registers are reset, except A.
  The retained resources consist only of A and input (former output)
  registers as "argv", current packet and memory segments and first
  `jt` (default BPF_MEMWORDS) of scratch memory as "environment".
  Everything other is cleared, just like if new program was loaded fresh.

  The platform-dependent identificator of new program is in `k` or `X`. The
  instruction does not return if load was successful, otherwise execution is
  continued from next instruction with A set to error number (so that program
  could e.g. deny or accept packet).

TBD addressing mode for using `k` as pointer to string in RODATA, and string
in segment - for dynamic dispatch

TBD tailcall should be a flag to external CALL and don't waste opcode


25.07.24 04:30 Эльбрус использует расширение регистрового окна два раза - вызывающая
скрывает свои локальные, вызываемая расширяет на свои локальные
http://ftp.altlinux.org/pub/people/mike/elbrus/docs/elbrus_prog/html/chapter9.html#register-description
- вот и решение проблемы нехватки битов на 3 группы сразу в прологе


7. in BPF_MISC:

Here as it was in classic BPF:

#define	BPF_TAX		0x00
/*			0x08	reserved */
/*			0x10	reserved */
/*			0x18	reserved */
#define	BPF_COP		0x20	/* NetBSD "coprocessor" extensions */
/*			0x28	reserved */
/*			0x30	reserved */
/*			0x38	reserved */
#define	BPF_COPX	0x40/* 	NetBSD "coprocessor" extensions */
/*				also used on BSD/OS */
/*			0x48	reserved */
/*			0x50	reserved */
/*			0x58	reserved */
/*			0x60	reserved */
/*			0x68	reserved */
/*			0x70	reserved */
/*			0x78	reserved */
#define	BPF_TXA		0x80
/*			0x88	reserved */
/*			0x90	reserved */
/*			0x98	reserved */
/*			0xa0	reserved */
/*			0xa8	reserved */
/*			0xb0	reserved */
/*			0xb8	reserved */
/*			0xc0	reserved; used on BSD/OS */
/*			0xc8	reserved */
/*			0xd0	reserved */
/*			0xd8	reserved */
/*			0xe0	reserved */
/*			0xe8	reserved */
/*			0xf0	reserved */
/*			0xf8	reserved */

BPF_TAX and BPF_TXA:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |        R32        |X numspace | BPF_TAX / BPF_TXA | BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                               | jf = register in number space |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

Extended number spaces:

0 - X register
1 - Y register
2 - 128-bit registers
3 - segment selector registers
4-7 reserved for future use

This way, it is possible to add more registers in the future, e.g. 128-bit
registers for IPv6 addresses - while only four of them will be available for
direct use in ALU/JMP/LD commands, it will be possible to have more fast
registers in hardware for storage than to reload from slower (host) memory.

TBD 06.09 do we need number spaces? see this day in ALU et al.


Extended length instructions:

Codes greater than 0x80 are for instructions which [may] occupy more than one
`bpf_insn`

=== variant 1

#define		BPF_LD128IMM	0x60	/* NEW */

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |                               | 1 |InstrOffset|MIF| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

      InstrOffset - 0 for first, 1 for second, etc.
      MIF - more instructions flag, like MF in IPv4

So errorneous jump into middle of instruction will be detected by non-first
offset, and invalid encoding of offset=0 and more=0 (header, but no next
instruction) will be impossible - it is BPF_TXA.

Two extended instructions are currently defined.

* BPF_STRING_LITERAL:

first instruction:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |BPF_STR_LITERAL = 0|PrcntBitmap| 1 |     0     | 1 | BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1




* BPF_LD128IMM

first instruction:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | BPF_LD128IMM=0x60 |Res|Registr| 1 |     0     | 1 | BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                  Highest 2 bytes of 128 bits                  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                   Next 4 bytes of 128 bits                    |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

subsequent instructions:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |   H_OFF   |   W_OFF   |Reservd| 1 |InstrOffset|MIF| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                  Halfword at H_OFF's hextet                   |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                    Word at W_OFF's hextet                     |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

single (non-extended) instruction: 

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |   H_OFF   |   W_OFF   |Registr| BPF_LD128IMM=0x60 | BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                  Halfword at H_OFF's hextet                   |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                    Word at W_OFF's hextet                     |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

A 16 bit or two octet quantity is sometimes also called a hextet.

off position, k position, if both=7 then it is low 64 bits: e.g. MAC address 00-0C-29-0C-47-D5 is turned into a 64-bit EUI-64 by inserting FF-FE in the middle: 00-0C-29-FF-FE-0C-47-D5.[f]

=== /variant 1


для TLV - jump table типа switch/case? а зачем MF, если можно заставить валидатор чекать отсутствие джампов в эту область

=== variant 2

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |  Opcode / reg / size  |   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      /                                                               /
      \                                                               \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

* BPF_DATA_LITERAL:

  Opcode reminds BPF_LD (0) and is destination for BPF_RODATA access mode

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 | 1   1 |   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      \                                                               \
      / Any data, interpreted as array of [double/half]words or bytes /
      \    e.g. ASCII/UTF-8 string, terminated/padded with 0x00's     \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

* BPF_LD128IMM:

  Opcode reminds BPF_LD (0) and specifies how many to load at once, 1-3:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 |Count-1|   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      /                                                               /
      \         Array of halfwords, describing pieces to load         \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  First there are 1-3 halfwords each describing how to load pieces of
  immediate(s) from halfwords, hereafter in which command called hextets,
  which form final value in register(s). Each description halfword looks like:

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | Hextets Seq 1 | Hextets Seq 2 | Hextets Seq 3 |PadSkip|Registr|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
	              '               '
        .___________./                \_______________________,
       /                                                       \
       +-------------+-------------+-------------+-------------+
       |Increment hextet offset in |  Load this number of      |
       |register by this number    |  hextets from stream      |
       +-------------+-------------+-------------+-------------+

  Offset is also incremented after putting hextets from stream, by their number.
  So, in other words, first two bits in each sequence mean "load this number
  of zero hextets".

  Four examples of instructions where only one address is loaded into register 2.

  Example 1. An address with 3 zero hextets is loaded by length 2 instruction
  (16 bytes total).

  Hextet offset       0    4    5    6    7
  IPv6 address 1   fe80::1ff:fe23:4567:890a

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 | 0   0 | 0   0   0   0   0   1 |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 desc |   0   |   2   |    2  |   3   |   0   |   1   |   0   | 1   0 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0xfe80 - hextet to load by seq 1               |
    6 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0000 - hextet to load by seq 1               |
    8 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x01ff - hextet to load by seq 2               |
   10 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0xfe23 - hextet to load by seq 2               |
   12 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x4567 - hextet to load by seq 2               |
   14 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x890a - hextet to load by seq 3               |
   16 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

   1) offset is not incremented (0) as there is nothing to skip, then
      two hextets copied (2), and offset incremented by 2
   2) offset is incremented by 2 and now becomes 4, then 3 hextets (3+1)
      are copied, then offset is incremented by their amount
   3) offset is 7, one last hextet is load from stream to least significant
      hextet of register.


  Example 2. An address with 4 zero hextets is loaded by instruction of
  length 2 (16 bytes total).

  Hextet offset     0    1    6       7
  IPv6 address 2   64:ff9b::1.1.255.255

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 | 0   0 | 0   0   0   0   0   1 |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 desc |   0   |   2   |   3   |   2   |   0   |   0   |   0   | 1   0 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0064 - hextet to load by seq 1               |
    6 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0xff9b - hextet to load by seq 1               |
    8 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0000 - hextet to load by seq 2               |
   10 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0101 - hextet to load by seq 2               |
   12 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0xffff - hextet to load by seq 2               |
   14 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                        0x0000 - padding                       |
   16 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

   1) offset is not incremented (0) as there is nothing to skip, then
      two hextets copied (2), so then offset incremented by 2
   2) offset was 2 and is incremented by 3, becoming 5, but this is not
      enough to skip entire zero "::" gap, so an 0x0000 hextet is present
      in the stream, and 3 hextets are copied from stream into register,
      after which offset is incremented by 3 (their amount)
   3) as offset is now 8, nothing left to do, hextet sequence 3 is ignored,
      leftover 0x0000 hextet in the stream is padding to instruction boundary
      and also ignored.


  Example 3. An address with all bytes being non-zero hextets is loaded by
  instruction of length 3, padded, 24 bytes total.

  Hextet offset       0   1    2   3    4    5   6    7
  IPv6 address 3   2001:db8:85a3:8d3:1319:8a2e:370:7348

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 | 0   0 | 0   0   0   0   0   1 |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 desc |   0   |   3   |   0   |   3   |   0   |   2   | 1   0 | 1   0 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                        0x0000 - padding                       |
    6 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                        0x0000 - padding                       |
    8 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x2001 - hextet to load by seq 1               |
   10 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0db8 - hextet to load by seq 1               |
   12 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x85a3 - hextet to load by seq 1               |
   14 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x08d3 - hextet to load by seq 2               |
   16 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x1319 - hextet to load by seq 2               |
   18 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x8a2e - hextet to load by seq 2               |
   20 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0370 - hextet to load by seq 3               |
   22 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x7348 - hextet to load by seq 3               |
   24 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

   1) first PadSkip is processed, giving two words of padding to skip in
      stream.
   2) offset is not incremented (0) as there is nothing to skip, then
      three (3) hextets are copied from stream, so then offset is
      incremented by 3, becoming 3
   3) offset was 3 and not incremented (0), 3 hextets are copied from stream
      into register, offset is incremented by 3, becoming 6
   4) finally, two (2) hextets are loaded from stream at offset 6.
 

  Example 4. An IPv4-compatible address (on network with old clients).
 
  Hextet offset    0   6   7
  IPv6 address 2   ::8.8.8.8

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   0   0   0 | 0   0 | 0   0   0   0   0   1 |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 desc |   3   |   0   |   3   |   0   |   0   |   2   | 1   0 | 1   0 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0808 - hextet to load by seq 3               |
    6 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                0x0808 - hextet to load by seq 3               |
    8 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

   1) offset is incremented by 3 but nothing loaded from stream (0)
   2) same, offset is incremented by 3 becoming 6, but nothing is taken
      from stream
   3) last (3rd) sequence add nothing (0) to offset and loads final 2
      hextets from stream.


Extended jumps, with multiple checks at once - opcodes remind BPF_JMP (5).

* BPF_JUMP_TABLE:

  Byte-version - low byte of register (unsigned) is used as index into table.
  This may be useful for separate processing of each TLV chunk by type.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   1   0   1 | 1   0 |   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                    Jump offset at index 1                     |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                    Jump offset at index 2                     |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      /                                                               /
      \                                                               \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                    Jump offset at index N                     |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

  For value 0, jump is not stored in table - it is implicitly first
  instruction after jump table. For values greater than N, the same place is
  used (as if no jump occured).

TBD why same? just add "default not matched" after N, and it also could be
padding (repeated) value

* BPF_JUMP_RANGES:

  Often occured task - check if a number belongs to one or more ranges in
  short (16 bit) fields, e.g. ports or Ethernet protocol numbers. As
  specifying jump offset for each pair would consume too much space, only
  a single jump offset is provided - if register A & (0xffff) falls into any
  interval.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   1   0   1 | 0   1 |   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                    Jump offset if matched                     |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                 Range 0 low bound, inclusive                  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                 Range 0 high bound, inclusive                 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                 Range 1 low bound, inclusive                  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                 Range 1 high bound, inclusive                 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      /                                                               /
      \                                                               \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                 Range N low bound, inclusive                  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |                 Range N high bound, inclusive                 |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

  Ranges are inclusive, as both ipfw2 and tcpdump/libpcap 'portrange' do it
  inclusive - it allows to use single numbers, e.g. '0-1023,6000,8000-8080'
  is equivalent to '0-1023,6000-6000,8000-8080' and the latter is encoded.
  Whenever padding is needed, the last range could be simply repeated.

  A straightforward implementation fragment may look like:

	for (i = cmdlen*2 - 1; !match && i>0; i--, p += 2)
		match = (x>=p[0] && x<=p[1]);

  Underlying hardware or JIT compiler may utilize whatever optimizations
  available, of course.

* BPF_JUMP_BITSET:

  More space-efficient version of ranges when overall interval fits into
  about 8100 above some base value - match is checked against a bit set in
  a bitmap. First instruction dword looks like

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 0   1   0   1 | 0   1 |   Remaining length    |X=1| BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                    Jump offset if matched                     |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |           Base value of A above which to count bits           |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

   Subsequent dwords contain bytes with bits, which are checked against the
   value, with a straightforward implementation's fragment like:

	    if (A < k)
		    break;
	    A -= k; /* subtract base */
	    match = (A < (cmdlen-1)*64) &&
		( d[ 1 + (A>>5)] & (1<<(A & 0x1f)) );

   so unused (padding) bits at end are just set to 0.

=== /variant 2

TBD tasks line netgraph-messages ACL may require tables much more than 512
bytes, so larger instructions are needed, at least for data literals

на самом деле, большие литералы нужны только и исключительно под DATA - в
каждой из команд, тех же BPF_JMP, можно просто ввести суб-опкоды со ссылкой
на литерал с таблицей, а иначе это какой-то ad hoc - но выгода от этого ad hoc
как раз на инструкциях длиной 1-2, например сжатых LD128IMM

со слишком большими jump-литералами отдельно от команд две проблемы:
1) увеличивают расстояние для обхода условных джампов до них, а лимит
2) валидатор: как проверять итоговый оффсет на "только вперёд", если
   таблица-литерал может находиться как до самой команды, так и после?

ну проблему 2 можно решить, положив для jump table k всегда равным 0, т.е.
следующим после команды, и оффсеты считать от него - в остальных jump-литералах
есть только 1-2 джампа, они могут быть в самой команде вместо литерала

вообще можно придать какой-то смысл, если 0x88..0xbf отвести под длины 1..7
и назвать их BPF_PACKED - по аналогии с ARM Thumb, MIPS16e/microMIPS or RV16E,
потому что на нескольких 64-битных литералах тоже можно сэкономить

<<Because (like Thumb-1 and MIPS16) the compressed instructions are simply
alternate encodings (aliases) for a selected subset of larger instructions,
the compression can be implemented in the assembler, and it is not essential
for the compiler to even know about it. >>

TODO значит в стандартных LD/LDX надо предусмотреть 64/128-битные immediate

BPF_LITERAL:
c0..d8 - 2 бита + старший байт code = 8 Kb
e0..f8 - 2 бита + старший байт code + off = 26 бит

This is 512 Mb, such a bitmap can cover entire IPv4 space.

и без Base value можно обойтись, когда в нормальной команде доступно много
регистров - просто вычесть в одном и считать с нуля


TBD `errno` from copfuncs? or bad idea?

https://nxr.netbsd.org/xref/src/sys/net/bpf_filter.c#567 seems that NetBSD's
variant anyway 64-bit non-compatible, so let be incompatible with them (but
refactorable for them) - e.g. let BPF_COPX be BPF_COP|BPF_X
- no, let's better define our new code, e.g. 0x10
TBD which additional arguments to kernel function to pass except outregs?

`A = fn(bc, args, A, void *outregs, uchar nregs);`
- let it be so? as x86_64 ABI uses registers for first 6 int/ptr args, what
  one arg can be added here?

TBD may be KERNP converted to real addr?
- for every? it prepared for ((segnumber << 32) | offset_of_str_in_0th_literal)
  not pointer,  so why special reg for *every* "user" function?
- 29.07.24 let KERNP be double-purpose - on user call it contains type for
  registers to convert to scalars
TBD and validator should be able to check bounds of requests to create segments
from literals, so special opcode? BPF_SYSCALL? BPF_SYSRQ
- e.g. BPF_SYSRQ with 0 has segment lentgh in k, with 1 - signal handler in
  KERNP, etc. ?
- and `jf` if !0 jump in case of error (or terminate), `jt` for other means
  ("target")
- 21.08 creating segments from literals should be done by header, not code

жаль нельзя va_arg самому создать, придется костылить 15 макросов...

хм, а как generic-обёртка для printf поймёт, какие из аргументов %p - без
реимплементации самого printf? реально разделить понятие segment и bpf_sv
и завернуть в скаляры вообще всё, включая инты?
- похоже вот и 6-й аргумент - битмап, какие из регистров скаляры
  - и 33 байта на битмапы в bpf_process_mem, а там уже столько нет...

а если мы просто оборачиваем printf(9), то еще ip6_sprintf() нужен:
	char action2[92], proto[128], fragment[32];
	...
#ifdef INET6
		ip6f_mf = offset & IP6F_MORE_FRAG;
		offset &= IP6F_OFF_MASK;

		if (IS_IP6_FLOW_ID(&(args->f_id))) {
			char ip6buf[INET6_ADDRSTRLEN];
			snprintf(src, sizeof(src), "[%s]",
			    ip6_sprintf(ip6buf, &args->f_id.src_ip6));
			snprintf(dst, sizeof(dst), "[%s]",
			    ip6_sprintf(ip6buf, &args->f_id.dst_ip6));

			ip6 = (struct ip6_hdr *)ip;
			tcp = (struct tcphdr *)(((char *)ip) + hlen);
			udp = (struct udphdr *)(((char *)ip) + hlen);
		} else
#endif
		{
			tcp = L3HDR(struct tcphdr, ip);
			udp = L3HDR(struct udphdr, ip);

			inet_ntop(AF_INET, &ip->ip_src, src, sizeof(src));
			inet_ntop(AF_INET, &ip->ip_dst, dst, sizeof(dst));
		}

		switch (args->f_id.proto) {
		case IPPROTO_TCP:
			len = snprintf(SNPARGS(proto, 0), "TCP %s", src);
			if (offset == 0)
				snprintf(SNPARGS(proto, len), ":%d %s:%d",
				    ntohs(tcp->th_sport),
				    dst,
				    ntohs(tcp->th_dport));
			else
				snprintf(SNPARGS(proto, len), " %s", dst);
			break;

а нельзя так: даже если затащить libffi в ядро (чтобы генерировать va_list)
или наклепать 2^16 макросов по длине аргументов, обёртка для printf всё равно
не годится, потому что упадёт в случае printf("%s", 42) - своя обёртка должна
проверять скаляры, значит :(

30.07.24 if the very first instruction is literal 0xc7c7 (1600 bytes), then
this is a program/link information - the BPF_S|BPF_CALL will use `k` as index
into `cvtab[]` which will be populated by function pointers behind the scenes.

    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code | 1   1   0   0   0   1   1   1 | 1   1   0   0   0 | BPF_MISC=7|
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |              'B'              |              'P'              |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |              'F'              |              '6'              |
   k  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |              '4'              | Version/Format/2nd flag byte  |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |                  Endianness marker = 0x1234                   |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      /                                                               /
      \   The rest is described by format, e.g. sequence for binary   \
      /                                                               /
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

That is, 0xc7c7 is literal marker, and to be same for both endianness, it
always equals to 199 more bpf_insn's, that is, 1600 bytes. Then 5 bytes
are ASCII marker, one format/format version (of the literal) byte, and
then 0x1234 which will be in wrong endianness if loaded on wrong architecture.
The rest is formatted according to format/version byte. Currently, value 0
is version 0 custom binary format, and high values are expected to be in some
self-descirbing encoding, e.g. 0xCB proposed if CBOR is used in the future.
Low bit (0x1) is set when 1600 bytes is not enough and another literal (next
to this) is used.

Current version 0 literal in customary binary format is described by the
following sequence - note that it starts from instruction itself so as to give
proper align for subsequent uint64_t's:

typedef struct {		/* must be 8 byte (insn) size */
    uint32_t	arg_name;	/* min # args reqd & strtab offset */
    uint32_t	version;	/* prog version */
} bpf_progdesc_t;

struct bpf_proglinkinfo_v0 {	/* header is 32 bytes (4 insns) */
    uint16_t	insn_code;	/* 0xc7c7 */
    char	magic[5];	/* "BPF64" */
    uint8_t	verformat;	/* e.g. 0, low bit  */
    uint16_t	endianness;	/* 0x1234 */
    uint16_t	platformver;	/* min ver req, depends on platform */
    char	platform[4];	/* zeroes if crossplatform */
    uint16_t	flags_me_links;	/* 0 dumbfast, 1 scalar-wrapped and */
    				/* size of me[] in low nibble */
    uint8_t	staticsv_sz;	/* static SVs array element count */
    uint8_t	cvtab_ofs;	/* referenced progs array offset in insns */
    uint16_t	cvtab_sz;	/* referenced progs array element count */
    uint16_t	strtab_ofs;	/* strings section offset in insns */
    uint64_t	__reserved;	/* padding to 32 bytes */
    bpf_progdesc_t	me[0];	/* what is my name(s) and version? */
    /* TODO required resources */
};

TBD platform be enterprise number as in syslog RFC ? ELF ABI byte?
- no, char[8] better - human readable like "FreeBSD" or "portable"

Name(s) of program itself are placed directly after header; immediately after
them starts array of required static SV's of word-size entries:

    uint32_t	staticsvs[]
#define BPF_PRGDESC_STATICSV_TYPEMASK	0xff000000
#define BPF_PRGDESC_STRINGOFS_MASK	0x000000ff

which has type of scalar and offset to it name from beginning of strings
section. Type byte is one char: '"" for ASCIIZ, '$' for PV and '@' for AV.
If entire word is zero, then this segement number is reserved for a static
literal which will be created by program at runtime - just that this number is
reserved so caller will not create additional SVs here.

As static scalars is 255 max (1020 bytes) and program names arrays are short
enough to always fit in 1600 bytes, they don't require offsets from header.
However, referenced programs section and/or strings section may be large, so
for them to be not "split" in the middle by starting bytes of next BPF_LITERAL
(which must follow immediately if (verformat & 0x1) is set), they have offsets
from the start of the header (meaning they can't be less than 5 and 6) in
bpf_insn's (8 byte) chunks (for alignment).

    bpf_progdesc_t cvtab[svtab_sz];

Format of both program itself description, in me[0] and possibly "hardlinks"
in me[1..], and required as dependencies programs, is the same: one word
with low 24 bits for name of program as offset into strings section

TBD do we need min # of arguments? how much to reserved

and another word with version. System compares versions simply as ">="
unsigned integers, so version could be just a Unix timestamp or more
complicated major-minor scheme as author of program chooses.

NOTE this scheme is uniform - written in C helpers like printf() or other bpf
programs all reside in same space looking like "programs" with versions
and accepting argv[] of SVs.

TODO chain commit/rollback (e.g. fw ssh loss) - more complex version checking?
- use BPF_J* itself for it, haha?

TBD 13.08 ~18:11 what if even calls to local functions be via id in `k` ? like
Perl package and it's symbol table, validator checks jumps to be inside such
chunks; everything called on one bpf_process_mem, not several - no mallocs
and no SVs for simple scalar arguments like integers!
- then what if functions from different packages expect different
  segments/SVs?
  - so some static segments must be local to bpf_ctx_t context
- then need to save bpf_ctx_t in each stack frame
  - so loops must be redone, in 24 byte frame 2 ptrs and reg info leave space
    only for 2 uint16_t loops or 1 uint32_t or some union must be employed
    - 17.08 possible to save bpf_ctx_t as 8 byte ptr, but uint32_t pc as
      offset from context start - makes call/return slower
      - but slower in VM, JIT can have backstack in real stack
	- no, that defeats whole idea of ROP protection by backstack
- каждую функцию с джампами только внутри не одобрила (видимо, оптимизации
  компилятора помешает), а так идея вполне
- 16.08 ipfwng chain необязательно RB-tree - можно в отдельный literal засунуть
  смещения rule numbers и иметь такую же BPF-программу
- ok, bpf_printf() has fmt str so don't need SVs, but other C funcs? and
  what about 128-bit registers / their arg passing, to printf() also?
  - можно костыль с регистром, где каждый байт ссылается на регистр/M[]


TBD include prog size? so it can be embedded in ELF like DOF?

TBD mark area with exception handlers for validator, to disallow calls/loops

CTF:
<<
   The String Section
     The last section of the ctf file is the string section.  This section
     encodes all of the strings that appear throughout the other sections.  It
     is laid out as a series of characters followed by a null terminator.
     Generally, all names are written out in ASCII, as most C compilers do not
     allow any characters to appear in identifiers outside of a subset of
     ASCII.  However, any extended characters sets should be written out as a
     series of UTF-8 bytes.

     The first entry in the section, at offset zero, is a single null
     terminator to reference the empty string.  Following that, each C string
     should be written out, including the null terminator.  Offsets that refer
     to something in this section should refer to the first byte which begins
     a string.  Beyond the first byte in the section being the null
     terminator, the order of strings is unimportant.
>>

Currently in format 0 no form of pathname string compression is attempted
(may be another section with "my name / ref to parent" will be added in 1).

TBD pushtr/pushtv in DTrace

TBD we can't keep SV-s directly in AV - what if references are held, and
AV resized thus realloc()'ed?

TBD SV count to prealloc so not to do it under M_NOWAIT

TBD 1600 bytes too much for many programs and too small for others, may be
change BPF_LITERAL from 0xc0 to something lower and then have several literals
as sections? so that offsets will be not needed, just from corresponding
literal's start

TBD 32-bit words, 8 "$@&" or SI/SO, 24 bit stringref, for SV static num and
reserved, for CV version and additional 24 bits of version on SO
- this contradicts with simple scheme when CALL's `k` is just array index
  - see 13.08: if this is array of function pointers (which it should be for
    performance) then it anyway will be built in run time and not referred via
    literal on each call, so it's enough to do some checking "this is k+1"
    when building it, thus encoding scheme can be any (but for CBOR need to
    think about simplicity of string compression, separate string section
    still looks better if that strings will be usable from BPF program)
  - 20.08 just sequence of VarUInt32 ?
    - then not enough for version, so 60 bit varint?
      - 21.08 define version as bytestring so memcmp() for any format user wants

int key_compare(const void *key1, int len1, const void *key2, int len2){
  int c = memcmp(key1, key2, len1<len2 ? len1 : len2);
  if( c==0 ) c = len1 - len2;
  return c;
}

separate export/import list - in export namespace "cd" may create, in import
non-existent path causes load error 
generic attributes like in Perl:
public funcname :version("abc") :expensive :input(var1,var2) { ... }
put (sysctl) description amongst them

       Version Strings

       A literal of the form "v1.20.300.4000" is parsed as a string composed
       of characters with the specified ordinals.  This form, known as
       v-strings, provides an alternative, more readable way to construct
       strings, rather than use the somewhat less readable interpolation form
       "\x{1}\x{14}\x{12c}\x{fa0}".  This is useful for representing Unicode
       strings, and for comparing version "numbers" using the string
       comparison operators, "cmp", "gt", "lt" etc.  If there are two or more
       dots in the literal, the leading "v" may be omitted.

           print v9786;              # prints SMILEY, "\x{263a}"
           print v102.111.111;       # prints "foo"
           print 102.111.111;        # same

       Such literals are accepted by both "require" and "use" for doing a
       version check.

23.08 02:00 okay, FreeBSD sysctl has linked lists / O(N), so to speed up loading
at least to some degree, no linear list with "foo::bar::baz" entry each, only
walk to node and {creating/checking} leafs with params. Thus a series of
commands:

* VarUInt32, low 7 bits operation code, rest number N of arguments to command:
  this way commands will still look as ASCII in debug/hexdump, and '}' will
  even occupy just one byte
* N (may be 0) VarUInt32's of arguments to command, each has type in low
  2 bits, rest bits we name K:
  * 00 - ASCIIZ string, K is offset in strings section
  * 01 - binary string or integer follows, K means:
    * 0..10 - these integers themselves
    * 11-14 - in next 2^P bytes, where P=K-11, follows unsigned integer
    * K>=15 - binary string of K-15 bytes follows
  * 10 - reserved for a sublist, with K elements (same format)
  * 11 - Reserved

TBD cbor-like with 0x80+ ? move bin strings to separ sect, ints too and only
4/8 size (as we have varint itself for lesser), offs in 4 byte units so only varints in main section, like in SQLite?

23.08 04:00 well, one-argument may be achieved by setting "registers" to:
#define	CTL_SYSCTL_NAME		1	/* string name of OID */
#define	CTL_SYSCTL_OIDFMT	4	/* OID's kind and format */
#define	CTL_SYSCTL_OIDDESCR	5	/* OID's description */
#define	CTL_SYSCTL_OIDLABEL	6	/* aggregation label */
and instead sublists just put child nodes?

TBD NetBSD does not have label & format string (and has lesser int types) and
restricts names to [A-Za-z0-9_-], but has "node version" (though it's API
version, not data) and supports "/" separator (in addition to ".") and API like
"//create=local.esm_debug,type=int,symbol=esm_debug,flags=w"

24.08 01:40 оно же не вполне на sysctl ложится - ведь в Foo::Bar::Baz
у Foo::Bar могут быть свои sub{}, Perl это решает просто конвенцией про
с большой буквы; может аналогом html сделать?
<namespace name="Foo" $=abc &entry=0x123 &version=1.20.30 ...>

02.09 01:00 не совсем так, в Perl stash=хэш с именем Bar:: т.е. sub'ы не могут
иметь такой символ в имени
struct gp {
    SV *	gp_sv;		/* scalar value */
    struct io *	gp_io;		/* filehandle value */
    CV *	gp_cv;		/* subroutine value */
    U32		gp_cvgen;	/* generational validity of cached gp_cv */
    U32		gp_refcnt;	/* how many globs point to this? */
    HV *	gp_hv;		/* hash value */
    AV *	gp_av;		/* array value */
    CV *	gp_form;	/* format value */
    GV *	gp_egv;		/* effective gv, if *glob */
    PERL_BITFIELD32 gp_line:31;	/* line first declared at (for -w) */
    PERL_BITFIELD32 gp_flags:1;
    HEK *	gp_file_hek;	/* file first declared in (for -w) */
};
но в sysctl (особенно NetBSD) для админа не запихнешь лишние :: в каждом уровне

24.08 also this reminds abandoned "cd 1.2.3.5; cd .." in previous versions of
muSCTP draft, so try to converge both?
- 28.08 the difference is, here in BPF64 we have everything at once (or in
  two, import/export), so "cd node" makes sense for compression, but muSCTP
  operates on just one or several values, so Compress::LZF is better for
  repeated paths there

TBD 02.09 02:54 is version needed at all for every *function* ? in every
mainstream (scripting) language it's not so: version is attribute of package,
not function (though in some package may export different by required version),
we just try to solve ABI versioning here as in libfoo.so.6 ? in any way, how
compatibility versions are supposed to coexist - sysctl has just one name?
- this was because first idea was about interacting BPF "programs", with
  argc/argv (in SVs), instead of "functions"
  - 03.09 hmm, seems that version could be returned to every symbol, not
    just entire package (of funcs), if attributes (sub)tree is worked through
    enough

    MSB                                                               LSB
       63   56 55                      29 28                         0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  '{'  |                          |       Namespace name       |
      +-------+-------+-------+-------+-------+-------+-------+-------+

    MSB                                                               LSB
       63   56 55                   32 31                            0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  '&'  |    Function name      |        Entry point / k        |
      +-------+-------+-------+-------+-------+-------+-------+-------+

    MSB                                                               LSB
       63   56 55                   32 31                    8 7     0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  '$'  |   Segment (SV) name   |    Type (fmt) name    |N/Ctltp|
      +-------+-------+-------+-------+-------+-------+-------+-------+

    MSB                                                               LSB
       63   56 55                      29 28                         0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  'd'  |Platform: label / API ver |       Description          |
      +-------+-------+-------+-------+-------+-------+-------+-------+

    MSB                                                               LSB
       63   56 55                                                    0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  'v'  |                    Version                            |
      +-------+-------+-------+-------+-------+-------+-------+-------+

TBD 03.09 04:00 ok, that's simple, but where to keep e.g. time keeping - again
attributes? just that not so dependent on import/export format now, but still
has to have place in sysctl

bpf64.namespace.foo.bar
bpf64.namespace.foo.bar.baz
bpf64.namespace.foo.bar.baz.$: "abcd efgh segment value"
bpf64.namespace.foo.bar.baz.&: { code_struct=members version=0x123 }
bpf64.namespace.foo.bar.baz.*attributes
bpf64.namespace.foo.bar.baz.*attributes.input: "nh_pos,l4_off"
bpf64.namespace.foo.bar.baz.*attributes.version: 1668969726

    MSB                                                               LSB
       63   56 55 53 52                29 28                         0
      +-------+-------+-------+-------+-------+-------+-------+-------+
      |  'a'  |4Type|   Attribute name   |     Attribute value        |
      +-------+-------+-------+-------+-------+-------+-------+-------+
- 03.09 no, not "for type", but just first symbol in name? e.g. "$name" for
  attribute on scalar and "&name" for attribute on code

TBD not only debug section, but doc (POD) section? with hash ident of main
prog; and place them in swappable memory instead of wired

sysctl -b vfs.nfs.diskless_rootaddr > file.bin



but overall language should be that [probably in-kernel] disassembler output, while
uncomfortable, is compilable by bpf64awc into same bytecode


TBD what in argv[0] ?
- if scalar ptr then need parent ptrs which need weak refs
  - if it is filled by calling program then no need
    - but this requires reverse lookup: from CALL's `k` to name
- if full path string then need to parse, put an AV ?

TODO if we add to sysctl, then header needs fields descr
TBD and S,TYPE ? also there are types for counter(9)/their array


#define	BPF_SVt_NULL		0	/* undefined value  */
#define	BPF_SVt_UB		1	/* unsigned byte */
#define	BPF_SVt_IB		2	/* signed byte */
#define	BPF_SVt_UH		3	/* unsigned half */
#define	BPF_SVt_IH		4	/* signed half */
#define	BPF_SVt_UW		5	/* unsigned word */
#define	BPF_SVt_IW		6	/* signed word */
#define	BPF_SVt_UD		7	/* unsigned dword */
#define	BPF_SVt_ID		8	/* signed dword */
#define	BPF_SVt_PV		9	/* memory region */
#define	BPF_SVt_RV		10	/* reference to another SV */
#define	BPF_SVt_AV		11	/* array of SV's */
#define	BPF_SVt_CV		12	/* executable code */

#define	BPF_SVf_TYPEMASK	0x0ff	/* mask for type byte */
#define	BPF_SVf_READONLY	0x08000000
#define	BPF_SVf_MEMOWNER	0x00000100 /* must free(svu_pv) */
#define	BPF_SVf_MEMSHARED	0x00000200 /* several SVs point to this mem */

typedef union {
    	uint8_t		svu_ub;
	int8_t		svu_ib;
	uint16_t	svu_uh;
	int16_t		svu_ih;
	uint32_t	svu_uw;
	int32_t		svu_iw;
	uint64_t	svu_ud;
	int64_t		svu_id;
	char*		svu_pv;	/* pointer to malloced string */
	struct bpf_sv*	svu_rv;	/* pointer to another SV */
	struct in6_addr	svu_q;
} bpf_sv_union_t;

/* 32 bytes - all types has same size for slab allocator */
struct bpf_sv {
    uint32_t	sv_flags;	/* type in low byte */
    uint32_t	sv_refcnt;	/* how many references to us */
    uint32_t	sv_limit;	/* max allowed size to access */
    uint32_t	sv_offset;	/* use depends on type */
    bpf_sv_union_t sv_u;
};

/* array value - casted from SV, head must match */
struct bpf_av {
    uint32_t	sv_flags;	/* type in low byte */
    uint32_t	sv_refcnt;	/* how many references to us */
    uint32_t	sv_limit;	/* max allowed size XXX bytes/elems? */
    uint32_t	av_offset;	/* offset of 0'th element (if "shift"'s) */
    struct bpf_sv** av_alloc;	/* pointer to beginning of C array of SVs */
    uint32_t	av_fill;	/* Index of last element present */
    uint32_t	av_spare;	/* reserved/alignment */
};


let's expand a line in process_tcp():
    call_sv bpf64_printf("process_tcp: nh_pos=%d +size=%d\n", nh_pos, B);

nh_pos is R0, first output param (err printarg1) is R9 - so register window
shift for dumb calls is 9 (0..8)
Let offset of fmt string ("process_tcp...") be 123 in segment 1 (usually
scalar from literal is 0, but to demonstrate)
references (RV) are encoded as scalar (segment) number in high 32 bits and
offset in low 32 bits
Let assume we have argument AV number already in AS selector register
creating SV functions return new number in CS selector register (mnemonic
is "created"/"current")

    R9 = AS
    CALL_L regs=9 k=av_clear	/* delete all elements from array */
    R9 = BPF_SVt_RV		/* constant: type argument to sv_new() */
    CALL_L regs=9 k=sv_new	/* create scalar, return be in CS */
    LD	R9, (1 << 32) | 123	/* constant known by compiler XXX */
    ST	R9, CS:P[0:8]		/* store reference value in new SV */
    R9 = CS
    CALL_L regs=9 k=av_push	/* push @argv, $fmtstr_ref */
    CALL_L regs=9 k=sv_close	/* decrement refcount on our SV */
    R9 = BPF_SVt_UW		/* 32 bits will be enough for offset */
    CALL_L regs=9 k=sv_new	/* create scalar, return be in CS */
    ST	R0, CS:P[0:4]		/* nh_pos is in R0 */
    R9 = CS
    CALL_L regs=9 k=av_push	/* push @argv, $nh_pos */
    CALL_L regs=9 k=sv_close	/* sole scalar owner is now AV */
    R9 = BPF_SVt_UW		/* 32 bits will be enough for size */
    CALL_L regs=9 k=sv_new	/* create scalar, return be in CS */
    ST	B, CS:P[0:4]		/* B is 32 bit, not Bd */
    R9 = CS
    CALL_L regs=9 k=av_push	/* push @argv, $b */
    CALL_L regs=9 k=sv_close	/* we close SV to not leak it */
    R9 = AS			/* where function will find argv? */
    CALL_S regs=9 k=bpf64_printf/* finally scalar-wrapped external call */

sv_close() is like close() for file descriptors - it deletes reference to
this scalar from available segments, decrementing refcount and freeing if
needed, so BPF program is not in direct control of refcounts and thus cannot
make harm with it, except possibly prolonged life of leaked scalar until
eventual program termination where free() will be done

TBD av_push preserves output register?
XXX av_push to use AS: by default?
TBD storing in RV automatically increments refcount on referenced scalar?

TBD which AV to use for such calls as argument stack? one for each prog and
it's direct children, or one for entire chain?

DEBUG:
    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |                               | 1   1   1   0   0 | BPF_MISC=7|
      +        Literal  Length        +---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |              'D'              |              'B'              |
   k  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
      |              'G'              | Version/Format|Zip|PaddingLen |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

As this section is for userland, it may be compressed if Zip flag is set, with
format detected by signature in data, and PaddingLen specifies how many bytes
at end are subtracted from literal (as it is multiple of 8 bytes), and is
not interpreted by kernel.
TODO simplified https://dwarfstd.org/doc/DWARF4.pdf Section 6.2 with
references to 2 strings sections: own inside this DBG and common in PKG;
also in each frag an optional argument to string with fragment of source at
that coordiantes, to decompile for e.g. if source file lost - sysadmins often
need to view loaded firewall rules (working system may differ from what
recorded in files), but traditional firewalls restrict format to be able to
decompile rules which restrict optimization ability - decompilation info
in debug section should mitigate this

  MSB 3 2                 2 1                 1                   LSB
    1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |HdrSz|Instructions size (offset to strings section from hdrend)|
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   line_base   |  line_range   |             Flags             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

just sequence of VarUInt32 ?

BPFDBG_LNOP_copy		- 0 operands
BPFDBG_LNOP_advance_pc		- 1 operand
BPFDBG_LNOP_set_pc		- 1 operand
BPFDBG_LNOP_inc_line		- 1 operand
BPFDBG_LNOP_dec_line		- 1 operand
BPFDBG_LNOP_set_column		- 1 operand
BPFDBG_LNOP_negate_stmt		- 0 operands
BPFDBG_LNOP_set_basic_block	- 0 operands
BPFDBG_LNOP_set_prologue_end	- 0 operands
BPFDBG_LNOP_set_epilogue_begin	- 0 operands
BPFDBG_LNOP_end_sequence	- 0 operands
BPFDBG_LNOP_set_discriminator	- 1 operand
BPFDBG_LNOP_set_file		- 1/4 operands???
BPFDBG_LNOP_define_file ? or merge with set_file due to string offset?
BPFDBG_LNOP_set_fragment - string offset to code fragment in this column

        2                |2 1            |    1      |
        9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       |           Immediate Argument        |NumArgs|1 1 1 1|SubOp|
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

TBD huh, line info is not full debug, need func and variable names, and
possibly other info which will be clear after bpf64awc export/import... or
func names is in PKG ? only public...
- 04.09 02:00 attaching attributes to every instruction like what variable
  name was used here (and using several attributes at prolog, :input et. al.)
  would allow decompilation without source text fragments... but such will
  work for only simple mapping like BAW, won't work for higher-level languages
  (не одобрил)

TBD 02.09 seems that decompilation requirement drastically change format: DWARF
special opcodes only increment `pc` and line, but as we have *assembly*
wrapper, then several statements per line will be more often (see e.g.
`parse_ipv6()` in `nuc_ts_incr.baw`)... Probably every file should first be
split into fragments (each having line/column) of text, and then those
fragments would be referenced in state machine / producing matrix

External container is in CBOR (RFC 7049) format, allowing easy extensibility,
any amount of structure nesting, and still allowing to parse it in the kernel
in the unlikely case such need arises.

55799([
  { // header
    "version": 0,
    "line_base": -2,
    ...
  },
  "Line Numbers bytecode...",
  [ // files array
    [ "linecol for file1", "linecol for file2", ... ], // bytecode
    [ // files metadata
      { "name": "/path/file1.baw", "mtime":123456789, ... },
      ...
    ],
    [ "concat text of file1 frags...", "concat text of file2 frags...", ],
  ],
])

File info and texts are placed at the end close to each other (not
interspersed by bytecode) to increase text compression ratio, if compressor is
employed (Zip flag is set in header).

So currently there are two bytecode cublanguages inside this CBOR. Simpler one
is in text fragments - these are triplets of line, column and text fragment
lengths. Other one, main, is like DWARF LNS bytecode.

TBD how to embed attributes/nesting in main bytecode (and BAW)? e.g.
Perl6::Export::Attrs and :input and so on
- 03.09 ok, for :export in source it's simple, binary debug info probably will
  also want to attach arbitrary attributes, e.g. `:label(labelname)` for
  source line starting with `labelname:` (BTW `sed` has branch/labels with colon
  before, not after)... however, do we need possibility of such attributes
  on *every* statement in BAW source? or allow them just before `{` and in
  `our` declarations?
  - well, may be for things like comments in `parse_ipv6()` in
    `nuc_ts_incr.baw` with original C code? but this then must be able to span
    several bpf_insn's and is not clear if this is better than comment/POD
    - probably not, as it is better to write more expressive language, leave
      asm to be asm
    - "to span" is what entire DWARF LNS about, so it's just about new
      columns in matrix?... also reminds of SQLite record format, LOL
      - huh, in-memory SQLite with proper indexes may be a way to implement
	userland emulator/debugger/decompiler... may be a way of thinking (how
	to compress such SQLite table)

TODO frags: 3 VarUInt32's inc_line, inc_col, frag_len - this is 3 bytes
instead of one for typical 80-column one-statement line
...sounds like early PBMFS?

also DOC (POD) section? so 2 bits: 3 sources of fragment (PKG, DBG, DOC) and
"recover by decompile", e.g. large (jump) table
- then files header must be in it's own section, as DOC will also have
  it's own fragments for same files

DWARF4 Section 6.2:
<<If space were not a consideration, the information provided in the .debug_line section could be
represented as a large matrix, with one row for each instruction in the emitted object code. The
matrix would have columns for:
• the source file name
• the source line number
• the source column number
• whether this instruction is the beginning of a source statement
• whether this instruction is the beginning of a basic block
• and so on
Such a matrix, however, would be impractically large. We shrink it with two techniques. First,
we delete from the matrix each row whose file, line, source column and discriminator
information is identical with that of its predecessors. Any deleted row would never be the
beginning of a source statement. Second, we design a byte-coded language for a state machine
and store a stream of bytes in the object file instead of the matrix. This language can be much
more compact than the matrix. When a consumer of the line number information executes, it
must “run” the state machine to generate the matrix for each compilation unit it is interested in.
The concept of an encoded matrix also leaves room for expansion. In the future, columns can be
added to the matrix to encode other things that are related to individual instruction addresses.
When the set of addresses of a compilation unit cannot be described as a single contiguous
range, there will be a separate matrix for each contiguous subrange.
>> -- if we'll think in SQLite terms, then "the source file name" column would
be just REFERENCE to another table (yep, normal form!), and source fragments
would also live in their own table, and DOC/POD section may be yet another
table, so for extensibility we can define a way to store several tables and
for some of them - the language like DWARF LNS to compress them.

So it's opcodes would be not of concrete names, unlike LNS, but generic
TBD now let's find a way to store tables in literals and in separate files...
- we have uuidgen(1) and uuid(3) API, this is 16 bytes - just 2 bpf_insn's,
  and alternative (as in git) as MD5 would be not secure enough, SHA256 is
  much longer, and in any case hashes would require zeroing it's own place,
  tracking changes etc. complexity - so real alternative is human readable
  names (like ".debug_info" huh) but those won't be unique in system

...seems that debug/decompile info is separate complex task, defer it for not
this month (first publishing), so for now it should decided: how it interacts
with other system - literals, hashes? - and affects first language (BAW)

This file header is always present in all BPF64 files - whether they contain
code, or debug info, or both. It contains UUID which allows to link files
together if they are split, and describes all sections which would be present
in file if contained everything from the program - however, not every section
may be present in particular file. Sections themselves are just BPF_LITERAL
which contains CRC32 of entire literal in it's `k` field (with first 4 bytes
of section header substituted to `k` while calculating - this allows producer,
in case of collision, to change section name offset to get CRC32 value which
remains unique), so section contents always starts at offset 8 from literal
start, and have no additional description (it is in the file header, which
must always present).

struct bpf_file_header_v0 {	/* header is multiple of 128 bytes (16 insns) */
    uint16_t	len_insn_code;	/* & 0xcfcf == 0x0f0f */
    char	magic[5];	/* "BPF64" */
    uint8_t	verformat;	/* e.g. 0, low bit  */
    uint16_t	endianness;	/* 0x4321 */
    uint8_t	numsections;	/* how many sections are in secthdr[] */
    uint8_t	flags;
    uint32_t	platformver;	/* min ver req, depends on platform */
    char	platform[8];	/* e.g. "portable" or "NetBSD\0\0" */
    uint32_t	sections_size;	/* sum of all present, so = offset to code */
    uint32_t	entrypoint;	/* counted from code offset */
    uint8_t	uuid[16];	/* same in all files, like BuildID */
    uint64_t	__reserved[2];	/* to 64 bytes */
    bpf_insn	secthdr[0];	/* 7 max in tinyest header size */
    /* char strings[0]; after */
};

Space in header after `numsections` section headers array is formatted just
like any other strings section contents (starts and ends with NUL byte), but
it is used only inside file header - it contains section names.

Section headers do not spawn another `struct` type and use `bpf_insn`'s which
are interpreted as follows:

* code - upper 3 bits padding, lower 13 bits - offset to section name
* jt - section type
* jf - section flags
* k - ident (CRC32) of section

#define BPF64_SHFLAG_ZIP	0x01	/* Section contents is compressed */
#define BPF64_SHFLAG_NEEDC	0x80	/* Section needed by code / loading */
#define BPF64_SHFLAG_NEEDD1	0x40	/* Section needed by D1 */
#define BPF64_SHFLAG_NEEDD2	0x20	/* Section needed by D2 */

Immediately after header follow BPF_LITERAL's with those sections which are
present in this file, always in order of secthdr[] - so missing section can be
detected by CRC32 of some later section in real literal.

As BPF_LITERAL short version has 0x08 bit set in BPF_MISC class allows 2 bits,
requirement for file header to be read as literal on BOTH endianness, this
essentially means `code & 0xcfcf == 0x0f0f` test for first two bytes of the
file - giving a few instructions, so wrong endainnes will be found by reading
(always available) second `bpf_insn` after first which matched magic number.
This - after masking out `BPF_MISC|0x08` (0x0f) - gives the following
possibilities for file header sizes:

0xf     128	code == 0x0f0f
0x1f    256	code == 0x1f0f
0x2f    384	code == 0x2f0f
0x3f    512	code == 0x3f0f
0x10f   2176	code == 0x0f1f
0x11f   2304	code == 0x1f1f
0x12f   2432	code == 0x2f1f
0x13f   2560	code == 0x3f1f
0x20f   4224	and so on
0x21f   4352
0x22f   4480
0x23f   4608
0x30f   6272
0x31f   6400
0x32f   6528
0x33f   6656	code == 03f3f

Segmetss (SVs) created from code's own literals described in separate section
called "rodatas", which is array of structs, each per segment:

struct bpf64_rodatas_entry {
    uint64_t	literal_iofs;	/* in insns from start of code */
    uint32_t	offset;		/* in bytes from literal start */
    uint32_t	size;		/* in bytes of new segment */
};

===
шаблон:
    MSB 15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0 LSB
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 code |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  off |                                                               |
      +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
k/imm |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
         3                   2                   1

для языка, если делать не Си, надо делать конвертер типов из Си и посмотреть
языки описания структур - Wireshark, Kaitai...

варианты конструкций языка low level / assembler wrapper (bpf64awc, .baw,
инклуды .bah):

loop i=1 ascending to 60 { ... }
loop i=A desc to 0 { ... }
msh X = pkt[14];
index tcp = X + 14; A = tcp[0:4]; //array variable for putting to index register
if A > 60 goto label; else { ... }
if r0 == 60 jt 1 jf 2;	// label names
alias B hdrsize;	// variable is actually register
if myvar = 8 { even_one_stmt_has_braces; }

func myfunc(uh var1, iw othervar)
my (localvar1, localvar2)	// alloc 2 input registers, 2 local registers
out (varForCalledFunc)		// and at least one output register
{
  body;
  A = CalledFunc(10, varForCalledFunc);
  if A > 63 {
    if varForCalledFunc > 255 { return 0; }
  }
  return 1;
}

sequence tcp {	// we have no structs/arrays, just one compound data "type"
    src_port 0  h;	// offset and size (halfword)
    dst_port 2  h;	// size also may be number - for char[N]
    seq_num  4  w;
    ack_num  8  w;
    off_rsvd 12 b subfields { // data offset and reserved bits
	data_off >>=12, &= 0x0f; // subfield: ops on reg after LD main field
    };
    flags    13 b;
    win      14 h
    cksum    16 h;
    urgent_p 18 h;
}

D = tcp[tcp.off_rsvd];	// type name and index name are in separate namespaces
D >>= 12;

TBD index tcp можно совместить - чтоб и tcp[30] и tcp.src_port работало

декларация asmtmp G, H, local 2 для юзания в макросах/разворачивании
конструкций компилятора чтоб не мешать своим переменным?

index name be X+20 // just declare - you must watch X yourself
index name = X+20 // just declare - you must watch X yourself
TBD be? =? which syntax better

/* declare, save current value in store now, do LDX from store each time index used */

`index name use X+20 on DS:P sequence tcp in M[8];`

means:

index name on DS:P using tcp take X+20 store in mem[8]

A = S0:P[123]; B = DS:P[123];

TBD ethernet addr is char[6] so distinct letter/number in `sequence`
сюда же инициализацию литералов

в ARM есть TBB и TBH

literal somename {
    port1 w 80;
    port2 w 0x2c00;
    str1  z "ASCIIZ string";
    str2  z "another %d-printf-like\tstring\n";
    charr с { 0x01, 0x02, 0x03 }; //character array?
};

literal myhdr use ethhdr { /* existing layout allows without type */
    h_dest   { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, };
    h_source { 0x01, 0x02, 0x03, 0x04, 0x05, 0x06 };
    h_proto  0x0800;
};

`kernfunc("C string", ...)` equiv to `kernfunc(0:"C string", ...)`
really passes ((segnumber << 32) | offset_of_str_in_0th_literal)
so a segment must be created from auto-literal before calls


foreach b in P[20:60] { // X will be actual index, A loaded value
    if A > 200 last;
    ...
}

для обертывания аргументов нужен отдельный тип скаляра, RV, со ссылкой на
скаляр, содержащий саму память - ведь смещение может быть разное в разных
bpf-программах, значит надо хранить пару (void *base_sv, int offset)
- значит, размер SV вырастает (не тратить же 4 байта padding на всех), можно в
  нём и IPv6 теперь хранить

если сделать argc/argv, можно любое число без привязки к регистрам

сохранение argc/argv простое: ST одного байта типа, потом значения 4/8/16,
потом следующего типа, потом значения, и всё на ту же область - обработчик
внутри автоматически пододвигает значения и конвертирует
This allows underlying implementation of scalar to change between platforms
and versions

а загрузку в main теперь как?

05.09.24 additional (to kernel packet & syscall) goals to design for:
1) muSCTP custom compression rules decompression
2) An alternative to https://capnproto.org/rpc.html for method calls on
high-latency links (e.g. MQTT5-like and/or for environments when Cap’n Proto itself
is not applicable, e.g. no direct connections)