lib: Add an intel_ctx wrapper struct and helpers (v6)

We're trying to clean up some of our technical debt in the i915 API.  In
particular, context mutability and unnecessary getparam().  There's
quite a bit of the introspection stuff that's not used by any userspace
other than IGT.  Most drivers don't care about fetching the set of
engines, for instance, because they don't forget about what set of
engines they asked for int the first place.

Unfortunately, IGT relies heavily on context introspection for just
about everything when it comes to multi-engine testing.  It also likes
to use ctx0 as temporary storage for whatever the current test config
is.  While effective at keeping IGC simple in some ways, this means
we're making heavy use of context mutability.  Also, passing data around
with in tests isn't really what contexts are for.

This patch adds a new intel_ctx_t struct which wraps a context and
remembers the full context configuration.  This will provide similar
ease-of-use without having use ctx0 as temporary storage.

v2 (Jason Ekstrand):
 - Make all intel_ctx_t's const

v3 (Jason Ekstrand):
 - Fix up the docs so they build properly

v4 (Jason Ekstrand):
 - Add an intel_ctx_create_for_engine helper

v5 (Zbigniew Kempczyński):
 - Use SPDX license identifiers
 - Document default context semantics

v6 (Ashutosh Dixit):
 - Fix SPDX in intel_ctx.h
 - Fix a typo in a comment

v6 (Jason Ekstrand):
 - Add documentation about num_engines to intel_ctx_cfg_t

Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
Reviewed-by: Zbigniew Kempczyński <zbigniew.kempczynski@intel.com>

1 files changed, 75 insertions, 0 deletions

diff --git a/lib/intel_ctx.h b/lib/intel_ctx.h
new file mode 100644
index 00000000..054fecc4
--- /dev/null
+++ b/lib/intel_ctx.h
@@ -0,0 +1,75 @@
+/* SPDX-License-Identifier: MIT */
+/*
+ * Copyright © 2021 Intel Corporation
+ */
+
+#ifndef INTEL_CTX_H
+#define INTEL_CTX_H
+
+#include "igt_core.h"
+
+#include "i915_drm.h"
+
+#define GEM_MAX_ENGINES		I915_EXEC_RING_MASK + 1
+
+/**
+ * intel_ctx_cfg_t:
+ * @flags: Context create flags
+ * @vm: VM to inherit or 0 for using a per-context VM
+ * @num_engines: Number of client-specified engines or 0 for legacy mode
+ * @engines: Client-specified engines
+ *
+ * Represents the full configuration of an intel_ctx.
+ *
+ * @num_engines not only specifies the number of engines in the context but
+ * also how engine information should be communicated to execbuf.  With the
+ * engines API, every context has two modes:
+ *
+ *   - In legacy mode (indicated by @num_engines == 0), the context has a
+ *     fixed set of engines.  The engine to use is specified to execbuf via
+ *     an I915_EXEC_* flag such as I915_EXEC_RENDER or I915_EXEC_BLT.  This
+ *     is the default behavior of a GEM context if CONTEXT_PARAM_ENGINES is
+ *     never set.
+ *
+ *   - In modern mode (indicated by @num_engines > 0), the set of engines
+ *     is provided by userspace via CONTEXT_PARAM_ENGINES.  Userspace
+ *     provides an array of i915_engine_class_instance which are class +
+ *     instance pairs.  When calling execbuf in this mode, the engine to
+ *     use is specified by passing an integer engine index into that array
+ *     of engines as part of the flags parameter.  (Because of the layout
+ *     of the flags, the maximum possible index value is 63.)
+ */
+typedef struct intel_ctx_cfg {
+	uint32_t flags;
+	uint32_t vm;
+	unsigned int num_engines;
+	struct i915_engine_class_instance engines[GEM_MAX_ENGINES];
+} intel_ctx_cfg_t;
+
+intel_ctx_cfg_t intel_ctx_cfg_for_engine(unsigned int class, unsigned int inst);
+intel_ctx_cfg_t intel_ctx_cfg_all_physical(int fd);
+
+/**
+ * intel_ctx_t:
+ * @id: the context id/handle
+ * @cfg: the config used to create this context
+ *
+ * Represents the full configuration of an intel_ctx.
+ */
+typedef struct intel_ctx {
+	uint32_t id;
+	intel_ctx_cfg_t cfg;
+} intel_ctx_t;
+
+int __intel_ctx_create(int fd, const intel_ctx_cfg_t *cfg,
+		       const intel_ctx_t **out_ctx);
+const intel_ctx_t *intel_ctx_create(int i915, const intel_ctx_cfg_t *cfg);
+const intel_ctx_t *intel_ctx_0(int fd);
+const intel_ctx_t *intel_ctx_create_for_engine(int fd, unsigned int class,
+					       unsigned int inst);
+const intel_ctx_t *intel_ctx_create_all_physical(int fd);
+void intel_ctx_destroy(int fd, const intel_ctx_t *ctx);
+
+unsigned int intel_ctx_engine_class(const intel_ctx_t *ctx, unsigned int engine);
+
+#endif