Skip to content

Commit 2677283

Browse files
authored
Merge pull request #1159 from rj-jesus/rjj/lazy-opaque-pointers
Add IR layer typed pointers mode
2 parents 75ebdf6 + a563953 commit 2677283

File tree

9 files changed

+86
-111
lines changed

9 files changed

+86
-111
lines changed

buildscripts/incremental/test.cmd

+3-3
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
call activate %CONDA_ENV%
33

44
if "%OPAQUE_POINTERS%"=="yes" (
5-
set LLVMLITE_ENABLE_OPAQUE_POINTERS=1
6-
echo "Testing with opaque pointers enabled"
5+
set LLVMLITE_ENABLE_IR_LAYER_TYPED_POINTERS=0
6+
echo "Testing with IR layer opaque pointers enabled"
77
) else (
8-
echo "Testing with opaque pointers disabled"
8+
echo "Testing with IR layer opaque pointers disabled"
99
)
1010

1111
python runtests.py -v

buildscripts/incremental/test.sh

+3-3
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ set -v -e
1010
python --version
1111

1212
if [ "$OPAQUE_POINTERS" == "yes" ]; then
13-
export LLVMLITE_ENABLE_OPAQUE_POINTERS=1
14-
echo "Testing with opaque pointers enabled"
13+
export LLVMLITE_ENABLE_IR_LAYER_TYPED_POINTERS=0
14+
echo "Testing with IR layer opaque pointers enabled"
1515
else
16-
echo "Testing with opaque pointers disabled"
16+
echo "Testing with IR layer opaque pointers disabled"
1717
fi
1818

1919
if [ "$WHEEL" == "yes" ]; then

docs/source/user-guide/deprecation.rst

+26-7
Original file line numberDiff line numberDiff line change
@@ -30,20 +30,38 @@ switching to `Opaque Pointers <https://llvm.org/docs/OpaquePointers.html>`_:
3030
therefore may have bugs that go unfixed).
3131
- In LLVM 17, support for Typed Pointers is removed.
3232

33-
Although Opaque Pointers are already the default in LLVM 15, llvmlite still uses
34-
Typed Pointers by default with LLVM 15.
33+
Although Opaque Pointers are already the default in LLVM 15, llvmlite still used
34+
Typed Pointers by default with LLVM 15 in llvmlite 0.44.
35+
36+
The binding layer will move to using Opaque Pointers. The IR layer will still
37+
support both Typed and Opaque Pointers, defaulting to Typed Pointers when
38+
pointee types are provided. This allows llvmlite to continue being used with
39+
LLVM-based projects that use an older LLVM version, such as `NVVM
40+
<https://docs.nvidia.com/cuda/nvvm-ir-spec/>`_.
3541

3642
Examples(s) of the impact
3743
-------------------------
3844

39-
Code that uses llvmlite to work with pointers or to parse assembly that uses
40-
pointers will break if not modified to use opaque pointers.
45+
In a future release, code that uses llvmlite to work with Typed Pointers or
46+
generate IR with Typed Pointers will break if not modified to use Opaque
47+
Pointers.
48+
49+
In the meantime, IR generated by the IR layer and parsed by the binding layer
50+
will be auto-upgraded to use Opaque Pointers transparently; no action is
51+
required by the user.
4152

4253
Schedule
4354
--------
4455

45-
- In llvmlite 0.44, Opaque Pointers will be the default pointer kind.
46-
- In llvmlite 0.45, support for Typed Pointers will be removed.
56+
- In llvmlite 0.45, support for Typed Pointers in the binding layer will be
57+
removed. The IR layer will still use Typed Pointers by default.
58+
- In a future version of llvmlite (>= 0.46), the IR layer will use Opaque
59+
Pointers by default.
60+
- In a subsequent version of llvmlite (>= 0.47), support for Typed Pointers at
61+
the IR layer will be removed.
62+
63+
This schedule may be updated to push out the deprecation / removal of Typed
64+
Pointer support to still later versions of llvmlite.
4765

