feature: add mkdocs-material documentation site with CI deployment
Generate comprehensive documentation for all 173 source units and integrate mkdocs-material into the build toolchain. Documentation covers kernel core, x86 architecture, drivers, applications, and all subsystems with a tabbed navigation structure. - Add mkdocs.yml with material theme, mermaid support, and tabbed nav - Add doc/index.md landing page - Generate doc/src/ markdown for every Pascal unit in src/ - Reorganize planning docs into doc/planning/ - Add compat, lvglh, and toolchain doc sections - Update Dockerfile to install python3 and mkdocs-material (pinned <2) - Replace pasdoc-based compile_docs.sh with mkdocs build --strict - Add compile_docs.sh to the main build pipeline in compile.sh - Add deploy-docs step in .drone.yml with host volume mount to nginx - Add site/.gitkeep for build output directory
This commit is contained in:
t3hn3rd committed
1 parent
7157a57513
commit
26e2fd947e
209 files changed
+16996
-13
No files matched your search
@@ -0,0 +1,56 @@
|
||||
# core.enc.base64
|
||||
|
||||
Base64 encoding and decoding.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.base64` implements RFC 4648 Base64 encoding and decoding for the kernel. It operates on raw byte buffers or null-terminated strings and returns heap-allocated results. The encoder inserts a newline character every 72 output characters and appends `=` padding to complete the final group. The decoder ignores whitespace and newlines in the input.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `memory.heap` — `kalloc`, `kfree`
|
||||
- `core.strings` — `stringSize`
|
||||
- `debug.tracer` — call-stack tracing
|
||||
- `core.util` — `memset`
|
||||
- `arch.x86.util` — architecture utilities
|
||||
|
||||
## Constants
|
||||
|
||||
### base64_enc_map
|
||||
A 64-element character array containing the standard Base64 alphabet (`A`–`Z`, `a`–`z`, `0`–`9`, `+`, `/`). Used by the encoder to map 6-bit values to output characters.
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### b64_encode
|
||||
```pascal
|
||||
function b64_encode(src : PuInt8; len : uInt32; out_len : PuInt32) : PuInt8;
|
||||
```
|
||||
Encodes `len` bytes from `src` into a heap-allocated Base64 string. If `out_len` is not `nil`, the output length (including the trailing null byte) is written there. Returns `nil` if the output length calculation overflows.
|
||||
|
||||
### b64_decode
|
||||
```pascal
|
||||
function b64_decode(src : PuInt8; len : uInt32; out_len : PuInt32) : PuInt8;
|
||||
```
|
||||
Decodes `len` bytes of Base64 data from `src` into a heap-allocated raw byte buffer. If `out_len` is not `nil`, the decoded byte count is written there. Returns `nil` if the input is invalid or allocation fails.
|
||||
|
||||
### b64_encode_str
|
||||
```pascal
|
||||
function b64_encode_str(src : PChar) : PChar;
|
||||
```
|
||||
Convenience wrapper: encodes the null-terminated string `src` and returns a heap-allocated Base64 string. Pushes tracer entries on entry and return.
|
||||
|
||||
### b64_decode_str
|
||||
```pascal
|
||||
function b64_decode_str(src : PChar) : PChar;
|
||||
```
|
||||
Convenience wrapper: decodes the null-terminated Base64 string `src` and returns a heap-allocated decoded string. Pushes tracer entries on entry and return.
|
||||
|
||||
## Notes
|
||||
|
||||
The encoder output includes newlines after every 72 characters. Consumers that do not expect line breaks should strip them or use `b64_encode` directly and handle the output buffer themselves.
|
||||
|
||||
The decoder builds a 256-entry decode table on the stack at each call. Unknown characters are mapped to `$80` (the sentinel for "skip"). Padding characters (`=`) are mapped to `0` and their count is tracked to trim the output length.
|
||||
|
||||
If the input to `b64_decode` is not a multiple of 4 valid Base64 characters, the function currently enters an unhandled branch (silent error). Callers should validate input length before decoding.
|
||||
|
||||
Both `b64_encode` and `b64_decode` return heap-allocated buffers that must be freed by the caller with `kfree`.
|
||||
@@ -0,0 +1,27 @@
|
||||
# core.enc.crc
|
||||
|
||||
CRC-32 checksum computation.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.crc` implements the standard CRC-32 algorithm using a pre-computed 256-entry lookup table (IEEE 802.3 polynomial `0xEDB88320` reflected). It is used for data integrity verification throughout the kernel.
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### CRC32
|
||||
```pascal
|
||||
function CRC32(p : puint8; size : uint32) : uint32;
|
||||
```
|
||||
Computes the CRC-32 checksum of `size` bytes starting at pointer `p`. The initial value is `$FFFFFFFF` and the result is bitwise inverted before returning, following the standard CRC-32 finalisation step.
|
||||
|
||||
## Notes
|
||||
|
||||
The lookup table is a compile-time constant array of 256 `uint32` values. No initialisation is required at runtime.
|
||||
|
||||
The algorithm processes one byte at a time using the standard table-driven update: `CRC = table[(CRC xor byte) and $FF] xor (CRC shr 8)`.
|
||||
|
||||
This implementation is suitable for file/block integrity checks but is not cryptographically secure.
|
||||
@@ -0,0 +1,55 @@
|
||||
# core.enc.djb2
|
||||
|
||||
DJB2 non-cryptographic hash functions in 32-bit and 64-bit widths.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.djb2` implements the DJB2 hash algorithm created by Daniel J. Bernstein. It provides fast, well-distributed hashing suitable for hash tables, Bloom filters, and string hashing. Two mixing strategies are provided — XOR and addition — in both 32-bit and 64-bit variants. All four variants share the same initial seed (`5381`) and the same shift-add structure (`h = ((h << 5) + h) op c`).
|
||||
|
||||
The XOR variant (`Hash_DJB2_32` / `Hash_DJB2_64`) is the classic djb2: `h = ((h << 5) + h) ^ c`.
|
||||
|
||||
The addition variant (`Hash_DJB2Add_32` / `Hash_DJB2Add_64`) uses `h = ((h << 5) + h) + c`, also known as the sdbm-style variant. It produces a different distribution and is used as the independent second hash in the double-hashing scheme of `core.ds.bloom`.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `io.syslog` — test output (implementation only)
|
||||
- `memory.heap` — `kfree` (implementation only)
|
||||
- `core.strings` — test output formatting (implementation only)
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### Hash_DJB2_32
|
||||
```pascal
|
||||
function Hash_DJB2_32(Data : void; DataLen : uint32) : uint32;
|
||||
```
|
||||
Computes a 32-bit DJB2 XOR hash of `DataLen` bytes starting at `Data`. Zero-length input returns the initial seed `5381`.
|
||||
|
||||
### Hash_DJB2_64
|
||||
```pascal
|
||||
function Hash_DJB2_64(Data : void; DataLen : uint32) : uint64;
|
||||
```
|
||||
Computes a 64-bit DJB2 XOR hash. Zero-length input returns `uint64(5381)`.
|
||||
|
||||
### Hash_DJB2Add_32
|
||||
```pascal
|
||||
function Hash_DJB2Add_32(Data : void; DataLen : uint32) : uint32;
|
||||
```
|
||||
Computes a 32-bit DJB2 addition (sdbm-style) hash. Produces a distribution independent from `Hash_DJB2_32`, useful as a second hash in double-hashing schemes.
|
||||
|
||||
### Hash_DJB2Add_64
|
||||
```pascal
|
||||
function Hash_DJB2Add_64(Data : void; DataLen : uint32) : uint64;
|
||||
```
|
||||
Computes a 64-bit DJB2 addition hash.
|
||||
|
||||
### UnitTest
|
||||
```pascal
|
||||
procedure UnitTest;
|
||||
```
|
||||
Runs the DJB2 test suite (determinism, distinctness for different inputs, length sensitivity, XOR vs. addition independence) and logs a pass/fail summary to syslog under the `'DJB2'` channel.
|
||||
|
||||
## Notes
|
||||
|
||||
All four functions are purely computational with no side effects or allocations. They may be called freely from any context, including interrupt handlers.
|
||||
|
||||
The 32-bit and 64-bit variants are independent algorithms; the low 32 bits of the 64-bit result are not guaranteed to equal the 32-bit result for the same input.
|
||||
@@ -0,0 +1,50 @@
|
||||
# core.enc.fnv1a
|
||||
|
||||
FNV-1a (Fowler-Noll-Vo) non-cryptographic hash in 32-bit and 64-bit widths.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.fnv1a` implements the FNV-1a variant of the Fowler-Noll-Vo hash algorithm. FNV-1a XORs each input byte into the hash value before multiplying by the FNV prime, which provides better avalanche characteristics than the original FNV-1 (which multiplies first). The algorithm is simple, fast, and produces well-distributed hashes suitable for hash tables, Bloom filters, and checksums.
|
||||
|
||||
FNV-1a is the primary hash function used by `core.ds.hashmap` (key hashing) and `core.ds.bloom` (first of two hash functions in the double-hashing scheme).
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `io.syslog` — test output (implementation only)
|
||||
- `memory.heap` — `kfree` (implementation only)
|
||||
- `core.strings` — test output formatting (implementation only)
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### Hash_FNV1a32
|
||||
```pascal
|
||||
function Hash_FNV1a32(Data : void; DataLen : uint32) : uint32;
|
||||
```
|
||||
Computes a 32-bit FNV-1a hash of `DataLen` bytes starting at `Data`.
|
||||
- Initial basis: `$811C9DC5`
|
||||
- FNV prime: `$01000193`
|
||||
- Per byte: `h = (h xor byte) * prime`
|
||||
|
||||
Zero-length input returns the basis value `$811C9DC5`.
|
||||
|
||||
### Hash_FNV1a64
|
||||
```pascal
|
||||
function Hash_FNV1a64(Data : void; DataLen : uint32) : uint64;
|
||||
```
|
||||
Computes a 64-bit FNV-1a hash.
|
||||
- Initial basis: `$CBF29CE484222325`
|
||||
- FNV prime: `$00000100000001B3`
|
||||
|
||||
Zero-length input returns the basis value.
|
||||
|
||||
### UnitTest
|
||||
```pascal
|
||||
procedure UnitTest;
|
||||
```
|
||||
Runs the FNV-1a test suite (known basis for empty input, determinism, distinctness for different inputs, length sensitivity, independence of 32-bit and 64-bit variants) and logs a pass/fail summary to syslog under the `'FNV1A'` channel.
|
||||
|
||||
## Notes
|
||||
|
||||
Both functions are purely computational with no side effects or allocations. They may be called from any context.
|
||||
|
||||
The low 32 bits of `Hash_FNV1a64` are not guaranteed to equal `Hash_FNV1a32` for the same input; they are independent algorithms.
|
||||
@@ -0,0 +1,80 @@
|
||||
# core.enc.md5
|
||||
|
||||
MD5 message-digest checksum.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.md5` implements the MD5 hash algorithm (RFC 1321) for the kernel. It provides an incremental streaming interface (`MD5Init` / `MD5Update` / `MD5Final`) for computing digests over data that arrives in multiple chunks, as well as a single-call convenience function (`MD5Buffer`) for hashing a complete buffer at once. A utility function (`MD5To32`) folds a 128-bit digest to a 32-bit value for use as a compact key.
|
||||
|
||||
MD5 is used in Asuro for file integrity verification and as a legacy key-hash function (replaced by FNV-1a in the hash map but retained for compatibility).
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `core.util` — `memset`, `memcpy`
|
||||
- `arch.x86.util` — `roldword` (32-bit left rotate)
|
||||
- `memory.heap` — `kalloc`, `kfree`
|
||||
- `debug.tracer` — call-stack tracing
|
||||
|
||||
## Constants
|
||||
|
||||
### MD5DefineBufferSize
|
||||
Internal working buffer size: `1024`. Not directly used by callers.
|
||||
|
||||
## Types
|
||||
|
||||
### TMD5Context / PMD5Context
|
||||
```pascal
|
||||
TMD5Context = record
|
||||
Align : uInt32;
|
||||
State : array[0..3] of uInt32;
|
||||
BufferCount : uInt64;
|
||||
Buffer : array[0..63] of uInt8;
|
||||
Length : uInt64;
|
||||
Checksum : array[0..15] of uInt8;
|
||||
end;
|
||||
```
|
||||
Incremental hashing context. `State` holds the four 32-bit MD5 state words. `Buffer` is an internal 64-byte accumulation buffer. `Length` tracks the total number of bytes processed by `MD5Transform`. `BufferCount` tracks how many bytes are currently buffered. `Align` is set to 64 (the block size).
|
||||
|
||||
### TMD5Digest / PMD5Digest
|
||||
```pascal
|
||||
TMD5Digest = array[0..15] of uInt8;
|
||||
```
|
||||
A 16-byte MD5 digest. Returned as a heap-allocated pointer by `MD5Final` and `MD5Buffer`.
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### MD5Init
|
||||
```pascal
|
||||
procedure MD5Init(context : PMD5Context);
|
||||
```
|
||||
Initialises an `MD5Context` to the standard MD5 initial state. Must be called before any `MD5Update` calls.
|
||||
|
||||
### MD5Update
|
||||
```pascal
|
||||
procedure MD5Update(context : PMD5Context; buffer : PuInt8; bufferLen : uInt32);
|
||||
```
|
||||
Feeds `bufferLen` bytes from `buffer` into the hash context. May be called multiple times to hash data arriving in chunks.
|
||||
|
||||
### MD5Final
|
||||
```pascal
|
||||
function MD5Final(context : PMD5Context) : PMD5Digest;
|
||||
```
|
||||
Finalises the hash by appending MD5 padding and the message length, then extracts and returns a heap-allocated 16-byte digest. Zeroes the context after use. The caller must free the returned digest with `kfree`.
|
||||
|
||||
### MD5Buffer
|
||||
```pascal
|
||||
function MD5Buffer(buffer : PuInt8; bufferLen : uInt32) : PMD5Digest;
|
||||
```
|
||||
Convenience function: allocates a context, runs `MD5Init` + `MD5Update` + `MD5Final`, frees the context, and returns the digest. The caller must free the returned digest with `kfree`.
|
||||
|
||||
### MD5To32
|
||||
```pascal
|
||||
function MD5To32(Input : PuInt128) : uint32;
|
||||
```
|
||||
Folds a 128-bit MD5 digest to a 32-bit value by XOR-ing the four 32-bit words of the digest. Useful as a compact hash key derived from a full MD5 digest.
|
||||
|
||||
## Notes
|
||||
|
||||
MD5 is not cryptographically secure and must not be used for security-critical purposes such as password hashing or digital signatures. It is retained in Asuro for non-security integrity checks and legacy compatibility.
|
||||
|
||||
`MD5Transform` operates on data in little-endian byte order, consistent with the MD5 specification. The internal `Invert` helper reorders bytes from a byte buffer into little-endian `uint32` words.
|
||||
@@ -0,0 +1,68 @@
|
||||
# core.enc.sha1
|
||||
|
||||
SHA-1 message-digest hash.
|
||||
|
||||
## Overview
|
||||
|
||||
`core.enc.sha1` implements the SHA-1 hash algorithm (FIPS 180-4) for the kernel. It provides an incremental streaming interface (`SHA1Init` / `SHA1Update` / `SHA1Final`) for computing 160-bit digests over data arriving in multiple chunks. The implementation uses big-endian byte order for state words and digest output, as required by the SHA-1 specification.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `core.util` — `memset`
|
||||
- `arch.x86.util` — `RolDWord`, `RorDWord` (32-bit rotate operations)
|
||||
|
||||
## Types
|
||||
|
||||
### TSHA1Digest / PSHA1Digest
|
||||
```pascal
|
||||
TSHA1Digest = array[0..19] of byte;
|
||||
```
|
||||
A 20-byte (160-bit) SHA-1 digest.
|
||||
|
||||
### TSHA1Context / PSHA1Context
|
||||
```pascal
|
||||
TSHA1Context = record
|
||||
State : array[0..4] of cardinal;
|
||||
Buffer: array[0..63] of uint8;
|
||||
BufCnt: uint32;
|
||||
Length: QWord;
|
||||
end;
|
||||
```
|
||||
Incremental hashing context. `State` holds the five 32-bit SHA-1 state words initialised to the standard constants. `Buffer` is a 64-byte block accumulation buffer. `BufCnt` tracks the number of bytes currently in `Buffer`. `Length` accumulates the total number of complete 64-byte blocks processed (in bytes).
|
||||
|
||||
## Functions and Procedures
|
||||
|
||||
### SHA1Init
|
||||
```pascal
|
||||
procedure SHA1Init(ctx : PSHA1Context);
|
||||
```
|
||||
Initialises the SHA-1 context to the standard initial state:
|
||||
- `State[0] = $67452301`
|
||||
- `State[1] = $EFCDAB89`
|
||||
- `State[2] = $98BADCFE`
|
||||
- `State[3] = $10325476`
|
||||
- `State[4] = $C3D2E1F0`
|
||||
|
||||
Must be called before any `SHA1Update` calls.
|
||||
|
||||
### SHA1Update
|
||||
```pascal
|
||||
procedure SHA1Update(ctx : PSHA1Context; buffer : puint8; bufferLen : uint32);
|
||||
```
|
||||
Feeds `bufferLen` bytes from `buffer` into the hash context. Internally buffers partial blocks and calls `SHA1Transform` when a complete 64-byte block is assembled. May be called multiple times.
|
||||
|
||||
### SHA1Final
|
||||
```pascal
|
||||
procedure SHA1Final(ctx : PSHA1Context; digest : PSHA1Digest);
|
||||
```
|
||||
Finalises the hash by appending SHA-1 padding (0x80 followed by zeroes) and the 64-bit big-endian message bit-length. Writes the 20-byte digest into the caller-supplied `digest` buffer. Zeroes the context after extraction.
|
||||
|
||||
Unlike `MD5Final`, `SHA1Final` does not allocate a digest buffer; the caller must provide one.
|
||||
|
||||
## Notes
|
||||
|
||||
SHA-1 is no longer considered cryptographically secure for collision resistance. It should not be used for new security-critical applications. It is included in Asuro for compatibility with existing protocols or formats that require it.
|
||||
|
||||
The internal `SHA1Transform` function processes data in big-endian format using the helper `Invert` to convert the 64-byte input buffer into 16 big-endian `uint32` words before applying the four SHA-1 rounds (0–19, 20–39, 40–59, 60–79).
|
||||
|
||||
`SHA1Final` does not allocate memory; the caller is responsible for providing a `TSHA1Digest`-sized buffer.
|
||||
Reference in new issue
Block a user