(** 'pahole' output parser. *)
(* Memory info command for virtual domains.
   (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
   http://libvirt.org/

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *)

(** This parses the output of the pahole command, allowing us
    to extract the layout of kernel structures for particular
    kernel versions.

    Its primary input is the [*.info] and [*.data*] files found
    in the [kernels/] subdirectory (ie. the kerneldb).
*)

(** {2 Types} *)

type pathname = string
  (** Path and filenames. *)

type info = {
  kernel_version : string;	       (** Kernel version that this matches. *)
  arch : string;		       (** Architecture, eg. "i686", "ppc64". *)
  basename : string;		       (** [basename.info] is the info
					   file and [basename.data*] is
					   the data file. *)
}
  (** Kernel metainformation, extracted from the [*.info] file. *)

type structure = {
  struct_name : string;			(** Structure name. *)
  struct_total_size : int;		(** Total size in bytes. *)
  struct_fields : field list;		(** Fields in the structure. *)
}
  (** A kernel structure, eg. [task_struct]. *)

and field = {
  field_name : string;			(** Field name. *)
  field_type : f_type;			(** Field type. *)
  field_offset : int;			(** Offset within the structure. *)
  field_size : int;			(** Size of the field (bytes). *)
}
  (** A kernel structure field.

      Note that nested fields are flattened with single quotes (')
      between elements, so you get names like [tasks'next]. *)

and f_type =
  | FStructPointer of string		(** A pointer to a named struct. *)
  | FVoidPointer			(** A [void*] pointer. *)
  | FListHeadPointer		        (** A pointer to a [list_head]. *)
  | FInteger				(** An integer. *)
  | FString of int			(** A char array of given width. *)
  (** Type of a kernel field. *)

val string_of_info : info -> string
val string_of_structure : structure -> string
val string_of_field : field -> string
val string_of_f_type : f_type -> string
  (** Printing functions. *)

(** {2 List kernels in kerneldb} *)

val list_kernels : pathname -> info list
  (** Return a list of all the kernels in the kerneldb at [path]. *)

(** {2 Load kernel structures} *)

val load_structures : info -> string list -> 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.
  *)