Skip to main content

Device Context

Context is a core instance to manage a MangoBoost DPU device. Each context has associated a device handle. Some APIs to access a device must be called through the context. Refer to related API documents for more details.

Example​

Here is an example of checking HW features of a DPU device.

example_dpu_features.cc
#include <libmango.h>

int main() {
  // Create a context
  mango_context_h context;
  mango_context_create (&context);

  // Get available DPU devices
  unsigned dev_num;
  unsigned *dev_idx = mango_get_hw_accel (MANGO_HW_ACCEL_DPU, &dev_num);

  if (dev_num < 0)
    return -ENOSUP;

  // Use the first DPU device
  mango_context_set_hw_accel (context, MANGO_HW_ACCEL_DPU, dev_idx[0]);

  bool enabled;
  
  // Check TCP/IP offload (TOE) feature
  mango_context_check_feature (context, MANGO_HW_FEATURE_TOE, &enabled);
  if (enabled)
    mango_log (MANGO_LOG_LEVEL_INFO, "/dev/mango%u supports TOE\n", dev_idx[0]);
 
  // Check RDMA (RoCEv2) feature
  mango_context_check_feature (context, MANGO_HW_FEATURE_RDMA, &enabled);
  if (enabled)
    mango_log (MANGO_LOG_LEVEL_INFO, "/dev/mango%u supports RDMA\n", dev_idx[0]);

  ...

  // Cleanup
  mango_context_destroy (context);

  return 0;
}

Datatypes​

mango_context_h​

typedef void * mango_context_h;

A handle of mango context.

Functions​

mango_context_create​

mango_status_e mango_context_create(mango_context_h *context)

Create mango context.

Parameters

  • out context The output context handle.

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

mango_context_destroy​

mango_status_e mango_context_destroy(mango_context_h context)

Destroy mango context.

Parameters

  • in context The context handle to be destroyed.

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

mango_context_reset​

mango_status_e mango_context_reset(mango_context_h context)

Reset mango context.

Parameters

  • in context The context handle.

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

mango_context_set_hw_accel​

mango_status_e mango_context_set_hw_accel(mango_context_h context,
                                          mango_hw_accel_e accel,
                                          int idx)

Set HW accelerator.

Parameters

  • in context The context handle.
  • in accel The HW accelerator.
  • in idx The HW accelerator index.

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

note

A negative idx targets any available device.

mango_context_get_accel_index​

mango_status_e mango_context_get_accel_index(mango_context_h context, int *idx)

Get HW accelerator index.

Parameters

  • in context The context handle.
  • out idx The HW accelerator index.

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

mango_context_get_accel_name​

mango_status_e mango_context_get_accel_name(mango_context_h context,
                                            char **name)

Get HW accelerator name.

Parameters

  • in context The context handle.
  • out name The name of associated accelerator.

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

note

The caller should free the output name using free().

mango_context_get_config​

mango_status_e mango_context_get_config(mango_context_h context,
                                        const char *field,
                                        char **value)

Get a config value from the mango context.

Parameters

  • in context The context handle.
  • in field The config field.
  • out value The config value newly allocated.

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

note

The caller should free the option value using free().

mango_context_set_config​

mango_status_e mango_context_set_config(mango_context_h context,
                                        const char *field,
                                        const char *value)

Set a config value to the mango context.

Parameters

  • in context The context handle.
  • in field The config field.
  • in value The config value.

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

mango_context_get_control​

mango_status_e mango_context_get_control(mango_context_h context,
                                         const char *field,
                                         char **value)

Get a control value from the mango context.

Parameters

  • in context The context handle.
  • in field The control field.
  • out value The control value newly allocated.

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

note

The caller should free the option value using free().

mango_context_set_control​

mango_status_e mango_context_set_control(mango_context_h context,
                                         const char *field,
                                         const char *value)

Set a control value to the mango context.

Parameters

  • in context The context handle.
  • in field The control field.
  • in value The control value.

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

mango_context_check_feature​

mango_status_e mango_context_check_feature(mango_context_h context,
                                           mango_hw_feature_e feature,
                                           bool *enabled)

Check the feature availability in the context.

Parameters

  • in context The context handle.
  • in feature The feature enum.
  • out enabled True if the feature is enabled.

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

mango_context_load_images​

mango_status_e mango_context_load_images(mango_context_h context,
                                         const char **images,
                                         unsigned int num)

Load image files.

Parameters

  • in context The context context.
  • in images The file path of images to be loaded.
  • in num The number of images.

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

mango_context_load_images_iov​

mango_status_e mango_context_load_images_iov(mango_context_h context,
                                             const struct iovec *iov,
                                             unsigned int iovcnt)

Load image buffers using I/O vector.

Parameters

  • in context The context context.
  • in iov I/O vectors with image buffers to be loaded.
  • in iovcnt I/O vector entry count.

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

mango_context_num_loaded_images​

mango_status_e mango_context_num_loaded_images(mango_context_h context,
                                               unsigned int *num)

Get number of loaded images.

Parameters

  • in context The context context.
  • out num The number of loaded images.

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

mango_context_decode_images​

mango_status_e mango_context_decode_images(mango_context_h context,
                                           mango_image_info_t *info)

Decode the loaded images.

Parameters

  • in context The created context.
  • out info (Optional) The detail info. of decoded images.

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

note

A caller has to allocate the buffer for 'info'.

mango_context_set_gpu_data​

mango_status_e mango_context_set_gpu_data(mango_context_h context,
                                          mango_gpu_h gpu,
                                          void *data,
                                          size_t size)

Set the GPU data buffer to be used.

Parameters

  • in context The created context.
  • in gpu The GPU handle.
  • in data The GPU data buffer.
  • in size The buffer size.

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

mango_context_images_to_gpu​

mango_status_e mango_context_images_to_gpu(mango_context_h context,
                                           mango_gpu_h gpu,
                                           uint64_t offset)

Deliver the decoded images to the given GPU device.

Parameters

  • in context The context handle.
  • in gpu The GPU handle to get the decoded images.
  • in offset The GPU memory offset

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

mango_context_map_memory​

mango_status_e mango_context_map_memory(mango_context_h context,
                                        mango_memory_h mem)

Map the memory to the context.

Parameters

  • in context The context handle.
  • in mem The memory handle.

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

mango_context_unmap_memory​

mango_status_e mango_context_unmap_memory(mango_context_h context,
                                          mango_memory_h mem)

Unmap the memory from the context.

Parameters

  • in context The context handle.
  • in mem The memory handle.

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

mango_context_map_dma​

mango_status_e mango_context_map_dma(mango_context_h context,
                                     void *data,
                                     size_t size,
                                     uint64_t *addr)

Map the user data as dma memory to the context.

Parameters

  • in context The context handle.
  • in data The user data.
  • in size The user data size.
  • out addr The dma memory address.

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

note

The user data should be physically contiguous.

mango_context_unmap_dma​

mango_status_e mango_context_unmap_dma(mango_context_h context,
                                       uint64_t addr,
                                       size_t size)

Unmap the user dma memory from the context.

Parameters

  • in context The context handle.
  • in addr The dma memory address.
  • in size The dma memory size.

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

mango_context_set_ppe​

mango_status_e mango_context_set_ppe(mango_context_h context, mango_ppe_h ppe)

Deliver the p4 pipeline spec info to the given DPU.

Parameters

  • in context The context handle.
  • in ppe The p4 pipeline spec.

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