Create Static Work
==================

.. panels::
        :container: container pb-4
        :column: col-lg-12 p-2
        :card: shadow

        Topics in this section,

                * :ref:`Version Info <create_static_workqueue_0>`

                * :ref:`Learnings in this program <create_static_workqueue_1>`
                
                * :ref:`Explanation of Workqueue APIs <create_static_workqueue_2>`

                        * :ref:`create_workqueue <create_static_workqueue_3>`

                        * :ref:`INIT_WORK <create_static_workqueue_4>`

                        * :ref:`queue_work <create_static_workqueue_5>`
                        
                        * :ref:`destroy_workqueue <create_static_workqueue_6>`       

                        * :ref:`create_singlethread_workqueue <create_static_workqueue_46>`

                        * :ref:`create_freezable_workqueue <create_static_workqueue_47>`

                * :ref:`Example 1 : Creating a workqueue <create_static_workqueue_7>`

                        * :ref:`List of headers <create_static_workqueue_8>`
                
                        * :ref:`Module macros <create_static_workqueue_9>`

                        * :ref:`Initializing work <create_static_workqueue_10>`

                        * :ref:`Workqueue Handler Function <create_static_workqueue_11>`

                        * :ref:`Queue Start Function <create_static_workqueue_12>`

                        * :ref:`Queue Init Function <create_static_workqueue_13>`

                        * :ref:`Queue Stop Function <create_static_workqueue_14>`

                        * :ref:`Queue Exit Function <create_static_workqueue_15>`

                        * :ref:`Driver entry points <create_static_workqueue_16>`

                        * :ref:`See the full program below <create_static_workqueue_17>`

                        * :ref:`Makefile <create_static_workqueue_18>`

                        * :ref:`Compile and Load <create_static_workqueue_19>`

                * :ref:`Example 2 : Creating a workqueue <create_static_workqueue_20>`

                        * :ref:`List of headers <create_static_workqueue_21>`
                
                        * :ref:`Module macros <create_static_workqueue_22>`

                        * :ref:`Initializing work <create_static_workqueue_23>`

                        * :ref:`Workqueue Handler Function <create_static_workqueue_24>`

                        * :ref:`Queue Start Function <create_static_workqueue_25>`

                        * :ref:`Queue Init Function <create_static_workqueue_26>`

                        * :ref:`Queue Stop Function <create_static_workqueue_27>`

                        * :ref:`Queue Exit Function <create_static_workqueue_28>`

                        * :ref:`Driver entry points <create_static_workqueue_29>`

                        * :ref:`See the full program below <create_static_workqueue_30>`

                        * :ref:`Makefile <create_static_workqueue_31>`

                        * :ref:`Compile and Load <create_static_workqueue_32>`

.. _create_static_workqueue_0:
 
.. tab-set::
 
    .. tab-item:: Version Info

        =============================== =======================================
        #                               Version
        =============================== =======================================
        Ubuntu                          Ubuntu 22.10
        Kernel                          6.8.0
        =============================== =======================================

.. _create_static_workqueue_1:

.. tab-set::

    .. tab-item:: Learnings in this section

        * In this program, you are going to learn

        .. panels::
                :container: container pb-4
                :column: col-lg-12 p-2
                :card: shadow

                * How to create workqueue ?

        .. panels::
                :container: container pb-4
                :column: col-lg-12 p-2
                :card: shadow

                * How to allocate the work to the queue ?

        .. panels::
                :container: container pb-4
                :column: col-lg-12 p-2
                :card: shadow

                * How to use Workqueue APIs ?

                        * `DECLARE_WORK <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L192>`_

                        * `work_busy <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L470>`_

                        * `schedule_work <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L562>`_

                        * `DECLARE_DELAYED_WORK <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L195>`_

                        * `schedule_delayed_work <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L667>`_

                        * `cancel_delayed_work_sync <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L461>`_

        .. panels::
                :container: container pb-4
                :column: col-lg-12 p-2
                :card: shadow

                * How to use below APIs ?

                        * `MODULE_LICENSE <https://elixir.bootlin.com/linux/v6.7.9/source/include/linux/module.h#L230>`_

                        * `MODULE_DESCRIPTION <https://elixir.bootlin.com/linux/v6.7.9/source/include/linux/module.h#L239>`_

                        * `MODULE_AUTHOR <https://elixir.bootlin.com/linux/v6.7.9/source/include/linux/module.h#L236>`_

                        * `module_init <https://elixir.bootlin.com/linux/v6.7.9/source/include/linux/module.h#L88>`_

                        * `module_exit <https://elixir.bootlin.com/linux/v6.7.9/source/include/linux/module.h#L100>`_

