WebAssembly/Globals: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | WebAssembly supports a feature, called "global variables" or just "globals". They differ from global variables in Pascal. This page discusses the possibility of extending FPC, in order to be able to declare WebAssembly globals from Pascal code. | |
| 2 | 2 | ||
| 3 | 3 | ## Differences between Pascal global variables and WebAssembly globals | |
| 4 | 4 | ||
| 5 | 5 | WebAssembly globals have the following restrictions: | |
| 6 | 6 | ||
| 7 | 7 | - They can be only one of the 4 WebAssembly basic types - int32, int64, float32 or float64. | |
| 8 | 8 | - Their address cannot be taken. They don't exist anywhere in linear memory. | |
| 9 | 9 | - In a multithreaded environment, they are usually not shared between threads, i.e. they behave like threadvars. | |
| 10 | 10 | ||
| 11 | 11 | These characteristics make them somewhat comparable to CPU or FPU registers on other architectures. However, they differ from registers in the following way: | |
| 12 | 12 | ||
| 13 | 13 | - There is an unlimited number of them. | |
| 14 | 14 | - They can be imported, exported, or just declared in a module (i.e. neither imported, nor exported, just declared and used by the module). | |
| 15 | 15 | ||
| 16 | 16 | In WebAssembly MVP (the original version of WebAssembly), they could only exist in the third state - neither imported, nor exported, but importing and exporting them from the module is a commonly implemented extension: [1](https://github.com/WebAssembly/mutable-global/blob/master/proposals/mutable-global/Overview.md) | |
| 17 | 17 | ||
| 18 | 18 | ## Special WebAssembly globals | |
| 19 | 19 | ||
| 20 | 20 | Free Pascal already creates and uses some WebAssembly globals, which are considered special and are part of the [Basic C ABI](https://github.com/WebAssembly/tool-conventions/blob/main/BasicCABI.md), which Free Pascal supports. | |
| 21 | 21 | ||
| 22 | 22 | ### __stack_pointer | |
| 23 | 23 | ||
| 24 | 24 | WebAssembly has an evaluation stack, which holds local variables, stack frames and temporary values. However, this stack is not visible in linear memory. This means that you cannot take the address of a value on this stack. Another restriction is that it can only hold the 4 basic WebAssembly types (int32, int64, float32, float64). To avoid these restrictions, Free Pascal maintains a second stack in linear memory. The WebAssembly global *__stack_pointer* points to the top of this stack. It is always 16-byte aligned. | |
| 25 | 25 | ||
| 26 | 26 | ### TLS-related globals | |
| 27 | 27 | ||
| 28 | 28 | When multithreading is enabled, the linker creates the following globals: | |
| 29 | 29 | ||
| 30 | 30 | - *__tls_size* - the total size of the thread local block of the program. This is the sum of the sizes of all threadvars, plus padding. | |
| 31 | 31 | - *__tls_align* - the alignment requirement for the thread local block. | |
| 32 | 32 | - *__tls_base* - initialized to 0, but can be set by the function *__wasm_init_tls*, which is created by the linker. All threadvar accesses, created by the compiler take the address of this variable and add an offset. | |
| 33 | 33 | ||
| 34 | 34 | ## Pascal syntax proposal | |
| 35 | 35 | ||
| 36 | 36 | WebAssembly globals are not yet implemented in Free Pascal. This section discusses the syntax for a possible language extension for supporting them. | |
| 37 | 37 | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 38 | + | ``` pascal | |
| 39 | + | var | |
| 40 | + | a: LongInt; wasmglobal; // FPC's name mangling applies | |
| 41 | + | aa: LongInt = 5; wasmglobal; // initialized global | |
| 42 | + | b: LongInt; wasmglobal name 'x'; // FPC's name mangling is not applied | |
| 43 | + | c: LongInt; wasmglobal; external name 'q'; // external, declared in a different unit, or .o module | |
| 44 | + | d: LongInt; wasmglobal; import name 'ddd'; // an import for the final .wasm module | |
| 44 | 45 | ||
| 45 | - | ||
| 46 | - | ||
| 46 | + | const | |
| 47 | + | ccc: LongInt = 10; wasmglobal; // immutable global | |
| 48 | + | ``` | |
| 47 | 49 | ||
| 48 | 50 | TODO: can we achieve this without introducing a new keyword? | |
| 49 | 51 | ||
| 50 | 52 | Introducing a new keyword can break existing code, if it happens to use the new keyword as a variable name, for example, the following code would break: | |
| 51 | 53 | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 54 | + | ``` pascal | |
| 55 | + | var | |
| 56 | + | a: Longint; | |
| 57 | + | wasmglobal: Boolean; | |
| 58 | + | ``` | |
| 55 | 59 | ||
| 56 | 60 | Proposed by Jonas: | |
| 57 | 61 | ||
| 58 | - | ||
| 59 | - | ||
| 62 | + | ``` pascal | |
| 63 | + | var | |
| 64 | + | a: LongInt; section 'WebAssembly.Global'; | |
| 65 | + | ``` | |
| 60 | 66 | ||
| 61 | 67 | Key here is the fact that the 'section' keyword already exists. | |
| 62 | 68 | ||
| 63 | 69 | Supported types: | |
| 64 | 70 | ||
| 65 | 71 | - LongInt (32-bit signed int) - mapped to i32 | |
| 66 | 72 | - LongWord (32-bit unsigned int) - mapped to i32 | |
| 67 | 73 | - Int64 (64-bit signed int) - mapped to i64 | |
| 68 | 74 | - QWord (64-bit unsigned int) - mapped to i64 | |
| 69 | 75 | - Single - mapped to f32 | |
| 70 | 76 | - Double - mapped to f64 | |
| 71 | 77 | - Pointer (typed or untyped) - mapped to i32 | |
| 72 | 78 | ||
| 73 | 79 | Unsupported types: | |
| 74 | 80 | ||
| 75 | 81 | - enum | |
| 76 | 82 | - set | |
| 77 | 83 | - string | |
| 78 | 84 | - class | |
| 79 | 85 | - object | |
| 80 | 86 | - record | |
| 81 | 87 | - smallint/shortint/byte/word | |
| 82 | 88 | - char | |
| 83 | 89 | - boolean | |
| 84 | 90 | - array | |
| 85 | 91 | - variant | |
| 86 | 92 | ||
| 87 | 93 | Some of the unsupported types can be supported in the future (good candidates are smallint/shortint/byte/word, boolean, char and enums). However, we generally don't want to cram all possible Pascal types. Wasmglobals are a very special feature, used for communicating with the WebAssembly hosting environment, they are not a replacement for normal Pascal global variables or threadvars. | |
| 88 | 94 | ||
| 89 | 95 | Restrictions: | |
| 90 | 96 | ||
| 91 | 97 | - You cannot take the address of a wasmglobal. | |
| 92 | 98 | - You cannot pass them as *var*, *constref* or *out* parameters. | |
| 93 | 99 | - You cannot declare them in the local variables section of a procedure/function. | |
| 94 | 100 | - *ABSOLUTE* is not supported, neither as a wasmglobal source, nor as a wasmglobal destination. | |
| 95 | 101 | - TODO: initial value restrictions??? | |
| 96 | 102 | ||
| 97 | 103 | --- | |
| 98 | 104 | *From the Free Pascal wiki, page "WebAssembly/Globals", as it stood on 2022-07-24 after a change by Nickysn, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 99 | 105 | Category: WebAssembly |