gazagnaire.org
RPMsg inter-partition messaging
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Thomas Gazagnaire. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** RPMsg inter-partition messaging.
7
8 Wraps the Linux RPMsg character device interface for message-based IPC
9 between partitions. Used on Jailhouse, Xen, and Zynq UltraScale+ platforms
10 for communication between SpaceOS (Linux) and co-processor partitions via
11 virtio vrings.
12
13 The [rpmsg_endpoint_info] struct layout is described via {!Wire.Codec},
14 avoiding manual C struct packing. On macOS, endpoint creation via {!Ctrl}
15 raises [Failure] (RPMsg does not exist outside Linux). *)
16
17(** {1 Endpoint info wire format} *)
18
19type endpoint_info = { name : string; src : int; dst : int }
20(** Matches Linux kernel [struct rpmsg_endpoint_info]. *)
21
22val endpoint_info_codec : endpoint_info Wire.Codec.t
23(** [endpoint_info_codec] is the wire codec for {!endpoint_info}: name[32],
24 src:u32, dst:u32. *)
25
26val endpoint_info_size : int
27(** [endpoint_info_size] is the wire size of {!endpoint_info} (40 bytes). *)
28
29(** {1 Control device} *)
30
31module Ctrl : sig
32 type t
33 (** A handle to [/dev/rpmsg_ctrlN]. *)
34
35 val open_ : ?index:int -> unit -> t
36 (** [open_ ?index ()] opens [/dev/rpmsg_ctrlN] (default [N=0]). *)
37
38 val create_endpoint : t -> name:string -> src:int -> dst:int -> int
39 (** [create_endpoint t ~name ~src ~dst] creates an RPMsg endpoint. Returns the
40 [/dev/rpmsgN] index. *)
41
42 val destroy_endpoint : t -> name:string -> src:int -> dst:int -> unit
43 (** [destroy_endpoint t ~name ~src ~dst] destroys an RPMsg endpoint. *)
44
45 val close : t -> unit
46 (** [close t] closes the control device. *)
47end
48
49(** {1 Message endpoint} *)
50
51module Endpoint : sig
52 type t
53 (** An RPMsg endpoint backed by Eio flows. *)
54
55 val max_message_size : int
56 (** 496 bytes (typical RPMsg limit: 512 - 16 byte virtio header). *)
57
58 val of_source_sink : source:_ Eio.Flow.source -> sink:_ Eio.Flow.sink -> t
59 (** [of_source_sink ~source ~sink] creates an endpoint from Eio flows. *)
60
61 val open_ : int -> Unix.file_descr
62 (** [open_ n] opens [/dev/rpmsgN] by index, returning the raw fd. *)
63
64 val recv : t -> max_size:int -> string option
65 (** [recv t ~max_size] receives a message. Returns [None] on EOF. *)
66
67 val send : t -> string -> unit
68 (** [send t msg] sends a message. *)
69
70 val close : t -> unit
71 (** [close t] closes the endpoint. *)
72end