.. _create_static_workqueue_2:

.. tab-set::

    .. tab-item:: Explanation of workqueue APIs

        .. _create_static_workqueue_3:

        .. tab-set::

            .. tab-item:: DECLARE_WORK

                * Here is the function prototype of the API: `DECLARE_WORK <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L192>`_

                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        #define DECLARE_WORK(n, f)

                * Here is an example of how to use the API,

                .. code-block:: c

                        static DECLARE_WORK(my_work_1,workqueue_func_1);

        .. _create_static_workqueue_4:

        .. tab-set::

            .. tab-item:: work_busy

                * Here is the function prototype of the API: `work_busy <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L470>`_

                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        extern unsigned int work_busy(struct work_struct *work);

                * Here is an example of how to use the API,

                .. code-block:: c
        
                        work_busy(&my_work_1);

        .. _create_static_workqueue_5:

        .. tab-set::

            .. tab-item:: schedule_work

                * Here is the function prototype of the API: `schedule_work <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L562>`_
                  
                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        static inline bool schedule_work(struct work_struct *work);

                * Here is an example of how to use the API,

                .. code-block:: c

                        schedule_work(&my_work_1);

        .. _create_static_workqueue_6:

        .. tab-set::

            .. tab-item:: DECLARE_DELAYED_WORK

                * Here is the function prototype of the API: `DECLARE_DELAYED_WORK <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L195>`_
               
                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        #define DECLARE_DEFERRABLE_WORK(n, f)

                * Here is an example of how to use the API,

                .. code-block:: c
        
                        static DECLARE_DELAYED_WORK(my_work_1,workqueue_func_1);

        .. _create_static_workqueue_46:

        .. tab-set::

            .. tab-item:: schedule_delayed_work

                * Here is the function prototype of the API: `schedule_delayed_work <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L667>`_

                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        static inline bool schedule_delayed_work(struct delayed_work *dwork, unsigned long delay);

                * Here is an example of how to use the API,

                .. code-block:: c
        
                        schedule_delayed_work(&my_work_1,msecs_to_jiffies(100));

        .. _create_static_workqueue_47:

        .. tab-set::

            .. tab-item:: cancel_delayed_work_sync

                * Here is the function prototype of the API: `cancel_delayed_work_sync <https://elixir.bootlin.com/linux/v6.2/source/include/linux/workqueue.h#L461>`_
                  
                .. code-block:: c

                        #include <linux/workqueue.h>
                        
                        extern bool cancel_delayed_work_sync(struct delayed_work *dwork);

                * Here is an example of how to use the API,

                .. code-block:: c
                        
                        cancel_delayed_work_sync(&my_work_1);

.. _create_static_workqueue_7:

