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