Index: head/sys/kern/device_if.m =================================================================== --- head/sys/kern/device_if.m (revision 327427) +++ head/sys/kern/device_if.m (revision 327428) @@ -1,344 +1,361 @@ #- # Copyright (c) 1998-2004 Doug Rabson # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # # $FreeBSD$ # #include /** * @defgroup DEVICE device - KObj methods for all device drivers * @brief A basic set of methods required for all device drivers. * * The device interface is used to match devices to drivers during * autoconfiguration and provides methods to allow drivers to handle * system-wide events such as suspend, resume or shutdown. * @{ */ INTERFACE device; +# Needed for timestamping device probe/attach calls +HEADER { + #include +} + # # Default implementations of some methods. # CODE { static int null_shutdown(device_t dev) { return 0; } static int null_suspend(device_t dev) { return 0; } static int null_resume(device_t dev) { return 0; } static int null_quiesce(device_t dev) { return 0; } static void * null_register(device_t dev) { return NULL; } }; /** * @brief Probe to see if a device matches a driver. * * Users should not call this method directly. Normally, this * is called via device_probe_and_attach() to select a driver * calling the DEVICE_PROBE() of all candidate drivers and attach * the winning driver (if any) to the device. * * This function is used to match devices to device drivers. * Typically, the driver will examine the device to see if * it is suitable for this driver. This might include checking * the values of various device instance variables or reading * hardware registers. * * In some cases, there may be more than one driver available * which can be used for a device (for instance there might * be a generic driver which works for a set of many types of * device and a more specific driver which works for a subset * of devices). Because of this, a driver should not assume * that it will be the driver that attaches to the device even * if it returns a success status from DEVICE_PROBE(). In particular, * a driver must free any resources which it allocated during * the probe before returning. The return value of DEVICE_PROBE() * is used to elect which driver is used - the driver which returns * the largest non-error value wins the election and attaches to * the device. Common non-error values are described in the * DEVICE_PROBE(9) manual page. * * If a driver matches the hardware, it should set the device * description string using device_set_desc() or * device_set_desc_copy(). This string is used to generate an * informative message when DEVICE_ATTACH() is called. * * As a special case, if a driver returns zero, the driver election * is cut short and that driver will attach to the device * immediately. This should rarely be used. * * For example, a probe method for a PCI device driver might look * like this: * * @code * int * foo_probe(device_t dev) * { * if (pci_get_vendor(dev) == FOOVENDOR && * pci_get_device(dev) == FOODEVICE) { * device_set_desc(dev, "Foo device"); * return (BUS_PROBE_DEFAULT); * } * return (ENXIO); * } * @endcode * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_probe, foo_probe) * @endcode * * @param dev the device to probe * * @retval 0 if this is the only possible driver for this * device * @retval negative if the driver can match this device - the * least negative value is used to select the * driver * @retval ENXIO if the driver does not match the device * @retval positive if some kind of error was detected during * the probe, a regular unix error code should * be returned to indicate the type of error * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device() */ +PROLOG { + TSENTER2(device_get_name(dev)); +} +EPILOG { + TSEXIT2(device_get_name(dev)); +} METHOD int probe { device_t dev; }; /** * @brief Allow a device driver to detect devices not otherwise enumerated. * * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA * bus driver) to help populate the bus device with a useful set of * child devices, normally by calling the BUS_ADD_CHILD() method of * the parent device. For instance, the ISA bus driver uses several * special drivers, including the isahint driver and the pnp driver to * create child devices based on configuration hints and PnP bus * probes respectively. * * Many bus drivers which support true plug-and-play do not need to * use this method at all since child devices can be discovered * automatically without help from child drivers. * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_identify, foo_identify) * @endcode * * @param driver the driver whose identify method is being called * @param parent the parent device to use when adding new children */ STATICMETHOD void identify { driver_t *driver; device_t parent; }; /** * @brief Attach a device to a device driver * * Normally only called via device_probe_and_attach(), this is called * when a driver has succeeded in probing against a device. * This method should initialise the hardware and allocate other * system resources (e.g. devfs entries) as required. * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_attach, foo_attach) * @endcode * * @param dev the device to probe * * @retval 0 success * @retval non-zero if some kind of error was detected during * the attach, a regular unix error code should * be returned to indicate the type of error * @see DEVICE_PROBE() */ +PROLOG { + TSENTER2(device_get_name(dev)); +} +EPILOG { + TSEXIT2(device_get_name(dev)); +} METHOD int attach { device_t dev; }; /** * @brief Detach a driver from a device. * * This can be called if the user is replacing the * driver software or if a device is about to be physically removed * from the system (e.g. for removable hardware such as USB or PCCARD). * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_detach, foo_detach) * @endcode * * @param dev the device to detach * * @retval 0 success * @retval non-zero the detach could not be performed, e.g. if the * driver does not support detaching. * * @see DEVICE_ATTACH() */ METHOD int detach { device_t dev; }; /** * @brief Called during system shutdown. * * This method allows drivers to detect when the system is being shut down. * Some drivers need to use this to place their hardware in a consistent * state before rebooting the computer. * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_shutdown, foo_shutdown) * @endcode */ METHOD int shutdown { device_t dev; } DEFAULT null_shutdown; /** * @brief This is called by the power-management subsystem when a * suspend has been requested by the user or by some automatic * mechanism. * * This gives drivers a chance to veto the suspend or save their * configuration before power is removed. * * To include this method in a device driver, use a line like this in * the driver's method list: * * @code * KOBJMETHOD(device_suspend, foo_suspend) * @endcode * * @param dev the device being suspended * * @retval 0 success * @retval non-zero an error occurred while attempting to prepare the * device for suspension * * @see DEVICE_RESUME() */ METHOD int suspend { device_t dev; } DEFAULT null_suspend; /** * @brief This is called when the system resumes after a suspend. * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_resume, foo_resume) * @endcode * * @param dev the device being resumed * * @retval 0 success * @retval non-zero an error occurred while attempting to restore the * device from suspension * * @see DEVICE_SUSPEND() */ METHOD int resume { device_t dev; } DEFAULT null_resume; /** * @brief This is called when the driver is asked to quiesce itself. * * The driver should arrange for the orderly shutdown of this device. * All further access to the device should be curtailed. Soon there * will be a request to detach, but there won't necessarily be one. * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_quiesce, foo_quiesce) * @endcode * * @param dev the device being quiesced * * @retval 0 success * @retval non-zero an error occurred while attempting to quiesce the * device * * @see DEVICE_DETACH() */ METHOD int quiesce { device_t dev; } DEFAULT null_quiesce; /** * @brief This is called when the driver is asked to register handlers. * * * To include this method in a device driver, use a line like this * in the driver's method list: * * @code * KOBJMETHOD(device_register, foo_register) * @endcode * * @param dev the device for which handlers are being registered * * @retval NULL method not implemented * @retval non-NULL a pointer to implementation specific static driver state * */ METHOD void * register { device_t dev; } DEFAULT null_register; Index: head/sys/tools/makeobjops.awk =================================================================== --- head/sys/tools/makeobjops.awk (revision 327427) +++ head/sys/tools/makeobjops.awk (revision 327428) @@ -1,509 +1,527 @@ #!/usr/bin/awk -f #- # SPDX-License-Identifier: BSD-3-Clause # # Copyright (c) 1992, 1993 # The Regents of the University of California. All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. Neither the name of the University nor the names of its contributors # may be used to endorse or promote products derived from this software # without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. # # From @(#)vnode_if.sh 8.1 (Berkeley) 6/10/93 # From @(#)makedevops.sh 1.1 1998/06/14 13:53:12 dfr Exp $ # From @(#)makedevops.sh ?.? 1998/10/05 # From src/sys/kern/makedevops.pl,v 1.12 1999/11/22 14:40:04 n_hibma Exp # From src/sys/kern/makeobjops.pl,v 1.8 2001/11/16 02:02:42 joe Exp # # $FreeBSD$ # # Script to produce kobj front-end sugar. # function usage () { print "usage: makeobjops.awk [-d] [-p] [-l ] [-c|-h]"; print "where -c produce only .c files"; print " -h produce only .h files"; print " -p use the path component in the source file for destination dir"; print " -l set line width for output files [80]"; print " -d switch on debugging"; exit 1; } function warn (msg) { print "makeobjops.awk:", msg > "/dev/stderr"; } function warnsrc (msg) { warn(src ":" lineno ": " msg); } function debug (msg) { if (opt_d) warn(msg); } function die (msg) { warn(msg); exit 1; } # These are just for convenience ... function printc(s) {if (opt_c) print s > ctmpfilename;} function printh(s) {if (opt_h) print s > htmpfilename;} # # If a line exceeds maxlength, split it into multiple # lines at commas. Subsequent lines are indented by # the specified number of spaces. # # In other words: Lines are split by replacing ", " # by ",\n" plus indent spaces. # function format_line (line, maxlength, indent) { rline = ""; while (length(line) > maxlength) { # # Find the rightmost ", " so that the part # to the left of it is just within maxlength. # If there is none, give up and leave it as-is. # if (!match(substr(line, 1, maxlength + 1), /^.*, /)) break; rline = rline substr(line, 1, RLENGTH - 1) "\n"; line = sprintf("%*s", indent, "") substr(line, RLENGTH + 1); } return rline line; } # # Join an array into a string. # function join (separator, array, num) { _result = "" if (num) { while (num > 1) _result = separator array[num--] _result; _result = array[1] _result; } return _result; } # # Execute a system command and report if it failed. # function system_check (cmd) { if ((rc = system(cmd))) warn(cmd " failed (" rc ")"); } # # Handle "INTERFACE" line. # function handle_interface () { intname = $2; sub(/;$/, "", intname); if (intname !~ /^[a-z_][a-z0-9_]*$/) { debug($0); warnsrc("Invalid interface name '" intname "', use [a-z_][a-z0-9_]*"); error = 1; return; } if (!/;[ ]*$/) warnsrc("Semicolon missing at end of line, no problem"); debug("Interface " intname); printh("#ifndef _" intname "_if_h_"); printh("#define _" intname "_if_h_\n"); printc("#include \"" intname "_if.h\"\n"); } # # Pass doc comments through to the C file # function handle_doc () { doc = "" while (!/\*\//) { doc = doc $0 "\n"; getline < src; lineno++; } doc = doc $0 "\n"; return doc; } # # Handle "CODE" and "HEADER" sections. # Returns the code as-is. # function handle_code () { code = "\n"; getline < src; indent = $0; sub(/[^ ].*$/, "", indent); # find the indent used while (!/^}/) { sub("^" indent, ""); # remove the indent code = code $0 "\n"; getline < src; lineno++;; } return code; } # # Handle "METHOD" and "STATICMETHOD" sections. # function handle_method (static, doc) { # # Get the return type and function name and delete that from # the line. What is left is the possibly first function argument # if it is on the same line. # if (!intname) { warnsrc("No interface name defined"); error = 1; return; } sub(/^[^ ]+[ ]+/, ""); ret = $0; sub(/[ ]*\{.*$/, "", ret); name = ret; sub(/^.*[ ]/, "", name); # last element is name of method sub(/[ ]+[^ ]+$/, "", ret); # return type debug("Method: name=" name " return type=" ret); sub(/^[^\{]*\{[ ]*/, ""); if (!name || !ret) { debug($0); warnsrc("Invalid method specification"); error = 1; return; } if (name !~ /^[a-z_][a-z_0-9]*$/) { warnsrc("Invalid method name '" name "', use [a-z_][a-z0-9_]*"); error = 1; return; } if (methods[name]) { warnsrc("Duplicate method name"); error = 1; return; } methods[name] = name; line = $0; while (line !~ /\}/ && (getline < src) > 0) { line = line " " $0; lineno++ } default_function = ""; if (!match(line, /\};?/)) { warnsrc("Premature end of file"); error = 1; return; } extra = substr(line, RSTART + RLENGTH); if (extra ~ /[ ]*DEFAULT[ ]*[a-zA-Z_][a-zA-Z_0-9]*[ ]*;/) { default_function = extra; sub(/.*DEFAULT[ ]*/, "", default_function); sub(/[; ]+.*$/, "", default_function); } else if (extra && opt_d) { # Warn about garbage at end of line. warnsrc("Ignored '" extra "'"); } sub(/\};?.*$/, "", line); # # Create a list of variables without the types prepended. # sub(/^[ ]+/, "", line); # remove leading ... sub(/[ ]+$/, "", line); # ... and trailing whitespace gsub(/[ ]+/, " ", line); # remove double spaces num_arguments = split(line, arguments, / *; */) - 1; delete varnames; # list of varnames num_varnames = 0; for (i = 1; i <= num_arguments; i++) { if (!arguments[i]) continue; # skip argument if argument is empty num_ar = split(arguments[i], ar, /[* ]+/); if (num_ar < 2) { # only 1 word in argument? warnsrc("no type for '" arguments[i] "'"); error = 1; return; } # Last element is name of variable. varnames[++num_varnames] = ar[num_ar]; } argument_list = join(", ", arguments, num_arguments); varname_list = join(", ", varnames, num_varnames); if (opt_d) { warn("Arguments: " argument_list); warn("Varnames: " varname_list); } mname = intname "_" name; # method name umname = toupper(mname); # uppercase method name firstvar = varnames[1]; if (default_function == "") default_function = "kobj_error_method"; # the method description printh("/** @brief Unique descriptor for the " umname "() method */"); printh("extern struct kobjop_desc " mname "_desc;"); # the method typedef printh("/** @brief A function implementing the " umname "() method */"); prototype = "typedef " ret " " mname "_t("; printh(format_line(prototype argument_list ");", line_width, length(prototype))); # Print out the method desc printc("struct kobjop_desc " mname "_desc = {"); printc("\t0, { &" mname "_desc, (kobjop_t)" default_function " }"); printc("};\n"); # Print out the method itself printh(doc); if (0) { # haven't chosen the format yet printh("static __inline " ret " " umname "(" varname_list ")"); printh("\t" join(";\n\t", arguments, num_arguments) ";"); } else { prototype = "static __inline " ret " " umname "("; printh(format_line(prototype argument_list ")", line_width, length(prototype))); } printh("{"); printh("\tkobjop_t _m;"); + if (ret != "void") + printh("\t" ret " rc;"); if (!static) firstvar = "((kobj_t)" firstvar ")"; + if (prolog != "") + printh(prolog); printh("\tKOBJOPLOOKUP(" firstvar "->ops," mname ");"); - retrn = (ret != "void") ? "return " : ""; - printh("\t" retrn "((" mname "_t *) _m)(" varname_list ");"); + rceq = (ret != "void") ? "rc = " : ""; + printh("\t" rceq "((" mname "_t *) _m)(" varname_list ");"); + if (epilog != "") + printh(epilog); + if (ret != "void") + printh("\treturn (rc);"); printh("}\n"); } # # Begin of the main program. # BEGIN { line_width = 80; gerror = 0; # # Process the command line. # num_files = 0; for (i = 1; i < ARGC; i++) { if (ARGV[i] ~ /^-/) { # # awk doesn't have getopt(), so we have to do it ourselves. # This is a bit clumsy, but it works. # for (j = 2; j <= length(ARGV[i]); j++) { o = substr(ARGV[i], j, 1); if (o == "c") opt_c = 1; else if (o == "h") opt_h = 1; else if (o == "p") opt_p = 1; else if (o == "d") opt_d = 1; else if (o == "l") { if (length(ARGV[i]) > j) { opt_l = substr(ARGV[i], j + 1); break; } else { if (++i < ARGC) opt_l = ARGV[i]; else usage(); } } else usage(); } } else if (ARGV[i] ~ /\.m$/) filenames[num_files++] = ARGV[i]; else usage(); } if (!num_files || !(opt_c || opt_h)) usage(); if (opt_p) debug("Will produce files in original not in current directory"); if (opt_l) { if (opt_l !~ /^[0-9]+$/ || opt_l < 1) die("Invalid line width '" opt_l "'"); line_width = opt_l; debug("Line width set to " line_width); } for (i = 0; i < num_files; i++) debug("Filename: " filenames[i]); for (file_i = 0; file_i < num_files; file_i++) { src = filenames[file_i]; cfilename = hfilename = src; sub(/\.m$/, ".c", cfilename); sub(/\.m$/, ".h", hfilename); if (!opt_p) { sub(/^.*\//, "", cfilename); sub(/^.*\//, "", hfilename); } debug("Processing from " src " to " cfilename " / " hfilename); ctmpfilename = cfilename ".tmp"; htmpfilename = hfilename ".tmp"; common_head = \ "/*\n" \ " * This file is produced automatically.\n" \ " * Do not modify anything in here by hand.\n" \ " *\n" \ " * Created from source file\n" \ " * " src "\n" \ " * with\n" \ " * makeobjops.awk\n" \ " *\n" \ " * See the source file for legal information\n" \ " */\n"; printc(common_head "\n" \ "#include \n" \ "#include \n" \ "#include \n" \ "#include "); printh(common_head); delete methods; # clear list of methods intname = ""; lineno = 0; error = 0; # to signal clean up and gerror setting lastdoc = ""; + prolog = ""; + epilog = ""; while (!error && (getline < src) > 0) { lineno++; # # Take special notice of include directives. # if (/^#[ ]*include[ ]+["<][^">]+[">]/) { incld = $0; sub(/^#[ ]*include[ ]+/, "", incld); debug("Included file: " incld); printc("#include " incld); } sub(/#.*/, ""); # remove comments sub(/^[ ]+/, ""); # remove leading ... sub(/[ ]+$/, ""); # ... and trailing whitespace if (/^$/) { # skip empty lines } else if (/^\/\*\*/) lastdoc = handle_doc(); else if (/^INTERFACE[ ]+[^ ;]*[ ]*;?[ ]*$/) { printh(lastdoc); lastdoc = ""; handle_interface(); } else if (/^CODE[ ]*{$/) printc(handle_code()); else if (/^HEADER[ ]*{$/) printh(handle_code()); else if (/^METHOD/) { handle_method(0, lastdoc); lastdoc = ""; + prolog = ""; + epilog = ""; } else if (/^STATICMETHOD/) { handle_method(1, lastdoc); lastdoc = ""; - } else { + prolog = ""; + epilog = ""; + } else if (/^PROLOG[ ]*{$/) + prolog = handle_code(); + else if (/^EPILOG[ ]*{$/) + epilog = handle_code(); + else { debug($0); warnsrc("Invalid line encountered"); error = 1; } } # # Print the final '#endif' in the header file. # printh("#endif /* _" intname "_if_h_ */"); close (ctmpfilename); close (htmpfilename); if (error) { warn("Output skipped"); system_check("rm -f " ctmpfilename " " htmpfilename); gerror = 1; } else { if (opt_c) system_check("mv -f " ctmpfilename " " cfilename); if (opt_h) system_check("mv -f " htmpfilename " " hfilename); } } exit gerror; }