All Manuals > LispWorks® User Guide and Reference Manual > 27 LispWorks' Operating Environment

27.6 Startup relocation

On startup, LispWorks normally maps its heap at the address where it was mapped when the image was saved. It maps more memory close to this when needed. This may cause memory clashes with other software, but such clashes may be avoided by relocating LispWorks.

32-bit LispWorks is relocatable on Microsoft Windows, Linux, x86/x64 Solaris and FreeBSD. 64-bit LispWorks is relocatable on all supported platforms. The discussion in this section is applicable to all relocatable implementations.

On Microsoft Windows and Macintosh, LispWorks detects memory clashes and avoids them automatically. On these platforms there is no need to explicitly relocate LispWorks. The other relocatable implementations - LispWorks (32-bit) for Linux, LispWorks (64-bit) for Linux, LispWorks (32-bit) for FreeBSD, LispWorks (64-bit) for FreeBSD, LispWorks (32-bit) for x86/x64 Solaris, LispWorks (64-bit) for x86/x64 Solaris - cannot safely detect memory clashes. Relocation may therefore be useful in these implementations.

27.6.1 How to relocate LispWorks

Relocate LispWorks by passing two parameters: the base address and the reserve amount. Both are optional. The interpretation of these parameters is very different between 64-bit LispWorks and 32-bit LispWorks.

To relocate a LispWorks executable, pass one or both of these command line arguments:

--relocate-image BaseAddress

The base address, interpreted as a hexadecimal number by calling:

--reserve-size ReserveSize

The reserve size, interpreted as a hexadecimal number by calling:


On all relocatable platforms, a LispWorks dynamic library or Windows DLL can be relocated by calling InitLispWorks with second and/or third argument non-zero.

On non-Windows platforms, you can add the appropriate call to InitLispWorks in wrappers written in C and added to the dynamic library by passing dll-added-files to save-image or deliver. There is no such option in LispWorks for Windows.

The startup relocation takes some time, normally less than 0.1 seconds on a modern machine. If the relocation address is fixed and known, this startup overhead can be eliminated by relocating the image before calling save-image or deliver.

27.6.2 Startup relocation of 32-bit LispWorks

32-bit LispWorks on x86 platforms maps its heap in one continuous block, and then grows upwards from the top. When it reaches a region that it cannot use, it can skip it. On Windows and Macintosh this skipping is safe, because LispWorks can safely detect regions of memory that it cannot use. On other x86 platforms, both the initial mapping and the further growth cannot safely detect when they overwrite some other code.

BaseAddress (passed on command line with --relocate-image or as the second argument to InitLispWorks) tells LispWorks where to map the heap. On Windows and Macintosh, if the address is already used the heap will be mapped elsewhere. On other platforms, the mapping always works, and may destroy what is already mapped at that address.

ReserveSize (passed on command line with --reserve-size or as the third argument to InitLispWorks) tells LispWorks how much additional memory to reserve. Reservation is properly supported on Windows and Macintosh, though the actual reserved size can be smaller if it fails to reserve as much as was requested. On platforms that do not support reservation (that is, not Windows or Macintosh), the reservation is done by using mmap with protection PROT_NONE.

For a description of the memory layout on each platform, see 11.3.5 Memory layout.

27.6.3 Startup relocation of 64-bit LispWorks

The size of address space that 64-bit LispWorks can use is limited by the size of internal tables to a "span" of 2^44 (16TB). The span always starts at 0.

Inside this span LispWorks can use any address. However, to avoid clashes with other software, it uses memory only in some defined range.

Startup relocation means changing this range. BaseAddress (passed on command line with --relocate-image or as the second argument to InitLispWorks, rounded up to 2^28) is the start of the range. ReserveSize (passed on command line with --reserve-size or as the third argument to InitLispWorks) is the size of the range. The default of the size of the range is 2^40.

If the entire heap is within the new range, nothing else is done. If some part of the heap is outside the new range, the heap is relocated.

The range in each 64-bit LispWorks implementation starts at #x4000000000 (256 GB). Linux

On old Linux systems LispWorks (64-bit) for Linux has range 192 GB, ending at #x7000000000, because old Linux systems cannot map above #x8000000000 and put the dynamic libraries just below that limit (at least in some configurations). Since LispWorks uses the address space sparsely, it will run out of memory with less virtual memory, probably around 150 GB to 160 GB. If more memory is required, the range can be extended downwards, and possibly some distance upwards too. If other software uses memory in the range from #x4000000000 to #x7000000000, LispWorks should be relocated (potentially just by decreasing the range) to avoid memory clashes.

Modern Linux systems have a much larger address space and the default size of the LispWorks range is #x4000000000 (4TB). Windows and Macintosh

In LispWorks (64-bit) for Windows and LispWorks (64-bit) for Macintosh the size of the range is #x3c000000000 (3.75TB). Since these platforms properly support reservation, there should not be any reason to change the range. The only time when this is needed is when other software insists on using some address in this range and does not relocate automatically.

LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:24