21. Plinth

The plinth is a program module that provides the MPS with the support it needs from the execution environment. The MPS uses the plinth instead of (say) the Standard C Library because:

1. The MPS is designed to be portable to systems that have only a freestanding implementation of the C language: that is, systems which potentially lack some of the facilities of the Standard C Library, such as standard I/O. The plinth provides a way to map MPS requirements to the facilities provided on the platform, whatever they are.
2. The plinth gives the client program complete control of interaction between the MPS and the user, including assertions and telemetry.

The plinth may be provided by the client program; however, a sample implementation of the plinth using ANSI Standard C Library facilities is included with the MPS, and this is good enough for most applications.

There are many reasons why you might want to write your own plinth. You may be targeting an embedded system with only a freestanding implementation of the C language. You might need to write the telemetry stream to a system logging facility, or transmit it over a serial port or network connection. Or you might need to direct debugging output to a convenient window in the user interface.

The plinth is divided into two parts:

1. The I/O module provides general-purpose I/O functionality. It is used to output a telemetry stream of events to assist with debugging and profiling.
2. The Library module provides miscellaneous functionality that would be available via the Standard C Library on a hosted platform, including functions for reporting errors and accessing a processor clock.

The functions in the plinth module may be called in the context of a signal handler for a protection fault (or equivalent), so they must not access memory that is managed by the MPS, and they need to take into account the restrictions imposed by the operating system. (See “Defining Signal Handlers” in the GNU C Library Reference Manual for useful advice.)

CONFIG_PLINTH_NONE

If this preprocessor constant is defined, exclude the ANSI plinth (mpsioan.c and mpsliban.c) from the MPS. For example:

cc -DCONFIG_PLINTH_NONE -c mps.c        (Unix/OS X)
cl /Gs /DCONFIG_PLINTH_NONE /c mps.c    (Windows)

Having excluded the ANSI plinth, you must of course supply your own.

21.1. I/O module

#include "mpsio.h"

mps_io_t

The type of an I/O stream.

This is an alias for a pointer to the incomplete structure mps_io_s, which the plinth may define if it needs to. Alternatively, it may leave the structure type undefined and simply cast its own pointer to and from mps_io_t.

Note

In the ANSI I/O module, mpsioan.c, this is an alias for FILE *.

mps_res_t mps_io_create(mps_io_t *io_o)

A plinth function for creating an I/O stream for the telemetry stream.

io_o points to a location suitable for storing a pointer to an I/O stream.

If successful, the function must update this location with a suitable pointer for the telemetry stream and return MPS_RES_OK. Otherwise, it must return some other result code.

The MPS calls this function to create the I/O stream for telemetry output. A typical plinth will use it to open a file for writing, or to connect to the system logging interface.

Note

In the ANSI I/O module, mpsioan.c, this calls fopen() on the file named by the environment variable MPS_TELEMETRY_FILENAME.

void mps_io_destroy(mps_io_t io)

A plinth function for destroying an I/O stream.

io is a pointer to the I/O stream to be destroyed. It was previously created by a call to mps_io_create().

After calling this function, the MPS guarantees not to use the value io again.

Note

In the ANSI I/O module, mpsioan.c, this calls fclose().

mps_res_t mps_io_write(mps_io_t io, void *buf, size_t size)

A plinth function for writing data to an I/O stream.

io is the I/O stream.

buf points to the data to write.

size is the size of the data in bytes⁽¹⁾.

Returns MPS_RES_OK if successful.

Note

In the ANSI I/O module, mpsioan.c, this calls fwrite().

mps_res_t mps_io_flush(mps_io_t io)

A plinth function for flushing an I/O stream.

io is the I/O stream.

Returns MPS_RES_OK if successful.

The MPS calls this function when it is done with the telemetry stream, or when the client program calls mps_telemetry_flush(). This function should ensure that the buffers of data passed to the latest calls to mps_io_write() are properly recorded, should the client program terminate (uncontrollably as a result of a bug, for example) or some interactive tool require access to the event data.

Note

In the ANSI I/O module, mpsioan.c, this calls fflush().

21.2. Library module

#include "mpslib.h"

mps_clock_t mps_clock(void)

Return the time since some epoch, in units given by mps_clocks_per_sec().

Note

The ANSI Library module, mpsliban.c, calls clock.

The MPS calls this function to make scheduling decisions (see Scheduling of collections), and to calibrate the time stamps on events in the telemetry stream. If your platform has a low-resolution clock(), and there are higher-resolution clocks readily available, then using one of those will improve MPS scheduling decisions and the quality of telemetry output. For instance, with getrusage():

#include <sys/resource.h>

mps_clock_t mps_clock(void) {
    struct rusage s;
    int res = getrusage(RUSAGE_SELF, &s);
    if (res != 0) {
        /* handle error */
    }
    return ((mps_clock_t)s.ru_utime.tv_sec) * 1000000 + s.ru_utime.tv_usec;
}

mps_clock_t mps_clocks_per_sec(void)

Return the number of clock units per second, as returned by mps_clock().

Note

The ANSI Library module, mpsliban.c, returns CLOCKS_PER_SEC.

void mps_lib_assert_fail(const char *message)

