From 86028619b9f653a30f5aa0d331fdedd899a1eea5 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Tue, 16 Aug 2011 18:42:22 +0200 Subject: docs/sysfs: Specify ABI documentation requirements Although it is expected nowadays that every new sysfs attribute is documented under Documentation/ABI, this is not yet mentioned in the kernel documentation. This patch adds a note in the sysfs documentation about that requirement. Signed-off-by: Bart Van Assche Cc: Andrew Morton Cc: Randy Dunlap Signed-off-by: Greg Kroah-Hartman --- Documentation/filesystems/sysfs.txt | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 597f728e7b4e..07235caec22c 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -4,7 +4,7 @@ sysfs - _The_ filesystem for exporting kernel objects. Patrick Mochel Mike Murphy -Revised: 15 July 2010 +Revised: 16 August 2011 Original: 10 January 2003 @@ -370,3 +370,11 @@ int driver_create_file(struct device_driver *, const struct driver_attribute *); void driver_remove_file(struct device_driver *, const struct driver_attribute *); +Documentation +~~~~~~~~~~~~~ + +The sysfs directory structure and the attributes in each directory define an +ABI between the kernel and user space. As for any ABI, it is important that +this ABI is stable and properly documented. All new sysfs attributes must be +documented in Documentation/ABI. See also Documentation/ABI/README for more +information. -- cgit v1.2.3 From d58cb9cc8a46c9e539cbf8007cd5ede3c09c3524 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Tue, 23 Aug 2011 19:27:27 +0200 Subject: docs/driver-model: Document device.groups Several drivers use device_create_file() where device.groups should be used instead. This patch documents that and also removes the comments about device classes since these should not be used in new code in the way documented until now in Documentation/driver-model/device.txt. Signed-off-by: Bart Van Assche Cc: Randy Dunlap Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-model/device.txt | 65 +++++++++++++++++------------------ 1 file changed, 32 insertions(+), 33 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt index bdefe728a737..1e70220d20f4 100644 --- a/Documentation/driver-model/device.txt +++ b/Documentation/driver-model/device.txt @@ -45,33 +45,52 @@ struct device_attribute { const char *buf, size_t count); }; -Attributes of devices can be exported via drivers using a simple -procfs-like interface. +Attributes of devices can be exported by a device driver through sysfs. Please see Documentation/filesystems/sysfs.txt for more information on how sysfs works. +As explained in Documentation/kobject.txt, device attributes must be be +created before the KOBJ_ADD uevent is generated. The only way to realize +that is by defining an attribute group. + Attributes are declared using a macro called DEVICE_ATTR: #define DEVICE_ATTR(name,mode,show,store) Example: -DEVICE_ATTR(power,0644,show_power,store_power); +static DEVICE_ATTR(type, 0444, show_type, NULL); +static DEVICE_ATTR(power, 0644, show_power, store_power); -This declares a structure of type struct device_attribute named -'dev_attr_power'. This can then be added and removed to the device's -directory using: +This declares two structures of type struct device_attribute with respective +names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be +organized as follows into a group: -int device_create_file(struct device *device, struct device_attribute * entry); -void device_remove_file(struct device * dev, struct device_attribute * attr); +static struct attribute *dev_attrs[] = { + &dev_attr_type.attr, + &dev_attr_power.attr, + NULL, +}; -Example: +static struct attribute_group dev_attr_group = { + .attrs = dev_attrs, +}; + +static const struct attribute_group *dev_attr_groups[] = { + &dev_attr_group, + NULL, +}; + +This array of groups can then be associated with a device by setting the +group pointer in struct device before device_register() is invoked: -device_create_file(dev,&dev_attr_power); -device_remove_file(dev,&dev_attr_power); + dev->groups = dev_attr_groups; + device_register(dev); -The file name will be 'power' with a mode of 0644 (-rw-r--r--). +The device_register() function will use the 'groups' pointer to create the +device attributes and the device_unregister() function will use this pointer +to remove the device attributes. Word of warning: While the kernel allows device_create_file() and device_remove_file() to be called on a device at any time, userspace has @@ -84,24 +103,4 @@ not know about the new attributes. This is important for device driver that need to publish additional attributes for a device at driver probe time. If the device driver simply calls device_create_file() on the device structure passed to it, then -userspace will never be notified of the new attributes. Instead, it should -probably use class_create() and class->dev_attrs to set up a list of -desired attributes in the modules_init function, and then in the .probe() -hook, and then use device_create() to create a new device as a child -of the probed device. The new device will generate a new uevent and -properly advertise the new attributes to userspace. - -For example, if a driver wanted to add the following attributes: -struct device_attribute mydriver_attribs[] = { - __ATTR(port_count, 0444, port_count_show), - __ATTR(serial_number, 0444, serial_number_show), - NULL -}; - -Then in the module init function is would do: - mydriver_class = class_create(THIS_MODULE, "my_attrs"); - mydriver_class.dev_attr = mydriver_attribs; - -And assuming 'dev' is the struct device passed into the probe hook, the driver -probe function would do something like: - device_create(&mydriver_class, dev, chrdev, &private_data, "my_name"); +userspace will never be notified of the new attributes. -- cgit v1.2.3 From b7565fa3a4b84460ce1765cc468700a6bfd82746 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Tue, 23 Aug 2011 19:28:43 +0200 Subject: docs/driver-model: Update device class docs The driver model documentation was added to the kernel tree before struct class was added to . Hence this patch that updates the paragraph about struct class in Documentation/driver-model/binding.txt. Signed-off-by: Bart Van Assche Cc: Randy Dunlap Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-model/binding.txt | 4 ---- 1 file changed, 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.txt index f7ec9d625bfc..abfc8e290d53 100644 --- a/Documentation/driver-model/binding.txt +++ b/Documentation/driver-model/binding.txt @@ -48,10 +48,6 @@ devclass_add_device is called to enumerate the device within the class and actually register it with the class, which happens with the class's register_dev callback. -NOTE: The device class structures and core routines to manipulate them -are not in the mainline kernel, so the discussion is still a bit -speculative. - Driver ~~~~~~ -- cgit v1.2.3 From 220c1ed1bd64b26a2edcd59ca9ff031e1b880727 Mon Sep 17 00:00:00 2001 From: Harry Wei Date: Sat, 24 Sep 2011 15:52:18 +0800 Subject: remove the messy code file Documentation/zh_CN/SubmitChecklist This patch can remove the messy code file Documentation/zh_CN/SumitChecklist. Of course, i will also fix this matter and proofread it again and then submit it again. Signed-off-by: Harry Wei Signed-off-by: Greg Kroah-Hartman --- Documentation/zh_CN/SubmitChecklist | 109 ------------------------------------ 1 file changed, 109 deletions(-) delete mode 100644 Documentation/zh_CN/SubmitChecklist (limited to 'Documentation') diff --git a/Documentation/zh_CN/SubmitChecklist b/Documentation/zh_CN/SubmitChecklist deleted file mode 100644 index 4c741d6bc048..000000000000 --- a/Documentation/zh_CN/SubmitChecklist +++ /dev/null @@ -1,109 +0,0 @@ -Chinese translated version of Documentation/SubmitChecklist - -If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have a problem -communicating in English you can also ask the Chinese maintainer for -help. Contact the Chinese maintainer if this translation is outdated -or if there is a problem with the translation. - -Chinese maintainer: Harry Wei ---------------------------------------------------------------------- -Documentation/SubmitChecklist 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 - -中文版维护者： 贾威威 Harry Wei -中文版翻译者： 贾威威 Harry Wei -中文版校译者： 贾威威 Harry Wei - - -以下为正文 ---------------------------------------------------------------------- -Linux内核提交清单 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -这里有一些内核开发者应该做的基本事情，如果他们想看到自己的内核补丁提交 -被接受的更快。 - -这些都是超出Documentation/SubmittingPatches文档里所提供的以及其他 -关于提交Linux内核补丁的说明。 - -1：如果你使用了一个功能那么就#include定义/声明那个功能的那个文件。 - 不要依靠其他间接引入定义/声明那个功能的头文件。 - -2：构建简洁适用或者更改CONFIG选项 =y，=m，或者=n。 - 不要有编译警告/错误， 不要有链接警告/错误。 - -2b：通过 allnoconfig, allmodconfig - -2c：当使用 0=builddir 成功地构建 - -3：通过使用本地交叉编译工具或者其他一些构建产所，在多CPU框架上构建。 - -4：ppc64 是一个很好的检查交叉编译的框架，因为它往往把‘unsigned long’ - 当64位值来使用。 - -5：按照Documentation/CodingStyle文件里的详细描述，检查你补丁的整体风格。 - 使用补丁风格检查琐碎的违规(scripts/checkpatch.pl)，审核员优先提交。 - 你应该调整遗留在你补丁中的所有违规。 - -6：任何更新或者改动CONFIG选项都不能打乱配置菜单。 - -7：所有的Kconfig选项更新都要有说明文字。 - -8：已经认真地总结了相关的Kconfig组合。这是很难通过测试做好的--脑力在这里下降。 - -9：检查具有简洁性。 - -10：使用'make checkstack'和'make namespacecheck'检查，然后修改所找到的问题。 - 注意：堆栈检查不会明确地出现问题，但是任何的一个函数在堆栈上使用多于512字节 - 都要准备修改。 - -11：包含kernel-doc到全局内核APIs文件。（不要求静态的函数，但是包含也无所谓。） - 使用'make htmldocs'或者'make mandocs'来检查kernel-doc，然后修改任何 - 发现的问题。 - -12：已经通过CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, - CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, - CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP测试，并且同时都 - 使能。 - -13：已经都构建并且使用或者不使用 CONFIG_SMP 和 CONFIG_PREEMPT测试执行时间。 - -14：如果补丁影响IO/Disk，等等：已经通过使用或者不使用 CONFIG_LBDAF 测试。 - -15：所有的codepaths已经行使所有lockdep启用功能。 - -16：所有的/proc记录更新都要作成文件放在Documentation/目录下。 - -17：所有的内核启动参数更新都被记录到Documentation/kernel-parameters.txt文件中。 - -18：所有的模块参数更新都用MODULE_PARM_DESC()记录。 - -19：所有的用户空间接口更新都被记录到Documentation/ABI/。查看Documentation/ABI/README - 可以获得更多的信息。改变用户空间接口的补丁应该被邮件抄送给linux-api@vger.kernel.org。 - -20：检查它是不是都通过`make headers_check'。 - -21：已经通过至少引入slab和page-allocation失败检查。查看Documentation/fault-injection/。 - -22：新加入的源码已经通过`gcc -W'（使用"make EXTRA_CFLAGS=-W"）编译。这样将产生很多烦恼， - 但是对于寻找漏洞很有益处，例如:"warning: comparison between signed and unsigned"。 - -23：当它被合并到-mm补丁集后再测试，用来确定它是否还和补丁队列中的其他补丁一起工作以及在VM，VFS - 和其他子系统中各个变化。 - -24：所有的内存屏障{e.g., barrier(), rmb(), wmb()}需要在源代码中的一个注释来解释他们都是干什么的 - 以及原因。 - -25：如果有任何输入输出控制的补丁被添加，也要更新Documentation/ioctl/ioctl-number.txt。 - -26：如果你的更改代码依靠或者使用任何的内核APIs或者与下面的kconfig符号有关系的功能，你就要 - 使用相关的kconfig符号关闭， and/or =m（如果选项提供）[在同一时间不是所用的都启用，仅仅各个或者自由 - 组合他们]： - - CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, - CONFIG_BLOCK, CONFIG_PM, CONFIG_HOTPLUG, CONFIG_MAGIC_SYSRQ, - CONFIG_NET, CONFIG_INET=n (后一个使用 CONFIG_NET=y) -- cgit v1.2.3 From 27a90700a4275c5178b883b65927affdafa5185c Mon Sep 17 00:00:00 2001 From: Kai Jiang Date: Mon, 17 Oct 2011 20:50:20 +0200 Subject: uio: Support physical addresses >32 bits on 32-bit systems To support >32-bit physical addresses for UIO_MEM_PHYS type we need to extend the width of 'addr' in struct uio_mem. Numerous platforms like embedded PPC, ARM, and X86 have support for systems with larger physical address than logical. Since 'addr' may contain a physical, logical, or virtual address the easiest solution is to just change the type to 'phys_addr_t' which should always be greater than or equal to the sizeof(void *) such that it can properly hold any of the address types. For physical address we can support up to a 44-bit physical address on a typical 32-bit system as we utilize remap_pfn_range() for the mapping of the memory region and pfn's are represnted by shifting the address by the page size (typically 4k). Signed-off-by: Kai Jiang Signed-off-by: Minghuan Lian Signed-off-by: Kumar Gala Signed-off-by: Hans J. Koch Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 2 +- drivers/uio/uio.c | 7 +++---- include/linux/uio_driver.h | 7 +++++-- 3 files changed, 9 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index 7c4b514d62b1..54883de5d5f9 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -529,7 +529,7 @@ memory (e.g. allocated with kmalloc()). There's also -unsigned long addr: Required if the mapping is used. +phys_addr_t addr: Required if the mapping is used. Fill in the address of your memory block. This address is the one that appears in sysfs. diff --git a/drivers/uio/uio.c b/drivers/uio/uio.c index c89f12a8b116..a783d533a1a6 100644 --- a/drivers/uio/uio.c +++ b/drivers/uio/uio.c @@ -69,7 +69,7 @@ static ssize_t map_name_show(struct uio_mem *mem, char *buf) static ssize_t map_addr_show(struct uio_mem *mem, char *buf) { - return sprintf(buf, "0x%lx\n", mem->addr); + return sprintf(buf, "0x%llx\n", (unsigned long long)mem->addr); } static ssize_t map_size_show(struct uio_mem *mem, char *buf) @@ -79,7 +79,7 @@ static ssize_t map_size_show(struct uio_mem *mem, char *buf) static ssize_t map_offset_show(struct uio_mem *mem, char *buf) { - return sprintf(buf, "0x%lx\n", mem->addr & ~PAGE_MASK); + return sprintf(buf, "0x%llx\n", (unsigned long long)mem->addr & ~PAGE_MASK); } struct map_sysfs_entry { @@ -634,8 +634,7 @@ static int uio_vma_fault(struct vm_area_struct *vma, struct vm_fault *vmf) if (idev->info->mem[mi].memtype == UIO_MEM_LOGICAL) page = virt_to_page(idev->info->mem[mi].addr + offset); else - page = vmalloc_to_page((void *)idev->info->mem[mi].addr - + offset); + page = vmalloc_to_page((void *)(unsigned long)idev->info->mem[mi].addr + offset); get_page(page); vmf->page = page; return 0; diff --git a/include/linux/uio_driver.h b/include/linux/uio_driver.h index 665517c05eaf..fd99ff9298c6 100644 --- a/include/linux/uio_driver.h +++ b/include/linux/uio_driver.h @@ -23,7 +23,10 @@ struct uio_map; /** * struct uio_mem - description of a UIO memory region * @name: name of the memory region for identification - * @addr: address of the device's memory + * @addr: address of the device's memory (phys_addr is used since + * addr can be logical, virtual, or physical & phys_addr_t + * should always be large enough to handle any of the + * address types) * @size: size of IO * @memtype: type of memory addr points to * @internal_addr: ioremap-ped version of addr, for driver internal use @@ -31,7 +34,7 @@ struct uio_map; */ struct uio_mem { const char *name; - unsigned long addr; + phys_addr_t addr; unsigned long size; int memtype; void __iomem *internal_addr; -- cgit v1.2.3 From 5fa224295f0e0358c8bc0e5390702338df889def Mon Sep 17 00:00:00 2001 From: Josh Boyer Date: Mon, 17 Oct 2011 21:16:39 -0400 Subject: Update email address for stable patch submission The stable@kernel.org email address has been replaced with the stable@vger.kernel.org mailing list. Change the stable kernel rules to reference the new list instead of the semi-defunct email alias. CC: CC: Signed-off-by: Josh Boyer Signed-off-by: Greg Kroah-Hartman --- Documentation/stable_kernel_rules.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index e213f45cf9d7..21fd05c28e73 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -24,10 +24,10 @@ Rules on what kind of patches are accepted, and which ones are not, into the Procedure for submitting patches to the -stable tree: - Send the patch, after verifying that it follows the above rules, to - stable@kernel.org. You must note the upstream commit ID in the changelog - of your submission. + stable@vger.kernel.org. You must note the upstream commit ID in the + changelog of your submission. - To have the patch automatically included in the stable tree, add the tag - Cc: stable@kernel.org + Cc: stable@vger.kernel.org in the sign-off area. Once the patch is merged it will be applied to the stable tree without anything else needing to be done by the author or subsystem maintainer. @@ -35,10 +35,10 @@ Procedure for submitting patches to the -stable tree: cherry-picked than this can be specified in the following format in the sign-off area: - Cc: # .32.x: a1f84a3: sched: Check for idle - Cc: # .32.x: 1b9508f: sched: Rate-limit newidle - Cc: # .32.x: fd21073: sched: Fix affinity logic - Cc: # .32.x + Cc: # .32.x: a1f84a3: sched: Check for idle + Cc: # .32.x: 1b9508f: sched: Rate-limit newidle + Cc: # .32.x: fd21073: sched: Fix affinity logic + Cc: # .32.x Signed-off-by: Ingo Molnar The tag sequence has the meaning of: -- cgit v1.2.3