runner/
lib.rs

1// Copyright (c) Microsoft Corporation.
2// Licensed under the MIT License.
3
4#![deny(clippy::all, clippy::pedantic)]
5#![allow(unused)]
6
7mod cli;
8pub use cli::main;
9
10pub use qir_backend::{
11    arrays::*, bigints::*, callables::*, exp::*, math::*, output_recording::*, range_support::*,
12    result_bool::*, strings::*, tuples::*, *,
13};
14
15use inkwell::{
16    attributes::AttributeLoc,
17    context::Context,
18    execution_engine::ExecutionEngine,
19    memory_buffer::MemoryBuffer,
20    module::Module,
21    passes::{PassBuilderOptions, PassManager},
22    targets::{CodeModel, InitializationConfig, RelocMode, Target, TargetMachine, TargetTriple},
23    values::FunctionValue,
24    OptimizationLevel,
25};
26use std::{
27    collections::HashMap,
28    ffi::OsStr,
29    io::{Read, Write},
30    path::Path,
31    ptr::null_mut,
32};
33
34/// # Errors
35///
36/// Will return `Err` if
37/// - `filename` does not exist or the user does not have permission to read it.
38/// - `filename` does not contain a valid bitcode module
39/// - `filename` does not have either a .ll or .bc as an extension
40/// - `entry_point` is not found in the QIR
41/// - Entry point has parameters or a non-void return type.
42pub fn run_file(
43    path: impl AsRef<Path>,
44    entry_point: Option<&str>,
45    shots: u32,
46    rng_seed: Option<u64>,
47    output_writer: &mut impl Write,
48) -> Result<(), String> {
49    if let Some(seed) = rng_seed {
50        qir_backend::set_rng_seed(seed);
51    }
52    let context = Context::create();
53    let module = load_file(path, &context)?;
54    run_module(&module, entry_point, shots, output_writer)
55}
56
57/// # Errors
58///
59/// Will return `Err` if
60/// - `bytes` does not contain a valid bitcode module
61/// - `entry_point` is not found in the QIR
62/// - Entry point has parameters or a non-void return type.
63pub fn run_bitcode(
64    bytes: &[u8],
65    entry_point: Option<&str>,
66    shots: u32,
67    output_writer: &mut impl Write,
68) -> Result<(), String> {
69    let context = Context::create();
70    let buffer = MemoryBuffer::create_from_memory_range(bytes, "");
71    let module = Module::parse_bitcode_from_buffer(&buffer, &context).map_err(|e| e.to_string())?;
72    run_module(&module, entry_point, shots, output_writer)
73}
74
75fn run_module(
76    module: &Module,
77    entry_point: Option<&str>,
78    shots: u32,
79    output_writer: &mut impl Write,
80) -> Result<(), String> {
81    module
82        .verify()
83        .map_err(|e| format!("Failed to verify module: {}", e.to_string()))?;
84
85    Target::initialize_native(&InitializationConfig::default())?;
86    let default_triple = TargetMachine::get_default_triple();
87    let target = Target::from_triple(&default_triple).map_err(|e| e.to_string())?;
88    if !target.has_asm_backend() {
89        return Err("Target doesn't have an ASM backend.".to_owned());
90    }
91    if !target.has_target_machine() {
92        return Err("Target doesn't have a target machine.".to_owned());
93    }
94
95    run_basic_passes_on(module, &default_triple, &target)?;
96
97    inkwell::support::load_library_permanently(Path::new(""));
98
99    let execution_engine = module
100        .create_jit_execution_engine(OptimizationLevel::None)
101        .map_err(|e| e.to_string())?;
102
103    bind_functions(module, &execution_engine)?;
104
105    let entry_point = choose_entry_point(module_functions(module), entry_point)?;
106    // TODO: need a cleaner way to get the attr strings for metadata
107    let attrs: Vec<(String, String)> = entry_point
108        .attributes(AttributeLoc::Function)
109        .iter()
110        .map(|attr| {
111            (
112                attr.get_string_kind_id()
113                    .to_str()
114                    .expect("Invalid UTF8 data")
115                    .to_string(),
116                attr.get_string_value()
117                    .to_str()
118                    .expect("Invalid UTF8 data")
119                    .to_string(),
120            )
121        })
122        .collect();
123
124    for _ in 1..=shots {
125        output_writer
126            .write_all("START\n".as_bytes())
127            .expect("Failed to write output");
128        for attr in &attrs {
129            output_writer
130                .write_all(format!("METADATA\t{}", attr.0).as_bytes())
131                .expect("Failed to write output");
132            if !attr.1.is_empty() {
133                output_writer
134                    .write_all(format!("\t{}", attr.1).as_bytes())
135                    .expect("Failed to write output");
136            }
137            output_writer
138                .write_all(qir_stdlib::output_recording::LINE_ENDING)
139                .expect("Failed to write output");
140        }
141
142        __quantum__rt__initialize(null_mut());
143        unsafe { run_entry_point(&execution_engine, entry_point)? }
144
145        // Write the saved output records to the output_writer
146        OUTPUT.with(|output| {
147            let mut output = output.borrow_mut();
148            output_writer
149                .write_all(output.drain().as_slice())
150                .expect("Failed to write output");
151        });
152
153        // Write the end of the shot
154        output_writer
155            .write_all("END\t0".as_bytes())
156            .expect("Failed to write output");
157        output_writer
158            .write_all(qir_stdlib::output_recording::LINE_ENDING)
159            .expect("Failed to write output");
160    }
161    Ok(())
162}
163
164fn load_file(path: impl AsRef<Path>, context: &Context) -> Result<Module, String> {
165    let path = path.as_ref();
166    let extension = path.extension().and_then(OsStr::to_str);
167
168    match extension {
169        Some("ll") => MemoryBuffer::create_from_file(path)
170            .and_then(|buffer| context.create_module_from_ir(buffer))
171            .map_err(|e| e.to_string()),
172        Some("bc") => Module::parse_bitcode_from_path(path, context).map_err(|e| e.to_string()),
173        _ => Err(format!("Unsupported file extension '{extension:?}'.")),
174    }
175}
176
177unsafe fn run_entry_point(
178    execution_engine: &ExecutionEngine,
179    entry_point: FunctionValue,
180) -> Result<(), String> {
181    if entry_point.count_params() == 0 {
182        execution_engine.run_function(entry_point, &[]);
183        Ok(())
184    } else {
185        Err("Entry point has parameters or a non-void return type.".to_owned())
186    }
187}
188
189fn choose_entry_point<'ctx>(
190    functions: impl Iterator<Item = FunctionValue<'ctx>>,
191    name: Option<&str>,
192) -> Result<FunctionValue<'ctx>, String> {
193    let mut entry_points = functions
194        .filter(|f| is_entry_point(*f) && name.iter().all(|n| f.get_name().to_str() == Ok(n)));
195
196    let entry_point = entry_points
197        .next()
198        .ok_or_else(|| "No matching entry point found.".to_owned())?;
199
200    if entry_points.next().is_some() {
201        Err("Multiple matching entry points found.".to_owned())
202    } else {
203        Ok(entry_point)
204    }
205}
206
207fn module_functions<'ctx>(module: &Module<'ctx>) -> impl Iterator<Item = FunctionValue<'ctx>> {
208    struct FunctionValueIter<'ctx>(Option<FunctionValue<'ctx>>);
209
210    impl<'ctx> Iterator for FunctionValueIter<'ctx> {
211        type Item = FunctionValue<'ctx>;
212
213        fn next(&mut self) -> Option<Self::Item> {
214            let function = self.0;
215            self.0 = function.and_then(inkwell::values::FunctionValue::get_next_function);
216            function
217        }
218    }
219
220    FunctionValueIter(module.get_first_function())
221}
222
223fn is_entry_point(function: FunctionValue) -> bool {
224    function
225        .get_string_attribute(AttributeLoc::Function, "entry_point")
226        .is_some()
227        || function
228            .get_string_attribute(AttributeLoc::Function, "EntryPoint")
229            .is_some()
230}
231
232fn run_basic_passes_on(
233    module: &Module,
234    target_triple: &TargetTriple,
235    target: &Target,
236) -> Result<(), String> {
237    // Description of this syntax:
238    // https://github.com/llvm/llvm-project/blob/2ba08386156ef25913b1bee170d8fe95aaceb234/llvm/include/llvm/Passes/PassBuilder.h#L308-L347
239    const BASIC_PASS_PIPELINE: &str = "globaldce,strip-dead-prototypes";
240
241    // Boilerplate taken from here:
242    // https://github.com/TheDan64/inkwell/blob/5c9f7fcbb0a667f7391b94beb65f1a670ad13221/examples/kaleidoscope/main.rs#L86-L95
243    let target_machine = target
244        .create_target_machine(
245            target_triple,
246            "generic",
247            "",
248            OptimizationLevel::None,
249            RelocMode::Default,
250            CodeModel::Default,
251        )
252        .ok_or("Unable to create TargetMachine from Target")?;
253    module
254        .run_passes(
255            BASIC_PASS_PIPELINE,
256            &target_machine,
257            PassBuilderOptions::create(),
258        )
259        .map_err(|e| e.to_string())
260}
261
262#[allow(clippy::too_many_lines)]
263fn bind_functions(module: &Module, execution_engine: &ExecutionEngine) -> Result<(), String> {
264    let mut uses_legacy = vec![];
265    let mut declarations: HashMap<String, FunctionValue> = HashMap::default();
266    for func in module_functions(module).filter(|f| {
267        f.count_basic_blocks() == 0
268            && !f
269                .get_name()
270                .to_str()
271                .expect("Unable to coerce function name into str.")
272                .starts_with("llvm.")
273    }) {
274        declarations.insert(
275            func.get_name()
276                .to_str()
277                .expect("Unable to coerce function name into str.")
278                .to_owned(),
279            func,
280        );
281    }
282
283    macro_rules! bind {
284        ($func:ident, $param_count:expr) => {
285            if let Some(func) = declarations.get(stringify!($func)) {
286                if func.get_params().len() != $param_count {
287                    return Err(format!(
288                        "Function '{}' has mismatched parameters: expected {}, found {}",
289                        stringify!($func),
290                        $param_count,
291                        func.get_params().len()
292                    ));
293                }
294                execution_engine.add_global_mapping(func, $func as usize);
295                declarations.remove(stringify!($func));
296            }
297        };
298    }
299
300    macro_rules! legacy_output {
301        ($func:ident) => {
302            if let Some(func) = declarations.get(stringify!($func)) {
303                execution_engine.add_global_mapping(
304                    func,
305                    qir_backend::output_recording::legacy::$func as usize,
306                );
307                declarations.remove(stringify!($func));
308                Some(true)
309            } else {
310                None
311            }
312        };
313    }
314
315    macro_rules! bind_output_record {
316        ($func:ident) => {
317            if let Some(func) = declarations.get(stringify!($func)) {
318                if func.get_params().len() == 1 {
319                    execution_engine.add_global_mapping(
320                        func,
321                        qir_backend::output_recording::legacy::$func as usize,
322                    );
323                    declarations.remove(stringify!($func));
324                    Some(true)
325                } else {
326                    execution_engine.add_global_mapping(func, $func as usize);
327                    declarations.remove(stringify!($func));
328                    Some(false)
329                }
330            } else {
331                None
332            }
333        };
334    }
335
336    // Legacy output methods
337    uses_legacy.push(legacy_output!(__quantum__rt__array_end_record_output));
338    uses_legacy.push(legacy_output!(__quantum__rt__array_start_record_output));
339    uses_legacy.push(legacy_output!(__quantum__rt__tuple_end_record_output));
340    uses_legacy.push(legacy_output!(__quantum__rt__tuple_start_record_output));
341
342    bind!(__quantum__rt__initialize, 1);
343    bind!(__quantum__qis__arccos__body, 1);
344    bind!(__quantum__qis__arcsin__body, 1);
345    bind!(__quantum__qis__arctan__body, 1);
346    bind!(__quantum__qis__arctan2__body, 2);
347    bind!(__quantum__qis__assertmeasurementprobability__body, 6);
348    bind!(__quantum__qis__assertmeasurementprobability__ctl, 6);
349    bind!(__quantum__qis__barrier__body, 0);
350    bind!(__quantum__qis__ccx__body, 3);
351    bind!(__quantum__qis__cnot__body, 2);
352    bind!(__quantum__qis__cos__body, 1);
353    bind!(__quantum__qis__cosh__body, 1);
354    bind!(__quantum__qis__cx__body, 2);
355    bind!(__quantum__qis__cz__body, 2);
356    bind!(__quantum__qis__drawrandomdouble__body, 2);
357    bind!(__quantum__qis__drawrandomint__body, 2);
358    bind!(__quantum__qis__dumpmachine__body, 1);
359    bind!(__quantum__qis__exp__body, 3);
360    bind!(__quantum__qis__exp__adj, 3);
361    bind!(__quantum__qis__exp__ctl, 2);
362    bind!(__quantum__qis__exp__ctladj, 2);
363    bind!(__quantum__qis__h__body, 1);
364    bind!(__quantum__qis__h__ctl, 2);
365    bind!(__quantum__qis__ieeeremainder__body, 2);
366    bind!(__quantum__qis__infinity__body, 0);
367    bind!(__quantum__qis__isinf__body, 1);
368    bind!(__quantum__qis__isnan__body, 1);
369    bind!(__quantum__qis__isnegativeinfinity__body, 1);
370    bind!(__quantum__qis__log__body, 1);
371    bind!(__quantum__qis__measure__body, 2);
372    bind!(__quantum__qis__mresetz__body, 2);
373    bind!(__quantum__qis__mz__body, 2);
374    bind!(__quantum__qis__nan__body, 0);
375    bind!(__quantum__qis__r__adj, 3);
376    bind!(__quantum__qis__r__body, 3);
377    bind!(__quantum__qis__r__ctl, 2);
378    bind!(__quantum__qis__r__ctladj, 2);
379    bind!(__quantum__qis__read_result__body, 1);
380    bind!(__quantum__qis__reset__body, 1);
381    bind!(__quantum__qis__rx__body, 2);
382    bind!(__quantum__qis__rx__ctl, 2);
383    bind!(__quantum__qis__rxx__body, 3);
384    bind!(__quantum__qis__ry__body, 2);
385    bind!(__quantum__qis__ry__ctl, 2);
386    bind!(__quantum__qis__ryy__body, 3);
387    bind!(__quantum__qis__rz__body, 2);
388    bind!(__quantum__qis__rz__ctl, 2);
389    bind!(__quantum__qis__rzz__body, 3);
390    bind!(__quantum__qis__s__adj, 1);
391    bind!(__quantum__qis__s__body, 1);
392    bind!(__quantum__qis__s__ctl, 2);
393    bind!(__quantum__qis__s__ctladj, 2);
394    bind!(__quantum__qis__sx__body, 1);
395    bind!(__quantum__qis__sin__body, 1);
396    bind!(__quantum__qis__sinh__body, 1);
397    bind!(__quantum__qis__sqrt__body, 1);
398    bind!(__quantum__qis__swap__body, 2);
399    bind!(__quantum__qis__t__adj, 1);
400    bind!(__quantum__qis__t__body, 1);
401    bind!(__quantum__qis__t__ctl, 2);
402    bind!(__quantum__qis__t__ctladj, 2);
403    bind!(__quantum__qis__tan__body, 1);
404    bind!(__quantum__qis__tanh__body, 1);
405    bind!(__quantum__qis__x__body, 1);
406    bind!(__quantum__qis__x__ctl, 2);
407    bind!(__quantum__qis__y__body, 1);
408    bind!(__quantum__qis__y__ctl, 2);
409    bind!(__quantum__qis__z__body, 1);
410    bind!(__quantum__qis__z__ctl, 2);
411    bind!(__quantum__rt__array_concatenate, 2);
412    bind!(__quantum__rt__array_copy, 2);
413    bind!(__quantum__rt__array_create_1d, 2);
414
415    // New calls
416    bind!(__quantum__rt__array_record_output, 2);
417    bind!(__quantum__rt__tuple_record_output, 2);
418
419    // calls with unlabeled signature variants
420    uses_legacy.push(bind_output_record!(__quantum__rt__bool_record_output));
421    uses_legacy.push(bind_output_record!(__quantum__rt__double_record_output));
422    uses_legacy.push(bind_output_record!(__quantum__rt__int_record_output));
423
424    // results need special handling as they aren't in the std lib
425    uses_legacy.push(
426        if let Some(func) = declarations.get("__quantum__rt__result_record_output") {
427            if func.get_params().len() == 1 {
428                execution_engine.add_global_mapping(
429                    func,
430                    qir_backend::legacy_output::__quantum__rt__result_record_output as usize,
431                );
432                declarations.remove("__quantum__rt__result_record_output");
433                Some(true)
434            } else {
435                execution_engine
436                    .add_global_mapping(func, __quantum__rt__result_record_output as usize);
437                declarations.remove("__quantum__rt__result_record_output");
438                Some(false)
439            }
440        } else {
441            None
442        },
443    );
444
445    // calls to __quantum__qis__m__body may use either dynamic or static results, so bind to the right
446    // implementation based on number of arguments.
447    if let Some(func) = declarations.get("__quantum__qis__m__body") {
448        if func.get_params().len() == 2 {
449            execution_engine
450                .add_global_mapping(func, qir_backend::__quantum__qis__mz__body as usize);
451        } else if func.get_params().len() == 1 {
452            execution_engine
453                .add_global_mapping(func, qir_backend::__quantum__qis__m__body as usize);
454        } else {
455            return Err(format!(
456                "Function '__quantum__qis__m__body' has mismatched parameters: expected 1 or 2, found {}",
457                func.get_params().len()
458            ));
459        }
460        declarations.remove("__quantum__qis__m__body");
461    }
462
463    bind!(__quantum__rt__array_get_element_ptr_1d, 2);
464    bind!(__quantum__rt__array_get_size_1d, 1);
465    bind!(quantum__rt__array_slice_1d, 3);
466    bind!(__quantum__rt__array_update_alias_count, 2);
467    bind!(__quantum__rt__array_update_reference_count, 2);
468    bind!(__quantum__rt__bigint_add, 2);
469    bind!(__quantum__rt__bigint_bitand, 2);
470    bind!(__quantum__rt__bigint_bitnot, 1);
471    bind!(__quantum__rt__bigint_bitor, 2);
472    bind!(__quantum__rt__bigint_bitxor, 2);
473    bind!(__quantum__rt__bigint_create_array, 2);
474    bind!(__quantum__rt__bigint_create_i64, 1);
475    bind!(__quantum__rt__bigint_divide, 2);
476    bind!(__quantum__rt__bigint_equal, 2);
477    bind!(__quantum__rt__bigint_get_data, 1);
478    bind!(__quantum__rt__bigint_get_length, 1);
479    bind!(__quantum__rt__bigint_greater, 2);
480    bind!(__quantum__rt__bigint_greater_eq, 2);
481    bind!(__quantum__rt__bigint_modulus, 2);
482    bind!(__quantum__rt__bigint_multiply, 2);
483    bind!(__quantum__rt__bigint_negate, 1);
484    bind!(__quantum__rt__bigint_power, 2);
485    bind!(__quantum__rt__bigint_shiftleft, 2);
486    bind!(__quantum__rt__bigint_shiftright, 2);
487    bind!(__quantum__rt__bigint_subtract, 2);
488    bind!(__quantum__rt__bigint_to_string, 1);
489    bind!(__quantum__rt__bigint_update_reference_count, 2);
490    bind!(__quantum__rt__bool_to_string, 1);
491    bind!(__quantum__rt__callable_copy, 2);
492    bind!(__quantum__rt__callable_create, 3);
493    bind!(__quantum__rt__callable_invoke, 3);
494    bind!(__quantum__rt__callable_make_adjoint, 1);
495    bind!(__quantum__rt__callable_make_controlled, 1);
496    bind!(__quantum__rt__callable_update_alias_count, 2);
497    bind!(__quantum__rt__callable_update_reference_count, 2);
498    bind!(__quantum__rt__capture_update_alias_count, 2);
499    bind!(__quantum__rt__capture_update_reference_count, 2);
500    bind!(__quantum__rt__double_to_string, 1);
501    bind!(__quantum__rt__fail, 1);
502    bind!(__quantum__rt__int_to_string, 1);
503    bind!(__quantum__rt__memory_allocate, 1);
504    bind!(__quantum__rt__message, 1);
505    bind!(__quantum__rt__pauli_to_string, 1);
506    bind!(__quantum__rt__qubit_allocate, 0);
507    bind!(__quantum__rt__qubit_allocate_array, 1);
508    bind!(__quantum__rt__qubit_release, 1);
509    bind!(__quantum__rt__qubit_release_array, 1);
510    bind!(__quantum__rt__qubit_to_string, 1);
511    bind!(__quantum__rt__result_equal, 2);
512    bind!(quantum__rt__range_to_string, 1);
513    bind!(__quantum__rt__result_get_one, 0);
514    bind!(__quantum__rt__result_get_zero, 0);
515    bind!(__quantum__rt__result_to_string, 1);
516    bind!(__quantum__rt__result_update_reference_count, 2);
517    bind!(__quantum__rt__string_concatenate, 2);
518    bind!(__quantum__rt__string_create, 1);
519    bind!(__quantum__rt__string_equal, 2);
520    bind!(__quantum__rt__string_get_data, 1);
521    bind!(__quantum__rt__string_get_length, 1);
522    bind!(__quantum__rt__string_update_reference_count, 2);
523    bind!(__quantum__rt__tuple_copy, 2);
524    bind!(__quantum__rt__tuple_create, 1);
525    bind!(__quantum__rt__tuple_update_alias_count, 2);
526    bind!(__quantum__rt__tuple_update_reference_count, 2);
527
528    if !(uses_legacy.iter().filter_map(|&b| b).all(|b| b)
529        || uses_legacy.iter().filter_map(|&b| b).all(|b| !b))
530    {
531        Err("Use of legacy and current output recording functions in the same program is not supported".to_string())
532    } else if declarations.is_empty() {
533        Ok(())
534    } else {
535        let keys = declarations.keys().collect::<Vec<_>>();
536        let (first, rest) = keys
537            .split_first()
538            .expect("Declarations list should be non-empty.");
539        Err(format!(
540            "Failed to link some declared functions: {}",
541            rest.iter().fold((*first).to_string(), |mut accum, f| {
542                accum.push_str(", ");
543                accum.push_str(f);
544                accum
545            })
546        ))
547    }
548}
runner/lib.rs

runner/
lib.rs
