Merge pull request #989 from slaclab/include-driver-syncing-up

re-synchronizing with external aes-stream-drivers source code

include/rogue/hardware/drivers/AxisDriver.h

@@ -1,9 +1,14 @@
 /**
  *-----------------------------------------------------------------------------
- * Title      : AXIS DMA Driver, Shared Header
+ * Company    : SLAC National Accelerator Laboratory
  * ----------------------------------------------------------------------------
  * Description:
- * Definitions and inline functions for interacting with AXIS driver.
+ *    This file contains definitions and inline functions for interacting
+ *    with the AXIS driver as part of the aes_stream_drivers package.
+ *
+ *    It includes functionalities for setting flags within the AXIS protocol
+ *    and performing specific actions such as acknowledging reads and indicating
+ *    missed write requests.
  * ----------------------------------------------------------------------------
  * This file is part of the aes_stream_drivers package. It is subject to
  * the license terms in the LICENSE.txt file found in the top-level directory
@@ -14,46 +19,88 @@
  * contained in the LICENSE.txt file.
  * ----------------------------------------------------------------------------
  **/
+
 #ifndef __ASIS_DRIVER_H__
 #define __ASIS_DRIVER_H__
 #include "DmaDriver.h"
 
-// Commands
-#define AXIS_Read_Ack 0x2001
+// Command definitions
+#define AXIS_Read_Ack 0x2001          // Command to acknowledge read
+#define AXIS_Write_ReqMissed 0x2002   // Command to indicate a missed write request
 
-// Everything below is hidden during kernel module compile
+// Only define the following if not compiling for kernel space
 #ifndef DMA_IN_KERNEL
 
-// Set flags
-// static constexpr inline uint32_t axisSetFlags(uint32_t fuser, uint32_t luser, uint32_t cont) {
-//   return ( ((cont & 0x1) << 16)  | ((luser & 0xFF) << 8) | ((fuser & 0xFF) << 0) );
-//}
-
+/**
+ * Set flags for AXIS transactions.
+ *
+ * @param fuser First user-defined flag.
+ * @param luser Last user-defined flag.
+ * @param cont  Continuation flag.
+ *
+ * @return The combined flags value.
+ */
 static inline uint32_t axisSetFlags(uint32_t fuser, uint32_t luser, uint32_t cont) {
-    uint32_t flags;
+   uint32_t flags;
 
-    flags = fuser & 0xFF;
-    flags += (luser << 8) & 0xFF00;
-    flags += (cont << 16) & 0x10000;
-    return (flags);
+   // Set flags based on input parameters, ensuring each is in its correct position
+   flags  = fuser & 0xFF;            // First user-defined flag
+   flags |= (luser << 8) & 0xFF00;   // Last user-defined flag
+   flags |= (cont  << 16) & 0x10000; // Continuation flag
+
+   return flags;
 }
 
+/**
+ * Extract the first user-defined flag from the combined flags.
+ *
+ * @param flags The combined flags value.
+ *
+ * @return The first user-defined flag.
+ */
 static inline uint32_t axisGetFuser(uint32_t flags) {
-    return (flags & 0xFF);
+   return flags & 0xFF;
 }
 
+/**
+ * Extract the last user-defined flag from the combined flags.
+ *
+ * @param flags The combined flags value.
+ *
+ * @return The last user-defined flag.
+ */
 static inline uint32_t axisGetLuser(uint32_t flags) {
-    return ((flags >> 8) & 0xFF);
+   return (flags >> 8) & 0xFF;
 }
 
+/**
+ * Extract the continuation flag from the combined flags.
+ *
+ * @param flags The combined flags value.
+ *
+ * @return The continuation flag.
+ */
 static inline uint32_t axisGetCont(uint32_t flags) {
-    return ((flags >> 16) & 0x1);
+   return (flags >> 16) & 0x1;
 }
 
-// Read ACK
+/**
+ * Acknowledge a read operation.
+ *
+ * @param fd File descriptor for the AXIS device.
+ */
 static inline void axisReadAck(int32_t fd) {
-    ioctl(fd, AXIS_Read_Ack, 0);
+   ioctl(fd, AXIS_Read_Ack, 0);
+}
+
+/**
+ * Indicate a missed write request.
+ *
+ * @param fd File descriptor for the AXIS device.
+ */
+static inline void axisWriteReqMissed(int32_t fd) {
+   ioctl(fd, AXIS_Write_ReqMissed, 0);
 }
 
-#endif
-#endif
+#endif // !DMA_IN_KERNEL
+#endif // __ASIS_DRIVER_H__