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