| commit | 5b2702db20f7bf2ff694b0a10680fc1de8c793e4 | [log] [tgz] |
|---|---|---|
| author | Andrew Jeffery <andrew@aj.id.au> | Mon Jul 25 16:21:43 2022 +0930 |
| committer | Andrew Jeffery <andrew@aj.id.au> | Mon Aug 08 07:01:00 2022 +0000 |
| tree | 1b3f50194527c2f0695245f33560c43d1b92a0bb | |
| parent | 59521c7f7e24f9757e53e357e1d84dba805e5169 [diff] |
astlpc: Fix up FILEIO function definitions The functions have no business being marked as const due to the logging. The GCC manual has this to say: > Calls to functions whose return value is not affected by changes to > the observable state of the program and that have no observable > effects on such state other than to return a value may lend themselves > to optimizations such as common subexpression elimination. Declaring > such functions with the const attribute allows GCC to avoid emitting > some calls in repeated invocations of the function with the same > argument values. > > For example, > > int square (int) __attribute__ ((const)); > > tells GCC that subsequent calls to function square with the same > argument value can be replaced by the result of the first call > regardless of the statements in between. > > The const attribute prohibits a function from reading objects that > affect its return value between successive invocations. However, > functions declared with the attribute can safely read objects that do > not change their return value, such as non-volatile constants. > > The const attribute imposes greater restrictions on a function’s > definition than the similar pure attribute. Declaring the same > function with both the const and the pure attribute is diagnosed. > Because a const function cannot have any observable side effects it > does not make sense for it to return void. Declaring such a function > is diagnosed. > > Note that a function that has pointer arguments and examines the data > pointed to must not be declared const if the pointed-to data might > change between successive invocations of the function. In general, > since a function cannot distinguish data that might change from data > that cannot, const functions should never take pointer or, in C++, > reference arguments. Likewise, a function that calls a non-const > function usually must not be const itself. https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes Further, the logging was broken as there was no valid astlpc object in the case of mctp_astlpc_init_fileio(), and any such instance passed to mctp_astlp_get_fd() would be invalid. Switch the logging to use mctp_prlog() instead. Signed-off-by: Andrew Jeffery <andrew@aj.id.au> Change-Id: Ic27ff76a7f5577004f53fb236d397b03fa55ec4a
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.
The APIs and ABI of libmctp are not yet stablised as we continue to explore ways to present the MCTP protocol to firmware and applications. Please bear with us!
When we approach a complete implementation of DSP0236 we will consider the suitability of the API/ABI for stabilisation.
In the mean time, we'd like your feedback on the library's suitability for your environment.
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 libmctp.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.