LDT - Linux Driver Template

Quoted 1 line

+ * Device Model (class, device)

Don't use class code in an example, it is slowly going away from the whole kernel.

Quoted 3 lines

Quoted 1 line

+ * Device Model (class, device)

Don't use class code in an example, it is slowly going away from the whole kernel.

What to use instead class_create and device_create?

Quoted 4 lines · Constantine Shulyupin

Quoted 3 lines

Quoted 1 line

+ * Device Model (class, device)

Don't use class code in an example, it is slowly going away from the whole kernel.

What to use instead class_create and device_create?

What are you trying to do?

Quoted 7 lines · Greg KH

Quoted 4 lines · Constantine Shulyupin

Quoted 3 lines

Quoted 1 line

+ * Device Model (class, device)

Don't use class code in an example, it is slowly going away from the whole kernel.

What to use instead class_create and device_create?

What are you trying to do?

I trying to properly register char device and device region. Single char device could be registered as misc device with just misc_register.

How to register properly char devices region?

Should to use device_register instead device_create to create dev files?

Which other registration functions char device must to call besides alloc_chrdev_region, cdev_add?

Now I agree using the char interface isn't the most "obvious" and I have a set of ideas/half-baked patches floating around that aim to clean it up, but for now, I'd recommend just using the misc interface, it's worlds simpler, makes sense, and handles all of the struct device work for you automatically.

samples/ltd/ldt.c line 80

Quoted 2 lines

samples/ltd/ldt.c new file +2 -0

+#define pr_debug_hex(h)      pr_debug("%s:%d %s %s = 0x%lX\n", \
+     __file__, __LINE__, __func__, #h, (long int)h)

This is not needed at all, just use the proper printk() attribute.

Quoted 4 lines · Greg KH

samples/ltd/ldt.c line 80

Quoted 2 lines

samples/ltd/ldt.c new file +2 -0

+#define pr_debug_hex(h)      pr_debug("%s:%d %s %s = 0x%lX\n", \
+     __file__, __LINE__, __func__, #h, (long int)h)

This is not needed at all, just use the proper printk() attribute.

Macro above allows tidy tracing code:

        pr_debug_hex(ioread8(port_ptr + UART_IER));
        pr_debug_hex(ioread8(port_ptr + UART_IIR));
        pr_debug_hex(ioread8(port_ptr + UART_FCR));
        pr_debug_hex(ioread8(port_ptr + UART_LCR));
        pr_debug_hex(ioread8(port_ptr + UART_MCR));
        pr_debug_hex(ioread8(port_ptr + UART_LSR));
        pr_debug_hex(ioread8(port_ptr + UART_MSR));

Without that macro, code above should be rewritten with pr_debug (or printk) as:

        pr_debug("UART_IER=0x%02X\n", ioread8(port_ptr + UART_IER));
        pr_debug("UART_IIR=0x%02X\n", ioread8(port_ptr + UART_IIR));
        pr_debug("UART_FCR=0x%02X\n", ioread8(port_ptr + UART_FCR));
        pr_debug("UART_LCR=0x%02X\n", ioread8(port_ptr + UART_LCR));
        pr_debug("UART_MCR=0x%02X\n", ioread8(port_ptr + UART_MCR));
        pr_debug("UART_LSR=0x%02X\n", ioread8(port_ptr + UART_LSR));
        pr_debug("UART_MSR=0x%02X\n", ioread8(port_ptr + UART_MSR));

That is less readable and less supportable.

I prefer the fist case.

Actually I use a lot shorter macro:
#define traceh(h) printk("%s = 0x%lX\n", #h, (long int)h)

What is you opinion? Which method is better?

Quoted 4 lines · Greg KH

samples/ltd/ldt.c line 80

Quoted 2 lines

samples/ltd/ldt.c new file +2 -0

+#define pr_debug_hex(h)      pr_debug("%s:%d %s %s = 0x%lX\n", \
+     __file__, __LINE__, __func__, #h, (long int)h)

This is not needed at all, just use the proper printk() attribute.

