diff --git a/sims/xcelium/arg-reshuffle b/sims/xcelium/arg-reshuffle
index 7ccca217..08176864 100755
--- a/sims/xcelium/arg-reshuffle
+++ b/sims/xcelium/arg-reshuffle
@@ -1,4 +1,13 @@
 
+# this is a wrapper that is copied into xcelium sim run scripts that
+# re-maps arguments from the argument pattern used by other
+# simulators (vcs, verilator) to the pattern required by xcelium.
+#
+# mainly:
+# * +vcdfile=VAL -> XCELIUM_WAVEFORM_FLAG=VAL, to be passed in as env var
+# * arguments not prefixed with a + or - are treated as the arguments to
+#   the target and are passed in instead with the +target-argument plusarg
+
 regular_args=""
 target_args="+permissive"
 for var in "$@"