uapi/habanalabs: add opcode for enable/disable device debug mode

This patch defines a new opcode in the DEBUG IOCTL that is used by the
user to notify the driver when the user wants to start or stop using the
debug and profile infrastructure of the device. i.e. set the device to
debug mode or to non-debug mode.

There are a couple of restrictions that this new opcode introduces:

1. The user can't configure the debug/profiling infrastructure before he
   sets the device to debug mode, by using this new opcode.

2. The user can't set the device to debug mode unless he is the only user
   that is currently using (has an open FD) the device.

3. Other users can't use the device (open a new FD) in case an existing
   user has set the device into debug mode.

These restrictions are needed because the debug and profiling
infrastructure is a shared component in the ASIC and therefore, can't be
used while multiple users are working on the device.

Because the driver currently does NOT support multiple users, the
implementation of the restrictions is not required at this point. However,
the interface definition is needed in order to avoid changing the user API
later on.

Signed-off-by: Oded Gabbay <oded.gabbay@gmail.com>

1 files changed, 20 insertions, 2 deletions

diff --git a/include/uapi/misc/habanalabs.h b/include/uapi/misc/habanalabs.h
index 8ac292cf4d00..204ab9b4ae67 100644
--- a/include/uapi/misc/habanalabs.h
+++ b/include/uapi/misc/habanalabs.h
@@ -413,6 +413,10 @@ struct hl_debug_params_spmu {
 #define HL_DEBUG_OP_SPMU	5
 /* Opcode for timestamp */
 #define HL_DEBUG_OP_TIMESTAMP	6
+/* Opcode for setting the device into or out of debug mode. The enable
+ * variable should be 1 for enabling debug mode and 0 for disabling it
+ */
+#define HL_DEBUG_OP_SET_MODE	7
 
 struct hl_debug_args {
 	/*
@@ -574,8 +578,22 @@ struct hl_debug_args {
  *
  * This IOCTL allows the user to get debug traces from the chip.
  *
- * The user needs to provide the register index and essential data such as
- * buffer address and size.
+ * Before the user can send configuration requests of the various
+ * debug/profile engines, it needs to set the device into debug mode.
+ * This is because the debug/profile infrastructure is shared component in the
+ * device and we can't allow multiple users to access it at the same time.
+ *
+ * Once a user set the device into debug mode, the driver won't allow other
+ * users to "work" with the device, i.e. open a FD. If there are multiple users
+ * opened on the device, the driver won't allow any user to debug the device.
+ *
+ * For each configuration request, the user needs to provide the register index
+ * and essential data such as buffer address and size.
+ *
+ * Once the user has finished using the debug/profile engines, he should
+ * set the device into non-debug mode, i.e. disable debug mode.
+ *
+ * The driver can decide to "kick out" the user if he abuses this interface.
  *
  */
 #define HL_IOCTL_DEBUG		\