Macro above allows tidy tracing code:

        pr_debug_hex(ioread8(port_ptr + UART_IER));
        pr_debug_hex(ioread8(port_ptr + UART_IIR));
        pr_debug_hex(ioread8(port_ptr + UART_FCR));
        pr_debug_hex(ioread8(port_ptr + UART_LCR));
        pr_debug_hex(ioread8(port_ptr + UART_MCR));
        pr_debug_hex(ioread8(port_ptr + UART_LSR));
        pr_debug_hex(ioread8(port_ptr + UART_MSR));

Without that macro, code above should be rewritten with pr_debug (or printk) as:

        pr_debug("UART_IER=0x%02X\n", ioread8(port_ptr + UART_IER));
        pr_debug("UART_IIR=0x%02X\n", ioread8(port_ptr + UART_IIR));
        pr_debug("UART_FCR=0x%02X\n", ioread8(port_ptr + UART_FCR));
        pr_debug("UART_LCR=0x%02X\n", ioread8(port_ptr + UART_LCR));
        pr_debug("UART_MCR=0x%02X\n", ioread8(port_ptr + UART_MCR));
        pr_debug("UART_LSR=0x%02X\n", ioread8(port_ptr + UART_LSR));
        pr_debug("UART_MSR=0x%02X\n", ioread8(port_ptr + UART_MSR));

That is less readable and less supportable.

I prefer the fist case.

Actually I use a lot shorter macro:
#define traceh(h) printk("%s = 0x%lX\n", #h, (long int)h)

What is you opinion? Which method is better?

From: Constantine Shulyupin <[email protected]>

LDT is useful for Linux driver development beginners,
hackers and as starting point for a new drivers.
The driver uses following Linux facilities: module, platform driver, file operations (read/write, mmap, ioctl, blocking and nonblocking mode, polling), kfifo, completion, interrupt, tasklet, work, kthread, timer, simple misc device, multiple char devices, Device Model, configfs, UART 0x3f8,
HW loopback, SW loopback, ftracer.

Signed-off-by Constantine Shulyupin <[email protected]>

---
 samples/Kconfig             |   14 +
 samples/Makefile            |    5 +-
 samples/ltd/Makefile        |    1 +
 samples/ltd/ldt.c           |  764 +++++++++++++++++++++++++++++++++++++++++++
 samples/ltd/ldt_plat_dev.c  |   68 ++++
 tools/testing/ldt/Makefile  |    6 +
 tools/testing/ldt/ctracer.h |  380 +++++++++++++++++++++
 tools/testing/ldt/dio.c     |  362 ++++++++++++++++++++
 tools/testing/ldt/ldt-test  |  142 ++++++++
 9 files changed, 1740 insertions(+), 2 deletions(-)
 create mode 100644 samples/ltd/Makefile
 create mode 100644 samples/ltd/ldt.c
 create mode 100644 samples/ltd/ldt_plat_dev.c
 create mode 100644 tools/testing/ldt/Makefile
 create mode 100644 tools/testing/ldt/ctracer.h
 create mode 100644 tools/testing/ldt/dio.c
 create mode 100755 tools/testing/ldt/ldt-test

samples/Kconfig +14 -0

index 7b6792a..2b93fd0 100644
@@ -69,4 +69,18 @@ config SAMPLE_RPMSG_CLIENT
 	  to communicate with an AMP-configured remote processor over
 	  the rpmsg bus.
 
+config SAMPLE_DRIVER_TEMPLATE
+	tristate "LDT - Linux driver template"
+	help
+	  Template of Linux device driver. Useful for Linux driver
+	  development beginners, hackers and as starting point for a new drivers.
+	  The driver uses following Linux facilities: module, platform driver,
+	  file operations (read/write, mmap, ioctl, blocking and nonblocking mode, polling),
+	  kfifo, completion, interrupt, tasklet, work, kthread, timer, simple misc device,
+	  multiple char devices, Device Model, configfs, UART 0x3f8, HW loopback,
+	  SW loopback, ftracer.
+	  Usermode test script and utility are located in tools/testing/ldt/
+
+	  List of more samples and skeletons can be found at http://elinux.org/Device_drivers
+
 endif # SAMPLES

samples/Makefile +3 -2

index 5ef08bb..d4b1818 100644
@@ -1,4 +1,5 @@
 # Makefile for Linux samples code
 
-obj-$(CONFIG_SAMPLES)	+= kobject/ kprobes/ tracepoints/ trace_events/ \
-			   hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/
+obj-$(CONFIG_SAMPLES)	+= kobject/ kprobes/ tracepoints/ trace_events/
+obj-$(CONFIG_SAMPLES)	+= hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/
+obj-$(CONFIG_SAMPLES)	+= ldt/

samples/ltd/Makefile new file +1 -0

new file mode 100644
index 0000000..efd691f
@@ -0,0 +1 @@
+obj-$(SAMPLE_DRIVER_TEMPLATE)+= ldt.o ldt_plat_dev.o

samples/ltd/ldt.c new file +74 -0

new file mode 100644
index 0000000..a4d2b3b
@@ -0,0 +1,764 @@
+/*
+ *	LDT - Linux Driver Template
+ *
+ *	Copyright (C) 2012 Constantine Shulyupin http://www.makelinux.net/
+ *
+ *	Dual BSD/GPL License
+ *
+ *
+ *	The driver demonstrates usage of following Linux facilities:
+ *
+ *	Linux kernel module
+ *	file_operations
+ *		read and write (UART)
+ *		blocking read
+ *		polling
+ *		mmap
+ *		ioctl
+ *	kfifo
+ *	completion
+ *	interrupt
+ *	tasklet
+ *	timer
+ *	work
+ *	kthread
+ *	simple single misc device file (miscdevice, misc_register)
+ *	multiple char device files (alloc_chrdev_region)
+ *	debugfs
+ *	platform_driver and platform_device in another module
+ *	simple UART driver on port 0x3f8 with IRQ 4
+ *	Device Model (class, device)
+ *	Power Management (dev_pm_ops)
+ *	Device Tree (of_device_id)
+ *
+ *	TODO:
+ *	linked list
+ *	private instance state struct
+ *
+ */
+
+#include <linux/io.h>
+#include <linux/mm.h>
+#include <linux/interrupt.h>
+#include <linux/sched.h>
+#include <linux/delay.h>
+#include <linux/kthread.h>
+#include <linux/timer.h>
+#include <linux/kfifo.h>
+#include <linux/fs.h>
+#include <linux/poll.h>
+#include <linux/module.h>
+#include <linux/miscdevice.h>
+#include <linux/platform_device.h>
+#include <linux/serial_reg.h>
+#include <linux/debugfs.h>
+#include <linux/cdev.h>
+#include <linux/of.h>
+#include <linux/of_platform.h>
+#include <linux/mod_devicetable.h>
+
+#define ctracer_cut_path(fn) (fn[0] != '/' ? fn : (strrchr(fn, '/') + 1))
+#define __file__	ctracer_cut_path(__FILE__)
+
+/*
+ *	print_context prints execution context:
+ *	hard interrupt, soft interrupt or scheduled task
+ */
+
+#define print_context()	\
+	pr_debug("%s:%d %s %s 0x%x\n", __file__, __LINE__, __func__, \
+			(in_irq() ? "harirq" : current->comm), preempt_count());
+
+#define once(exp) do { \
+	static int _passed; if (!_passed) { exp; }; _passed = 1; } while (0)
+

samples/ltd/ldt.c new file +20 -0

+
+static int port;
+module_param(port, int, 0);
+static int port_size;
+module_param(port_size, int, 0);
+
+static int irq;
+module_param(irq, int, 0);
+
+static int loopback;
+module_param(loopback, int, 0);
+
+static int isr_counter;
+static int ldt_work_counter;
+
+#define FIFO_SIZE 128		/* should be power of two */
+static DEFINE_KFIFO(in_fifo, char, FIFO_SIZE);
+static DEFINE_KFIFO(out_fifo, char, FIFO_SIZE);
+
+static DECLARE_WAIT_QUEUE_HEAD(ldt_readable);

samples/ltd/ldt.c new file +8 -0

+{
+	kfifo_in_spinlocked(&in_fifo, data, size, &fifo_lock);
+	wake_up_interruptible(&ldt_readable);
+}
+
+/*
+ *	ldt_send - send data to HW port or emulated SW loopback
+ */

samples/ltd/ldt.c new file +86 -0

