Name Date Size #Lines LOC

..--

docs/H--584428

systemd/system/H--2015

tests/H--3,7802,711

utils/H--1,241987

.clang-formatH A D20-Oct-20233.6 KiB119116

.gitignoreH A D06-Sep-2023302 3534

CMakeLists.txtH A D07-Nov-20241.8 KiB6447

LICENSEH A D29-May-201929 KiB548454

Makefile.amH A D07-Nov-20241.6 KiB6246

Makefile.incH A D09-Mar-2021227 106

OWNERSH A D21-Dec-20231.8 KiB5752

README.mdH A D24-Feb-20256.1 KiB169115

alloc.cH A D17-Sep-20242.2 KiB10788

astlpc.cH A D13-Sep-202440.8 KiB1,5481,099

bootstrap.shH A D04-Dec-2022690 3425

compiler.hH A D28-Jun-2022176 106

configure.acH A D06-Oct-20235 KiB167146

container_of.hH A D07-Jan-2025216 107

control.cH A D07-Nov-20247.9 KiB310254

control.hH A D07-Nov-2024303 126

core-internal.hH A D07-Nov-20242.6 KiB13484

core.cH A D13-Jan-202523.8 KiB1,067819

crc-16-ccitt.cH A D18-Apr-20242.7 KiB5842

crc-16-ccitt.hH A D18-Apr-2024323 157

crc32.cH A D09-Mar-2021433 2615

crc32.hH A D09-Mar-2021129 106

i2c-internal.hH A D08-Jan-2025873 4429

i2c.cH A D17-Sep-20245.8 KiB279223

libmctp-alloc.hH A D13-Sep-2024351 179

libmctp-astlpc.hH A D07-Sep-20231.6 KiB5940

libmctp-cmds.hH A D07-Nov-20244.1 KiB143102

libmctp-i2c.hH A D17-Sep-2024978 3219

libmctp-log.hH A D30-Sep-20241 KiB4026

libmctp-serial.hH A D10-Dec-20241.1 KiB4328

libmctp-sizes.h.inH A D17-Sep-2024158 64

libmctp.hH A D13-Jan-20258.7 KiB255122

libmctp.pc.inH A D28-Aug-2019207 119

log.cH A D12-Jan-20201.2 KiB7660

meson.buildH A D01-Feb-20254.6 KiB200173

meson.optionsH A D01-Feb-2025994 3938

range.hH A D11-Dec-2024166 139

serial.cH A D13-Jan-20259.8 KiB426331

README.md

