1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
.. index::
   pair: library interface; design

.. _design-lib:


Library interface
=================

.. mps:prefix:: design.mps.lib


Introduction
------------

:mps:tag:`intro` This document is the design of the MPS Library Interface, a
part of the plinth.

:mps:tag:`readership` Any MPS developer. Any clients that are prepared to
read this in order to get documentation.


Goals
-----

:mps:tag:`goal` The goals of the MPS library interface are:

:mps:tag:`goal.host` To control the dependency of the MPS on the hosted ISO
C library so that the core MPS remains freestanding (see
design.mps.exec-env).

:mps:tag:`goal.free` To allow the core MPS convenient access to ISO C
functionality that is provided on freestanding platforms (see
design.mps.exec-env.std.com.free).


Description
-----------

Overview
........

:mps:tag:`overview.access` The core MPS needs to access functionality that
could be provided by an ISO C hosted environment.

:mps:tag:`overview.hosted` The core MPS must not make direct use of any
facilities in the hosted environment (design.mps.exec-env). However,
it is sensible to make use of them when the MPS is deployed in a
hosted environment.

:mps:tag:`overview.hosted.indirect` The core MPS does not make any direct
use of hosted ISO C library facilities. Instead, it indirects through
the MPS Library Interface, impl.h.mpslib.

:mps:tag:`overview.free` The core MPS can make direct use of freestanding
ISO C library facilities and does not need to include any of the
header files ``<limits.h>``, ``<stdarg.h>``, and ``<stddef.h>``
directly.

:mps:tag:`overview.complete` The MPS Library Interface can be considered as
the complete "interface to ISO" (in that it provides direct access to
facilities that we get in a freestanding environment and equivalents
of any functionality we require from the hosted environment).

:mps:tag:`overview.provision.client` In a freestanding environment the
client is expected to provide functions meeting this interface to the
MPS.

:mps:tag:`overview.provision.hosted` In a hosted environment,
impl.c.mpsliban may be used. It just maps impl.h.mpslib directly onto
the ISO C library equivalents.

[missing diagram]


Outside the interface
.....................

We provide impl.c.mpsliban to the client, for two reasons:

#. the client can use it to connect the MPS to the ISO C library if it
   exists;

#. as an example implementation of the MPS Library Interface.


Implementation
--------------

:mps:tag:`impl` The MPS Library Interface comprises a header file
impl.h.mpslib and some documentation.

:mps:tag:`impl.decl` The header file defines the interface to definitions
which parallel those parts of the non-freestanding ISO headers which
are used by the MPS.

:mps:tag:`impl.include` The header file also includes the freestanding
headers ``<limits.h>``, ``<stdarg.h>``, and ``<stddef.h>`` (and not
``<float.h>``, though perhaps it should).