chore(docs): replace IN and OUT macros with docs

userspace/libscap/engine/bpf/scap_bpf.c

@@ -1661,7 +1661,7 @@ int32_t scap_bpf_load(
 	return SCAP_SUCCESS;
 }
 
-int32_t scap_bpf_get_stats(struct scap_engine_handle engine, OUT scap_stats* stats)
+int32_t scap_bpf_get_stats(struct scap_engine_handle engine, scap_stats* stats)
 {
 	struct bpf_engine *handle = engine.m_handle;
 	int j;
@@ -1703,7 +1703,7 @@ int32_t scap_bpf_get_stats(struct scap_engine_handle engine, OUT scap_stats* sta
 	return SCAP_SUCCESS;
 }
 
-const struct metrics_v2* scap_bpf_get_stats_v2(struct scap_engine_handle engine, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc)
+const struct metrics_v2* scap_bpf_get_stats_v2(struct scap_engine_handle engine, uint32_t flags, uint32_t* nstats, int32_t* rc)
 {
 	struct bpf_engine *handle = engine.m_handle;
 	int ret;
@@ -1879,7 +1879,7 @@ int32_t scap_bpf_get_n_tracepoint_hit(struct scap_engine_handle engine, long* re
 	return SCAP_SUCCESS;
 }
 
-static int32_t next(struct scap_engine_handle engine, OUT scap_evt **pevent, OUT uint16_t *pdevid, OUT uint32_t *pflags)
+static int32_t next(struct scap_engine_handle engine, scap_evt **pevent, uint16_t *pdevid, uint32_t *pflags)
 {
 	return ringbuffer_next(&engine.m_handle->m_dev_set, pevent, pdevid, pflags);
 }

userspace/libscap/engine/kmod/scap_kmod.c

@@ -526,8 +526,8 @@ int32_t scap_kmod_close(struct scap_engine_handle engine)
 	return SCAP_SUCCESS;
 }
 
-int32_t scap_kmod_next(struct scap_engine_handle engine, OUT scap_evt **pevent, OUT uint16_t *pdevid,
-		       OUT uint32_t *pflags)
+int32_t scap_kmod_next(struct scap_engine_handle engine, scap_evt **pevent, uint16_t *pdevid,
+		       uint32_t *pflags)
 {
 	return ringbuffer_next(&engine.m_handle->m_dev_set, pevent, pdevid, pflags);
 }
@@ -578,7 +578,7 @@ int32_t scap_kmod_get_stats(struct scap_engine_handle engine, scap_stats* stats)
 	return SCAP_SUCCESS;
 }
 