.. tab-set::

    .. tab-item:: Example 1 : Creating and initializing the workqueue

        * In this example let's see how to create workqueue and execute it.

        .. _create_static_workqueue_8:

        .. tab-set::

            .. tab-item:: List of headers

                * Include the follow header files(.h) to refer the API being used for the execution.

                .. code-block:: c

                        #include <linux/init.h>
                        #include <linux/kernel.h>
                        #include <linux/module.h>
                        #include <linux/workqueue.h>
                        #include <linux/delay.h>
                        #include <linux/jiffies.h>

        .. _create_static_workqueue_9:

        .. tab-set::

            .. tab-item:: Module macros

                * Add the following module macros to display information about the license, author and description about the module.

                .. code-block:: c

                        MODULE_LICENSE("GPL");
                        MODULE_AUTHOR("Linux_usr");
                        MODULE_DESCRIPTION("Example of DECLARE_WORK");

        .. _create_static_workqueue_10:

        .. tab-set::

            .. tab-item:: Declare and Initialize work

                * Declare and Initialize the work which we are going to use in this example

                .. code-block:: c

                        static DECLARE_WORK(my_work_1,workqueue_func_1);
                        static DECLARE_WORK(my_work_2,workqueue_func_2);

        .. _create_static_workqueue_11:

        .. tab-set::

            .. tab-item:: Workqueue Handler Function

                * This workqueue_func_1 function executes when work is queued to workqueue.

                .. code-block:: c

                        void workqueue_func_1(struct work_struct *work)
			{
			    int i = 0;
			    while (i < 10) {
				pr_info("Inside workqueue_func_1\n");
				i++;
				msleep(500);
			    }
			}

                * This  workqueue_func_2 function executes when work is queued to workqueue.

                .. code-block:: c

			void workqueue_func_2(struct work_struct * work)
			{
			    int i = 0;
			    while (i < 10) {
				pr_info("Inside workqueue_func_2\n");
				i++;
				msleep(500);
			    }
			}

        .. _create_static_workqueue_12:

        .. tab-set::

            .. tab-item:: Queue Start Function

                * This function executes during execution of queue_start, creates workqueue, intiializes work and queues to the workqueue.

                .. code-block:: c

                        void queue_start(void)
			{
			    static DECLARE_WORK(my_work_1,workqueue_func_1);
			    static DECLARE_WORK(my_work_2,workqueue_func_2);
			    if (!work_busy(&my_work_1))
				schedule_work(&my_work_1);
			    if (!work_busy(&my_work_2))
				schedule_work(&my_work_2);
			}
 
        .. _create_static_workqueue_13:

        .. tab-set::

            .. tab-item:: Queue Init Function

                * This function executes when module is loaded.

                .. code-block:: c

                        static int __init queue_init(void)
                        {
                                pr_info("Inside queue_init function\n");
                                queue_start();
                                return 0;
                        }

        .. _create_static_workqueue_14:

        .. tab-set::

            .. tab-item:: Queue Stop Function

                * This function executes during execution of queue_exit, waits until the completion and destroys workqueue.

                .. code-block:: c

                        void queue_stop(void)
                        {
                                pr_info("Destroying workqueue\n");
                        }

        .. _create_static_workqueue_15:

        .. tab-set::

            .. tab-item:: Queue Exit Function

                * This function executes when module is unloaded.

                .. code-block:: c

                        static void __exit queue_exit(void)
                        {
                                pr_info("Inside queue_exit function\n");
                                queue_stop();
                                return;
                        }

        .. _create_static_workqueue_16:

        .. tab-set::

            .. tab-item:: Driver entry points

                * Add the driver entry points which will be executed once the module is inserted or removed from the kernel.

                .. code-block:: c

                        module_init(queue_init);
                        module_exit(queue_exit);

.. _create_static_workqueue_17:

.. tab-set::

    .. tab-item:: See the full program below

        .. tab-set::

            .. tab-item:: tc1.c
                
                .. literalinclude:: create_static_work/DECLARE_WORK/tc1.c
	            :language: c
        	    :linenos:

.. _create_static_workqueue_18:

.. tab-set::

    .. tab-item:: Makefile

	.. literalinclude:: create_static_work/DECLARE_WORK/Makefile
		:language: c
		:linenos:

.. _create_static_workqueue_19:

