Documentation

LVE userland API

• Home
•  > 
• Documentation

currently LVE userland API consist three files lve-ctl.h and liblve.so for dynamic and liblve.a for static linking.

Data Structures

struct liblve_settings { 
int32_t ls_cpu; /** cpu power */ 
int32_t ls_cpus; /** number cores */ 
int32_t ls_io; /** io limit */  int32_t ls_enters; /** enter processes limit */  
int32_t ls_memory; /** mem limit in 4096 pages */ 
}; 

enum lve_flags { 
    LVE_NO_UBC = 1 << 0, /** < enter without attaching ubc counter (no memory limits) */  
   LVE_NAMESPACE = 1 << 1, /** < enter in lve VFS namespace (securelve, reserved) */ 
     LVE_NO_MAXENTER = 1 << 2, /** < don't apply entry processes limits */  
}; 

Check availability 

• int lve_is_available(void);
  return 1 if lve is available
  0 otherwise.

Admin functions 

• lve_set_default1(struct liblve *lve, struct liblve_settings *set);
  set default parameters for newly created light weight virtual environments.
  
  • args: 
    lve - pointer to fully init lve library instance.
    set - pointer to lve settings
  • returns: 
    0 OK, otherwise is error.
• int lve_set_default(uint32_t cpu, uint32_t io);
  set default parameters for newly created light weight virtual environments. 
  
  • args: 
    cpu - default CPU power 
    io - default IO priority 
    returns: 
    0 OK, otherwise is error.
  int lve_create(uint32_t ve_id);
  create custom configured virtual environment
      args:
      ve_id = id associated with new created LVE
  
  int lve_destroy(uint32_t ve_id);
  destroy configured virtual environment
      args:
      ve_id = id associated with LVE
• 
  
• int lve_setup(uint32_t ve_id, int32_t cpu, int32_t io, int32_t maxentryproc)
  adjust parameters for virtual environment. if ve not exist, that will be created.
      args:
      ve_id = id associated with LVE
      cpu - CPU power, -1 if don't adjust
      io - IO priority, -1 if don't set 
      maxentryproc -- max number of entry processes
• 
  int lve_setup_enter(uint32_t ve_id, int32_t cpu, int32_t io, int32_t maxentryproc, uint32_t *cookie); 
  setup virtual environment and enter into (puts current process in LVE) if setup successully finished.
  We can't leave from it!!
      args:
      ve_id = id associated with LVE
      cpu - CPU power, -1 if don't adjust
      io - IO priority, -1 if don't set 
      maxentryproc -- max number of entry processes
      cookie = pointer to cookie, which returned if task correctly migrated in LVE and used to leave from this LVE
      returns: 0 = OK,
      negative return code means an errors:
      -EPERM - don't have permissions, or called from outside ROOT VE
      -ENOMEM - don't have memory to allocate new VE
      -EFAULT - cookie or parameters is bad pointer or kernel not able read/write from that pointer
      -E2BIG - too many enters in LVE
      -EALEADY - lve_enter to enter ROOT context (same as called).
      -EINVAL - some invalid arguments (mostly used in fairsched rate).
      -EBUSY - scheduler node isn't deleted correctly before enter
      -ENOSPC - radix tree is overloaded.
  
  int lve_info(uint32_t ve_id, int32_t *cpu, int32_t *io, int32_t *maxenters)
  get info about context
      args:
      ve_id = id associated with LVE
      cpu - CPU 
      io - IO priority
      maxenters - max entry procs
      returns: 0 - result is ok

application functions 

• struct liblve *init_lve(liblve_alloc alloc, liblve_free free);
  instantiates LVE
• args
  alloc - pointer to function to allocate memory
  free - pointer to function to free allocated memory
  returns
  NULL on error, errno will be set. 
  errno will be EINVAL/ENOSYS if incompatible versions kernel and liblve used.
• 
  
• int lve_instance_init(struct liblve *lve); /* deprecated */ 
  create lve library instance
  args 
  libvlve - pointer to allocated memory to store per instance info
  or NULL to return how many memory need for per
  instance structure.
  return codes:
  > 0, size of lve instance structure, if liblve == NULL.
  0 = if instance is correctly init.
  < 0, if any error is hit
• 
  
• *int destroy_lve(struct liblve *lve); 
•  /* The use of this function is not recommended. It can crash server on production system */ 
  destroy lve library instance
  args: 
  lve = instantiated liblive instance
  return 0 on success
  negative number on error. errno will be set

• int lve_instance_destroy(struct liblve *lve); /* deprecated */
  destroy lve library instance
  args:
  lve = fully init liblve instance

• int lve_enter(struct liblve *lve, uint32_t ve_id,uint32_t uid, uint32_t gid, uint32_t *cookie);
  enter into virtual environment (puts current process in LVE)
  args:
  lve = pointer to fully init lve library instance.
  ve_id = id associated with LVE
  uid = user id to switch, -1 if switch not need. (NOT USED, should always be -1)
  gid = group id to switch, -1 if switch not need. (NOT USED, should always be -1)
  cookie = pointer to cookie, which returned if task correctly migrated
  in LVE and used to leave from this LVE
• returns:
  0 = none error,
  all less zero is errors:
  -EPERM - don't have permission to call, or called from outside root VE
  -ENOMEM - don't have memory to allocate new VE
  -EFAULT - cookie or parameters is bad pointer or kernel not able read/write from that pointer
  -E2BIG - too many enters in LVE
  -EALEADY - lve_enter called from same context as need to enter
  -EINVAL - some invalid arguments (mostly used in fairsched rate).
  -EBUSY - scheduler node isn't deleted correctly before enter
  -ENOSPC - radix tree is overloaded.
• 
  

  int lve_enter_flags(struct liblve *lve, uint32_t lve_id, uint32_t *cookie, uint32_t flags);
  enter into virtual environment (puts current process in LVE)
  args:
  lve = pointer to fully initialized lve library instance.
  lve_id = id associated with LVE
  cookie = pointer to cookie, which returned if task correctly migrated in LVE and used to leave from this LVE
  flags - flags to enter in LVE

  returns:
  0 = none error,
  all less zero is errors:
  -EPERM - don't have permission to call, or called from outside root VE
  -ENOMEM - don't have memory to allocate new VE
  -EFAULT - cookie or parameters is bad pointer or kernel not able read/write from that pointer
  -E2BIG - too many enters in LVE
  -EALEADY - lve_enter called from same context as need to enter
  -EINVAL - some invalid arguments (mostly used in fairsched rate).
  -EBUSY - scheduler node isn't deleted correctly before enter
  -ENOSPC - radix tree is overloaded.

• int lve_leave(struct liblve *lve, uint32_t *cookie);
  leave from virtual environment, if fatal error is occurred task will be killed.
  args:
  lve = pointer to fully init lve library instance.
  cookie - pointer to cookie returned from lve_enter.
  return:
  0 = none error, all less zero is errors:
  -ESRCH = task not in virtual environment