Commit b96142cf authored by Kunshan Wang's avatar Kunshan Wang

Details of automagic relocation.

Only uptr<T> is eligible for "automagic relocation", but both uptr<T>
and ufuncptr<symbol> can use explicit "symbolic relocation".
parent af0bf827
...@@ -1055,11 +1055,11 @@ of creating boot image is not atomic. Both concurrent modifications of the ...@@ -1055,11 +1055,11 @@ of creating boot image is not atomic. Both concurrent modifications of the
memory reachable from the white-listed global cells, and concurrent bundle memory reachable from the white-listed global cells, and concurrent bundle
loading, have undefined behaviours. loading, have undefined behaviours.
Fields of ``uptr<T>`` types are subject to relocation. If the value of a Fields of ``uptr<T>`` types are subject to **automagic relocation**. If the
``uptr<T>`` field happens to be the address of a field of a Mu global cell, the value of a ``uptr<T>`` field happens to be the address of a field of a Mu global
destination will be preserved so that when the boot image is loaded, the cell, the destination will be preserved so that when the boot image is loaded,
``uptr<T>`` field will still point to the same field it pointed to before boot the ``uptr<T>`` field will still point to the same field it pointed to before
image building. Otherwise the content of the ``uptr<T>`` field is intact. boot image building. Otherwise the content of the ``uptr<T>`` field is intact.
``sym_fields`` and ``sym_strings`` are two arrays, and the lengths of both are ``sym_fields`` and ``sym_strings`` are two arrays, and the lengths of both are
``nsyms``. These parameters are reserved and have no effect. ``nsyms``. These parameters are reserved and have no effect.
...@@ -1076,10 +1076,13 @@ image building. Otherwise the content of the ``uptr<T>`` field is intact. ...@@ -1076,10 +1076,13 @@ image building. Otherwise the content of the ``uptr<T>`` field is intact.
``reloc_fields``, ``reloc_strings`` are also two arrays, and the length of both ``reloc_fields``, ``reloc_strings`` are also two arrays, and the length of both
are ``nrelocs``. These two arrays form a list of IRef-string pairs, too. The are ``nrelocs``. These two arrays form a list of IRef-string pairs, too. The
IRef must refer to a field of a global cell or a heap object in the boot image. IRef must refer to a field of a global cell in the boot image. The string is a
The string is a symbol. All fields referred in ``reloc_fields`` must have symbol. All fields referred in ``reloc_fields`` must have pointer types
pointer types (``uptr`` or ``ufuncptr``). At load time, the address of the (``uptr`` or ``ufuncptr``). At load time, the address of the corresponding
corresponding symbol will be stored into the field by the loader. symbol will be stored into the field by the loader. This is called **symbolic
relocation**. It is an error if there are multiple IRefs in the ``reloc_fields``
array for the same field. If a field is eligible for both *automagic relocation*
and *symbolic relocation*, then *symbolic relocation* will take precedence.
NOTE: The system's native loader may have more features than this API, such NOTE: The system's native loader may have more features than this API, such
as adding numbers to a field rather than simply assigning them. This API is as adding numbers to a field rather than simply assigning them. This API is
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment