Differences

This shows you the differences between two versions of the page.

--- netkpikbi [2009/06/30 09:58] – More structure details. RobertWatson
+++ netkpikbi [2009/08/01 11:04] (current) – Downgrade KBI status from immutable to extendable for some global structs due to removal of vinet.h RobertWatson
@@ Line 3: / Line 3: @@
 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.
-===== Data structure statuses =====
+===== Data structure status key =====
 The following status options exist for each structure:
@@ Line 22: / Line 22: @@
 These data structures are used only inside of the kernel or specific modules, and the layout may be changed without (excessive) concern.
+===== Key to usage =====
+The following uses are of particular interest from a KPI/KBI perspective:
+^ Abbreviation ^ Description ^
+| MD | Module dereference: kernel modules encode the offset and type of structure fields in their implementation. |
+| MA | Module allocation: kernel modules encode size of structure in their implementation, possibly in BSS, on the stack, or as an a direct argument to malloc(9) or uma(9). |
+| SE | Sysctl export: the data structure is exposed to userspace via the sysctl(2) system call, and therefore part of the ABI. |
+| SC | System call argument: data structure is an argument to a system call. |
+| KD | KVM dereference: userspace monitoring or post-mortem analysis tools encode offset and type of structure fields in their implementation. |
+| KS | KVM size dependency: userspace monitoring or post-mortem analysis tools encode the length of the structure in their implementation (i.e., due to the struct being allocated in an array in the kernel). |
 ===== sys =====
-| struct mbuf | Immutable | Extreme caution required. |
+^ Type ^ Status ^ MD ^ MA ^ SE ^ SC ^ KD ^ KS ^ Comments ^
-| struct sockopt | Immutable | Allocated on the stack in kernel modules. |
+| struct mbuf | Immutable | Yes | ?? | No | No | No | No | Extreme caution required. |
-| struct sockaddr | Immutable | Allocated statically, embedded in kernel structures, and part of the system call ABI. |
+| struct sockopt | Immutable | Yes | Yes | No | No | No | No | Allocated on the stack in kernel modules. |
-| struct unpcb | Immutable | Allocated only by uipc_usrreq.c, but accessed by portalfs, and, mysteriously, embedded in xunpcb, or would be **Extendable**. |
+| struct sockaddr | Immutable | Yes | Yes | Yes | Yes | ?? | ?? | Allocated statically, embedded in kernel structures, and part of the system call ABI. |
-| struct xsocket | Immutable | Exposed explicitly via sysctl to userspace. |
+| struct unpcb | Immutable | Yes | No | Yes | No | Yes | ?? | Allocated only by uipc_usrreq.c, but accessed by portalfs, and, mysteriously, embedded in xunpcb, or would be **Extendable**. |
-| struct xunpcb | Immutable | Allocated only by uipc_usrreq.c, but exposed explicitly via sysctl to userspace. |
+| struct xsocket | Immutable | No | No | Yes | No | No | No | Exposed explicitly via sysctl to userspace. |
+| struct xunpcb | Immutable | No | No | No | Yes | No | No | Allocated only by uipc_usrreq.c, but exposed explicitly via sysctl to userspace. |
 ===== net =====
@@ Line 45: / Line 58: @@
 ^ Type ^ Status ^ Comments ^
-| struct in_addr |  |  |
+| struct in_addr | Immutable | Embedded in countless user and kernel data structures and ABIs. |
-| struct in_ifaddr |  |  |
+| struct in_ifaddr | Extendable | Allocated only by in.c, but used in many places in net, netinet, netipsec. |
 | struct inpcb | Padded | Allocated from a number of zones, depending on protocol type; exposed explicitly to userspace via xinpcb, xtcpcb via sysctl.  Without exposure via sysctl, might be **Extendable** but would need to review all protocols to make sure that is safe.  Is accessed from modules including firewalls, IPSEC, and TOE. |
-| struct inpcbinfo | Immutable | Embedded in struct vinet; accessed by user monitoring tools via KVM. |
+| struct inpcbinfo | Extendable | Accessed by user monitoring tools via KVM. |
-| struct ipq |  |  |
+| struct ipq | Extendable | Allocated only by ip_input.c, but some fields read by MAC policy modules. |
-| struct route_in |  |  |
+| struct sackhint | Padded | Used only inside of TCP, but embedded in struct tcpcb so is exposed to userspace and other kernel modules with tcpcb visibility. |
 | struct sockaddr_in | Immutable | Allocated statically and part of the system call ABI; embedded in other data structures. |
 | struct syncache | Extendable | Currently allocated/consumed only in TCP, but user monitoring tools will access it via KVM in the future. |
-| struct syncache_head |
+| struct syncache_head | Private | Currently allocated and accessed only by TCP, but may be accessed via KVM by user monitoring tools in the future. |
 | struct tcp_hostcache | Extendable | Currently allocated/consumed only in TCP, but user monitoring tools will access it via KVM in the future. |
-| struct tcpcb |  |  |
+| struct tcpcb | Immutable | Currently allocated only by TCP, but accessed in a number of places including NFS, and exported to userspace directly via xtcpcb in sysctl.  Would probably be **Extendable** if it weren't exported directly. |
-| struct tcptw |  |  |
+| struct tcpopt | Padded | Allocated and used only within TCP -- except for TOE modules, also allocated it (on the stack) and pass it into syncache entry initialization. |
-| struct tcp_syncache | Immutable | Embedded in struct vinet; user monitoring tools will access it via KVM in the future. |
+| struct tcptw | Private | Currently allocated and accessed only by TCP, but may be accessed via KVM by user monitoring tools in the future. |
+| struct tcp_syncache | Extendable | User monitoring tools will access it via KVM in the future. |
 | struct udpdb | Private | Currently allocated and accessed only by UDP/UDP6, but may be accessed via KVM by user monitoring tools in the future. |