.. tab-set::

    .. tab-item:: Compile and Load
        
        * Run make to load the kernel module.

        .. code-block:: shell

                $ make

        * Check if work_queue.ko is generated or not using ls command.

        .. code-block:: shell

                $ ls -l
                total 376
		-rw-rw-r-- 1 test test    151 Aug  2 11:44 Makefile
		-rw-rw-r-- 1 test test     78 Aug  2 12:35 modules.order
		-rw-rw-r-- 1 test test      0 Aug  2 12:35 Module.symvers
		-rw-rw-r-- 1 test test   2108 Aug  2 11:44 tc1.c
		-rw-rw-r-- 1 test test 179016 Aug  2 12:35 tc1.ko
		-rw-rw-r-- 1 test test     78 Aug  2 12:35 tc1.mod
		-rw-rw-r-- 1 test test   1088 Aug  2 12:35 tc1.mod.c
		-rw-rw-r-- 1 test test 149280 Aug  2 12:35 tc1.mod.o
		-rw-rw-r-- 1 test test  31192 Aug  2 12:35 tc1.o

        * Load the module to kernel using insmod command.

        .. code-block:: shell

            $ sudo insmod ./tc1.ko
           
        * Check kernel messages to verify if the module is loaded or not.

        .. code-block:: shell
                
                $ dmesg
                [ 1002.253754] Inside queue_init function
		[ 1002.254259] Inside workqueue_func_1
		[ 1002.254796] Inside workqueue_func_2
		[ 1002.778660] Inside workqueue_func_2
		[ 1002.778688] Inside workqueue_func_1
		[ 1003.290690] Inside workqueue_func_1
		[ 1003.290706] Inside workqueue_func_2
		[ 1003.802673] Inside workqueue_func_1
		[ 1003.802700] Inside workqueue_func_2
		[ 1004.314534] Inside workqueue_func_2
		[ 1004.314554] Inside workqueue_func_1
		[ 1004.826694] Inside workqueue_func_1
		[ 1004.826711] Inside workqueue_func_2
		[ 1005.338667] Inside workqueue_func_2
		[ 1005.338685] Inside workqueue_func_1
		[ 1005.850679] Inside workqueue_func_1
		[ 1005.850696] Inside workqueue_func_2
		[ 1006.362675] Inside workqueue_func_2
		[ 1006.362692] Inside workqueue_func_1
		[ 1006.874679] Inside workqueue_func_1
		[ 1006.874695] Inside workqueue_func_2
           
        * Unload the module using rmmod command.

        .. code-block:: shell
                
                $ sudo rmmod tc1 

        * Check kernel messages to see if the module is unloaded or not.

        .. code-block:: shell

                $ dmesg
                [ 1020.585671] Inside queue_exit function
                [ 1020.585677] Destroying workqueue

.. _create_static_workqueue_20:

.. tab-set::

    .. tab-item:: Example 2 : Creating and initializing the workqueue

        * In this example let's see how to Create and initialize the workqueue workqueue and execute it.

        .. _create_static_workqueue_21:

        .. tab-set::

            .. tab-item:: List of headers

                * Include the follow header files(.h) to refer the API being used for the execution.

                .. code-block:: c

                        #include <linux/init.h>
                        #include <linux/kernel.h>
                        #include <linux/module.h>
                        #include <linux/workqueue.h>
                        #include <linux/delay.h>
                        #include <linux/jiffies.h>

        .. _create_static_workqueue_22:

        .. tab-set::

            .. tab-item:: Module macros

                * Add the following module macros to display information about the license, author and description about the module.

                .. code-block:: c

                        MODULE_LICENSE("GPL");
                        MODULE_AUTHOR("Linux_usr");
                        MODULE_DESCRIPTION("Example of DECLARE_DELAYED_WORK");

        .. _create_static_workqueue_23:

        .. tab-set::

            .. tab-item:: Declaring and Initializing work

                * Declare and Initialize the work which we are going to use in this example

                .. code-block:: c

                        static DECLARE_DELAYED_WORK(my_work_1,workqueue_func_1);
                        static DECLARE_DELAYED_WORK(my_work_2,workqueue_func_2);

        .. _create_static_workqueue_24:

        .. tab-set::

            .. tab-item:: Workqueue Handler Function

                * This workqueue_func_1 function executes when work is queued to workqueue.

                .. code-block:: c

                        void workqueue_func_1(struct work_struct *work)
			{
			    int i = 0;
			    while (i < 10) {
				pr_info("Inside workqueue_func_1\n");
				i++;
				msleep(500);
			    }
			}

                * This workqueue_func_2 function executes when work is queued to workqueue.

                .. code-block:: c

			void workqueue_func_2(struct work_struct * work)
			{
			    int i = 0;
			    while (i < 10) {
				pr_info("Inside workqueue_func_2\n");
				i++;
				msleep(500);
			    }
			}

        .. _create_static_workqueue_25:

        .. tab-set::

            .. tab-item:: Queue Start Function

                * This function executes during execution of queue_start, creates workqueue, intiializes work and queues to the workqueue.

                .. code-block:: c

                        void queue_start(void)
                        {
                                schedule_delayed_work(&my_work_1,msecs_to_jiffies(100));
                                schedule_delayed_work(&my_work_2,msecs_to_jiffies(50));
                        }
 
        .. _create_static_workqueue_26:

        .. tab-set::

            .. tab-item:: Queue Init Function

                * This function executes when module is loaded.

                .. code-block:: c

                        static int __init queue_init(void)
                        {  
                                pr_info("Inside queue_init function\n");
                                queue_start();
                                return 0;
                        }

        .. _create_static_workqueue_27:

        .. tab-set::

            .. tab-item:: Queue Stop Function

                * This function executes during execution of queue_exit, waits until the completion and destroys workqueue.

                .. code-block:: c

                        void queue_stop(void)
                        {
                                pr_info("Destroying workqueue\n");
                                cancel_delayed_work_sync(&my_work_1);
                                cancel_delayed_work_sync(&my_work_2);
                        }

        .. _create_static_workqueue_28:

        .. tab-set::

            .. tab-item:: Queue Exit Function

                * This function executes when module is unloaded.

                .. code-block:: c

                        static void __exit queue_exit(void)
                        {
                                pr_info("Inside queue_exit function\n");
                                queue_stop();
                                return;
                        }

        .. _create_static_workqueue_29:

        .. tab-set::

            .. tab-item:: Driver entry points

                * Add the driver entry points which will be executed once the module is inserted or removed from the kernel.

                .. code-block:: c

                        module_init(queue_init);
                        module_exit(queue_exit);