1# libmctp: Implementation of MCTP (DTMF DSP0236)
2
3This library is intended to be a portable implementation of the Management
4Component Transport Protocol (MCTP), as defined by DMTF standard "DSP0236", plus
5transport binding specifications.
6
7## Target usage
8
9`libmctp` is a library that implements a straightforward MCTP stack. It will be
10useful in a two main scenarios:
11
12- where you are implementing MCTP in an embedded device; or
13- where you have Linux system:
14  - with no kernel MCTP support,
15  - need a single application implementing all of the MCTP stack; and
16  - you are providing your own hardware drivers for MCTP transports.
17
18Notably, if you are implementing an MCTP application on Linux, you _almost
19certainly_ want to use the in-kernel MCTP support, which gives you a standard
20sockets-based interface to transmit and receive MCTP messages. When using the
21Linux kernel MCTP support, you do not need to use `libmctp` at all, and can use
22the sockets directly. `libmctp` does not provide functions to interact with the
23kernel MCTP sockets.
24
25There is an overview and example code for the in-kernel support in the [MCTP
26kernel docs][kernel-mctp], and a general guide in an [introduction to MCTP on
27Linux][mctp-linux-intro] document.
28
29[kernel-mctp]: https://docs.kernel.org/networking/mctp.html
30[mctp-linux-intro]:
31  https://codeconstruct.com.au/docs/mctp-on-linux-introduction/
32
33## Contact
34
35- Email: See [OWNERS](OWNERS). Please also Cc <openbmc@lists.ozlabs.org>
36- Discord: #mctp on <https://discord.gg/69Km47zH98>
37- IRC: #openbmc on Freenode
38
39## API/ABI Stability
40
41The APIs and ABI of libmctp are not yet stablised as we continue to explore ways
42to present the MCTP protocol to firmware and applications. Please bear with us!
43
44When we approach a complete implementation of DSP0236 we will consider the
45suitability of the API/ABI for stabilisation.
46
47In the mean time, we'd like your feedback on the library's suitability for your
48environment.
49
50## Core API
51
52To initialise the MCTP stack with a single hardware bus:
53
54- `mctp = mctp_init()`: Initialise the MCTP core
55- `binding = mctp_<binding>_init()`: Initialise a hardware binding
56- `mctp_register_bus(mctp, binding, eid)`: Register the hardware binding with
57  the core, using a predefined EID
58
59Then, register a function call to be invoked when a message is received:
60
61- `mctp_set_rx_all(mctp, function)`: Provide a callback to be invoked when a
62  MCTP message is received
63
64Or transmit a message:
65
66- `mctp_message_tx(mctp, message, len)`: Transmit a MCTP message
67
68The binding may require you to notify it to receive packets. For example, for
69the serial binding, the `mctp_serial_read()` function should be invoked when the
70file-descriptor for the serial device has data available.
71
72### Bridging
73
74libmctp implements basic support for bridging between two hardware bindings. In
75this mode, bindings may have different MTUs, so packets are reassembled into
76their messages, then the messages are re-packetised for the outgoing binding.
77
78For bridging between two endpoints, use the `mctp_bridge_busses()` function:
79
80- `mctp = mctp_init()`: Initialise the MCTP core
81- `b1 = mctp_<binding>_init(); b2 = mctp_<binding>_init()`: Initialise two
82  hardware bindings
83- `mctp_bridge_busses(mctp, b1, b2)`: Setup bridge
84
85Note that no EIDs are defined here; the bridge does not deliver any messages to
86a local rx callback, and messages are bridged as-is.
87
88## Binding API
89
90Hardware bindings provide a method for libmctp to send and receive packets
91to/from hardware. A binding defines a hardware specific structure
92(`struct mctp_binding_<name>`), which wraps the generic binding
93(`struct mctp_binding`):
94
95    struct mctp_binding_foo {
96        struct mctp_binding binding;
97        /* hardware-specific members here... */
98    };
99
100The binding code then provides a method (`_init`) to allocate and initialise the
101binding; this may be of any prototype (calling code will know what arguments to
102pass):
103
104    struct mctp_binding_foo *mctp_binding_foo_init(void);
105
106or maybe the `foo` binding needs a path argument:
107
108    struct mctp_binding_foo *mctp_binding_foo_init(const char *path);
109
110The binding then needs to provide a function (`_core`) to convert the
111hardware-specific struct to the libmctp generic core struct
112
113    struct mctp_binding *mctp_binding_foo_core(struct mctp_binding_foo *b);
114
115(Implementations of this will usually be fairly consistent, just returning
116`b->binding`). Callers can then use that generic pointer to register the binding
117with the core:
118
119    struct mctp_binding *binding = mctp_binding_foo_core(foo);
120    mctp_register_bus(mctp, binding, 8);
121
122## Integration
123
124The libmctp code is intended to be integrated into other codebases by two
125methods:
126
1271. as a simple library (`libmctp.{a,so}`) which can be compiled separately and
128   linked into the containing project
129
1302. as a set of sources to be included into the containing project (either
131   imported, or as a git subtree/submodule)
132
133For (1), you can use the top-level makefile to produce `libmctp.a`.
134
135For (2), the `Makefile.inc` file provides the minimum set of dependencies to
136either build libmctp.a, or just the actual object files (`LIBMCTP_OBS`), which
137you can include into your existing make definitions. You'll want to set
138`LIBMTCP_DIR` to refer to the subdirectory that contains that makefile, so we
139can set the correct paths to sources.
140
141## Environment configuration
142
143This library is intended to be portable to be used in a range of environments,
144but the main targets are:
145
146- Linux userspace, typically for BMC use-cases
147- Low-level firmware environments
148
149For the latter, we need to support customisation of the functions that libmctp
150uses (for example, POSIX file IO is not available).
151
152In order to support these, we have a few compile-time definitions:
153
154- `MCTP_HAVE_FILEIO`: define if POSIX file io is available, allowing the serial
155  hardware binding to access char devices for IO.
156
157- `MCTP_HAVE_SYSLOG`: allow logging to syslog, through the `vsyslog` call.
158
159- `MCTP_DEFAULT_ALLOC`: set default allocator functions (malloc, free, realloc),
160  so that applications do not have to provide their own.
161
162## TODO
163
164- Partial packet queue transmit
165- Control messages
166- Message- and packet-buffer pools and preallocation
167- C++ API
168- Non-file-based serial binding
169