[flang] Add EXECUTE_COMMAND_LINE runtime and lowering intrinsics implementation (#74077)

This patch add support of intrinsics Fortran 2008 EXECUTE_COMMAND_LINE.
The patch contains both the lowering and the runtime code and works on
both Windows and Linux. The patch contains a list of commits, to convey
the authorship and the history of changes. Some implementation specifics
or status has been added to `flang/docs/Intrinsics.md`.

I have provided a summary of the usage and the options required for the
`EXECUTE_COMMAND_LINE intrinsic`. The intrinsic supports both a
synchronous
(by default) and an asynchronous option.

| System  | Mode  | Implemention              |
|---------|-------|---------------------------|
| Linux   | Sync  | std::system()             |
| Windows | Sync  | std::system()             |
| Linux   | Async | fork()  |
| Windows | Async | CreateProcess             |

Support for the SYSTEM GNU extension will be added in a separate PR.

Co-authored with @jeffhammond

---------

Signed-off-by: Jeff Hammond <[email protected]>
Co-authored-by: Jeff Hammond <[email protected]>
Co-authored-by: Yi Wu <[email protected]>

Author: 3 people

flang/docs/Intrinsics.md

@@ -841,3 +841,48 @@ TRIM, UBOUND, UNPACK, VERIFY.
 
 Coarray, non standard, IEEE and ISO_C_BINDINGS intrinsic functions that can be
 used in constant expressions have currently no folding support at all.
+
+### Standard Intrinsics: EXECUTE_COMMAND_LINE
+
+#### Usage and Info
+
+- **Standard:** Fortran 2008 and later, specified in 16.9.73
+- **Class:** Subroutine
+- **Syntax:** `CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])`
+- **Arguments:**
+
+  | Argument  | Description                                                  |
+  |-----------|--------------------------------------------------------------|
+  | `COMMAND` | Shall be a default CHARACTER scalar.                         |
+  | `WAIT`    | (Optional) Shall be a default LOGICAL scalar.                |
+  | `EXITSTAT`| (Optional) Shall be an INTEGER of the default kind.          |
+  | `CMDSTAT` | (Optional) Shall be an INTEGER of the default kind.          |
+  | `CMDMSG`  | (Optional) Shall be a CHARACTER scalar of the default kind.  |
+
+#### Implementation Specifics
+
+- **`COMMAND`:**
+  - Must be preset.
+
+- **`WAIT`:**
+  - If set to `false`, the command is executed asynchronously. If not preset or set to `false`, it is executed synchronously.
+  - Sync: achieved by passing command into `std::system` on all systems.
+  - Async: achieved by calling a `fork()` on POSIX-compatible systems, or `CreateProcess()` on Windows.
+
+- **`CMDSTAT`:**
+  - -2: No error condition occurs, but `WAIT` is present with the value `false`, and the processor does not support asynchronous execution.
+  - -1: The processor does not support command line execution.
+  - \+ (positive value): An error condition occurs.
+    - 1: Fork Error, where `pid_t < 0`, would only occur on POSIX-compatible systems.
+    - 2: Execution Error, a command exits with status -1.
+    - 3: Invalid Command Error, determined by the exit code depending on the system.
+      - On Windows, if the exit code is 1.
+      - On POSIX-compatible systems, if the exit code is 127 or 126.
+    - 4: Signal error, either it is stopped or killed by signal, would only occur on POSIX-compatible systems.
+  - 0: Otherwise.
+
+- **`CMDMSG`:**
+  - If an error condition occurs, it is assigned an explanatory message. Otherwise, it remains unchanged.
+  - If a condition occurs that would assign a nonzero value to `CMDSTAT` but the `CMDSTAT` variable is not present, error termination is initiated.
+    - On POSIX-compatible systems, this applies to both synchronous and asynchronous error termination. When the execution mode is set to async with error termination, the child process (async process) will be terminated with no effect on the parent process (continues).
+    - On Windows, this only applies to synchronous error termination.

flang/include/flang/Optimizer/Builder/IntrinsicCall.h

@@ -214,6 +214,7 @@ struct IntrinsicLibrary {
   mlir::Value genDshiftr(mlir::Type, llvm::ArrayRef<mlir::Value>);
   fir::ExtendedValue genEoshift(mlir::Type, llvm::ArrayRef<fir::ExtendedValue>);
   void genExit(llvm::ArrayRef<fir::ExtendedValue>);
+  void genExecuteCommandLine(mlir::ArrayRef<fir::ExtendedValue> args);
   mlir::Value genExponent(mlir::Type, llvm::ArrayRef<mlir::Value>);
   fir::ExtendedValue genExtendsTypeOf(mlir::Type,
                                       llvm::ArrayRef<fir::ExtendedValue>);

flang/include/flang/Optimizer/Builder/Runtime/Execute.h

@@ -0,0 +1,35 @@
+//===-- Command.cpp -- generate command line runtime API calls ------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef FORTRAN_OPTIMIZER_BUILDER_RUNTIME_EXECUTE_H
+#define FORTRAN_OPTIMIZER_BUILDER_RUNTIME_EXECUTE_H
+
+namespace mlir {
+class Value;
+class Location;
+} // namespace mlir
+
+namespace fir {
+class FirOpBuilder;
+} // namespace fir
+
+namespace fir::runtime {
+
+/// Generate a call to the ExecuteCommandLine runtime function which implements
+/// the GET_EXECUTE_ARGUMENT intrinsic.
+/// \p wait must be bool that can be absent.
+/// \p exitstat, \p cmdstat and \p cmdmsg must be fir.box that can be
+/// absent (but not null mlir values). The status exitstat and cmdstat are
+/// returned, along with the message cmdmsg.
+void genExecuteCommandLine(fir::FirOpBuilder &, mlir::Location,
+                           mlir::Value command, mlir::Value wait,
+                           mlir::Value exitstat, mlir::Value cmdstat,
+                           mlir::Value cmdmsg);
+
+} // namespace fir::runtime
+#endif // FORTRAN_OPTIMIZER_BUILDER_RUNTIME_EXECUTE_H

flang/include/flang/Runtime/execute.h

@@ -0,0 +1,29 @@
+//===-- include/flang/Runtime/command.h -------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef FORTRAN_RUNTIME_EXECUTE_H_
+#define FORTRAN_RUNTIME_EXECUTE_H_
+
+#include "flang/Runtime/entry-names.h"
+
+namespace Fortran::runtime {
+class Descriptor;
+
+extern "C" {
+
+// 16.9.83 EXECUTE_COMMAND_LINE
+// Execute a command line.
+// Returns a EXITSTAT, CMDSTAT, and CMDMSG as described in the standard.
+void RTNAME(ExecuteCommandLine)(const Descriptor &command, bool wait = true,
+    const Descriptor *exitstat = nullptr, const Descriptor *cmdstat = nullptr,
+    const Descriptor *cmdmsg = nullptr, const char *sourceFile = nullptr,
+    int line = 0);
+}
+} // namespace Fortran::runtime
+
+#endif // FORTRAN_RUNTIME_EXECUTE_H_

flang/lib/Optimizer/Builder/CMakeLists.txt

@@ -20,6 +20,7 @@ add_flang_library(FIRBuilder
   Runtime/Derived.cpp
   Runtime/EnvironmentDefaults.cpp
   Runtime/Exceptions.cpp
+  Runtime/Execute.cpp
   Runtime/Inquiry.cpp
   Runtime/Intrinsics.cpp
   Runtime/Numeric.cpp

flang/lib/Optimizer/Builder/IntrinsicCall.cpp

@@ -26,6 +26,7 @@
 #include "flang/Optimizer/Builder/Runtime/Command.h"
 #include "flang/Optimizer/Builder/Runtime/Derived.h"
 #include "flang/Optimizer/Builder/Runtime/Exceptions.h"
+#include "flang/Optimizer/Builder/Runtime/Execute.h"
 #include "flang/Optimizer/Builder/Runtime/Inquiry.h"
 #include "flang/Optimizer/Builder/Runtime/Intrinsics.h"
 #include "flang/Optimizer/Builder/Runtime/Numeric.h"
@@ -213,6 +214,14 @@ static constexpr IntrinsicHandler handlers[]{
        {"boundary", asBox, handleDynamicOptional},
        {"dim", asValue}}},
      /*isElemental=*/false},
+    {"execute_command_line",
+     &I::genExecuteCommandLine,
+     {{{"command", asBox},
+       {"wait", asValue, handleDynamicOptional},
+       {"exitstat", asBox, handleDynamicOptional},
+       {"cmdstat", asBox, handleDynamicOptional},
+       {"cmdmsg", asBox, handleDynamicOptional}}},
+     /*isElemental=*/false},
     {"exit",
      &I::genExit,
      {{{"status", asValue, handleDynamicOptional}}},
@@ -2901,6 +2910,40 @@ IntrinsicLibrary::genEoshift(mlir::Type resultType,
   return readAndAddCleanUp(resultMutableBox, resultType, "EOSHIFT");
 }
 
+// EXECUTE_COMMAND_LINE
+void IntrinsicLibrary::genExecuteCommandLine(
+    llvm::ArrayRef<fir::ExtendedValue> args) {
+  assert(args.size() == 5);
+  mlir::Value command = fir::getBase(args[0]);
+  const fir::ExtendedValue &wait = args[1];
+  const fir::ExtendedValue &exitstat = args[2];
+  const fir::ExtendedValue &cmdstat = args[3];
+  const fir::ExtendedValue &cmdmsg = args[4];
+
+  if (!command)
+    fir::emitFatalError(loc, "expected COMMAND parameter");
+
+  mlir::Type boxNoneTy = fir::BoxType::get(builder.getNoneType());
+
+  mlir::Value waitBool = isStaticallyPresent(wait)
+                             ? fir::getBase(wait)
+                             : builder.createBool(loc, true);
+  mlir::Value exitstatBox =
+      isStaticallyPresent(exitstat)
+          ? fir::getBase(exitstat)
+          : builder.create<fir::AbsentOp>(loc, boxNoneTy).getResult();
+  mlir::Value cmdstatBox =
+      isStaticallyPresent(cmdstat)
+          ? fir::getBase(cmdstat)
+          : builder.create<fir::AbsentOp>(loc, boxNoneTy).getResult();
+  mlir::Value cmdmsgBox =
+      isStaticallyPresent(cmdmsg)
+          ? fir::getBase(cmdmsg)
+          : builder.create<fir::AbsentOp>(loc, boxNoneTy).getResult();
+  fir::runtime::genExecuteCommandLine(builder, loc, command, waitBool,
+                                      exitstatBox, cmdstatBox, cmdmsgBox);
+}
+
 // EXIT
 void IntrinsicLibrary::genExit(llvm::ArrayRef<fir::ExtendedValue> args) {
   assert(args.size() == 1);

flang/lib/Optimizer/Builder/Runtime/Execute.cpp

@@ -0,0 +1,44 @@
+//===-- Execute.cpp -- generate command line runtime API calls ------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "flang/Optimizer/Builder/Runtime/Execute.h"
+#include "flang/Optimizer/Builder/FIRBuilder.h"
+#include "flang/Optimizer/Builder/Runtime/RTBuilder.h"
+#include "flang/Runtime/execute.h"
+
+using namespace Fortran::runtime;
+
+// Certain runtime intrinsics should only be run when select parameters of the
+// intrisic are supplied. In certain cases one of these parameters may not be
+// given, however the intrinsic needs to be run due to another required
+// parameter being supplied. In this case the missing parameter is assigned to
+// have an "absent" value. This typically happens in IntrinsicCall.cpp. For this
+// reason the extra indirection with `isAbsent` is needed for testing whether a
+// given parameter is actually present (so that parameters with "value" absent
+// are not considered as present).
+inline bool isAbsent(mlir::Value val) {
+  return mlir::isa_and_nonnull<fir::AbsentOp>(val.getDefiningOp());
+}
+
+void fir::runtime::genExecuteCommandLine(fir::FirOpBuilder &builder,
+                                         mlir::Location loc,
+                                         mlir::Value command, mlir::Value wait,
+                                         mlir::Value exitstat,
+                                         mlir::Value cmdstat,
+                                         mlir::Value cmdmsg) {
+  auto runtimeFunc =
+      fir::runtime::getRuntimeFunc<mkRTKey(ExecuteCommandLine)>(loc, builder);
+  mlir::FunctionType runtimeFuncTy = runtimeFunc.getFunctionType();
+  mlir::Value sourceFile = fir::factory::locationToFilename(builder, loc);
+  mlir::Value sourceLine =
+      fir::factory::locationToLineNo(builder, loc, runtimeFuncTy.getInput(6));
+  llvm::SmallVector<mlir::Value> args = fir::runtime::createArguments(
+      builder, loc, runtimeFuncTy, command, wait, exitstat, cmdstat, cmdmsg,
+      sourceFile, sourceLine);
+  builder.create<fir::CallOp>(loc, runtimeFunc, args);
+}

flang/runtime/CMakeLists.txt

@@ -105,6 +105,7 @@ set(sources
   edit-output.cpp
   environment.cpp
   exceptions.cpp
+  execute.cpp
   extensions.cpp
   extrema.cpp
   file.cpp