mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-04-27 08:43:40 -07:00
Add design.mps.exec-env from //info.ravenbrook.com/project/mps/import/2001-09-27/mminfo/doc/design/mps/exec-env/index.txt and bring it up to date; move design.mps.writef from old to current.
Copied from Perforce Change: 187693 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees
parent
fb7794dd06
commit
89d1e01915
7 changed files with 230 additions and 30 deletions
189
mps/design/exec-env.txt
Normal file
189
mps/design/exec-env.txt
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
.. mode: -*- rst -*-
|
||||
|
||||
Execution environment
|
||||
=====================
|
||||
|
||||
:Tag: design.mps.exec-env
|
||||
:Author: Richard Brooksby
|
||||
:Date: 1996-08-30
|
||||
:Status: incomplete design
|
||||
:Revision: $Id$
|
||||
:Copyright: See section `Copyright and License`_.
|
||||
:Index terms: pair: execution; environment
|
||||
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
_`.intro`: This document describes how the MPS is designed to work in
|
||||
different execution environments (see standard.ansic section 5.1.2).
|
||||
|
||||
|
||||
Discussion
|
||||
----------
|
||||
|
||||
_`.std`: These are the relevant statements from the International
|
||||
Standard ISO/IEC 9899:1990 "Programming languages — C", with tags
|
||||
added:
|
||||
|
||||
4. Compliance
|
||||
|
||||
[…]
|
||||
|
||||
_`.std.com.hosted`: A "conforming hosted implementation" shall
|
||||
accept any strictly conforming program. _`.std.com.free`: A
|
||||
"conforming freestanding implementation" shall accept any strictly
|
||||
conforming program in which the use of the features specified in
|
||||
the library clause (clause 7) is confined to the contents of the
|
||||
standard headers ``<float.h>``, ``<limits.h>``, ``<stdarg.h>``,
|
||||
and ``<stddef.h>``. A conforming implementation may have
|
||||
extensions (including additional library functions), provided they
|
||||
do not alter the behaviour of any strictly conforming program.
|
||||
|
||||
[…]
|
||||
|
||||
5.1.2 Execution environments
|
||||
|
||||
_`.std.def`: Two execution environments are defined:
|
||||
"freestanding" and "hosted". […]
|
||||
|
||||
_`.std.init`: All objects in static storage shall be "initialized"
|
||||
(set to their initial values) before program startup. The manner
|
||||
and timing of such initialization are otherwise unspecified. […]
|
||||
|
||||
_`.std.term`: "Program termination" returns control to the execution
|
||||
environment. […]
|
||||
|
||||
5.1.2.1 Freestanding environment
|
||||
|
||||
_`.std.free.lib`: Any library facilities available to a
|
||||
freestanding environment are implementation-defined.
|
||||
|
||||
_`.std.free.term`: The effect of program termination in a
|
||||
free-standing environment is implementation-defined.
|
||||
|
||||
|
||||
Interpretation
|
||||
--------------
|
||||
|
||||
_`.int.free`: We interpret the "freestanding environment" as being the
|
||||
sort of environment you'd expect in an embedded system. The classic
|
||||
example is a washing machine. There are no library facilities
|
||||
available, only language facilities.
|
||||
|
||||
_`.int.free.lib`: We assume that the headers ``<float.h>``,
|
||||
``<limits.h>``, ``<stdarg.h>`` and ``<stddef.h>`` are available in the
|
||||
freestanding environment, because they define only language features
|
||||
and not library calls. We assume that we may not make use of any other
|
||||
definitions if freestanding parts of the system.
|
||||
|
||||
_`.int.free.term`: We may not terminate the program in a freestanding
|
||||
environment, and therefore we may not call :c:func:`abort`. We can't
|
||||
call :c:func:`abort` anyway, because it's not defined in the headers
|
||||
listed above (`.int.free.lib`_).
|
||||
|
||||
_`.int.free.term.own`: We can add an interface for asserting, that is,
|
||||
reporting an error and not returning, for use in debugging builds
|
||||
only. This is because the environment can implement this in a way that
|
||||
does not return to the MPS, but doesn't terminate, either. We need
|
||||
this if debugging builds are to run in a (possibly simulated or
|
||||
emulated) freestanding environment at all.
|
||||
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
_`.req`: It should be possible to make use of the MPS in a
|
||||
freestanding environment such as an embedded controller.
|
||||
|
||||
_`.req.conf`: There can be configurations of the MPS that are not
|
||||
freestanding (such as using a VM arena).
|
||||
|
||||
|
||||
Architecture
|
||||
------------
|
||||
|
||||
_`.arch`: Like Gaul, the MPS is divided into three parts: the *core*,
|
||||
the *platform*, and the *plinth*.
|
||||
|
||||
_`.arch.core`: The *core* consists of the Memory Pool Manager (the
|
||||
core data structures and algorithms) and the built-in Pool Classes.
|
||||
The core must be freestanding.
|
||||
|
||||
_`.arch.platform`: The *platform* provides the core with interfaces to
|
||||
features of the operating system and processor (locks, memory
|
||||
protection, protection mutator context, stack probing, stack and
|
||||
register scanning, thread management, and virtual memory). The
|
||||
platform is specialized to a particular environment and so can safely
|
||||
use whatever features are available in that environment.
|
||||
|
||||
_`.arch.plinth`: The *plinth* provides the core with interfaces to
|
||||
features of the user environment (time, assertions, and logging). See
|
||||
design.mps.io_ and design.mps.lib_.
|
||||
|
||||
.. _design.mps.io: io
|
||||
.. _design.mps.lib: lib
|
||||
|
||||
_`.arch.distinction`: The distinction between *plinth* and *platform*
|
||||
is that end users will need to customize the features provided by the
|
||||
plinth for most programs that use the MPS (and so the interface needs
|
||||
to be simple, documented and supported), whereas implementing the
|
||||
platform interface is a specialized task that will typically be done
|
||||
once for each platform and then maintained alongside the core.
|
||||
|
||||
|
||||
Document History
|
||||
----------------
|
||||
|
||||
- 1996-08-30 RB_ Created to clarify concepts needed for
|
||||
design.mps.io_.
|
||||
|
||||
- 2015-02-06 GDR_ Converted to reStructuredText; bring the
|
||||
architecture description up to date by describing the platform
|
||||
interface.
|
||||
|
||||
.. _RB: http://www.ravenbrook.com/consultants/rb/
|
||||
.. _GDR: http://www.ravenbrook.com/consultants/gdr/
|
||||
|
||||
|
||||
Copyright and License
|
||||
---------------------
|
||||
|
||||
Copyright © 1996-2014 Ravenbrook Limited. All rights reserved.
|
||||
<http://www.ravenbrook.com/>. This is an open source license. Contact
|
||||
Ravenbrook for commercial licensing options.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are
|
||||
met:
|
||||
|
||||
#. Redistributions of source code must retain the above copyright
|
||||
notice, this list of conditions and the following disclaimer.
|
||||
|
||||
#. Redistributions in binary form must reproduce the above copyright
|
||||
notice, this list of conditions and the following disclaimer in the
|
||||
documentation and/or other materials provided with the distribution.
|
||||
|
||||
#. Redistributions in any form must be accompanied by information on how
|
||||
to obtain complete source code for this software and any
|
||||
accompanying software that uses this software. The source code must
|
||||
either be included in the distribution or be available for no more than
|
||||
the cost of distribution plus a nominal fee, and must be freely
|
||||
redistributable under reasonable conditions. For an executable file,
|
||||
complete source code means the source code for all modules it contains.
|
||||
It does not include source code for modules or files that typically
|
||||
accompany the major components of the operating system on which the
|
||||
executable file runs.
|
||||
|
||||
**This software is provided by the copyright holders and contributors
|
||||
"as is" and any express or implied warranties, including, but not
|
||||
limited to, the implied warranties of merchantability, fitness for a
|
||||
particular purpose, or non-infringement, are disclaimed. In no event
|
||||
shall the copyright holders and contributors be liable for any direct,
|
||||
indirect, incidental, special, exemplary, or consequential damages
|
||||
(including, but not limited to, procurement of substitute goods or
|
||||
services; loss of use, data, or profits; or business interruption)
|
||||
however caused and on any theory of liability, whether in contract,
|
||||
strict liability, or tort (including negligence or otherwise) arising in
|
||||
any way out of the use of this software, even if advised of the
|
||||
possibility of such damage.**
|
||||
|
|
@ -53,6 +53,7 @@ collection_ Collection framework
|
|||
config_ MPS configuration
|
||||
critical-path_ The critical path through the MPS
|
||||
diag_ Diagnostic feedback
|
||||
exec-env_ Execution environment
|
||||
failover_ Fail-over allocator
|
||||
finalize_ Finalization
|
||||
fix_ The generic fix function
|
||||
|
|
@ -129,6 +130,7 @@ writef_ The WriteF function
|
|||
.. _config: config
|
||||
.. _critical-path: critical-path
|
||||
.. _diag: diag
|
||||
.. _exec-env: exec-env
|
||||
.. _failover: failover
|
||||
.. _finalize: finalize
|
||||
.. _fix: fix
|
||||
|
|
@ -231,7 +233,7 @@ Document History
|
|||
Copyright and License
|
||||
---------------------
|
||||
|
||||
Copyright © 2002-2014 Ravenbrook Limited. All rights reserved.
|
||||
Copyright © 2002-2015 Ravenbrook Limited. All rights reserved.
|
||||
<http://www.ravenbrook.com/>. This is an open source license. Contact
|
||||
Ravenbrook for commercial licensing options.
|
||||
|
||||
|
|
|
|||
|
|
@ -95,17 +95,19 @@ which the MPM sends and receives "messages" to and from the hosted I/O
|
|||
module.
|
||||
|
||||
_`.arch.module`: The modules are part of the MPS but not part of the
|
||||
freestanding core system (see design.mps.exec-env). The I/O module is
|
||||
freestanding core system (see design.mps.exec-env_). The I/O module is
|
||||
responsible for transmitting those messages to the external tools, and
|
||||
for receiving messages from external tools and passing them to the
|
||||
MPM.
|
||||
|
||||
.. _design.mps.exec-env: exec-env
|
||||
|
||||
_`.arch.module.example`: For example, the "file implementation" might
|
||||
just send/write telemetry messages into a file so that they can be
|
||||
received/read later by an off-line measurement tool.
|
||||
|
||||
_`.arch.external`: The I/O Interface is part of interface to the
|
||||
freestanding core system (see design.mps.exec-env). This is so that
|
||||
freestanding core system (see design.mps.exec-env_). This is so that
|
||||
the MPS can be deployed in a freestanding environment, with a special
|
||||
I/O module. For example, if the MPS is used in a washing machine the
|
||||
I/O module could communicate by writing output to the seven-segment
|
||||
|
|
@ -429,7 +431,7 @@ Document History
|
|||
Copyright and License
|
||||
---------------------
|
||||
|
||||
Copyright © 2013-2014 Ravenbrook Limited. All rights reserved.
|
||||
Copyright © 2013-2015 Ravenbrook Limited. All rights reserved.
|
||||
<http://www.ravenbrook.com/>. This is an open source license. Contact
|
||||
Ravenbrook for commercial licensing options.
|
||||
|
||||
|
|
|
|||
|
|
@ -29,11 +29,13 @@ _`.goal`: The goals of the MPS library interface are:
|
|||
|
||||
_`.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).
|
||||
design.mps.exec-env_).
|
||||
|
||||
.. _design.mps.exec-env: exec-env
|
||||
|
||||
_`.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).
|
||||
design.mps.exec-env_).
|
||||
|
||||
|
||||
Description
|
||||
|
|
@ -46,7 +48,7 @@ _`.overview.access`: The core MPS needs to access functionality that
|
|||
could be provided by an ISO C hosted environment.
|
||||
|
||||
_`.overview.hosted`: The core MPS must not make direct use of any
|
||||
facilities in the hosted environment (design.mps.exec-env). However,
|
||||
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.
|
||||
|
||||
|
|
@ -93,7 +95,7 @@ Document History
|
|||
Copyright and License
|
||||
---------------------
|
||||
|
||||
Copyright © 2013-2014 Ravenbrook Limited. All rights reserved.
|
||||
Copyright © 2013-2015 Ravenbrook Limited. All rights reserved.
|
||||
<http://www.ravenbrook.com/>. This is an open source license. Contact
|
||||
Ravenbrook for commercial licensing options.
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ The WriteF function
|
|||
:Tag: design.mps.writef
|
||||
:Author: Richard Brooksby
|
||||
:Date: 1996-10-18
|
||||
:Status: incomplete design
|
||||
:Status: complete design
|
||||
:Revision: $Id$
|
||||
:Copyright: See `Copyright and License`_.
|
||||
:Index terms: pair: WriteF function; design
|
||||
|
|
@ -16,11 +16,13 @@ Introduction
|
|||
------------
|
||||
|
||||
_`.intro`: This document describes the ``WriteF()`` function, which
|
||||
allows formatted output in a manner similar to ANSI C ``printf``, but
|
||||
allows the MPM to operate in a freestanding environment (see
|
||||
design.mps.exec-env).
|
||||
allows formatted output in a manner similar to ``printf()`` from the
|
||||
Standard C library, but allows the Memory Pool Manager (MPM) to
|
||||
operate in a freestanding environment (see design.mps.exec-env_).
|
||||
|
||||
_`.background`: The documents design.mps.exec-env and design.mps.lib_
|
||||
.. _design.mps.exec-env: exec-env
|
||||
|
||||
_`.background`: The documents design.mps.exec-env_ and design.mps.lib_
|
||||
describe the design of the library interface and the reason that it
|
||||
exists.
|
||||
|
||||
|
|
@ -31,10 +33,10 @@ Design
|
|||
------
|
||||
|
||||
_`.no-printf`: There is no dependency on ``printf()``. The MPM only
|
||||
depends on ``fputc()`` and ``fputs()``, via the Library Interface
|
||||
(design.mps.lib_). This makes it much easier to deploy the MPS in a
|
||||
freestanding environment. This is achieved by implementing our own
|
||||
internal output routines in mpm.c.
|
||||
depends on ``mps_io_fputc()`` and ``mps_io_fputs()``, via the library
|
||||
interface (design.mps.lib_), part of the *plinth*. This makes it much
|
||||
easier to deploy the MPS in a freestanding environment. This is
|
||||
achieved by implementing our own output routines.
|
||||
|
||||
_`.writef`: Our output requirements are few, so the code is short. The
|
||||
only output function which should be used in the rest of the MPM is
|
||||
|
|
@ -42,9 +44,9 @@ only output function which should be used in the rest of the MPM is
|
|||
|
||||
``Res WriteF(mps_lib_FILE *stream, Count depth, ...)``
|
||||
|
||||
If ``depth`` is greater than zero, then the first format character,
|
||||
and each format character after a newline, is preceded by ``depth``
|
||||
spaces.
|
||||
If ``depth`` is greater than zero, then the first output character,
|
||||
and each output character after a newline in a format string, is
|
||||
preceded by ``depth`` spaces.
|
||||
|
||||
``WriteF()`` expects a format string followed by zero or more items to
|
||||
insert into the output, followed by another format string, more items,
|
||||
|
|
@ -54,7 +56,8 @@ and so on, and finally a ``NULL`` format string. For example::
|
|||
"Hello: $A\n", (WriteFA)address,
|
||||
"Spong: $U ($S)\n", (WriteFU)number, (WriteFS)string,
|
||||
NULL);
|
||||
if (res != ResOK) return res;
|
||||
if (res != ResOK)
|
||||
return res;
|
||||
|
||||
This makes ``Describe()`` methods much easier to write. For example, ``BufferDescribe()`` contains the following code::
|
||||
|
||||
|
|
@ -83,14 +86,15 @@ This makes ``Describe()`` methods much easier to write. For example, ``BufferDes
|
|||
" alignment $W\n", (WriteFW)buffer->alignment,
|
||||
" rampCount $U\n", (WriteFU)buffer->rampCount,
|
||||
NULL);
|
||||
if (res != ResOK) return res;
|
||||
if (res != ResOK)
|
||||
return res;
|
||||
|
||||
_`.types`: For each format ``$X`` that ``WriteF()`` supports, there is a
|
||||
type defined in impl.h.mpmtypes ``WriteFX()`` which is the promoted
|
||||
version of that type. These are provided both to ensure promotion and
|
||||
to avoid any confusion about what type should be used in a cast. It is
|
||||
easy to check the casts against the formats to ensure that they
|
||||
correspond.
|
||||
_`.types`: For each format ``$X`` that ``WriteF()`` supports, there is
|
||||
a type ``WriteFX`` defined in mpmtypes.h, which is the promoted
|
||||
version of that type. These types are provided both to ensure
|
||||
promotion and to avoid any confusion about what type should be used in
|
||||
a cast. It is easy to check the casts against the formats to ensure
|
||||
that they correspond.
|
||||
|
||||
_`.types.cast`: Every argument to ``WriteF()`` must be cast, because
|
||||
in variable-length argument lists the "default argument promotion"
|
||||
|
|
@ -154,7 +158,7 @@ Document History
|
|||
Copyright and License
|
||||
---------------------
|
||||
|
||||
Copyright © 2013-2014 Ravenbrook Limited. All rights reserved.
|
||||
Copyright © 2013-2015 Ravenbrook Limited. All rights reserved.
|
||||
<http://www.ravenbrook.com/>. This is an open source license. Contact
|
||||
Ravenbrook for commercial licensing options.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@ Design
|
|||
cbs
|
||||
config
|
||||
critical-path
|
||||
exec-env
|
||||
failover
|
||||
freelist
|
||||
guide.hex.trans
|
||||
|
|
@ -33,3 +34,4 @@ Design
|
|||
thread-manager
|
||||
type
|
||||
vm
|
||||
writef
|
||||
|
|
|
|||
|
|
@ -60,4 +60,3 @@ Old design
|
|||
version
|
||||
vmo1
|
||||
vmso
|
||||
writef
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue