### Navigation

- index
- next |
- previous |
- Memory Pool System 1.111.0 documentation »
- Internals »

# 1. 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 conforming 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 a freestanding environment such as an embedded system. 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 enables the MPS to write binary messages to an output stream.
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.

`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.

## 1.1. I/O module

    #include "mpsio.h"

`mps_io_t`

  The type of the internal state of the I/O module.

  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 setting up the I/O module.

  `io_o` points to a location which the plinth may update with a pointer to its internal state, if any.

  Returns `MPS_RES_OK` if successful.

  The MPS calls this function to set up the I/O module, for example if there are events in the telemetry stream that need to be 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 tearing down the I/O module.

  `io` is the value that the plinth wrote to `io_o` when the MPS called `mps_io_create()`. If the plinth wrote no value, this parameter is undefined.

  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 via the I/O module.

  `io` is the value that the plinth wrote to `io_o` when the MPS called `mps_io_create()`. If the plinth wrote no value, this parameter is undefined.

  `buf` points to the data to write.

  `size` is the size of the data in bytes(1).

  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 the I/O module.

  `io` is the value that the plinth wrote to `io_o` when the MPS called `mps_io_create()`. If the plinth wrote no value, this parameter is undefined.

  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`.

## 1.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 and abort.

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

  Note

  In the ANSI Library module, `mpsliban.c`, this reports the failure using `fprintf(stderr, "...%s...", message)` and terminates the program by calling `abort`.

`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`.

### Navigation

- index
- next |
- previous |
- Memory Pool System 1.111.0 documentation »
- Internals »