LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    numa

    
    
    

    SYNOPSIS

           #include <numa.h>
    
           cc ... -lnuma
    
           int numa_available(void);
    
           int numa_max_possible_node(void);
           int numa_num_possible_nodes();
    
           int numa_max_node(void);
           int numa_num_configured_nodes();
           struct bitmask *numa_get_mems_allowed(void);
    
           int numa_num_configured_cpus(void);
           struct bitmask *numa_all_nodes_ptr;
           struct bitmask *numa_no_nodes_ptr;
           struct bitmask *numa_all_cpus_ptr;
    
           int numa_num_task_cpus();
           int numa_num_task_nodes();
    
           int numa_parse_bitmap(char *line , struct bitmask *mask);
           struct bitmask *numa_parse_nodestring(char *string);
           struct bitmask *numa_parse_cpustring(char *string);
    
           long numa_node_size(int node, long *freep);
           long long numa_node_size64(int node, long long *freep);
    
           int numa_preferred(void);
           void numa_set_preferred(int node);
           int numa_get_interleave_node(void);
           struct bitmask *numa_get_interleave_mask(void);
           void numa_set_interleave_mask(struct bitmask *nodemask);
           void  numa_interleave_memory(void  *start,  size_t size, struct bitmask
           *nodemask);
           void numa_bind(struct bitmask *nodemask);
           void numa_set_localalloc(void);
           void numa_set_membind(struct bitmask *nodemask);
           struct bitmask *numa_get_membind(void);
    
           void *numa_alloc_onnode(size_t size, int node);
           void *numa_alloc_local(size_t size);
           void *numa_alloc_interleaved(size_t size);
           void *numa_alloc_interleaved_subset(size_t size,  struct bitmask *node-
           mask); void *numa_alloc(size_t size);
           void *numa_realloc(void *old_addr, size_t old_size, size_t new_size);
           void numa_free(void *start, size_t size);
    
           int numa_run_on_node(int node);
           int numa_run_on_node_mask(struct bitmask *nodemask);
           struct bitmask *numa_get_run_node_mask(void);
           int numa_node_of_cpu(int cpu);
    
           struct bitmask *numa_allocate_cpumask();
    
           void numa_free_cpumask();
           struct bitmask *numa_allocate_nodemask();
    
           void numa_free_nodemask();
           struct bitmask *numa_bitmask_alloc(unsigned int n);
           struct bitmask *numa_bitmask_clearall(struct bitmask *bmp);
           struct bitmask *numa_bitmask_clearbit(struct bitmask *bmp, unsigned int
           n);
           int numa_bitmask_equal(const struct bitmask *bmp1, const struct bitmask
           *bmp2);
           void numa_bitmask_free(struct bitmask *bmp);
           int numa_bitmask_isbitset(const struct bitmask *bmp, unsigned int n);
           unsigned int numa_bitmask_nbytes(struct bitmask *bmp);
           struct bitmask *numa_bitmask_setall(struct bitmask *bmp);
           struct bitmask *numa_bitmask_setbit(struct bitmask *bmp,  unsigned  int
           n);
           void  copy_bitmask_to_nodemask(struct  bitmask  *bmp, nodemask_t *node-
           mask)
           void  copy_nodemask_to_bitmask(nodemask_t  *nodemask,  struct   bitmask
           *bmp)
           void  copy_bitmask_to_bitmask(struct  bitmask  *bmpfrom, struct bitmask
           *bmpto)
           unsigned int numa_bitmask_weight(const struct bitmask *bmp )
    
           int numa_move_pages(int pid, unsigned long count, void  **pages,  const
           int *nodes, int *status, int flags);
           int  numa_migrate_pages(int pid, struct bitmask *fromnodes, struct bit-
           mask *tonodes);
    
           void numa_error(char *where);
    
           extern int numa_exit_on_error;
           extern int numa_exit_on_warn;
           void numa_warn(int number, char *where, ...);
    
    
    

    DESCRIPTION

           The libnuma library offers a simple programming interface to  the  NUMA
           (Non  Uniform Memory Access) policy supported by the Linux kernel. On a
           NUMA architecture some memory areas have different latency or bandwidth
           than others.
    
           Available  policies  are  page interleaving (i.e., allocate in a round-
           robin fashion from all, or a subset, of the nodes on the system),  pre-
           ferred  node  allocation  (i.e.,  preferably  allocate  on a particular
           node), local allocation (i.e., allocate on the node on which  the  task
           is  currently  executing),  or allocation only on specific nodes (i.e.,
           allocate on some subset of the available nodes).  It is  also  possible
    
           For setting a specific policy globally for all memory allocations in  a
           process  and its children it is easiest to start it with the numactl(8)
           utility. For more finegrained policy inside an application this library
           can be used.
    
           All  numa  memory  allocation  policy  only takes effect when a page is
           actually faulted into the address space of a process by  accessing  it.
           The numa_alloc_* functions take care of this automatically.
    
           A  node  is  defined  as an area where all memory has the same speed as
           seen from a particular CPU.  A node can contain multiple CPUs.   Caches
           are ignored for this definition.
    
           Most  functions in this library are only concerned about numa nodes and
           their  memory.   The  exceptions  to  this  are:   numa_node_to_cpus(),
           numa_node_of_cpu(),           numa_bind(),          numa_run_on_node(),
           numa_run_on_node_mask() and numa_get_run_node_mask().  These  functions
           deal  with  the  CPUs associated with numa nodes.  See the descriptions
           below for more information.
    
           Some of these functions accept or return a pointer to  struct  bitmask.
           A  struct  bitmask  controls a bit map of arbitrary length containing a
           bit    representation    of    nodes.     The    predefined    variable
           numa_all_nodes_ptr  points  to  a bit mask that has all available nodes
           set; numa_no_nodes_ptr points to the empty set.
    
           Before any other calls in this library  can  be  used  numa_available()
           must  be  called. If it returns -1, all other functions in this library
           are undefined.
    
           numa_max_possible_node() returns the number  of  the  highest  possible
           node in a system.  In other words, the size of a kernel type nodemask_t
           (in bits) minus 1.  This number can be gotten by calling  numa_num_pos-
           sible_nodes() and subtracting 1.
    
           numa_num_possible_nodes()  returns the size of kernel's node mask (ker-
           nel type nodemask_t).  In other words, large enough  to  represent  the
           maximum number of nodes that the kernel can handle. This will match the
           kernel's   MAX_NUMNODES   value.    This   count   is   derived    from
           /proc/self/status, field Mems_allowed.
    
           numa_max_node()  returns  the highest node number available on the cur-
           rent system.  (See the node  numbers  in  /sys/devices/system/node/  ).
           Also see numa_num_configured_nodes().
    
           numa_num_configured_nodes()  returns  the number of memory nodes in the
           system. This count includes any nodes that are currently disabled. This
           count  is  derived  from  the node numbers in /sys/devices/system/node.
           (Depends on the kernel being configured with /sys (CONFIG_SYSFS)).
    
           numa_get_mems_allowed() returns the mask of nodes from which  the  pro-
           numa_allocate_nodemask()  using size numa_max_possible_node().  The set
           of  nodes  to  record  is   derived   from   /proc/self/status,   field
           "Mems_allowed".  The user should not alter this bitmask.
    
           numa_no_nodes_ptr  points to a bitmask that is allocated by the library
           and left all zeroes.  The bitmask is allocated by a call to  numa_allo-
           cate_nodemask()  using  size numa_max_possible_node().  The user should
           not alter this bitmask.
    
           numa_all_cpus_ptr points to a bitmask that is allocated by the  library
           with  bits representing all cpus on which the calling task may execute.
           This set may be up to all cpus on the system, or up to the cpus in  the
           current  cpuset.   The  bitmask  is  allocated  by a call to numa_allo-
           cate_cpumask() using size numa_num_possible_cpus().  The set of cpus to
           record  is  derived  from /proc/self/status, field "Cpus_allowed".  The
           user should not alter this bitmask.
    
           numa_num_task_cpus() returns the number of cpus that the  calling  task
           is  allowed to use.  This count is derived from the map /proc/self/sta-
           tus, field "Cpus_allowed". Also see the bitmask numa_all_cpus_ptr.
    
           numa_num_task_nodes() returns the number of nodes on which the  calling
           task is allowed to allocate memory.  This count is derived from the map
           /proc/self/status,  field  "Mems_allowed".   Also   see   the   bitmask
           numa_all_nodes_ptr.
    
           numa_parse_bitmap()  parses  line , which is a character string such as
           found in /sys/devices/system/node/nodeN/cpumap into  a  bitmask  struc-
           ture.  The string contains the hexadecimal representation of a bit map.
           The bitmask may be allocated with numa_allocate_cpumask().  Returns   0
           on  success.  Returns -1 on failure.  This function is probably of lit-
           tle use to a user application, but it is used by libnuma internally.
    
           numa_parse_nodestring() parses a character string list of nodes into  a
           bit  mask.  The bit mask is allocated by numa_allocate_nodemask().  The
           string is a comma-separated list of node numbers  or  node  ranges.   A
           leading  ! can be used to indicate "not" this list (in other words, all
           nodes except this list), and a leading + can be used to  indicate  that
           the  node  numbers  in the list are relative to the task's cpuset.  The
           string can be "all" to specify all  (  numa_num_task_nodes()  )  nodes.
           Node   numbers   are   limited  by  the  number  in  the  system.   See
           numa_max_node() and numa_num_configured_nodes().
           Examples:  1-5,7,10   !4-5   +0-3
           If the string is of 0 length, bitmask  numa_no_nodes_ptr  is  returned.
           Returns 0 if the string is invalid.
    
           numa_parse_cpustring()  parses  a  character string list of cpus into a
           bit mask.  The bit mask is allocated by  numa_allocate_cpumask().   The
           string is a comma-separated list of cpu numbers or cpu ranges.  A lead-
           ing ! can be used to indicate "not" this list (in other words, all cpus
           except this list), and a leading + can be used to indicate that the cpu
           numbers in the list are relative to the task's cpuset.  The string  can
           numa_preferred()  returns the preferred node of the current task.  This
           is the node on which the kernel  preferably  allocates  memory,  unless
           some other policy overrides this.
    
           numa_set_preferred()  sets  the  preferred node for the current task to
           node.  The system will attempt to allocate memory  from  the  preferred
           node,  but  will  fall back to other nodes if no memory is available on
           the the preferred node.  Passing a node of -1 argument specifies  local
           allocation and is equivalent to calling numa_set_localalloc().
    
           numa_get_interleave_mask()  returns  the current interleave mask if the
           task's memory allocation policy is page interleaved.   Otherwise,  this
           function returns an empty mask.
    
           numa_set_interleave_mask() sets the memory interleave mask for the cur-
           rent task to nodemask.  All new memory allocations are page interleaved
           over  all  nodes in the interleave mask. Interleaving can be turned off
           again by passing an empty mask (numa_no_nodes).  The page  interleaving
           only occurs on the actual page fault that puts a new page into the cur-
           rent address space. It is also only a hint: the kernel will  fall  back
           to other nodes if no memory is available on the interleave target.
    
           numa_interleave_memory()  interleaves size bytes of memory page by page
           from start on nodes specified in nodemask.  The size argument  will  be
           rounded up to a multiple of the system page size.  If nodemask contains
           nodes that are externally denied to this process, this call will  fail.
           This  is  a  lower  level  function to interleave allocated but not yet
           faulted in memory. Not yet faulted in means  the  memory  is  allocated
           using  mmap(2)  or  shmat(2),  but has not been accessed by the current
           process yet. The memory is page interleaved to all nodes  specified  in
           nodemask.  Normally numa_alloc_interleaved() should be used for private
           memory instead, but this function is useful  to  handle  shared  memory
           areas.  To  be  useful  the  memory area should be several megabytes at
           least  (or  tens  of  megabytes   of   hugetlbfs   mappings)   If   the
           numa_set_strict()  flag  is  true  then  the  operation  will  cause  a
           numa_error if there were already pages in the mapping that do not  fol-
           low the policy.
    
           numa_bind() binds the current task and its children to the nodes speci-
           fied in nodemask.  They will only run on  the  CPUs  of  the  specified
           nodes  and only be able to allocate memory from them.  This function is
           equivalent  to  calling  numa_run_on_node_mask(nodemask)  followed   by
           numa_set_membind(nodemask).   If  tasks  should  be bound to individual
           CPUs  inside   nodes   consider   using   numa_node_to_cpus   and   the
           sched_setaffinity(2) syscall.
    
           numa_set_localalloc() sets the memory allocation policy for the calling
           task to local allocation.  In this mode, the preferred node for  memory
           allocation  is  effectively the node where the task is executing at the
           time of a page allocation.
    
           numa_set_membind() sets the memory allocation mask.  The task will only
    
           numa_alloc_local() allocates size bytes of memory on  the  local  node.
           The  size  argument will be rounded up to a multiple of the system page
           size.  This function is relatively slow compared to the malloc(3)  fam-
           ily  of  functions.   The  memory  must  be freed with numa_free().  On
           errors NULL is returned.
    
           numa_alloc_interleaved() allocates size bytes  of  memory  page  inter-
           leaved  on  all nodes. This function is relatively slow and should only
           be used for large areas consisting of multiple pages. The  interleaving
           works  at  page  level  and  will  only show an effect when the area is
           large.  The allocated memory must be freed with numa_free().  On error,
           NULL is returned.
    
           numa_alloc_interleaved_subset() attempts to allocate size bytes of mem-
           ory page interleaved on all nodes.  The size argument will  be  rounded
           up to a multiple of the system page size.  The nodes on which a process
           is allowed to allocate memory may be constrained externally.   If  this
           is  the case, this function may fail.  This function is relatively slow
           compare to malloc(3), family of functions and should only be  used  for
           large  areas  consisting  of multiple pages.  The interleaving works at
           page level and will only show an effect when the area  is  large.   The
           allocated  memory  must  be  freed with numa_free().  On error, NULL is
           returned.
    
           numa_alloc() allocates size bytes of memory with the current NUMA  pol-
           icy.   The size argument will be rounded up to a multiple of the system
           page size.  This function is relatively slow compare to  the  malloc(3)
           family  of  functions.   The memory must be freed with numa_free().  On
           errors NULL is returned.
    
           numa_realloc() changes the size  of  the  memory  area  pointed  to  by
           old_addr  from  old_size  to  new_size.   The memory area pointed to by
           old_addr must have been allocated with one  of  the  numa_alloc*  func-
           tions.   The  new_size  will  be rounded up to a multiple of the system
           page size. The contents of the memory area will  be  unchanged  to  the
           minimum of the old and new sizes; newly allocated memory will be unini-
           tialized. The memory policy (and node  bindings)  associated  with  the
           original  memory  area will be preserved in the resized area. For exam-
           ple, if the initial area was allocated with a call  to  numa_alloc_onn-
           ode(),  then  the new pages (if the area is enlarged) will be allocated
           on the same node.  However, if no memory policy was set for the  origi-
           nal  area, then numa_realloc() cannot guarantee that the new pages will
           be allocated on the same node. On success, the address of  the  resized
           area  is  returned  (which  might be different from that of the initial
           area), otherwise NULL is returned and errno  is  set  to  indicate  the
           error.  The  pointer returned by numa_realloc() is suitable for passing
           to numa_free().
    
           numa_free() frees size bytes of memory starting at start, allocated  by
           the numa_alloc_* functions above.  The size argument will be rounded up
           returned; on error -1 is returned, and errno is  set  to  indicate  the
           error.
    
           numa_get_run_node_mask()  returns  a  mask of CPUs on which the current
           task is allowed to run.
    
           numa_tonode_memory() put memory on a  specific  node.  The  constraints
           described for numa_interleave_memory() apply here too.
    
           numa_tonodemask_memory()  put  memory  on  a specific set of nodes. The
           constraints described for numa_interleave_memory() apply here too.
    
           numa_setlocal_memory() locates memory on the  current  node.  The  con-
           straints described for numa_interleave_memory() apply here too.
    
           numa_police_memory()  locates  memory with the current NUMA policy. The
           constraints described for numa_interleave_memory() apply here too.
    
           numa_distance() reports the distance in the  machine  topology  between
           two  nodes.   The  factors  are a multiple of 10. It returns 0 when the
           distance cannot be determined.  A  node  has  distance  10  to  itself.
           Reporting  the  distance  requires  a Linux kernel version of 2.6.10 or
           newer.
    
           numa_set_bind_policy() specifies whether calls that bind  memory  to  a
           specific  node should use the preferred policy or a strict policy.  The
           preferred policy allows the kernel to allocate memory  on  other  nodes
           when  there  isn't enough free on the target node. strict will fail the
           allocation in that case.  Setting the argument to specifies  strict,  0
           preferred.  Note that specifying more than one node non strict may only
           use the first node in some kernel versions.
    
           numa_set_strict() sets a flag that says whether the functions  allocat-
           ing  on specific nodes should use use a strict policy. Strict means the
           allocation will fail if the memory cannot be allocated  on  the  target
           node.   Default operation is to fall back to other nodes.  This doesn't
           apply to interleave and default.
    
           numa_get_interleave_node() is used by libnuma internally. It is  proba-
           bly  not useful for user applications.  It uses the MPOL_F_NODE flag of
           the get_mempolicy system call, which is not  intended  for  application
           use (its operation may change or be removed altogether in future kernel
           versions). See get_mempolicy(2).
    
           numa_pagesize() returns the number of bytes in page. This  function  is
           simply  a  fast alternative to repeated calls to the getpagesize system
           call.  See getpagesize(2).
    
           numa_sched_getaffinity() retrieves a bitmask of the  cpus  on  which  a
           task  may run.  The task is specified by pid.  Returns the return value
           of the sched_getaffinity system call.  See  sched_getaffinity(2).   The
           bitmask  must  be at least the size of the kernel's cpu mask structure.
           represent all possible cpu's.  Use  numa_allocate_cpumask()  to  create
           it.   If the bitmask is not long enough errno will be set to ERANGE and
           -1 returned. On success 0 is returned.
    
           numa_node_of_cpu() returns the node that a cpu belongs to. If the  user
           supplies  an  invalid  cpu  errno  will be set to EINVAL and -1 will be
           returned.
    
           numa_allocate_cpumask () returns a bitmask of a size equal to the  ker-
           nel's  cpu  mask (kernel type cpumask_t).  In other words, large enough
           to represent NR_CPUS cpus.  This number of cpus can be gotten by  call-
           ing numa_num_possible_cpus().  The bitmask is zero-filled.
    
           numa_free_cpumask  frees  a  cpumask  previously allocate by numa_allo-
           cate_cpumask.
    
           numa_allocate_nodemask() returns a bitmask of a size equal to the  ker-
           nel's node mask (kernel type nodemask_t).  In other words, large enough
           to represent MAX_NUMNODES nodes.  This number of nodes can be gotten by
           calling numa_num_possible_nodes().  The bitmask is zero-filled.
    
           numa_free_nodemask()  frees a nodemask previous allocated by numa_allo-
           cate_nodemask().
    
           numa_bitmask_alloc() allocates a bitmask structure and  its  associated
           bit  mask.  The memory allocated for the bit mask contains enough words
           (type unsigned long) to contain n bits.  The bit mask  is  zero-filled.
           The  bitmask structure points to the bit mask and contains the n value.
    
           numa_bitmask_clearall() sets all bits in the bit mask to 0.   The  bit-
           mask  structure  points  to  the  bit  mask and contains its size ( bmp
           ->size).  The value of bmp is always  returned.   Note  that  numa_bit-
           mask_alloc() creates a zero-filled bit mask.
    
           numa_bitmask_clearbit() sets a specified bit in a bit mask to 0.  Noth-
           ing is done if the n value is greater than the size of the bitmask (and
           no error is returned). The value of bmp is always returned.
    
           numa_bitmask_equal() returns 1 if two bitmasks are equal.  It returns 0
           if they are not equal.  If the bitmask structures control bit masks  of
           different  sizes,  the  "missing" trailing bits of the smaller bit mask
           are considered to be 0.
    
           numa_bitmask_free() deallocates the memory of both the  bitmask  struc-
           ture  pointed to by bmp and the bit mask.  It is an error to attempt to
           free this bitmask twice.
    
           numa_bitmask_isbitset() returns the value of a specified bit in  a  bit
           mask.   If  the  n  value is greater than the size of the bit map, 0 is
           returned.
    
           numa_bitmask_nbytes() returns the size (in bytes) of the bit mask  con-
           is truncated to the size of the receiving field or zero-filled.
    
           copy_nodemask_to_bitmask()  copies  the nodemask_t structure pointed to
           by the nodemask pointer to the body (the bit map itself) of the bitmask
           structure  pointed  to  by  the bmp pointer. If the two areas differ in
           size, the copy is truncated to the size of the receiving field or zero-
           filled.
    
           copy_bitmask_to_bitmask()  copies  the body (the bit map itself) of the
           bitmask structure pointed to by the bmpfrom pointer to the body of  the
           bitmask  structure  pointed  to  by the bmpto pointer. If the two areas
           differ in size, the copy is truncated to  the  size  of  the  receiving
           field or zero-filled.
    
           numa_bitmask_weight()  returns  a count of the bits that are set in the
           body of the bitmask pointed to by the bmp argument.
    
           numa_move_pages() moves a list of pages in the  address  space  of  the
           currently  executing or current process.  It simply uses the move_pages
           system call.
           pid - ID of task.  If not valid, use the current task.
           count - Number of pages.
           pages - List of pages to move.
           nodes - List of nodes to which pages can be moved.
           status - Field to which status is to be returned.
           flags - MPOL_MF_MOVE or MPOL_MF_MOVE_ALL
           See move_pages(2).
    
           numa_migrate_pages() simply uses the migrate_pages system call to cause
           the  pages of the calling task, or a specified task, to be migated from
           one set of nodes to another.  See migrate_pages(2).  The bit masks rep-
           resenting the nodes should be allocated with numa_allocate_nodemask() ,
           or  with  numa_bitmask_alloc()  using  an   n   value   returned   from
           numa_num_possible_nodes().   A task's current node set can be gotten by
           calling numa_get_membind().  Bits in the tonodes mask  can  be  set  by
           calls to numa_bitmask_setbit().
    
           numa_error()  is  a libnuma internal function that can be overridden by
           the user program.  This function is called with a char * argument  when
           a  libnuma  function fails.  Overriding the library internal definition
           makes it possible to specify a different error handling strategy when a
           libnuma  function  fails.  It  does  not  affect numa_available().  The
           numa_error() function defined in libnuma prints an error on stderr  and
           terminates  the  program  if  numa_exit_on_error  is  set to a non-zero
           value.  The default value of numa_exit_on_error is zero.
    
           numa_warn() is a libnuma internal function that can be also  overridden
           by  the  user  program.   It  is called to warn the user when a libnuma
           function encounters a  non-fatal  error.   The  default  implementation
           prints  a  warning  to  stderr.   The first argument is a unique number
           identifying each warning. After that there is a printf(3)-style  format
           string and a variable number of arguments.  numa_warn exits the program
           other calls are thread safe.
    
    
    

    COPYRIGHT

           Copyright  2002,  2004,  2007,  2008 Andi Kleen, SuSE Labs.  libnuma is
           under the GNU Lesser General Public License, v2.1.
    
    
    

    SEE ALSO

           get_mempolicy(2), set_mempolicy(2), getpagesize(2), mbind(2),  mmap(2),
           shmat(2),    numactl(8),    sched_getaffinity(2)   sched_setaffinity(2)
           move_pages(2) migrate_pages(2)
    
    
    

    SuSE Labs December 2007 NUMA(3)

    
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz