diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dev_notes.md | 12 | ||||
| -rw-r--r-- | doc/impl.md | 106 | ||||
| -rw-r--r-- | doc/sws.md | 3 | ||||
| -rw-r--r-- | doc/user_guide.md | 2 |
4 files changed, 119 insertions, 4 deletions
diff --git a/doc/dev_notes.md b/doc/dev_notes.md index 10843c5..544606a 100644 --- a/doc/dev_notes.md +++ b/doc/dev_notes.md @@ -1,5 +1,10 @@ # Proone Dev Notes +## Debugging +### Capabilities(7) +Both gdb and the executable to debug must have `CAP_NET_RAW` set in order for +BNE to work. + ## Platform-specifics ### Erasing arguments passed to Proone The Proone instance processes may look suspicious because the cmdline string @@ -37,7 +42,12 @@ to real threads, expect some race condition related bugs. ### Put Mbed TLS on Diet The build is not light because the Mbed TLS library is extensive. Proone is tested using default Mbed TLS config included in Buildroot, but size reduction -may be achieved by disabling unnessary features like threading and DTLS support. +may be achieved by disabling unnessary features. + +* Threading +* DTLS +* TLS Renegotiation +* ZLIB ### Don't Build Clean-up Code Disabling clean-up code for release build is widely accepted technique to reduce diff --git a/doc/impl.md b/doc/impl.md new file mode 100644 index 0000000..2d598ef --- /dev/null +++ b/doc/impl.md @@ -0,0 +1,106 @@ +# Proone Implementation Note +## Dynamic Memory Allocation +POSIX compliant dynamic memory functions may return a valid pointer that can be +passed to `free()`(MALLOC(3)). Proone does not appreciate this inconsistency as +it has to be tolerant to memory allocation failure. + +Consider following snippet. + +```c +int *get_int_arr (size_t n) { + int *ret = (int*)calloc(sizeof(int), n); + + if (ret == NULL) { + abort(); + } + + for (size_t i = 0; i < n; i += 1) { + ret[i] = i % INT_MAX; + } + + return ret; +} +``` + +The behaviour of this code depends on whether `calloc()` returns a null or valid +pointer for zero-length allocation. To avoid mistakes like this one, the memory +allocation functions of the Proone framework(prefixed `prne_`) always returns +NULL for zero-length allocation. This way, the implementation is forced to infer +memory allocation failure from the parameter and the return value. + +```c + if (n > 0 && ret == NULL) { +``` + +All the memory allocated using the framework allocaiton functions(`prne_*()`) +must be freed with `prne_free()`. + +## Resource Allocation Hook +One of the purposes of `prne_free()` and `prne_close()` is to facilitate the +implementation of a framework-level resource debugging(like MSVC macros) in the +future. This may be useful when use of Valgrind becomes too cumbersome. Another +is to keep a registry of the file descriptors for use in `prefork()` and +`atfork()` equivalent. + +## Resource Allocation +### Transparent Structures + +```c +prne_init_llist() +prne_free_llist() +``` + +Transparent structures must be initialised and deinitialised using the functions +provided. + +The initialisation functions set the members of the structures to their default +values and prepares the structures for the deinitialisation calls. This is +normally done by zeroing the entire structure, but there are exceptions where +values other than zero are used for default values. + +The deinitialisation functions are like "desctructors" in other languages. The +functions free any dynamically allocated members. For the structures that have +no dynamic members, the functions have no effect. + +All initialisation and deinitialisation functions must be used to ensure that +the members added in the future are initialised/freed. Are guaranteed to take +one argument. + +Deinitialised structures are not reusable. The structures must be reinitialised +after being deinitialised. + +### Opaque Types + +```c +prne_rnd_alloc_well512() +prne_alloc_resolv() +``` + +Opaque types, usually poly-morphed objects(class), are dynamically allocated by +"instantiation functions". Examples include `resolv` and `rnd`. The destructor +functions are provided upon successful instantiation. The underlying abstraction +layer is responsible for the invocation of the destructor functions. + +### Dynamic Members + +```c +prne_htbt_alloc_host_info() +prne_alloc_iobuf() +``` + +Some types have dynamically allocated members and the dynamic member allocation +functions are defined for dynamic members. Dynamic members can be freed by +calling the functions with zero for the size argument. Dynamic members are freed +by the deinitialisation functions. + +### Ownership of Dynamically Resources +Some structures have the `ownership` flag member so their dynamic members, +especially large memory, can be used with other instances. If the structure has +the flag and its value is set, it means that the structure is the owner of the +dynamically allocated memory and is responsible for freeing it upon destruction +by the deinitialisation function. If the flag is unset, the deinitialisation +function will not free the dynamic members. + +The flag can be used to form a chain of structures with the same dynamic +members. The flag can also be used to use data from .bss or .data as dynamic +members. @@ -360,7 +360,8 @@ proone-htbtclient. MariaDB for DB backend. ### Executables * /src/proone: Proone instance executable with DVault only * /src/proone.bin: Proone instance executable ELF part only (not runnable) -* /src/proone-bne: standalone bne tool for testing and index case(P0) +* /src/proone-bne: standalone bne tool for testing and deployment of an index + case(P0) * /src/proone-hostinfod: hostinfo daemon, an example of authoritive heartbeat implementation * /src/proone-htbtclient: heartbeat client, Proone instance maintenance tool diff --git a/doc/user_guide.md b/doc/user_guide.md deleted file mode 100644 index 7f82da5..0000000 --- a/doc/user_guide.md +++ /dev/null @@ -1,2 +0,0 @@ -# Proone User Guide -TODO |