+			pr_debug_hex(ioread8(port_ptr + UART_LSR));
+			pr_debug_dec(data_out);
+			if (data_out >= 32)
+				pr_debug("data_out = '%c' ", data_out);
+			ldt_send(&data_out, sizeof(data_out));
+		}
+		while (rx_ready()) {
+			pr_debug_hex(ioread8(port_ptr + UART_LSR));
+			data_in = ioread8(port_ptr + UART_RX);
+			pr_debug_dec(data_in);
+			if (data_in >= 32)
+				pr_debug("data_out = '%c' ", data_in);
+			ldt_received(&data_in, sizeof(data_in));
+		}
+	} else {
+		while (kfifo_out_spinlocked(&out_fifo, &data_out, sizeof(data_out), &fifo_lock)) {
+			pr_debug_dec(data_out);
+			ldt_send(&data_out, sizeof(data_out));
+		}
+	}
+	schedule_work(&ldt_work);
+	complete(&ldt_complete);
+}
+
+static DECLARE_TASKLET(ldt_tasklet, ldt_tasklet_func, 0);
+
+/*
+ *	interrupt
+ */
+
+static irqreturn_t ldt_isr(int irq, void *dev_id, struct pt_regs *regs)
+{
+	/*
+	 *      UART interrupt is not fired in loopback mode,
+	 *      therefore fire ldt_tasklet from timer too
+	 */
+	once(print_context());
+	isr_counter++;
+	pr_debug_hex(ioread8(port_ptr + UART_FCR));
+	pr_debug_hex(ioread8(port_ptr + UART_IIR));
+	tasklet_schedule(&ldt_tasklet);
+	return IRQ_HANDLED;	/* our IRQ */
+}
+
+/*
+ *	timer
+ */
+
+static struct timer_list ldt_timer;
+static void ldt_timer_func(unsigned long data)
+{
+	/*
+	 *      this timer is used just to fire ldt_tasklet,
+	 *      when there is no interrupt in loopback mode
+	 */
+	if (loopback)
+		tasklet_schedule(&ldt_tasklet);
+	mod_timer(&ldt_timer, jiffies + HZ / 100);
+}
+
+static DEFINE_TIMER(ldt_timer, ldt_timer_func, 0, 0);
+
+/*
+ *	file_operations
+ */
+
+static int ldt_open(struct inode *inode, struct file *file)
+{
+	print_context();
+	pr_debug_dec(imajor(inode));
+	pr_debug_dec(iminor(inode));
+	pr_debug_hex(file->f_flags & O_NONBLOCK);
+	return 0;
+}
+
+static int ldt_release(struct inode *inode, struct file *file)
+{
+	print_context();
+	pr_debug_dec(imajor(inode));
+	pr_debug_dec(iminor(inode));
+	pr_debug_dec(isr_counter);
+	pr_debug_dec(ldt_work_counter);
+	return 0;
+}
+
+/*

samples/ltd/ldt.c new file +11 -0

+exit:
+	return ret ? ret : copied;
+}
+
+/*
+ *	write
+ */
+
+static DEFINE_MUTEX(write_lock);
+
+static ssize_t ldt_write(struct file *file, const char __user * buf, size_t count, loff_t * ppos)

samples/ltd/ldt.c new file +39 -0

+		if (value)
+			__set_bit(mask, &page->flags);
+		else
+			__clear_bit(mask, &page->flags);
+}
+
+/*
+ *	mmap
+ */
+static int ldt_mmap(struct file *filp, struct vm_area_struct *vma)
+{
+	void *buf = NULL;
+	if (vma->vm_flags & VM_WRITE)
+		buf = in_buf;
+	else if (vma->vm_flags & VM_READ)
+		buf = out_buf;
+	if (!buf)
+		return -EINVAL;
+	if (remap_pfn_range(vma, vma->vm_start, virt_to_phys(buf) >> PAGE_SHIFT,
+			    vma->vm_end - vma->vm_start, vma->vm_page_prot)) {
+		pr_err_msg("remap_pfn_range failed");
+		return -EAGAIN;
+	}
+	return 0;
+}
+
+/*
+ *	ioctl
+ */
+
+#define trace_ioctl(nr) printk("ioctl=(%c%c %c #%i %i)\n", \
+	(_IOC_READ & _IOC_DIR(nr)) ? 'r' : ' ', (_IOC_WRITE & _IOC_DIR(nr)) ? 'w' : ' ', \
+	_IOC_TYPE(nr), _IOC_NR(nr), _IOC_SIZE(nr))
+
+static long ldt_ioctl(struct file *f, unsigned int cmnd, unsigned long arg)
+{
+	void __user *user = (void *)arg;
+	pr_debug_hex(cmnd);
+	pr_debug_hex(arg);

samples/ltd/ldt.c new file +10 -0

+	switch (_IOC_TYPE(cmnd)) {
+	case 'A':
+		switch (_IOC_NR(cmnd)) {
+		case 0:
+			break;
+		}
+		break;
+	}
+	return 0;
+}

