man2/alloc_hugepages.2

   1 .\" Copyright 2003 Andries E. Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH alloc_hugepages 2 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 alloc_hugepages, free_hugepages \- allocate or free huge pages
   8 .SH SYNOPSIS
   9 .nf
  10 .BI "void *syscall(SYS_alloc_hugepages, int " key ", void " addr [. len "], \
  11 size_t " len ,
  12 .BI "              int " prot ", int " flag );
  13 .\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr,
  14 .\" unsigned long len, int prot, int flag);
  15 .BI "int syscall(SYS_free_hugepages, void *" addr );
  16 .\" asmlinkage int sys_free_hugepages(unsigned long addr);
  17 .fi
  18 .PP
  19 .IR Note :
  20 glibc provides no wrappers for these system calls,
  21 necessitating the use of
  22 .BR syscall (2).
  23 .SH DESCRIPTION
  24 The system calls
  25 .BR alloc_hugepages ()
  26 and
  27 .BR free_hugepages ()
  28 were introduced in Linux 2.5.36 and removed again in Linux 2.5.54.
  29 They existed only on i386 and ia64 (when built with
  30 .BR CONFIG_HUGETLB_PAGE ).
  31 In Linux 2.4.20, the syscall numbers exist,
  32 but the calls fail with the error
  33 .BR ENOSYS .
  34 .PP
  35 On i386 the memory management hardware knows about ordinary pages (4\ KiB)
  36 and huge pages (2 or 4\ MiB).
  37 Similarly ia64 knows about huge pages of
  38 several sizes.
  39 These system calls serve to map huge pages into the
  40 process's memory or to free them again.
  41 Huge pages are locked into memory, and are not swapped.
  42 .PP
  43 The
  44 .I key
  45 argument is an identifier.
  46 When zero the pages are private, and
  47 not inherited by children.
  48 When positive the pages are shared with other applications using the same
  49 .IR key ,
  50 and inherited by child processes.
  51 .PP
  52 The
  53 .I addr
  54 argument of
  55 .BR free_hugepages ()
  56 tells which page is being freed: it was the return value of a
  57 call to
  58 .BR alloc_hugepages ().
  59 (The memory is first actually freed when all users have released it.)
  60 The
  61 .I addr
  62 argument of
  63 .BR alloc_hugepages ()
  64 is a hint, that the kernel may or may not follow.
  65 Addresses must be properly aligned.
  66 .PP
  67 The
  68 .I len
  69 argument is the length of the required segment.
  70 It must be a multiple of the huge page size.
  71 .PP
  72 The
  73 .I prot
  74 argument specifies the memory protection of the segment.
  75 It is one of
  76 .BR PROT_READ ,
  77 .BR PROT_WRITE ,
  78 .BR PROT_EXEC .
  79 .PP
  80 The
  81 .I flag
  82 argument is ignored, unless
  83 .I key
  84 is positive.
  85 In that case, if
  86 .I flag
  87 is
  88 .BR IPC_CREAT ,
  89 then a new huge page segment is created when none
  90 with the given key existed.
  91 If this flag is not set, then
  92 .B ENOENT
  93 is returned when no segment with the given key exists.
  94 .SH RETURN VALUE
  95 On success,
  96 .BR alloc_hugepages ()
  97 returns the allocated virtual address, and
  98 .BR free_hugepages ()
  99 returns zero.
 100 On error, \-1 is returned, and
 101 .I errno
 102 is set to indicate the error.
 103 .SH ERRORS
 104 .TP
 105 .B ENOSYS
 106 The system call is not supported on this kernel.
 107 .SH FILES
 108 .TP
 109 .I /proc/sys/vm/nr_hugepages
 110 Number of configured hugetlb pages.
 111 This can be read and written.
 112 .TP
 113 .I /proc/meminfo
 114 Gives info on the number of configured hugetlb pages and on their size
 115 in the three variables HugePages_Total, HugePages_Free, Hugepagesize.
 116 .SH STANDARDS
 117 These extinct system calls were specific to Linux on Intel processors.
 118 .SH NOTES
 119 These system calls are gone;
 120 they existed only in Linux 2.5.36 through to Linux 2.5.54.
 121 Now the hugetlbfs filesystem can be used instead.
 122 Memory backed by huge pages (if the CPU supports them) is obtained by
 123 using
 124 .BR mmap (2)
 125 to map files in this virtual filesystem.
 126 .PP
 127 The maximal number of huge pages can be specified using the
 128 .B hugepages=
 129 boot parameter.
 130 .\".PP
 131 .\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features")
 132 .\" and CONFIG_HUGETLBFS (under "Filesystems").
 133 .\" mount \-t hugetlbfs hugetlbfs /huge
 134 .\" SHM_HUGETLB