Document changes to large/huge page support in 10.5

The changes introduced by MDEV-18851 need to be documented for MariaDB 10.5.3 and later.

System Variables

large_pages

The large_pages system variable and the corresponding mariadbd command-line option are now supported for many different OSes, which may use different internal implementations. The different internal implementations are described below.

This effects these pages:

• https://mariadb.com/docs/reference/mdb/system-variables/large_pages/
• https://mariadb.com/docs/reference/mdb/cli/mariadbd/large-pages/
• https://mariadb.com/kb/en/server-system-variables/#large_pages

Linux

The Linux implementation supports multiple page sizes using Linux's built-in huge page feature with the enhancements available in the Linux kernel 3.8 and later.

Windows

The Windows implementation uses the Windows GetLargePageMinimum() syscall to determine the supported page sizes.

Generic Implementation with Multiple Page Sizes

The generic implementation with support for multiple page sizes uses the getpagesizes() syscall to determine the supported page sizes.

This implementation supports:

• Solaris
• FreeBSD
• NetBSD

Generic Implementation with a Single Page Size

The generic implementation with support for multiple page sizes uses the getpagesize() syscall to determine the system's current page size.

This implementation supports:

• macOS
• OpenBSD

large_page_size

The large_page_size system variable is now deprecated for all OSes. The value of the system variable will always be 0 in MariaDB 10.5.3+.

This system variable is read-only, so there is no corresponding command-line option.

This effects these pages:

• https://mariadb.com/docs/reference/mdb/system-variables/large_page_size/
• https://mariadb.com/kb/en/server-system-variables/#large_page_size

Deprecated mariadbd Command-line Options

--super-large-pages

The --super-large-pages command-line option only ever had an effect on Solaris. It still works on Solaris, but the command-line option is now officially deprecated for:

• Linux

This effects these pages:

• https://mariadb.com/docs/reference/mdb/cli/mariadbd/super-large-pages/

OS Configuration Details

Configure Huge Pages on Linux

On Linux, when the large_pages system variable is set for MariaDB 10.5.3+, it will no longer allocate large pages from shm. Instead, MariaDB will automatically use Linux's built-in huge page support, as long as the Linux kernel is configured to have huge pages available.

To configure Linux to use huge pages, set the hugepages and hugepagesz kernel paramters. Users can configure these kernel parameters by setting GRUB_CMDLINE_LINUX.

Grant Lock Memory Privilege on Windows

On Windows, MariaDB 10.5.3+ can only use huge pages if the user that runs mariadbd has the SeLockMemoryPrivilege privilege.

The patch that refactored huge page support added an error message if the privilege cannot be obtained. The error message points to this KB section for details on how to add the privilege for the user. The details do not currently exist on that KB page, so they will need to be added. We do not know the proper way to set this privilege, so that will have to be determined as well.

OS Monitoring Details

Check Huge Pages on Linux

Users can check available huge page sizes on their Linux system by running the following:

ls -la /sys/devices/system/node/node0/hugepages/

Users can check how many huge pages are free on their Linux system by running the following:

more /sys/devices/system/node/node*/hugepages/hugepages-*kB/free_hugepages

Check Huge Pages on Solaris

Users can check available huge page sizes on their Solaris system by calling the getpagessizes syscall, which seems to depend on the memcntl syscall.

For an example of how to call the memcntl syscall, see this patch.

Check Lock Memory Privilege on Windows

Users should check whether the user that runs mariadbd has the SeLockMemoryPrivilege privilege. We do not know the proper way to check for this privilege, so that will have to be determined as well.

MariaDB Configuration Details

Configure innodb_buffer_pool_chunk_size

In MariaDB 10.5.3+, we should recommend that users set the innodb_buffer_pool_chunk_size system variable to a multiple of one of the available large page sizes on their system. Previously, MariaDB would automatically round up to the large page size, but it the extra memory was only allocated, and not actually used, so that behavior is probably not worth mentioning.

This effects these pages:

• https://mariadb.com/docs/reference/es/system-variables/innodb_buffer_pool_chunk_size/
• https://mariadb.com/docs/reference/mdb/cli/mariadbd/innodb-buffer-pool-chunk-size/
• https://mariadb.com/kb/en/innodb-system-variables/#innodb_buffer_pool_chunk_size

Other KB Updates

Huge Page Changes

Remove the following lines from the referenced KB page:

innodb memory usage vs swap
That thread has more details on what to look for and what to set.
Overall performance gain: A few percent. Yawn. Too much hassle for too little benefit.
Jumbo Pages? Turn off.

https://mariadb.com/kb/en/mariadb-memory-allocation/#huge-pages