[mlir][capi] make MLIR Pass C-API type safe

[sequencer]

This PR changes C-API name mlirCreateExternalPass to mlirExternalPassCreate for aligning the naming convention in C-API, and now it returns MlirExternalPass.
I added a new C-API MlirExternalPassGetPass to cast MlirExternalPass to MlirPass;

The X Problem is in the MLIR C-API, there is no way to create a MlirExternalPass, related API mlirCreateExternalPass create a MlirPass.
While creation of MlirExternalPassCallbacks requires MlirExternalPass, see

llvm-project/mlir/include/mlir-c/Pass.h

Lines 169 to 171 in 1557eed

	/// See Pass::runOnOperation().
	void (*run)(MlirOperation op, MlirExternalPass pass, void *userData);
	};

Thus it's impossible to create MlirExternalPassCallbacks type safely externally.

[github-actions]

Thank you for submitting a Pull Request (PR) to the LLVM Project!

This PR will be automatically labeled and the relevant teams will be notified.

If you wish to, you can add reviewers by using the "Reviewers" section on this page.

If this is not working for you, it is probably because you do not have write permissions for the repository. In which case you can instead tag reviewers by name in a comment by using @ followed by their GitHub username.

If you have received no comments on your PR for a week, you can request a review by "ping"ing the PR by adding a comment “Ping”. The common courtesy "ping" rate is once a week. Please remember that you are asking for valuable time from other developers.

If you have further questions, they may be answered by the LLVM GitHub User Guide.

You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums.

[SpriteOvO]

First of all, the renaming is a breaking change, if we do want to align the convention, we should also keep the old one and comment deprecated on it.

Second, MlirExternalPass is not supposed to be constructed from an external program. It is used in the run callback field in MlirExternalPassCallbacks, which is a callback parameter - an external program provides a callback function pointer which receives a MlirExternalPass passed from MLIR, and signals failure via mlirExternalPassSignalFailure if the pass implementation encountered any error.

See the test cases for examples

llvm-project/mlir/test/CAPI/pass.c

Lines 309 to 336 in 66dd7e6

	void testRunExternalPass(MlirOperation op, MlirExternalPass pass,
	void *userData) {
	++((TestExternalPassUserData *)userData)->runCallCount;
	}
	void testRunExternalFuncPass(MlirOperation op, MlirExternalPass pass,
	void *userData) {
	++((TestExternalPassUserData *)userData)->runCallCount;
	MlirStringRef opName = mlirIdentifierStr(mlirOperationGetName(op));
	if (!mlirStringRefEqual(opName,
	mlirStringRefCreateFromCString("func.func"))) {
	mlirExternalPassSignalFailure(pass);
	}
	}
	void testRunFailingExternalPass(MlirOperation op, MlirExternalPass pass,
	void *userData) {
	++((TestExternalPassUserData *)userData)->runCallCount;
	mlirExternalPassSignalFailure(pass);
	}
	MlirExternalPassCallbacks makeTestExternalPassCallbacks(
	MlirLogicalResult (*initializePass)(MlirContext ctx, void *userData),
	void (*runPass)(MlirOperation op, MlirExternalPass, void *userData)) {
	return (MlirExternalPassCallbacks){testConstructExternalPass,
	testDestructExternalPass, initializePass,
	testCloneExternalPass, runPass};
	}

[sequencer]

How does ExternalPassCallbacks construct? It should construct from 5 callbacks:

construct: void => void
destruct: void => void
initialize: Option[MlirContext => MlirLogicalResult]
clone: void => void
run (MlirOperation, MlirExternalPass) => void

The MlirExternalPass is a struct that need to be construct from the C-API.

[SpriteOvO]

How does ExternalPassCallbacks construct?

See

llvm-project/mlir/test/CAPI/pass.c

Lines 330 to 336 in 66dd7e6

	MlirExternalPassCallbacks makeTestExternalPassCallbacks(
	MlirLogicalResult (*initializePass)(MlirContext ctx, void *userData),
	void (*runPass)(MlirOperation op, MlirExternalPass, void *userData)) {
	return (MlirExternalPassCallbacks){testConstructExternalPass,
	testDestructExternalPass, initializePass,
	testCloneExternalPass, runPass};
	}

The MlirExternalPass is a struct that need to be construct from the C-API.

MlirExternalPass is an opaque struct type defined here,

llvm-project/mlir/include/mlir-c/Pass.h

Line 44 in 6cbc64e

DEFINE_C_API_STRUCT(MlirExternalPass, void);

you don't need to construct it, it will be an argument in your callback and you just use it as needed.

void yourRunCallback(MlirOperation op, MlirExternalPass pass, void *userData) {
  if (anyError) {
    mlirExternalPassSignalFailure(pass);
  }
}