.. _create_static_workqueue_30:

.. tab-set::

    .. tab-item:: See the full program below

        .. tab-set::

            .. tab-item:: tc2.c
                
                .. literalinclude:: create_static_work/DECLARE_DELAYED_WORK/tc2.c
	            :language: c
        	    :linenos:

.. _create_static_workqueue_31:

.. tab-set::

    .. tab-item:: Makefile

	.. literalinclude:: create_static_work/DECLARE_DELAYED_WORK/Makefile
		:language: c
		:linenos:

.. _create_static_workqueue_32:

.. tab-set::

    .. tab-item:: Compile and Load
        
        * Run make to load the kernel module.

        .. code-block:: shell

                $ make

        * Check if work_queue.ko is generated or not using ls command.

        .. code-block:: shell

                $ ls -l
                total 384
		-rw-rw-r-- 1 test test    151 Aug  2 11:44 Makefile
		-rw-rw-r-- 1 test test     86 Aug  2 12:37 modules.order
		-rw-rw-r-- 1 test test      0 Aug  2 12:37 Module.symvers
		-rw-rw-r-- 1 test test   2162 Aug  2 11:44 tc2.c
		-rw-rw-r-- 1 test test 183096 Aug  2 12:37 tc2.ko
		-rw-rw-r-- 1 test test     86 Aug  2 12:37 tc2.mod
		-rw-rw-r-- 1 test test   1154 Aug  2 12:37 tc2.mod.c
		-rw-rw-r-- 1 test test 149360 Aug  2 12:37 tc2.mod.o
		-rw-rw-r-- 1 test test  35232 Aug  2 12:37 tc2.o

        * Load the module to kernel using insmod command.

        .. code-block:: shell

                $ sudo insmod ./tc2.ko
           
        * Check kernel messages to verify if the module is loaded or not.

        .. code-block:: shell
                
                $ dmesg
                [ 1103.744537] Inside queue_init function
		[ 1103.802566] Inside workqueue_func_2
		[ 1103.846670] Inside workqueue_func_1
		[ 1104.318668] Inside workqueue_func_2
		[ 1104.382460] Inside workqueue_func_1
		[ 1104.826648] Inside workqueue_func_2
		[ 1104.890626] Inside workqueue_func_1
		[ 1105.338669] Inside workqueue_func_2
		[ 1105.402457] Inside workqueue_func_1
		[ 1105.850645] Inside workqueue_func_2
		[ 1105.914622] Inside workqueue_func_1
		[ 1106.362673] Inside workqueue_func_2
		[ 1106.426647] Inside workqueue_func_1
		[ 1106.874644] Inside workqueue_func_2
		[ 1106.938592] Inside workqueue_func_1
		[ 1107.386669] Inside workqueue_func_2
		[ 1107.450623] Inside workqueue_func_1
		[ 1107.898637] Inside workqueue_func_2
		[ 1107.962624] Inside workqueue_func_1
		[ 1108.410666] Inside workqueue_func_2
		[ 1108.474643] Inside workqueue_func_1
           
        * Unload the module using rmmod command.

        .. code-block:: shell
                
                $ sudo rmmod tc2

        * Check kernel messages to see if the module is unloaded or not.

        .. code-block:: shell

                $ dmesg
                [ 1117.920445] Inside queue_exit function
                [ 1117.920449] Destroying workqueue