1# 2# This file and its contents are supplied under the terms of the 3# Common Development and Distribution License ("CDDL"), version 1.0. 4# You may only use this file in accordance with the terms of version 5# 1.0 of the CDDL. 6# 7# A full copy of the text of the CDDL should have accompanied this 8# source. A copy of the CDDL is also available via the Internet at 9# http://www.illumos.org/license/CDDL. 10# 11 12# 13# Copyright 2016 Joyent, Inc. 14# 15 16Kernel Module Build Time Symbol Verification 17-------------------------------------------- 18 19Historically, kernel modules have all been built as relocatable objects. 20They are not dynamic objects and dependency information is always noted 21in individual makefiles. Along with this, there has never been any 22verification of the symbols that are being used. This means that it's 23possible for a kernel module author to refer to a symbol that doesn't 24exist and not find out until they try to install the module. 25 26To help find these problems at build time, we provide an opt-in system 27for modules to use, leveraging the link-editor's '-z defs' option. This 28option ensures that there are no unknown definitons at link-edit time. 29To supply these definitions we supply a series of mapfiles in this 30directory. 31 32These mapfiles are not the traditional versioning mapfiles like those in 33usr/src/lib/README.mapfiles! Please review the following differences 34closely: 35 36* These mapfiles do not declare any versions! 37* These mapfiles do not use the 'SYMBOL_VERSION' directive, instead they 38 use the 'SYMBOL_SCOPE' directive. 39* These mapfiles do not hide symbols! Library mapfiles always have 40 something to catch all local symbols. That should *never* be used 41 here. These mapfiles should not affect visibility. 42* All symbols in these mapfiles should be marked 'EXTERN' to indicate 43 that they are not provided by the kernel module but by another. 44* These mapfiles do not declare what is or isn't a public interface, 45 though they are often grouped around interfaces, to make it easier for 46 a driver author to get this right. 47 48Mapfiles are organized based on kernel module. For example the GLDv3 49device driver interface is provided by the 'mac' module and thus is 50found in the file 'mac.mapfile'. The DDI is currently in the 'ddi' 51mapfile. Functions that are found in genunix and unix that aren't in 52the DDI should not be put in that mapfile. 53 54Note, the existing files may not be complete. These are intended to only 55have the public interfaces provided by modules and thus should not 56include every symbol in them. As the need arises, add new symbols or 57modules as appropriate. 58 59To opt a module into this, first declare a series of MAPFILES that they 60should check against in the module. This should be a series of one or 61more files, for example: 62 63MAPFILES += ddi mac 64 65Next, you should add an include of Makefile.mapfile right before you 66include Makefile.targ. You can do this with the following line: 67 68include $(UTSBASE)/Makefile.mapfile 69