Added Italian, updated Polish PO files.

[virt-mem.git] / extract / codegen / pahole_parser.mli

diff --git a/extract/codegen/pahole_parser.mli b/extract/codegen/pahole_parser.mli
index f34b7e3..1bbd701 100644 (file)
--- a/extract/codegen/pahole_parser.mli
+++ b/extract/codegen/pahole_parser.mli
@@ -32,6 +32,8 @@ type pathname = string
   (** Path and filenames. *)
 
 type info = {
+  kv_i : int;                         (** Each kernel is given a unique
+                                          number. *)
   kernel_version : string;            (** Kernel version that this matches. *)
   arch : string;                      (** Architecture, eg. "i686", "ppc64". *)
   basename : string;                  (** [basename.info] is the info
@@ -61,7 +63,12 @@ and field = {
 and f_type =
   | FStructPointer of string           (** A pointer to a named struct. *)
   | FVoidPointer                       (** A [void*] pointer. *)
-  | FListHeadPointer                   (** A pointer to a [list_head]. *)
+  | FAnonListHeadPointer               (** A pointer to an unknown
+                                           [list_head]. *)
+  | FListHeadPointer of (string * string) option
+      (** A pointer to a [list_head].  If the value is not [None] then
+         this relates to another named struct/field, else it relates
+         to this struct/field. *)
   | FInteger                           (** An integer. *)
   | FString of int                     (** A char array of given width. *)
   (** Type of a kernel field. *)
@@ -79,13 +86,62 @@ val list_kernels : pathname -> info list
 
 (** {2 Load kernel structures} *)
 
-val load_structures : info -> string list -> structure list
+val load_structures : info -> string list -> (string * structure) list
   (** [load_structures info names] loads the named kernel structures
       from a particular kernel.
 
       The returned list is not necessarily in the same order, or the
-      same length, as the [names] list.  Check the
-      {!structure.struct_name} field for the structure name.
-      Structures which don't actually occur in the given kernel are
-      not loaded and not present in the final list.
+      same length, as the [names] list.  Check the first field in each
+      pair for the structure name.  Structures which don't actually
+      occur in the given kernel are not loaded and not present in the
+      final list.
+
+      The fields list in {!structure} is always sorted by field offset.
   *)
+
+(** {2 Transpose and check field types}
+
+    After we've used {!load_structures} for each kernel, we end
+    up with a list of kernels, and within that a list of structures
+    supported by the kernel.  What we really want is to see how
+    each structure changes over time, and also to check if field
+    types have changed between versions (which we currently disallow).
+
+    The {!transpose} operation transposes the original list
+    of kernels to a list of structures.
+
+    The {!get_fields} operation gets a complete list of fields
+    and their types, and checks that the types haven't changed over
+    kernel versions.  (Note that particular fields can be missing from
+    some kernel version, but that is OK).
+*)
+
+val transpose : string list ->
+  (info * (string * structure) list) list ->
+  (string * (info * structure) list) list
+  (** Transpose list of kernels to list of structures.  The result
+      shows, for each structure, how it changed over kernel versions.
+
+      The first parameter is the list of structure names of interest,
+      and should be the same as was passed to {!load_structures}. *)
+
+val get_fields : (info * structure) list -> (string * (f_type * bool)) list
+  (** This gets a complete list of fields which have appeared in
+      any kernel version.
+
+      The return list contains [(field_name, (field_type,
+      always_present))] where [always_present] is a boolean flag which
+      is true if the field is present in every kernel version we
+      examined.
+
+      Fields must not change type between kernel versions - if
+      so this function prints an error and exits. (We may support
+      fields which change type in future, but we don't right now).
+      "Type" is quite widely defined here, see {!f_type}, and so
+      certain changes such as between sizes of ints are allowed,
+      but you can't have a field which once was a pointer and then
+      became a string or anything like that.
+
+      Note that a field may not be present in particular kernel
+      versions, but if it appears at all in any version, then it
+      will be in the result list. *)