samples/ltd/ldt.c new file +4 -0

+#endif
+
+/*
+ *	kthread

samples/ltd/ldt.c new file +19 -0

+
+static int ldt_thread(void *data)
+{
+	int ret = 0;
+	print_context();
+	allow_signal(SIGINT);
+	while (!kthread_should_stop()) {
+		ret = wait_for_completion_interruptible(&ldt_complete);
+		if (ret == -ERESTARTSYS) {
+			pr_err_msg("interrupted");
+			ret = -EINTR;
+			break;
+		}
+		ret = ldt_thread_sub(data);
+	}
+	return ret;
+}
+
+/*

samples/ltd/ldt.c new file +15 -0

+		}
+		if (!uart_detected && loopback) {
+			pr_warn("Emulating loopback in software\n");
+			ret = -ENODEV;
+		}
+	}
+	pr_debug_hex(uart_detected);
+	pr_debug_hex(ioread8(port_ptr + UART_IER));
+	pr_debug_hex(ioread8(port_ptr + UART_IIR));
+	pr_debug_hex(ioread8(port_ptr + UART_FCR));
+	pr_debug_hex(ioread8(port_ptr + UART_LCR));
+	pr_debug_hex(ioread8(port_ptr + UART_MCR));
+	pr_debug_hex(ioread8(port_ptr + UART_LSR));
+	pr_debug_hex(ioread8(port_ptr + UART_MSR));
+	return ret;

samples/ltd/ldt.c new file +19 -0

+	dev_t devid;
+	devid = MKDEV(major, 0);
+	ret = check(alloc_chrdev_region(&devid, 0, devs, dev_name));
+	major = MAJOR(devid);
+	pr_debug_dec(major);
+	cdev_init(&ldt_cdev, &ldt_fops);
+	check(cdev_add(&ldt_cdev, MKDEV(major, 0), devs));
+	ldt_class = class_create(THIS_MODULE, dev_name);
+	/* ldt_class->devnode = ldt_devnode; */
+	ldt_dev = device_create(ldt_class, NULL, devid, NULL, "%s", dev_name);
+	for (d = 1; d < devs; d++)
+		device_create(ldt_class, NULL, MKDEV(major, d), NULL, "%s%d", dev_name, d);
+	pr_debug_dec(IS_ERR(ldt_dev));
+	pr_debug_hex(ldt_dev);
+	return major;
+}
+
+/*
+ *	ldt_probe - main initialization function

samples/ltd/ldt.c new file +79 -0

+		dev_dbg(&pdev->dev, "%s:%d %s detaching driver\n", __file__, __LINE__, __func__);
+	/* remove_proc_entry(ldt_name, NULL); depricated */
+	if (debugfs)
+		debugfs_remove(debugfs);
+#ifdef USE_MISCDEV
+	misc_deregister(&ldt_miscdev);
+#else
+	for (d = 0; d < devs; d++)
+		device_destroy(ldt_class, MKDEV(major, d));
+	class_destroy(ldt_class);
+	cdev_del(&ldt_cdev);
+	unregister_chrdev_region(MKDEV(major, 0), devs);
+#endif
+	if (!IS_ERR_OR_NULL(thread)) {
+		send_sig(SIGINT, thread, 1);
+		kthread_stop(thread);
+	}
+	del_timer(&ldt_timer);
+	if (port_r)
+		release_region(port, port_size);
+	if (irq) {
+		if (uart_detected) {
+			iowrite8(0, port_ptr + UART_IER);
+			iowrite8(0, port_ptr + UART_FCR);
+			iowrite8(0, port_ptr + UART_MCR);
+			ioread8(port_ptr + UART_RX);
+		}
+		free_irq(irq, THIS_MODULE);
+	}
+	tasklet_kill(&ldt_tasklet);
+	if (in_buf) {
+		pages_flag(virt_to_page(in_buf), PFN_UP(bufsize), PG_reserved, 0);
+		free_pages_exact(in_buf, bufsize);
+	}
+	if (out_buf) {
+		pages_flag(virt_to_page(out_buf), PFN_UP(bufsize), PG_reserved, 0);
+		free_pages_exact(out_buf, bufsize);
+	}
+	pr_debug_dec(isr_counter);
+	pr_debug_dec(ldt_work_counter);
+	if (port_ptr)
+		ioport_unmap(port_ptr);
+	return 0;
+}
+
+#ifdef USE_PLATFORM_DEVICE
+
+/*
+ * Following code requires platform_device (ldt_plat_dev.*) to work
+ */
+
+#ifdef CONFIG_PM
+
+static int ldt_suspend(struct device *dev)
+{
+	return 0;
+}
+
+static int ldt_resume(struct device *dev)
+{
+	return 0;
+}
+
+static const struct dev_pm_ops ldt_pm = {
+	.suspend = ldt_suspend,
+	.resume = ldt_resume,
+};
+
+#define ldt_pm_ops (&ldt_pm)
+#else
+#define ldt_pm_ops NULL
+#endif
+
+static const struct of_device_id ldt_of_match[] = {
+	{.compatible = "linux-driver-template",},
+	{},
+};
+
+MODULE_DEVICE_TABLE(of, ldt_of_match);

