xref: /openbmc/libmctp/README.md (revision e62b4257)
1libmctp: Implementation of MCTP (DTMF DSP0236)
2==============================================
3
4This library is intended to be a portable implementation of the Management
5Component Transport Protocol (MCTP), as defined by DMTF standard "DSP0236",
6plus transport binding specifications.
7
8Currently, the library is is only at prototyping stage. Interfaces will likely
9change, and are missing lots of components of the standard.
10
11Core API
12--------
13
14To initialise the MCTP stack with a single hardware bus:
15
16 * `mctp = mctp_init()`: Initialise the MCTP core
17 * `binding = mctp_<binding>_init()`: Initialise a hardware binding
18 * `mctp_register_bus(mctp, binding, eid)`: Register the hardware binding with
19   the core, using a predefined EID
20
21Then, register a function call to be invoked when a message is received:
22
23 * `mctp_set_rx_all(mctp, function)`: Provide a callback to be invoked when a
24   MCTP message is received
25
26Or transmit a message:
27
28 * `mctp_message_tx(mctp, message, len)`: Transmit a MCTP message
29
30The binding may require you to notify it to receive packets. For example,
31for the serial binding, the `mctp_serial_read()` function should be invoked
32when the file-descriptor for the serial device has data available.
33
34### Bridging
35
36libmctp implements basic support for bridging between two hardware bindings.
37In this mode, bindings may have different MTUs, so packets are reassembled into
38their messages, then the messages are re-packetised for the outgoing binding.
39
40For bridging between two endpoints, use the `mctp_bridge_busses()` function:
41
42 * `mctp = mctp_init()`: Initialise the MCTP core
43 * `b1 = mctp_<binding>_init(); b2 = mctp_<binding>_init()`: Initialise two hardware bindings
44 * `mctp_bridge_busses(mctp, b1, b2)`: Setup bridge
45
46Note that no EIDs are defined here; the bridge does not deliver any messages
47to a local rx callback, and messages are bridged as-is.
48
49Binding API
50-----------
51
52Hardware bindings provide a method for libmctp to send and receive packets
53to/from hardware. A binding defines a hardware specific structure (`struct
54mctp_binding_<name>`), which wraps the generic binding (`struct mctp_binding`):
55
56    struct mctp_binding_foo {
57	    struct mctp_binding binding;
58	    /* hardware-specific members here... */
59    };
60
61The binding code then provides a method (`_init`) to allocate and initialise
62the binding; this may be of any prototype (calling code will know what
63arguments to pass):
64
65    struct mctp_binding_foo *mctp_binding_foo_init(void);
66
67or maybe the `foo` binding needs a path argument:
68
69    struct mctp_binding_foo *mctp_binding_foo_init(const char *path);
70
71The binding then needs to provide a function (`_core`) to convert the
72hardware-specific struct to the libmctp generic core struct
73
74    struct mctp_binding *mctp_binding_foo_core(struct mctp_binding_foo *b);
75
76(Implementations of this will usually be fairly consistent, just returning
77`b->binding`). Callers can then use that generic pointer to register the
78binding with the core:
79
80    struct mctp_binding *binding = mctp_binding_foo_core(foo);
81    mctp_register_bus(mctp, binding, 8);
82
83
84Integration
85-----------
86
87The libmctp code is intended to be integrated into other codebases by two
88methods:
89
90 1. as a simple library (`libmctp.{a,so}`) which can be compiled separately
91    and linked into the containing project
92
93 2. as a set of sources to be included into the containing project (either
94    imported, or as a git subtree/submodule)
95
96For (1), you can use the top-level makefile to produce `libmtcp.a`.
97
98For (2), the `Makefile.inc` file provides the minimum set of dependencies to
99either build libmctp.a, or just the actual object files (`LIBMCTP_OBS`), which
100you can include into your existing make definitions.  You'll want to set
101`LIBMTCP_DIR` to refer to the subdirectory that contains that makefile, so we
102can set the correct paths to sources.
103
104
105Environment configuration
106-------------------------
107
108This library is intended to be portable to be used in a range of environments,
109but the main targets are:
110
111  - Linux userspace, typically for BMC use-cases
112  - Low-level firmware environments
113
114For the latter, we need to support customisation of the functions that libmctp
115uses (for example, POSIX file IO is not available).
116
117In order to support these, we have a few compile-time definitions:
118
119 - `MCTP_HAVE_FILEIO`: define if POSIX file io is available, allowing the
120   serial hardware binding to access char devices for IO.
121
122 - `MCTP_HAVE_SYSLOG`: allow logging to syslog, through the `vsyslog`
123   call.
124
125 - `MCTP_DEFAULT_ALLOC`: set default allocator functions (malloc, free,
126   realloc), so that applications do not have to provide their own.
127
128TODO
129----
130
131 - Partial packet queue transmit
132 - Control messages
133 - Message- and packet-buffer pools and preallocation
134 - C++ API
135 - Non-file-based serial binding
136