RDMA PCC

Programmable Congestion Control (PCC) APIs to configure user algorithms and parameters for a RDMA device.

Example

Here is an example of how to use the PCC APIs.

example_pcc.cc

#include <libmango.h>

typedef strict {
  ...
} my_algo_params;

static const my_algo_params initial_params = {
  ...
};

void
my_algo (void *params)
{
  my_algo_params *p = (my_algo_params *) params;
  unsigned int cnp = mango_pcc_event_cnp_cnt ();
  unsigned int cwnd = mango_pcc_window_current ();
  unsigned int nwnd;

  // calculate new window size
  nwnd = ...

  mango_pcc_window_update (nwnd);

  ...
}

int main() {
  // Create a PCC handle
  mango_pcc_h pcc;
  mango_pcc_create ("roce0", &pcc);

  // Configure PCC parameters
  mango_pcc_config_t config;
  config.option = MANGO_PCC_CONFIG_INTERVAL;
  config.value.interval_us = 60;
  mango_pcc_ctrl_config (pcc, &config);

  // Register PCC algorithm
  mango_pcc_ctrl_reg_algo (pcc, 1, algo, &initial_params, sizeof (initial_params));

  // Run PCC engine with 4 threads
  mango_pcc_ctrl_run (pcc, 4);
  ...

  // Stop PCC engine
  mango_pcc_ctrl_stop (pcc);
  mango_pcc_destroy (pcc);

  return 0;
}

Datatypes

mango_pcc_algo_fn

typedef void(void *) mango_pcc_algo_fn;

User-provided CC algorithm function.

mango_pcc_config_option_e

typedef enum _mango_pcc_config_option mango_pcc_config_option_e;

PCC configuration options.

Values

MANGO_PCC_CONFIG_INTERVAL

Algorithm execution interval

mango_pcc_config_t

typedef struct _mango_pcc_config mango_pcc_config_t;

PCC configuration value type.

Members

option	PCC configuration option
interval_us	microseconds

mango_pcc_event_e

typedef enum _mango_pcc_event mango_pcc_event_e;

PCC event types for mango_pcc_event_get_val()

mango_pcc_h

typedef void * mango_pcc_h;

A handle of mango pcc.

Functions

mango_pcc_create

mango_status_e mango_pcc_create(const char *roce_dev_name, mango_pcc_h *pcc)

Create a PCC handle.

Parameters

• in roce_dev_name Name of the roce device.
• out pcc Pointer to receive the newly created PCC handle.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_ctrl_config

mango_status_e mango_pcc_ctrl_config(mango_pcc_h pcc,
                                     const mango_pcc_config_t *config)

Set a PCC configuration value.

Parameters

• in pcc The PCC handle.
• in config The configuration value.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_ctrl_reg_algo

mango_status_e mango_pcc_ctrl_reg_algo(mango_pcc_h pcc,
                                       unsigned int slot,
                                       mango_pcc_algo_fn *algo,
                                       const void *initial_params,
                                       size_t param_size)

Register a congestion control algorithm callback.

Parameters

• in pcc The PCC handle.
• in slot The slot index at which to register the algorithm.
• in algo Pointer to the algorithm function to be invoked.
• in initial_params Pointer to the algorithm parameters with the initial values.
• in param_size The size of the parameter structure.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_ctrl_run

mango_status_e mango_pcc_ctrl_run(mango_pcc_h pcc, unsigned int num_threads)

Start the PCC control loop with a given number of threads.

Parameters

• in pcc The PCC handle.
• in num_threads Number of poller threads to spawn.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_ctrl_stop

mango_status_e mango_pcc_ctrl_stop(mango_pcc_h pcc)

Stop the PCC control loop.

Parameters

• in pcc The PCC handle.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_destroy

mango_status_e mango_pcc_destroy(mango_pcc_h pcc)

Destroy a PCC handle.

Parameters

• in pcc The PCC handle to destroy.

Returns 0 on success, Otherwise, a negative error value.

mango_pcc_event_get_val

unsigned int mango_pcc_event_get_val(mango_pcc_event_e event)

Get the value of a PCC event by type.

Parameters

• in event The PCC event type.

Returns The event value depending on type. 0 if not available.

note

This API must only be invoked internally by the PCC algorithm.

mango_pcc_event_request

mango_status_e mango_pcc_event_request(mango_pcc_event_e event)

Request a PCC event-specific action to the current executing QP.

Parameters

• in event The PCC event type.

Returns 0 on success, or a negative error code on failure.

mango_pcc_get_context

mango_context_h mango_pcc_get_context(mango_pcc_h pcc)

Get the context handle from a pcc handle.

Parameters

• in pcc The PCC handle.

Returns the context handle on success, Otherwise, nullptr.

note

DO NOT CALL mango_context_destroy with the result; it will be destroyed when mango_pcc_destroy is called.

mango_pcc_log

void mango_pcc_log(mango_log_level_e level, const char *fmt,...)

Print a log message with Poller index and QP number.

Parameters

• in level The log level.
• in fmt The format string.

note

The message will be ignore if the system log level is lower.

mango_pcc_window_current

unsigned int mango_pcc_window_current(void)

Get the current PCC window size of the QP.

Returns The current window size.

note

This API must only be invoked internally by the PCC algorithm.

mango_pcc_window_update

void mango_pcc_window_update(unsigned int new_window)

Update the PCC window size of the QP.

Parameters

• in new_window The new window size to set.