This is an old revision of the document!
Network Stack KPI/KPI
This wiki page attempts to identify kernel data structures which, if changed after a .0 release on a branch, may prevent network device drivers, firewall modules, as well as userland monitoring tools, etc, from working properly.
The following status options exist for each structure:
- Immutable - This data structure should not be changed
The data structure is very sensitive to change, and may be allocated statically in BSS, on the stack, etc, by modules. Changing the size of the structure could lead to (possibly extensive) kernel memory corruption, panics, etc.
- Padded - Padding has been added to this data structure that may be reused
While the data structure is very sensitive to change, “spare” fields have been added to the structure that may be reused with identically sized data. Special caution should be paid to compiler padding and architecture variation in field length (sizeof(void *) == sizeof(int) on i386, but not on amd64, for example). Also, care should be taken when making assumptions about values found in fields when left uninitialized – do all callers always allocate it in BSS, resulting in spare fields being zeroed, or might they allocate it on the stack, meaning that they may be filled with garbage if not explicitly initialized by a caller?
- Extendable - New fields may be added to the end of this data structure (typically a kernel-allocated structure, such as struct thread, struct proc, etc).
These data structures are visible in APIs used by third-party code, but the data structures are always allocated and managed by the base kernel; this means that you can't change the layout of fields known to modules (etc) after the branch, but you can add new fields at the end that only newer modules will use and be aware of. When extending fields, it is important to make certain that consumers of the new fields run only on kernels where the fields are defined.
- Private
These data structures are used only inside of the kernel or specific modules, and the layout may be changed without (excessive) concern.
net
| Structure | Status | Comments |
|---|---|---|
| struct bpf_d | Extendable | Always allocated by the BPF code; MAC policy modules may dereference fields, such as bd_label. |
| struct mbuf | Immutable | Used throughout the kernel with extensive assumptions about layout, alignment, etc. Change only with extreme caution. |
| struct ifnet | Padded | Allocated by the base kernel, but used in all device drivers. |
| struct netisr_handler | Padded | Allocated statically by protocol modules in BSS, but padded for future growth. |
| struct route | Immutable | Allocated statically in BSS, inside of data structures, and on the stack by protocols, device drivers, etc. |