Overview
| Comment: | add rasuir spec, other updates |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
6bda93a90502b8b3b6276b962b207d9f |
| User & Date: | lexi on 2023-01-29 19:21:56 |
| Other Links: | manifest | tags |
Context
|
2023-01-29
| ||
| 21:16 | iterate on rasuir check-in: e15188634a user: lexi tags: trunk | |
| 19:21 | add rasuir spec, other updates check-in: 6bda93a905 user: lexi tags: trunk | |
|
2022-12-31
| ||
| 03:22 | add rndcbytes and richascii spec; add notes to soda check-in: fc9b35c962 user: lexi tags: trunk | |
Changes
Modified mkpw.c from [9bb8a09cb3] to [6aa024ebe0].
22 22 #include <sys/random.h> 23 23 #include <sys/syscall.h> 24 24 #include <stddef.h> 25 25 #include <stdint.h> 26 26 #include <string.h> 27 27 #define sz(a) ( sizeof (a) / sizeof (a) [0] ) 28 28 #define say(x) (write(2, (x), sizeof (x))) 29 + 30 +long syscall(long, ...); 29 31 30 32 #ifdef _CLIPBOARD 31 33 # include <sys/types.h> 32 34 # include <pwd.h> 33 35 # include <stdlib.h> 34 36 # define _cl_opt o('n',nocopy,copy = false) 35 37 #else
Modified ord.c from [4549cc99f3] to [95972fed18].
39 39 #endif 40 40 #include <stddef.h> 41 41 #include <stdint.h> 42 42 #include <string.h> 43 43 #include <limits.h> 44 44 #define sz(x) ( sizeof (x) / sizeof (x) [0] ) 45 45 46 - 47 -enum /* constants */ { 48 - null = 0, 49 -}; 46 +#define null ((void*)0) 50 47 51 48 typedef unsigned long long word; 52 49 typedef _Bool bool; 53 50 enum { false = 0, true = 1 }; 54 51 55 52 56 53 #define error_list \
Added spec/rasuir.ct version [13ce85cdbb].
1 +# rasuir protocol spec 2 +rasuir is a simple protocol for semi-dumb remotes to retrieve menus and informational displays from a server. it is a stateless protocol; connections are ephemeral 3 + 4 +%author lexi hale 5 +%toc 6 + 7 +## client and server state 8 +a client uses two state variables when communicating with a server. these are [$mode] and [$ref]. [$mode] is an [!int<16>] menu number, where 0 is the root menu. [$ref] is an [!int<64>] opaque value. 9 +a server is not required to store any state, but may do so in order to implement sessions if complex behavior is absolutely required 10 + 11 +## definitions 12 + 13 +an italicized form indicates a formally specified sequence of bytes. parameters (e.g. the length of an integer form) are placed in angle brackets after the identifier. if the form is bound to a name in context, it is followed by a [`:] and a name in variable notation. 14 +* [*byte], [*byte<1>] ==> one octet 15 +* [*byte<[$N]>] ==> [!byte] [!byte<[=N-1]>] 16 +* [*int<[$N]>] ==> [!byte<[=N / 8]>] interpreted as a little-endian unsigned integer (e.g. [!int<32>] represents an unsigned little-endian 32-bit integer) 17 +* [*sigint<[$N]>] ==> like the above, but interpreted as a two's-complement signed integer 18 +* [*byte-sequence<[$L]>] ==> [!int<[$L]>:[$N]] [!byte<[$N]>], with no specific semantics. that is, a variable-length byte sequence whose size prefix is [$L] bits long 19 +* [*string] ==> [!byte-sequence<8>] interpreted as a UTF-8 string 20 +* [*text] ==> [!byte-sequence<16>] interpreted as a UTF-8 string 21 +* [*bitmap] ==> [!int<16>:[$pxl-width]] [!byte-sequence<8>:[$map]] 22 +* [*state] ==> 23 +*: if on the root menu: [`0x00] 24 +*: if on a menu with an ID between [`1]-[`127] and the opaque [$ref] value is [`0] ("null"): the menu number cast to [!int<8>] (e.g. [`0x00 4A] --> [`0x4A]) 25 +*: if on a menu between [`128]-[`383] with a null [$ref] value: [`0x80] [!int<8>:[=mode - 128]] 26 +*: if on a menu greater than [`383] with a null [$ref]: [`0x81] [!int<16>:[$mode]]. this form is also valid if the number is lower than [`383], and can be used where logical simplicity is more important than compact signalling 27 +*: otherwise: 28 +*:: let [$ref-len] be the length in bytes of the [$ref] value, maximum 8 (0 is valid, in which case no [$ref] sequence is sent) 29 +*:: let [$mode-range] be [`0] if [$mode] is between [`0] and [`255], [`1] otherwise 30 +*:: let [$signal-byte] be [`([$ref-len] << 1) | [$mode]-[$range]] 31 +*:: send [!int<8>:[$signal-byte]] [!int<[=8 + 8*mode-range]>:[$mode]] [!int<[$ref-len*8]>:[$ref]] 32 +* [*link] ==> [!int<8>:[$role]] [!state:[$target]] 33 + 34 +## outline 35 + 36 +: client connects to server 37 +: client transmits {m.n con-ack} 38 +: client authenticates by one of the following 39 +:: to authenticate anonymously, client transmits byte [`0x00]. 40 +:: to authenticate by shortname, client transmits byte [`0x01] followed by a [!byte-sequence<8>]. this may be a PSK, a URI, a literal text name, an OID, or anything else depending on what the server is configured to recognize. 41 +:: to authenticate by longname, client transmits byte [`0x01] followed by a [!byte-sequence<16>]. this is identical to the above but allows to longer values. technically these are different forms of the "name" authentication method; the difference is relevant only at the byte-level 42 +:: other authentication methods may be defined later. a server that encounters an unknown authentication method must transmit an error and close the connection, as it cannot know how to interpret any further communications from the client 43 +: server reports authentication status 44 +:: if the authentication failed, xmit {m.n status-fail} and close the connection 45 +:: if the authentication succeeded, xmit {m.n status-ok} 46 +: client transmits a command 47 +:: {m.n cmd-get} retrieves a menu. it takes the form [!state] [!action] 48 +:: {m.n cmd-hint} transmits a hint to the server. it takes the form [!int<8>:[$hint]] [!byte-sequence<16>] 49 +:: {m.n cmd-meta} requests metadata from the server. it takes the form [!int<16>] 50 +:: {m.n cmd-end} closes the connection. it takes no arguments 51 +: server issues [>rep reply] 52 +: while command was not {m.n cmd-end}, previous two steps repeat 53 +: peers disconnect 54 + 55 +##rep server replies 56 +all replies begin with a one-byte status code. 57 + 58 +### cmd-get reply 59 +the hint reply code may be: 60 +* {m.n status-ok}: the request was valid but the current display should not be changed 61 +* {m.n status-fail}: the request was not valid 62 +* {m.n status-ignore}: the action did nothing 63 +* {m.n status-data}: the request was valid and a form is being returned to display. 64 + 65 +if the reply is {m.n status-data}, it is followed by the header [!byte:[$flags]] [!int<16>:[$widget-count]] 66 +* [$flags] is a bitmask 67 +** [`0x01] = [*passthrough]: all actions should be passed through raw, instead of being used to select a choice in a device-dependent way 68 +** [`0x02] = [*refresh]: client should poll the server for periodic updates on this screen. the header should be followed by an additional parameter [!int<16>:[$refresh]] where refresh time is [=10ms * refresh] 69 + 70 +[$widget-count] widgets then follow. a widget takes the form [!byte:[$wid]] [!byte-sequence<18>:[$data]]. [$wid] identifies the widget type. [$data] holds the widget contents. it is widget-dependent; this value is given as sequence so it can be skipped over by clients that don't implement [$wid]; e.g. images on text displays (though a hint should be sent to disable images instead, in order to save bandwidth). 71 + 72 +### cmd-hint reply 73 +the hint reply code may be: 74 +* {m.n status-ok}: the hint was understood and applied 75 +* {m.n status-fail}: the hint was invalid 76 +* {m.n status-ignore}: the hint was not understood and was ignored 77 +* {m.n status-data}: the hint was understood, and metadata is being returned 78 +if the reply is {m.n status-data}, the code must be followed by a [!byte-sequence<16>]. the meaning of this sequence is hint-dependent. 79 + 80 +### cmd-meta reply 81 +the meta reply code may be: 82 +* {m.n status-ok}: the metadata request was understood but the field is empty/blank 83 +* {m.n status-fail}: the data requested could not be retrieved 84 +* {m.n status-ignore}: the request was not understood and was ignored 85 +* {m.n status-data}: the request was understood, and metadata is being returned 86 +if the reply is {m.n status-data}, the code must be followed by a [!byte-sequence<16>]. the meaning of this sequence is hint-dependent. 87 + 88 + 89 +## widgets 90 +the special notation [!tail] refers to the remainder of entry data body, which is wrapped in a sequence header, so the final element does not need an explicit length or termination marker. [!tail<T>] indicates a type [$T] modified such that any length marker for the final value is removed; for instance [!tail<bitmap>] means ([!int<16>:[$pxl-width]] [!tail:[$map]]). 91 +* {m.n w-paragraph} = [`0x00] [!tail] / shows a block of text 92 +* {m.n w-section} = [`0x02] [!tail] / inserts a heading 93 +* {m.n w-rule} = [`0x07] / inserts a horizontal line that stretches across the screen 94 +* {m.n w-define} = [`0x03] [!string:[$name]] [!tail:[$val]] / shows a definition (e.g. [`[*Name]: Value]); sequential definitions may be arranged into a table 95 +* {m.n w-pbar} = [`0x04] [!int<8>:[$progress]] / shows a progress bar; [`0] means empty, [`255] means full 96 +* {m.n w-bitmap} = [`0x05] [!tail<bitmap>] / shows an image 97 +* {m.n wi-bitmap} = [`0x06] [!link] [!string] [!tail<bitmap>] / shows an image that can be activated as an option, along with caption that may be displayed in vertical layout or as a substitute for the image in text-only displays 98 +* {m.n wi-choice} = [`0x01] [!link:[$target]] [!tail:[$label]] / adds an option that can be selected from the menu, causing the client for query for [$target]. 99 +* {m.n wl-horiz} = [`0x80] [!int<8>:[$N]] / the next [$N] widgets will be arranged horizontally into a grid if possible 100 + 101 +## roles 102 +a role is a small piece of metadata that alters the appearance of an object, for example by changing color or applying an icon. defined roles consist of: 103 +: generic 104 +: accept 105 +: abort 106 +: cancel 107 +: next 108 +: back 109 +: delete 110 +: pause 111 +: play 112 +: stop 113 + 114 +## hints 115 +* {m.n device-kind}: [!int<8>:[$kind]] where [$kind] denotes the kind of device the client is running on. can be repeated to add additional characteristics 116 +*: miniscreen: tiny embedded screen 117 +*: midscreen: phone-sized screen 118 +*: bigscreen: tablet- or larger-sized screen 119 +*: e-ink: the display device uses e-ink (implies bw unless color is also sent) 120 +*: bw: display is black and white 121 +*: color: display supports color 122 +*: slow: device refreshes slowly 123 +*: no-img: do not send bitmap images 124 + 125 +## meta requests 126 +* {m.n server-name} = [`0x00 00]: returns the hostname of the server as a UTF-8 string, or {m.n status-fail} if the hostname is not known 127 +* {m.n server-desc} = [`0x00 01]: returns a textual description of the server, or {m.n status-ok} if no description is set 128 + 129 +##m magic numbers 130 + n: ‹[*[#1]]› 131 + 132 ++ ID + value + 133 +| con-ack | [`0x7A] | 134 +| status-ok | [`0xFF] | 135 +| status-data | [`0xF0] | 136 +| status-ignore | [`0x0F] | 137 +| status-fail | [`0x00] | 138 +| cmd-get | [`0x01] | 139 +| cmd-hint | [`0x02] | 140 +| cmd-meta | [`0x03] | 141 +| cmd-end | [`0x00] | 142 +| w-paragraph | [`0x00] | 143 +| w-section | [`0x02] | 144 +| w-pbar | [`0x04] | 145 +| w-define | [`0x03] | 146 +| w-rule | [`0x07] | 147 +| w-bitmap | [`0x05] | 148 +| wi-bitmap | [`0x06] | 149 +| wi-choice | [`0x01] | 150 +| wl-horiz | [`0x80] |
Name change from rich-ascii.ct to spec/rich-ascii.ct.