Report an assertion failure.

message is a NUL-terminated string describing the assertion failure.

Note

In the ANSI Library module, mpsliban.c, this reports the failure by calling fprintf(stderr, "...%s...", message), flushes the telemetry stream by calling mps_telemetry_flush(), and, in the cool variety, terminates the program by calling abort(). You can change this behaviour with mps_lib_assert_fail_install(). For a discussion of the default behaviour, see Assertion handling.

Warning

This function must not call any function in MPS, and it must not access memory managed by the MPS.

extern mps_lib_assert_fail_t mps_lib_assert_fail_install(mps_lib_assert_fail_t handler)

This function customises the behaviour of the default assertion handler in the ANSI Library module. It is not otherwise required by the MPS and you need not implement it if you are providing an alternative plinth.

If you’re using the ANSI Library module, you can use this function to change the behaviour of the MPS when an assertion fails. For example, you could terminate the program in the hot variety too. (The MPS test programs do exactly that.)

handler is the assertion handler to install.

Returns the previously installed handler.

Warning

The installed assertion handler must not call any function in MPS, and it must not access memory managed by the MPS.

typedef void (*mps_lib_assert_fail_t)(const char *, unsigned, const char *)

The type of assertion handlers passed to and returned by mps_lib_assert_fail_install().

mps_lib_FILE

The type of output streams provided by the plinth.

Note

In the ANSI Library module, mpsliban.c, this is an alias for FILE *.

int mps_lib_fputc(int c, mps_lib_FILE *stream)

Write a character to an output stream.

c is the character.

stream is the stream.

Return the character written if successful, or mps_lib_get_EOF() if not.

This function is intended to have the same semantics as the fputc() function of the ANSI C Standard (ISO/IEC 9899:1990 §7.11.7.3).

Note

In the ANSI Library module, mpsliban.c, this is a simple wrapper around fputc().

int mps_lib_fputs(const char *s, mps_lib_FILE *stream)

Write a string to an output stream.

s is the NUL-terminated string.

stream is the stream.

This function is intended to have the same semantics as the fputs() function of the ANSI C Standard (ISO/IEC 9899:1990 §7.11.7.4).

Return a non-negative integer if successful, or mps_lib_get_EOF() if not.

Note

In the ANSI Library module, mpsliban.c, this is a simple wrapper around fputs().

int mps_lib_get_EOF(void)

Return the value that is returned from mps_lib_fputc() and mps_lib_fputs() to indicate failure.

Note

In the ANSI Library module, mpsliban.c, this returns EOF.

mps_lib_FILE *mps_lib_get_stderr(void)

Returns an output stream suitable for reporting errors.

Note

In the ANSI Library module, mpsliban.c, this returns stderr.

Note

The MPS does not use this at present, but it may be required in future.

mps_lib_FILE *mps_lib_get_stdout(void)

Returns an output stream suitable for reporting informative output.

Note

In the ANSI Library module, mpsliban.c, this returns stdout.

Note

The MPS does not use this at present, but it may be required in future.

int mps_lib_memcmp(const void *s1, const void *s2, size_t n)

A plinth function similar to the standard C function memcmp().

s1 and s2 point to blocks of memory to be compared.

n is the size of the blocks.

Returns an integer that is greater than, equal to, or less than zero, accordingly as the block pointed to by s1 is greater than, equal to, or less than the block pointed to by s2.

This function is intended to have the same semantics as the memcmp() function of the ANSI C Standard (ISO/IEC 9899:1990 §7.11.4.1).

Note

In the ANSI Library module, mpsliban.c, this is a simple wrapper around memcmp().

void *mps_lib_memcpy(void *dest, const void *source, size_t n)

A plinth function similar to the standard C function memcpy().

dest points to the destination.

source points to the source.

n is the number of bytes to copy from source to dest.

Returns dest.

This function is intended to have the same semantics as the memcpy() function of the ANSI C Standard (ISO/IEC 9899:1990 §7.11.2.1).

The MPS never passes overlapping blocks to mps_lib_memcpy().

Note

In the ANSI Library module, mpsliban.c, this is a simple wrapper around memcpy().

void *mps_lib_memset(void *s, int c, size_t n)

A plinth function similar to the standard C function memset().

s points to the block to fill with the byte c.

c is the byte to fill with (when converted to unsigned char).

n is the size of the block.

Returns s.

This function is intended to have the same semantics as the memset() function of the ANSI C Standard (ISO/IEC 9899:1990 §7.11.6.1).

Note

In the ANSI Library module, mpsliban.c, this is a simple wrapper around memset().

Note

The MPS does not use this at present, but it may be required in future.

unsigned long mps_lib_telemetry_control()

A plinth function to supply a default value for the telemetry filter from the environment. See mps_telemetry_control() for more information on the significant of the value.

Returns the default value of the telemetry filter, as derived from the environment. It is recommended that the environment be consulted for a symbol analogous to MPS_TELEMETRY_CONTROL, subject to local restrictions.

In the absence of environmental data, a default of zero is recommended.

Note

In the ANSI Library module, mpsliban.c, this reads the environment variable MPS_TELEMETRY_CONTROL.