-const struct metrics_v2* scap_kmod_get_stats_v2(struct scap_engine_handle engine, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc)
+const struct metrics_v2* scap_kmod_get_stats_v2(struct scap_engine_handle engine, uint32_t flags, uint32_t* nstats, int32_t* rc)
 {
 	struct kmod_engine *handle = engine.m_handle;
 	struct scap_device_set *devset = &handle->m_dev_set;

userspace/libscap/engine/modern_bpf/scap_modern_bpf.c

@@ -49,8 +49,8 @@ static void scap_modern_bpf__free_engine(struct scap_engine_handle engine)
 /* The third parameter is not the CPU number from which we extract the event but the ring buffer number.
  * For the old BPF probe and the kernel module the number of CPUs is equal to the number of buffers since we always use a per-CPU approach.
  */
-static int32_t scap_modern_bpf__next(struct scap_engine_handle engine, OUT scap_evt** pevent, OUT uint16_t* buffer_id,
-				     OUT uint32_t* pflags)
+static int32_t scap_modern_bpf__next(struct scap_engine_handle engine, scap_evt** pevent, uint16_t* buffer_id,
+				     uint32_t* pflags)
 {
 	pman_consume_first_event((void**)pevent, (int16_t*)buffer_id);
 
@@ -250,7 +250,7 @@ static uint32_t scap_modern_bpf__get_n_devs(struct scap_engine_handle engine)
 	return pman_get_required_buffers();
 }
 
-int32_t scap_modern_bpf__get_stats(struct scap_engine_handle engine, OUT scap_stats* stats)
+int32_t scap_modern_bpf__get_stats(struct scap_engine_handle engine, scap_stats* stats)
 {
 	if(pman_get_scap_stats(stats))
 	{
@@ -259,7 +259,7 @@ int32_t scap_modern_bpf__get_stats(struct scap_engine_handle engine, OUT scap_st
 	return SCAP_SUCCESS;
 }
 
-const struct metrics_v2* scap_modern_bpf__get_stats_v2(struct scap_engine_handle engine, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc)
+const struct metrics_v2* scap_modern_bpf__get_stats_v2(struct scap_engine_handle engine, uint32_t flags, uint32_t* nstats, int32_t* rc)
 {
 	struct modern_bpf_engine* handle = engine.m_handle;
 	if (!(handle->m_flags & ENGINE_FLAG_BPF_STATS_ENABLED))
@@ -270,7 +270,7 @@ const struct metrics_v2* scap_modern_bpf__get_stats_v2(struct scap_engine_handle
 	return pman_get_metrics_v2(flags, nstats, rc);
 }
 
-int32_t scap_modern_bpf__get_n_tracepoint_hit(struct scap_engine_handle engine, OUT long* ret)
+int32_t scap_modern_bpf__get_n_tracepoint_hit(struct scap_engine_handle engine, long* ret)
 {
 	if(pman_get_n_tracepoint_hit(ret))
 	{

userspace/libscap/engine/source_plugin/source_plugin.c

@@ -156,7 +156,7 @@ static int close_engine(struct scap_engine_handle engine)
 	return SCAP_SUCCESS;
 }
 
-static int32_t next(struct scap_engine_handle engine, OUT scap_evt** pevent, OUT uint16_t* pdevid, OUT uint32_t* pflags)
+static int32_t next(struct scap_engine_handle engine, scap_evt** pevent, uint16_t* pdevid, uint32_t* pflags)
 {
 	struct source_plugin_engine *handle = engine.m_handle;
 	char *lasterr = engine.m_handle->m_lasterr;
@@ -267,14 +267,14 @@ static int32_t next(struct scap_engine_handle engine, OUT scap_evt** pevent, OUT
 	return SCAP_SUCCESS;
 }
 
-static int32_t get_stats(struct scap_engine_handle engine, OUT scap_stats* stats)
+static int32_t get_stats(struct scap_engine_handle engine, scap_stats* stats)
 {
 	struct source_plugin_engine *handle = engine.m_handle;
 	stats->n_evts = handle->m_nevts;
 	return SCAP_SUCCESS;
 }
 
-const struct metrics_v2* get_source_plugin_stats_v2(struct scap_engine_handle engine, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc)
+const struct metrics_v2* get_source_plugin_stats_v2(struct scap_engine_handle engine, uint32_t flags, uint32_t* nstats, int32_t* rc)
 {
 	struct source_plugin_engine *handle = engine.m_handle;
 	*nstats = MAX_SOURCE_PLUGIN_COUNTERS_STATS;

userspace/libscap/examples/02-validatebuffer/test.c

@@ -46,7 +46,7 @@ size_t g_get_event_size(ppm_event_code event_type, uint16_t* lens)
 #endif
 }
 
-int32_t g_check_integrity(uint32_t* cur_event, char* copy_buffer, int buf_len, OUT uint32_t* nevents)
+int32_t g_check_integrity(uint32_t* cur_event, char* copy_buffer, int buf_len, uint32_t* nevents)
 {
 	uint32_t offset = 0;
 	*nevents = 0;

userspace/libscap/linux/scap_ppm_sc.c

@@ -462,7 +462,7 @@ static const ppm_sc_code *g_events_to_sc_map[] = {
 _Static_assert(sizeof(g_events_to_sc_map) / sizeof(*g_events_to_sc_map) == PPM_EVENT_MAX, "Missing entries in g_events_to_sc_map table.");
 #endif
 
-int scap_get_modifies_state_ppm_sc(OUT uint8_t ppm_sc_array[PPM_SC_MAX])
+int scap_get_modifies_state_ppm_sc(uint8_t ppm_sc_array[PPM_SC_MAX])
 {
 	if(ppm_sc_array == NULL)
 	{
@@ -500,7 +500,7 @@ int scap_get_modifies_state_ppm_sc(OUT uint8_t ppm_sc_array[PPM_SC_MAX])
 	return SCAP_SUCCESS;
 }
 
-int scap_get_events_from_ppm_sc(IN const uint8_t ppm_sc_array[PPM_SC_MAX], OUT uint8_t events_array[PPM_EVENT_MAX])
+int scap_get_events_from_ppm_sc(const uint8_t ppm_sc_array[PPM_SC_MAX], uint8_t events_array[PPM_EVENT_MAX])
 {
 	if(ppm_sc_array == NULL || events_array == NULL)
 	{
@@ -531,7 +531,7 @@ int scap_get_events_from_ppm_sc(IN const uint8_t ppm_sc_array[PPM_SC_MAX], OUT u
 	return SCAP_SUCCESS;
 }
 
-int scap_get_ppm_sc_from_events(IN const uint8_t events_array[PPM_EVENT_MAX], OUT uint8_t ppm_sc_array[PPM_SC_MAX])
+int scap_get_ppm_sc_from_events(const uint8_t events_array[PPM_EVENT_MAX], uint8_t ppm_sc_array[PPM_SC_MAX])
 {
 	if (events_array == NULL || ppm_sc_array == NULL)
 	{

userspace/libscap/ringbuffer/ringbuffer.h

@@ -86,7 +86,11 @@ static inline void ringbuffer_advance_tail(struct scap_device* dev)
 
 #ifndef READBUF
 #define READBUF ringbuffer_readbuf
-static inline int32_t ringbuffer_readbuf(struct scap_device *dev, OUT char** buf, OUT uint32_t* len)
+/**
+ * \param buf [out] buffer holding the returned data
+ * \param len [out] number of bytes read into buf
+ */
+static inline int32_t ringbuffer_readbuf(struct scap_device *dev, char** buf, uint32_t* len)
 {
 	uint64_t thead;
 	uint64_t ttail;
@@ -197,22 +201,30 @@ static inline void ringbuffer_advance_to_evt(scap_device* dev, scap_evt *event)
 }
 #endif
 
-/* The flow here is:
+/**
+ * \brief Get next event in the ringbuffer
+ *
+ * The flow here is:
  * - For every buffer, read how many data are available and save the pointer + its length. (this is what we call a block)
  * - Consume from all these blocks the event with the lowest timestamp. (repeat until all the blocks are empty!)
  *   When we have read all the data from a buffer block, update the consumer position for that buffer, and wait
  *   for all the other buffer blocks to be read.
  * - When we have consumed all the blocks we are ready to read again a new block for every buffer
- * 
+ *
  * Possible pain points:
  * - if the buffers are not full enough we sleep and this could be dangerous in this situation!
  * - we increase the consumer position only when we have consumed the entire block, but if the block
  *   is huge we could cause several drops.
  * - before refilling a buffer we have to consume all the others!
  * - we perform a lot of cycles but we have to be super fast here!
+ *
+ * \param pevent [out] where the pointer to the next event gets stored
+ * \param pdevid [out] where the device on which the event was received
+ *               gets stored
+ * \param pflags [out] where the flags for the event get stored
  */
-static inline int32_t ringbuffer_next(struct scap_device_set* devset, OUT scap_evt** pevent, OUT uint16_t* pdevid,
-				      OUT uint32_t* pflags)
+static inline int32_t ringbuffer_next(struct scap_device_set* devset, scap_evt** pevent, uint16_t* pdevid,
+				      uint32_t* pflags)
 {
 	uint32_t j;
 	uint64_t min_ts = 0xffffffffffffffffLL;

userspace/libscap/scap.c

@@ -211,7 +211,7 @@ uint32_t scap_get_ndevs(scap_t* handle)
 	return 1;
 }
 
-int32_t scap_readbuf(scap_t* handle, uint32_t cpuid, OUT char** buf, OUT uint32_t* len)
+int32_t scap_readbuf(scap_t* handle, uint32_t cpuid, char** buf, uint32_t* len)
 {
 	// engines do not even necessarily have a concept of a buffer
 	// that you read events from
@@ -227,7 +227,7 @@ uint64_t scap_max_buf_used(scap_t* handle)
 	return 0;
 }
 
-int32_t scap_next(scap_t* handle, OUT scap_evt** pevent, OUT uint16_t* pdevid, OUT uint32_t* pflags)
+int32_t scap_next(scap_t* handle, scap_evt** pevent, uint16_t* pdevid, uint32_t* pflags)
 {
 	// Note: devid is like cpuid but not 1:1, e.g. consider CPU1 offline:
 	// CPU0 CPU1 CPU2 CPU3
@@ -254,7 +254,7 @@ int32_t scap_next(scap_t* handle, OUT scap_evt** pevent, OUT uint16_t* pdevid, O
 //
 // Return the number of dropped events for the given handle.
 //
-int32_t scap_get_stats(scap_t* handle, OUT scap_stats* stats)
+int32_t scap_get_stats(scap_t* handle, scap_stats* stats)
 {
 	if(!handle || stats == NULL)
 	{
@@ -297,7 +297,7 @@ int32_t scap_get_stats(scap_t* handle, OUT scap_stats* stats)
 //
 // Return engine statistics (including counters and `bpftool prog show` like stats)
 //
-const struct metrics_v2* scap_get_stats_v2(scap_t* handle, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc)
+const struct metrics_v2* scap_get_stats_v2(scap_t* handle, uint32_t flags, uint32_t* nstats, int32_t* rc)
 {
 	if(handle && handle->m_vtable)
 	{

userspace/libscap/scap.h

@@ -459,13 +459,6 @@ typedef struct scap_const_sized_buffer scap_const_sized_buffer;
 
 /*@}*/
 
-///////////////////////////////////////////////////////////////////////////////
-// Structs and defines used internally
-///////////////////////////////////////////////////////////////////////////////
-
-#define IN
-#define OUT
-
 ///////////////////////////////////////////////////////////////////////////////
 // API functions
 ///////////////////////////////////////////////////////////////////////////////
@@ -566,17 +559,17 @@ uint64_t scap_max_buf_used(scap_t* handle);
   \brief Get the next event from the from the given capture instance
 
   \param handle Handle to the capture instance.
-  \param pevent User-provided event pointer that will be initialized with address of the event.
-  \param pdevid User-provided event pointer that will be initialized with the ID of the device
+  \param pevent [out] User-provided event pointer that will be initialized with address of the event.
+  \param pdevid [out] User-provided event pointer that will be initialized with the ID of the device
     where the event was captured.
-  \param pflags User-provided event pointer that will be initialized with the flags of the event.
+  \param pflags [out] User-provided event pointer that will be initialized with the flags of the event.
 
   \return SCAP_SUCCESS if the call is successful and pevent, pcpuid and pflags contain valid data.
    SCAP_TIMEOUT in case the read timeout expired and no event is available.
    SCAP_EOF when the end of an offline capture is reached.
    On Failure, SCAP_FAILURE is returned and scap_getlasterr() can be used to obtain the cause of the error.
 */
-int32_t scap_next(scap_t* handle, OUT scap_evt** pevent, OUT uint16_t* pcpuid, OUT uint32_t* pflags);
+int32_t scap_next(scap_t* handle, scap_evt** pevent, uint16_t* pcpuid, uint32_t* pflags);
 
 /*!
   \brief Get the length of an event
@@ -636,41 +629,49 @@ int64_t scap_get_readfile_offset(scap_t* handle);
   \brief Return the capture statistics for the given capture handle.
 
   \param handle Handle to the capture instance.
-  \param stats Pointer to a \ref scap_stats structure that will be filled with the
+  \param stats [out] Pointer to a \ref scap_stats structure that will be filled with the
   statistics.
 
   \return SCAP_SECCESS if the call is successful.
    On Failure, SCAP_FAILURE is returned and scap_getlasterr() can be used to obtain
    the cause of the error.
 */
-int32_t scap_get_stats(scap_t* handle, OUT scap_stats* stats);
+int32_t scap_get_stats(scap_t* handle, scap_stats* stats);
 
 /*!
   \brief Get engine statistics (including counters and `bpftool prog show` like stats)
 
   \param handle Handle to the capture instance.
   \param flags holding statistics category flags.
-  \param nstats Pointer reflecting number of statistics in returned buffer.
-  \param rc Pointer to return code.
+  \param nstats [out] Pointer reflecting number of statistics in returned buffer.
+  \param rc [out] Pointer to return code.
 
   \return Pointer to a \ref metrics_v2 structure filled with the statistics.
 */
-const struct metrics_v2* scap_get_stats_v2(scap_t* handle, uint32_t flags, OUT uint32_t* nstats, OUT int32_t* rc);
+const struct metrics_v2* scap_get_stats_v2(scap_t* handle, uint32_t flags, uint32_t* nstats, int32_t* rc);
 
 /*!
   \brief Returns the set of ppm_sc whose events have EF_MODIFIES_STATE flag or whose syscall have UF_NEVER_DROP flag.
+
+  \param ppm_sc_array [out] the array of ppm_sc that had their state modified
 */
-int scap_get_modifies_state_ppm_sc(OUT uint8_t ppm_sc_array[PPM_SC_MAX]);
+int scap_get_modifies_state_ppm_sc(uint8_t ppm_sc_array[PPM_SC_MAX]);
 
 /*!
   \brief Take an array of `ppm_sc` as input and provide the associated array of events as output.
+
+  \param ppm_sc_array [in] the `ppm_sc` to look for
+  \param events_array [out] the array of events associated to the provided `ppm_sc`s
 */
-int scap_get_events_from_ppm_sc(IN const uint8_t ppm_sc_array[PPM_SC_MAX], OUT uint8_t events_array[PPM_EVENT_MAX]);
+int scap_get_events_from_ppm_sc(const uint8_t ppm_sc_array[PPM_SC_MAX], uint8_t events_array[PPM_EVENT_MAX]);
 
 /*!
   \brief Take an array of `ppm_event_code` as input and provide the associated array of ppm_sc as output.
+
+  \param events_array [in] the array of events to look for
+  \param ppm_sc_array [out] the array of `ppm_sc`s associated to the provided events
 */
-int scap_get_ppm_sc_from_events(IN const uint8_t events_array[PPM_EVENT_MAX], OUT uint8_t ppm_sc_array[PPM_SC_MAX]);
+int scap_get_ppm_sc_from_events(const uint8_t events_array[PPM_EVENT_MAX], uint8_t ppm_sc_array[PPM_SC_MAX]);
 
 /*!
   \brief Given a name, returns associated ppm_sc.
@@ -856,8 +857,13 @@ uint64_t scap_get_engine_flags(scap_t* handle);
 //
 uint32_t scap_get_ndevs(scap_t* handle);
 
-// Retrieve a buffer of events from one of the cpus
-extern int32_t scap_readbuf(scap_t* handle, uint32_t cpuid, OUT char** buf, OUT uint32_t* len);
+/*
+ * \brief Retrieve a buffer of events from one of the cpus
+ *
+ * \param buf [out] buffer holding the returned events
+ * \param len [out] number of bytes read into buf
+ */
+extern int32_t scap_readbuf(scap_t* handle, uint32_t cpuid, char** buf, uint32_t* len);
 
 #ifdef PPM_ENABLE_SENTINEL
 // Get the sentinel at the beginning of the event

userspace/libscap/scap_vtable.h

@@ -208,16 +208,16 @@ struct scap_vtable {
 	/**
 	 * @brief get engine statistics
 	 * @param engine wraps the pointer to the engine-specific handle
-	 * @param stats the stats struct to be filled
+	 * @param stats [out] the stats struct to be filled
 	 * @return SCAP_SUCCESS or a failure code
 	 */
 	int32_t (*get_stats)(struct scap_engine_handle engine, struct scap_stats *stats);
 
 	/**
 	 * @brief get engine statistics (including counters and `bpftool prog show` like stats)
 	 * @param flags holding statistics category flags
-	 * @param nstats Pointer reflecting number of statistics in returned buffer
-	 * @param rc Pointer to return code
+	 * @param nstats [out] Pointer reflecting number of statistics in returned buffer
+	 * @param rc [out] Pointer to return code
 	 * @return Pointer to a \ref metrics_v2 structure filled with the statistics
 	 */
 	const struct metrics_v2* (*get_stats_v2)(struct scap_engine_handle engine, uint32_t flags, uint32_t* nstats, int32_t* rc);

userspace/libsinsp/event.cpp

@@ -825,7 +825,7 @@ std::string sinsp_evt::get_base_dir(uint32_t id, sinsp_threadinfo *tinfo)
 	return rel_path_base;
 }
 
-const char* sinsp_evt::get_param_as_str(uint32_t id, OUT const char** resolved_str, sinsp_evt::param_fmt fmt)
+const char* sinsp_evt::get_param_as_str(uint32_t id, const char** resolved_str, sinsp_evt::param_fmt fmt)
 {
 	char* prfmt = NULL;
 	const ppm_param_info* param_info = NULL;
@@ -1852,7 +1852,7 @@ std::string sinsp_evt::get_param_value_str(uint32_t i, bool resolved)
 	}
 }
 
-const char* sinsp_evt::get_param_value_str(std::string_view name, OUT const char** resolved_str, param_fmt fmt)
+const char* sinsp_evt::get_param_value_str(std::string_view name, const char** resolved_str, param_fmt fmt)
 {
 	for(uint32_t i = 0; i < get_num_params(); i++)
 	{
@@ -1866,7 +1866,7 @@ const char* sinsp_evt::get_param_value_str(std::string_view name, OUT const char
 	return NULL;
 }
 
-void sinsp_evt::get_category(OUT sinsp_evt::category* cat) const
+void sinsp_evt::get_category(sinsp_evt::category* cat) const
 {
 	/* We always search the category inside the event table */
 	cat->m_category = get_category();
@@ -1940,7 +1940,7 @@ bool sinsp_evt::is_filtered_out() const
 	return m_filtered_out;
 }
 
-scap_dump_flags sinsp_evt::get_dump_flags(OUT bool* should_drop) const
+scap_dump_flags sinsp_evt::get_dump_flags(bool* should_drop) const
 {
 	uint32_t dflags = SCAP_DF_NONE;
 	*should_drop = false;