samples/ltd/ldt.c new file +16 -0

+}
+
+static void ldt_exit(void)
+{
+	platform_driver_unregister(&ldt_driver);
+}
+
+module_init(ldt_init);
+module_exit(ldt_exit);
+#endif /* module_platform_driver */
+
+#else /* !USE_PLATFORM_DEVICE */
+
+/*
+ *	Standalone module initialization to run without platform_device
+ */

samples/ltd/ldt.c new file +9 -0

+}
+
+module_init(ldt_init);
+module_exit(ldt_exit);
+#endif
+
+MODULE_DESCRIPTION("LDT - Linux Driver Template");
+MODULE_AUTHOR("Constantine Shulyupin <[email protected]>");
+MODULE_LICENSE("Dual BSD/GPL");

samples/ltd/ldt_plat_dev.c new file +26 -0

new file mode 100644
index 0000000..cd45057
@@ -0,0 +1,68 @@
+/*
+ *	LDT - Linux Driver Template
+ *
+ *	Copyright (C) 2012 Constantine Shulyupin  http://www.makelinux.net/
+ *
+ *	Dual BSD/GPL License
+ *
+ *	platform_device template driver
+ *
+ *	uses
+ *
+ *	platform_data
+ *	resources
+ *
+ */
+
+#include <linux/module.h>
+#include <linux/platform_device.h>
+#include "tracing.h"
+
+static struct resource ldt_resource[] = {
+	{
+	 .flags = IORESOURCE_IO,
+	 .start = 0x3f8,
+	 .end = 0x3ff,
+	 },

samples/ltd/ldt_plat_dev.c new file +10 -0

+	.dev.platform_data = "test data",
+	.dev.release = ldt_dev_release,
+};
+
+static int ldt_plat_dev_init(void)
+{
+	return platform_device_register(&ldt_platform_device);
+}
+
+static void ldt_plat_dev_exit(void)

Quoted 2 lines · Constantine Shulyupin

From: Constantine Shulyupin <[email protected]>
+ if (kfifo_is_empty(&in_fifo)) {

Doesn't this require locking against whatever is filling the fifo?

Quoted 1 line

+ if (mutex_lock_interruptible(&read_lock)) {

The read_lock is only used here, so would only protect against concurrent reads. Isn't the read for a device function already synchronised against itself by the caller?

Quoted 1 line

+ ret = kfifo_from_user(&out_fifo, buf, count, &copied);

Shouldn't this function be grabbing fifo_lock to prevent concurrent access to the fifo by the tasklet function? write_lock has the same issues described for read_lock above.

Doing this is the past has always led to obsolete stale broken examples because they are not actively in use and maintained. Far better to work from actual live in use driver code.