qcacld-3.0: Introduce mac_handle_t

Currently tHalHandle is used as the opaque handle for the primary data
structure within the protocol stack. This name is an anachronism given
that the HAL layer was moved to firmware many generations ago. In
addition the name does not conform to the Linux Kernel naming
convention.

To address these issues introduce a new identifier, mac_handle_t, to
be used as the opaque handle. Keep tHalHandle as a typedef to
mac_handle_t until such time that all references have been replaced.

In addition introduce a new set of conversion functions, MAC_CONTEXT()
and MAC_HANDLE(), to be used to convert between these two kinds of
references.

Change-Id: I9d0d7d109621237f29d66f7b06c5b63c38f63fb2
CRs-Fixed: 2257659

core/mac/inc/ani_global.h

@@ -43,9 +43,40 @@
 #include <lim_ft_defs.h>
 #include "wlan_objmgr_psoc_obj.h"
 
-/* Check if this definition can actually move here from halInternal.h even for Volans. In that case */
-/* this featurization can be removed. */
-#define PMAC_STRUCT(_hHal)  ((tpAniSirGlobal)_hHal)
+/**
+ * MAC_CONTEXT() - Convert an opaque mac handle into a mac context
+ * @handle: MAC handle to be converted
+ *
+ * Given an opaque mac handle this function will return the mac
+ * context that is associated with that handle.
+ *
+ * This is the inverse function of MAC_HANDLE()
+ *
+ * Return: mac context for @handle
+ */
+static inline tpAniSirGlobal MAC_CONTEXT(mac_handle_t handle)
+{
+	return (tpAniSirGlobal)handle;
+}
+
+/* legacy definition */
+#define PMAC_STRUCT(handle)  MAC_CONTEXT(handle)
+
+/**
+ * MAC_HANDLE() - Convert a mac context into an opaque mac handle
+ * @mac: MAC context to be converted
+ *
+ * Given a mac context this function will return the opaque mac handle
+ * that is associated with that handle.
+ *
+ * This is the inverse function of PMAC_STRUCT()
+ *
+ * Return: opaque handle for @mac
+ */
+static inline mac_handle_t MAC_HANDLE(tpAniSirGlobal mac)
+{
+	return (mac_handle_t)mac;
+}
 
 #define ANI_DRIVER_TYPE(pMac)     (((tpAniSirGlobal)(pMac))->gDriverType)
 

core/mac/inc/sir_types.h

@@ -30,15 +30,25 @@
 #include <qdf_types.h>
 
 
-/** ------------------------------------------------------------------------ *
-
-    \typedef tHalHandle
-
-    \brief Handle to the HAL.  The HAL handle is returned by the HAL after it
-    is opened (by calling halOpen).
+/**
+ * typedef mac_handle_t - MAC Handle
+ *
+ * Handle to the MAC.  The MAC handle is returned to the HDD from the
+ * UMAC on Open.  The MAC handle is an input to all UMAC function
+ * calls and represents an opaque handle to the UMAC instance that is
+ * tied to the HDD instance
+ *
+ * The UMAC must be able to derive it's internal instance structure
+ * pointer through this handle.
+ */
+/*
+ * NOTE WELL: an upcoming change will replace the void * with an
+ * opaque pointer just as is currently done with hdd_handle_t
+ */
+typedef void *mac_handle_t;
 
-    ------------------------------------------------------------------------- */
-typedef void *tHalHandle;
+/* retain legacy name until all instances have been replaced */
+typedef mac_handle_t tHalHandle;
 
 /**
  * typedef hdd_handle_t - HDD Handle