4866
Recommendations
4967
---------------
@@ -127,7 +145,8 @@ When working with global variables and functions (which will be :class:`ValueRef
127145

128146
When passing assembly to :func:`llvmlite.binding.parse_assembly`:
129147

130-
- Ensure that any IR passed to ``parse_assembly()`` uses Opaque Pointers.
148+
- IR passed to ``parse_assembly()`` is free to use either Typed or Opaque
149+
Pointers.
131150

132151

133152
Deprecation of `llvmlite.llvmpy` module

docs/source/user-guide/ir/types.rst

+9-9
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,14 @@ Atomic types
100100
Pointer Types
101101
=============
102102

103-
llvmlite presently supports both *Typed Pointers* and *Opaque Pointers*. Typed
104-
Pointers are currently the default; Opaque Pointers will become the default in
105-
future, and support for Typed Pointers will be eventually be removed.
103+
The IR layer presently supports both *Typed Pointers* and *Opaque Pointers*.
104+
Support for Typed Pointers will eventually be removed.
106105

107106
.. note::
108107
Further details of the migration to Opaque Pointers are outlined in the
109108
section on :ref:`deprecation-of-typed-pointers`.
110109

111-
When Typed Pointers are enabled, the pointer type is represented using:
110+
Typed Pointers are created using:
112111

113112
.. class:: PointerType(pointee, addrspace=0)
114113

@@ -126,23 +125,24 @@ When Typed Pointers are enabled, the pointer type is represented using:
126125

127126
The type pointed to.
128127

129-
Opaque pointers can be enabled by setting the environment variable:
128+
Printing of Typed Pointers as Opaque Pointers can be enabled by setting the
129+
environment variable:
130130

131131
.. code:: bash
132132
133-
LLVMLITE_ENABLE_OPAQUE_POINTERS=1
133+
LLVMLITE_ENABLE_IR_LAYER_TYPED_POINTERS=0
134134
135-
or by setting the ``opaque_pointers_enabled`` attribute after importing
135+
or by setting the ``ir_layer_typed_pointers_enabled`` attribute after importing
136136
llvmlite, but prior to using any of its functionality. For example:
137137

138138
.. code:: python
139139
140140
import llvmlite
141-
llvmlite.opaque_pointers_enabled = True
141+
llvmlite.ir_layer_typed_pointers_enabled = False
142142
143143
# ... continue using llvmlite ...
144144
145-
When Opaque Pointers are enabled, the pointer type is represented using:
145+
Opaque Pointers can be created by using:
146146

147147
.. class:: PointerType(addrspace=0)
148148
:no-index:

examples/opaque_pointers/llvmir.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import llvmlite
2-
llvmlite.opaque_pointers_enabled = True
2+
llvmlite.ir_layer_typed_pointers_enabled = False
33

44
import llvmlite.ir as ll
55

examples/opaque_pointers/sum.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
pass
1616

1717
import llvmlite
18-
llvmlite.opaque_pointers_enabled = True
18+
llvmlite.ir_layer_typed_pointers_enabled = False
1919

2020
import llvmlite.ir as ll
2121
import llvmlite.binding as llvm

llvmlite/__init__.py

+8-4
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,12 @@
33
del get_versions
44

55
# FIXME: Remove me once typed pointers are no longer supported.
6-
def _opaque_pointers_enabled():
6+
# Opaque pointers unconditionally required for later LLVM versions
7+
opaque_pointers_enabled = True
8+
# We default to IR layer typed pointers being enabled, since they're needed in
9+
# the most common usage scenarios with later LLVMs.
10+
def _ir_layer_typed_pointers_enabled():
711
import os
8-
return os.environ.get('LLVMLITE_ENABLE_OPAQUE_POINTERS', '0') == '1'
9-
opaque_pointers_enabled = _opaque_pointers_enabled()
10-
del _opaque_pointers_enabled
12+
return os.environ.get('LLVMLITE_ENABLE_IR_LAYER_TYPED_POINTERS', '1') == '1'
13+
ir_layer_typed_pointers_enabled = _ir_layer_typed_pointers_enabled()
14+
del _ir_layer_typed_pointers_enabled

llvmlite/ir/types.py

+2-17
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,9 @@
44

55
import struct
66

7+
from llvmlite import ir_layer_typed_pointers_enabled
78
from llvmlite.ir._utils import _StrCaching
89

9-
# FIXME: Remove me once typed pointers are no longer supported.
10-
from llvmlite import opaque_pointers_enabled
11-
1210

1311
def _wrapname(x):
1412
return '"{0}"'.format(x.replace('\\', '\\5c').replace('"', '\\22'))
@@ -145,8 +143,6 @@ def from_llvm(cls, typeref, ir_ctx):
145143
"""
146144
Create from a llvmlite.binding.TypeRef
147145
"""
148-
if not opaque_pointers_enabled:
149-
return _TypedPointerType.from_llvm(typeref, ir_ctx)
150146
return cls()
151147

152148

@@ -163,7 +159,7 @@ def __init__(self, pointee, addrspace=0):
163159
self.is_opaque = False
164160

165161
def _to_string(self):
166-
if not opaque_pointers_enabled:
162+
if ir_layer_typed_pointers_enabled:
167163
return "{0}*".format(self.pointee) if self.addrspace == 0 else \
168164
"{0} addrspace({1})*".format(self.pointee, self.addrspace)
169165
return super(_TypedPointerType, self)._to_string()
@@ -190,17 +186,6 @@ def gep(self, i):
190186
def intrinsic_name(self):
191187
return 'p%d%s' % (self.addrspace, self.pointee.intrinsic_name)
192188

193-
@classmethod
194-
def from_llvm(cls, typeref, ir_ctx):
195-
"""
196-
Create from a llvmlite.binding.TypeRef
197-
"""
198-
assert not opaque_pointers_enabled
199-
# opaque pointer will change this
200-
[pointee] = typeref.elements
201-
# addrspace is not handled
202-
return cls(pointee.as_ir(ir_ctx=ir_ctx))
203-
204189

205190
class VoidType(Type):
206191
"""

0 commit comments

Comments
 (0)