README: New kernel module source layout for NVIDIA Linux kernel modules ======================================================================= The NVIDIA GPU driver for Linux consists of multiple user space and kernel space components, with the kernel space components implemented as Linux kernel modules. The NVIDIA Linux driver package includes source code for any portions of these kernel modules which interface directly with the Linux kernel, and the NVIDIA kernel modules must be built against the target kernel from a combination of these source code files and precompiled binary portions. Beginning with the 355.xx release of the NVIDIA Linux driver, a new layout and kernel module build system will be used for the kernel modules that are included in the installer package. Some key differences between the existing build system and the new one include: * Each kernel module will have its own subdirectory within the top level kernel module source directory. * Invoking the kernel module build from the top level directory will, by default, build all NVIDIA kernel modules at once. For example, instead of first building "nvidia.ko" as a prerequisite to building "nvidia-uvm.ko", under the new build system, both "nvidia.ko" and "nvidia-uvm.ko" are built within the same `make` invocation, with the Linux Kbuild system handling the inter-module dependencies. * All built kernel modules will be saved to the top level directory. For example, instead of "nvidia.ko" being saved to the top level directory, and "nvidia-uvm.ko" being saved to the "uvm/" subdirectory, both modules will be saved to the top level directory. * The new build system no longer supports building multiple instances of the NVIDIA kernel module (e.g. "nvidia0.ko", "nvidia1.ko", ...) which are managed by a shared "nvidia-frontend.ko" frontend module. As this new build system may prove disruptive to existing tools which repackage the NVIDIA driver, NVIDIA is providing example installer packages which demonstrate the new layout. These packages include the driver components from the already released 352.21 driver, with the layout of the kernel module source files updated to reflect the layout that will be used in the upcoming 355.xx and later driver releases. These packages also include a version of `nvidia-installer` which has been updated to handle the new kernel module source layout. An archive which contains source code for the updated version of `nvidia-installer` should be available from the same location as the example packages and this README document. If you are a repackager of the NVIDIA Linux driver, please use these packages to test any changes to your packaging tools that you may need to make in order to accommodate the new layout. Special considerations for driver repackagers --------------------------------------------- In addition to the differences between the old and new kernel module build systems which have been highlighted above, there are a few special considerations that repackagers of the NVIDIA Linux driver should keep in mind: ### Dynamic Kernel Module Support (DKMS) ### For packages that use DKMS to build the NVIDIA kernel modules, note that the format of the included dkms.conf file has changed. Previous driver versions included a dkms.conf for building "nvidia.ko", and an separate dkms.conf.fragment to be optionally appended to the base dkms.conf file to add support for building the "nvidia-uvm.ko" kernel module via DKMS. The dkms.conf file in the new driver packages is no longer a valid dkms.conf file in its own right, but is rather a template file, which `nvidia-installer` modifies at installation time, as appropriate for the target installation. Repackagers are free to develop their own dkms.conf files, but for those who wish to use the dkms.conf included in the driver package as a starting point, please note the following tokens and substitutions: * __VERSION_STRING This should be replaced with the driver version, e.g. "352.21" * __JOBS `nvidia-installer` detects the number of available processors during installation, and by default will build the kernel module with a level of parallelism matching the number of CPUs. `nvidia-installer` will also fill this level of parallelism in as an argument to `make` within the dkms.conf file. * __EXCLUDE_MODULES Some kernel modules, such as "nvidia-uvm.ko", are optional parts of the driver installation and may be excluded. The __EXCLUDE_MODULES token in the dkms.conf template included with the driver package should be replaced with a space-separated list of kernel module names (excluding the ".ko" filename extension) which should be excluded from the build. * __DKMS_MODULES This token should be replaced with a list of kernel modules that DKMS should install. Each entry in the list should have two lines: one `BUILT_MODULE_NAME[$index]` line to specify the name of the kernel module (excluding the ".ko" filename extension), as well as one `DEST_MODULE_LOCATION[$index]` line to specify the destination where the built module should be installed (so long as no local distribution-specific policy overrides this location; see dkms(8)). Each pair of entries should carry a unique, incrementing, 0-based array index to tie together its pair of `BUILT_MODULE_NAME[]` and `DEST_MODULE_LOCATION[]` entries. For example, a dkms.conf to install the "nvidia" and "nvidia-uvm" kernel modules should contain entries for the `BUILT_MODULE_NAME[]` and `DEST_MODULE_LOCATION[]` arrays such as the following: BUILT_MODULE_NAME[0]="nvidia" DEST_MODULE_LOCATION[0]="/kernel/drivers/video" BUILT_MODULE_NAME[1]="nvidia-uvm" DEST_MODULE_LOCATION[1]="/kernel/drivers/video" As noted above, the built modules are now all saved to the top level of the kernel module source directory. Under the previous build system, the "nvidia-uvm" kernel module was built in a subdirectory, and it was necessary to set its BUILT_MODULE_LOCATION entry to the subdirectory path, but under the new build system, this is no longer necessary. * "generated by nvidia-installer" comment A comment above the list of auto-generated `BUILT_MODULE_NAME[]` and `DEST_MODULE_LOCATION[]` entries is edited by the installer from "The list of kernel modules will be generated by nvidia-installer at runtime." to read "The list of kernel modules was generated by nvidia-installer at runtime." This change has no effect on the functionality of the dkms.conf file, but the comment should probably be updated or removed when producing dkms.conf files which are based on the template file included in the driver package, but which were not processed using `nvidia-installer`. ### List of built kernel modules ### The list of built kernel modules should not be hardcoded into driver repackaging tools, as it may vary between target architectures or driver versions. The 355.xx release series will not add any new kernel modules as compared to 352.xx; however, future driver releases will add new kernel modules, which will be built using the new kernel module build system. The fourth line of the .manifest file at the top level of the extracted contents of a .run installer package (set the --extract-only or -x option on the .run file's command line to extract its contents) contains a space-separated list of kernel modules which are included within that package. `nvidia-installer` iterates over this list for any operations that involve kernel modules; it would be prudent for repackaging tools to be updated to use this list as well. ### Kernel module signing ### Support for kernel module signing within the kernel module makefiles has been removed. The "module_sign" target that existed in the old build system was merely a thin wrapper around the kernel's own `sign-file` utility script, and required that several arguments be passed to it, only to be passed directly onto `sign-file`. `nvidia-installer` now simply invokes `sign-file` directly when performing module signing.