(*---------------------------------------------------------------------------
   Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** RPMsg inter-partition messaging.

    Wraps the Linux RPMsg character device interface for message-based IPC
    between partitions. Used on Jailhouse, Xen, and Zynq UltraScale+ platforms
    for communication between SpaceOS (Linux) and co-processor partitions via
    virtio vrings.

    The [rpmsg_endpoint_info] struct layout is described via {!Wire.Codec},
    avoiding manual C struct packing. On macOS, endpoint creation via {!Ctrl}
    raises [Failure] (RPMsg does not exist outside Linux). *)

(** {1 Endpoint info wire format} *)

type endpoint_info = { name : string; src : int; dst : int }
(** Matches Linux kernel [struct rpmsg_endpoint_info]. *)

val endpoint_info_codec : endpoint_info Wire.Codec.t
(** [endpoint_info_codec] is the wire codec for {!endpoint_info}: name[32],
    src:u32, dst:u32. *)

val endpoint_info_size : int
(** [endpoint_info_size] is the wire size of {!endpoint_info} (40 bytes). *)

(** {1 Control device} *)

module Ctrl : sig
  type t
  (** A handle to [/dev/rpmsg_ctrlN]. *)

  val open_ : ?index:int -> unit -> t
  (** [open_ ?index ()] opens [/dev/rpmsg_ctrlN] (default [N=0]). *)

  val create_endpoint : t -> name:string -> src:int -> dst:int -> int
  (** [create_endpoint t ~name ~src ~dst] creates an RPMsg endpoint. Returns the
      [/dev/rpmsgN] index. *)

  val destroy_endpoint : t -> name:string -> src:int -> dst:int -> unit
  (** [destroy_endpoint t ~name ~src ~dst] destroys an RPMsg endpoint. *)

  val close : t -> unit
  (** [close t] closes the control device. *)
end

(** {1 Message endpoint} *)

module Endpoint : sig
  type t
  (** An RPMsg endpoint backed by Eio flows. *)

  val max_message_size : int
  (** 496 bytes (typical RPMsg limit: 512 - 16 byte virtio header). *)

  val of_source_sink : source:_ Eio.Flow.source -> sink:_ Eio.Flow.sink -> t
  (** [of_source_sink ~source ~sink] creates an endpoint from Eio flows. *)

  val open_ : int -> Unix.file_descr
  (** [open_ n] opens [/dev/rpmsgN] by index, returning the raw fd. *)

  val recv : t -> max_size:int -> string option
  (** [recv t ~max_size] receives a message. Returns [None] on EOF. *)

  val send : t -> string -> unit
  (** [send t msg] sends a message. *)

  val close : t -> unit
  (** [close t] closes the endpoint. *)
end