| commit | 3a540664c5fbf8cabeca0c1a1af27b1b979eb253 | [log] [tgz] |
|---|---|---|
| author | Andrew Jeffery <andrew@aj.id.au> | Tue May 26 19:55:30 2020 +0930 |
| committer | Andrew Jeffery <andrew@aj.id.au> | Fri Jun 12 10:37:23 2020 +0930 |
| tree | 8a0541fff464818da091d18048739ebc2c44290b | |
| parent | 4e8264b705d3575bea8312d6467d5fd9fb440caf [diff] |
astlpc: Introduce MTU negotiation MTU negotiation is implemented in a backwards-compatible manner with version 1 of the astlpc binding. Functionally, MTU negotation involves proposing arrangements of the Rx and Tx buffer layouts. It is assumed that the MTU is a packet sized to fill the Tx buffer as described in the control space. For v1 of the binding the MTU is defined in terms of the MCTP_BTU constant provided by libmctp.h. MCTP_BTU is used regardless of the buffer sizes specified in the control space (which MUST describe buffers supporting at least MCTP_BTU-sized packets). For v2 of the binding the MTU is defined in terms of the appropriate buffer's size field in the control space. The sequence of events for negotiating the MTU under v2 is as follows: 1. The BMC initialises its binding, filling out the Rx and Tx buffer properties with the largest configuration it supports. 2. The host initialises its binding, writing its maximum Rx buffer size before sending `channel-init` to the BMC. 3. The BMC receives `channel-init`, negotiates protocol version 2 and then validates the host's proposed buffer configuration. If the proposed configuration is invalid (e.g. out-of-bounds values) the BMC terminates channel initialisation leaving the channel-active bit clear and writing the zero to the negotiated version field. If the proposal is valid, the BMC calculates the buffer sizes according to the available constraints and writes the chosen buffer configuration to the control region. 4. Assuming the version negotiation and buffer configuration are successful, the BMC sets `channel-active` and notifies the host 5. The host reads `channel-active`, accepts the negotiation of v2 and validates the buffer configuration. If the validation passes, then the buffer configuration is the configuration used for the remainder of the session. If validation fails then the host MUST NOT send MCTP packets via the LPC binding until a valid buffer configuration can be negotiated. Change-Id: I89107593f220418d746c2d73771348ed8f7f3e87 Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
This library is intended to be a portable implementation of the Management Component Transport Protocol (MCTP), as defined by DMTF standard "DSP0236", plus transport binding specifications.
Currently, the library is is only at prototyping stage. Interfaces will likely change, and are missing lots of components of the standard.
To initialise the MCTP stack with a single hardware bus:
mctp = mctp_init(): Initialise the MCTP corebinding = mctp_<binding>_init(): Initialise a hardware bindingmctp_register_bus(mctp, binding, eid): Register the hardware binding with the core, using a predefined EIDThen, register a function call to be invoked when a message is received:
mctp_set_rx_all(mctp, function): Provide a callback to be invoked when a MCTP message is receivedOr transmit a message:
mctp_message_tx(mctp, message, len): Transmit a MCTP messageThe binding may require you to notify it to receive packets. For example, for the serial binding, the mctp_serial_read() function should be invoked when the file-descriptor for the serial device has data available.
libmctp implements basic support for bridging between two hardware bindings. In this mode, bindings may have different MTUs, so packets are reassembled into their messages, then the messages are re-packetised for the outgoing binding.
For bridging between two endpoints, use the mctp_bridge_busses() function:
mctp = mctp_init(): Initialise the MCTP coreb1 = mctp_<binding>_init(); b2 = mctp_<binding>_init(): Initialise two hardware bindingsmctp_bridge_busses(mctp, b1, b2): Setup bridgeNote that no EIDs are defined here; the bridge does not deliver any messages to a local rx callback, and messages are bridged as-is.
Hardware bindings provide a method for libmctp to send and receive packets to/from hardware. A binding defines a hardware specific structure (struct mctp_binding_<name>), which wraps the generic binding (struct mctp_binding):
struct mctp_binding_foo {
struct mctp_binding binding;
/* hardware-specific members here... */
};
The binding code then provides a method (_init) to allocate and initialise the binding; this may be of any prototype (calling code will know what arguments to pass):
struct mctp_binding_foo *mctp_binding_foo_init(void);
or maybe the foo binding needs a path argument:
struct mctp_binding_foo *mctp_binding_foo_init(const char *path);
The binding then needs to provide a function (_core) to convert the hardware-specific struct to the libmctp generic core struct
struct mctp_binding *mctp_binding_foo_core(struct mctp_binding_foo *b);
(Implementations of this will usually be fairly consistent, just returning b->binding). Callers can then use that generic pointer to register the binding with the core:
struct mctp_binding *binding = mctp_binding_foo_core(foo); mctp_register_bus(mctp, binding, 8);
The libmctp code is intended to be integrated into other codebases by two methods:
as a simple library (libmctp.{a,so}) which can be compiled separately and linked into the containing project
as a set of sources to be included into the containing project (either imported, or as a git subtree/submodule)
For (1), you can use the top-level makefile to produce libmtcp.a.
For (2), the Makefile.inc file provides the minimum set of dependencies to either build libmctp.a, or just the actual object files (LIBMCTP_OBS), which you can include into your existing make definitions. You'll want to set LIBMTCP_DIR to refer to the subdirectory that contains that makefile, so we can set the correct paths to sources.
This library is intended to be portable to be used in a range of environments, but the main targets are:
For the latter, we need to support customisation of the functions that libmctp uses (for example, POSIX file IO is not available).
In order to support these, we have a few compile-time definitions:
MCTP_HAVE_FILEIO: define if POSIX file io is available, allowing the serial hardware binding to access char devices for IO.
MCTP_HAVE_SYSLOG: allow logging to syslog, through the vsyslog call.
MCTP_DEFAULT_ALLOC: set default allocator functions (malloc, free, realloc), so that applications do not have to provide their own.