src: Add a new example kernel module

[Repository Conversion <srcmastr%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/cdb03464e89e
branches:  trunk
changeset: 318147:cdb03464e89e
user:      kamil <kamil%NetBSD.org@localhost>
date:      Fri Apr 13 20:30:09 2018 +0000
description:
Add a new example kernel module

executor - basic implementation of callout and RUN_ONCE

While there, perform a small cleanup in README.

Patch by <Siddharth Muralee>
Polishing by myself.

diffstat:

 sys/modules/examples/Makefile            |    3 +-
 sys/modules/examples/README              |   15 ++--
 sys/modules/examples/executor/Makefile   |   11 +++
 sys/modules/examples/executor/executor.c |  108 +++++++++++++++++++++++++++++++
 4 files changed, 129 insertions(+), 8 deletions(-)

diffs (179 lines):

diff -r f06b0f634af7 -r cdb03464e89e sys/modules/examples/Makefile
--- a/sys/modules/examples/Makefile     Fri Apr 13 17:43:37 2018 +0000
+++ b/sys/modules/examples/Makefile     Fri Apr 13 20:30:09 2018 +0000
@@ -1,8 +1,9 @@
-#      $NetBSD: Makefile,v 1.3 2018/04/13 01:20:27 kamil Exp $
+#      $NetBSD: Makefile,v 1.4 2018/04/13 20:30:09 kamil Exp $
 
 .include <bsd.own.mk>
 
 SUBDIR+=       hello
+SUBDIR+=       executor
 #SUBDIR+=      luahello        # Nothing to build here, only text files
 SUBDIR+=       luareadhappy    # Needs an additional Lua script
 SUBDIR+=       ping            # Needs an additional helper program
diff -r f06b0f634af7 -r cdb03464e89e sys/modules/examples/README
--- a/sys/modules/examples/README       Fri Apr 13 17:43:37 2018 +0000
+++ b/sys/modules/examples/README       Fri Apr 13 20:30:09 2018 +0000
@@ -1,17 +1,18 @@
-       $NetBSD: README,v 1.5 2018/04/13 01:20:27 kamil Exp $
+       $NetBSD: README,v 1.6 2018/04/13 20:30:09 kamil Exp $
 
                            Kernel Developer's Manual
 
 DESCRIPTION
      The kernel example dynamic modules.
 
-     This directory contains the following example modules
+     This directory contains the following example modules:
+     * executor        - basic implementation of callout and RUN_ONCE
      * hello           - the simplest `hello world' module
-     * properties      - handle incoming properties during the module load
-     * readhappy       - basic implementation of read(9) with happy numbers
-     * ping            - basic ioctl(9)
      * luahello        - the simplest `hello world' Lua module
      * luareadhappy    - demonstrates calling Lua code from C
+     * properties      - handle incoming properties during the module load
+     * ping            - basic ioctl(9)
+     * readhappy       - basic implementation of read(9) with happy numbers
      * sysctl          - demonstrates adding a sysctl handle dynamically
 
      To build the examples you need a local copy of NetBSD sources. You also
@@ -57,8 +58,8 @@
      ping, luahello and luareadhappy) first appeared in NetBSD 8.0; they were
      written by Kamil Rytarowski.
 
-     The sysctl module first appeared in NetBSD 9.0 and was authored by
-     Siddharth Muralee.
+     The executor and sysctls module first appeared in NetBSD 9.0 and were
+     authored by Siddharth Muralee.
 
 AUTHORS
      This document was written by Kamil Rytarowski.
diff -r f06b0f634af7 -r cdb03464e89e sys/modules/examples/executor/Makefile
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/modules/examples/executor/Makefile    Fri Apr 13 20:30:09 2018 +0000
@@ -0,0 +1,11 @@
+#      $NetBSD: Makefile,v 1.1 2018/04/13 20:30:09 kamil Exp $
+
+.include "../Makefile.inc"
+
+#S?=   /usr/src/sys
+
+KMOD=  executor
+SRCS=  executor.c
+
+.include <bsd.kmodule.mk>
+
diff -r f06b0f634af7 -r cdb03464e89e sys/modules/examples/executor/executor.c
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/modules/examples/executor/executor.c  Fri Apr 13 20:30:09 2018 +0000
@@ -0,0 +1,108 @@
+/*     $NetBSD: executor.c,v 1.1 2018/04/13 20:30:09 kamil Exp $       */
+
+/*-
+ * Copyright (c) 2018 The NetBSD Foundation, Inc.
+ * 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+ */
+
+#include <sys/cdefs.h>
+__KERNEL_RCSID(0, "$NetBSD: executor.c,v 1.1 2018/04/13 20:30:09 kamil Exp $");
+
+#include <sys/param.h>
+#include <sys/module.h>
+#include <sys/callout.h>
+#include <sys/once.h>
+
+/*
+ * Check if dmesg prints
+ * "executor <no-of-seconds-after-loading>" every second
+ * and "executor once" exactly once in the beginning
+ * to test this module
+ */
+
+MODULE(MODULE_CLASS_MISC, executor, NULL);
+
+static void callout_example(void *);
+static int runonce_example(void);
+
+static int executor_count = 0; //To hold the count of seconds
+
+static callout_t sc;
+
+/* Creating a variable that marks whether the function has executed or not */
+static once_t ctl;
+static ONCE_DECL(ctl);
+
+/*
+ * runonce_example : This function should execute only once
+ * It should return 0 as RUN_ONCE calls the function until it returns 0.
+ */
+
+static int
+runonce_example(void) {
+       printf("executor once\n");
+       return 0;
+}
+
+/*
+ * callout_example : This function should get executed every second.
+ * It calls runonce_example each time.
+ * It prints the seconds elasped after the module was loaded.
+ * It reschedules the callout to the next second using callout_schedule
+ */
+
+static void
+callout_example(void *arg) {
+       RUN_ONCE(&ctl, runonce_example);
+       executor_count++;
+       printf("Callout %d\n", executor_count);
+       callout_schedule(&sc, mstohz(1000));
+}
+
+/*
+ * executor_modcmd : has two tasks
+ * On loading the module it needs to initialize a callout handle and schedule
+ * the first callout.
+ * On unloading the module it needs to stop and destroy the callout handle
+ */
+
+static int
+executor_modcmd(modcmd_t cmd, void *arg)
+{
+       switch(cmd) {
+       case MODULE_CMD_INIT:
+               printf("executor module inserted\n");
+               callout_init(&sc, 0);
+               callout_reset(&sc, mstohz(1000), callout_example, NULL);
+               break;
+       case MODULE_CMD_FINI:
+               printf("executor module unloaded\n");
+               callout_stop(&sc);
+               callout_destroy(&sc);
+               break;
+       default:
+               return ENOTTY;
+       }
+       return 0;
+}