Documentation_driver-model_devre

Chinese translated version of Documentation/CodingStyle


If you have any comment or update to the content, please post to LKML directly.
However, if you have problem communicating in English you can also ask the
Chinese maintainer for help. Contact the Chinese maintainer, if this
translation is outdated or there is problem with translation.


Chinese maintainer: mdwang <[e-mail]>
---------------------------------------------------------------------
Documentation/CodingStyle的中文翻译


如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。


中文版维护者： 王明达  <[e-mail]>
中文版翻译者： 王明达 <[e-mail]>
中文版校译者： 王明达 <[e-mail]>
 
 
 
以下为正文
--------------------------------------------------------------------- 


  1. Intro
  --------


  1.介绍
  
devres came up while trying to convert libata to use iomap.  Each
iomapped address should be kept and unmapped on driver detach.  For
example, a plain SFF ATA controller (that is, good old PCI IDE) in
native mode makes use of 5 PCI BARs and all of them should be
maintained.


在试图转换libata使用iomap时出现了devres。应保持每个iomapped地址和映射的驱动
器分离。例如，一个普通的SFF ATA控制器（也就是，良好的旧的PCI IDE）原生模式
利用5 PCI BARs，且这些全都都应该包括进去。


As with many other device drivers, libata low level drivers have
sufficient bugs in ->remove and ->probe failure path.  Well, yes,
that's probably because libata low level driver developers are lazy
bunch, but aren't all low level driver developers?  After spending a
day fiddling with braindamaged hardware with no document or
braindamaged document, if it's finally working, well, it's working.


与许多其他的设备驱动程序一样,libata低电平驱动程序在->remove 和 ->probe有大量
的漏洞和错误路径。嗯,是的，这可能是因为libata低级别驱动程序开发人员是很懒的
一群人,但不是所有的低级别驱动程序开发人员吗?在没有文档或braindamaged文档经过
一个天摆弄braindamaged硬件,如果最后它能运行了,那就运行吧。




For one reason or another, low level drivers don't receive as much
attention or testing as core code, and bugs on driver detach or
initialization failure don't happen often enough to be noticeable.
Init failure path is worse because it's much less travelled while
needs to handle multiple entry points.


对于这样那样的原因，底层驱动没有收到尽可能多的核心代码和错误驱动分
离或关注或测试初始化失败不经常发生，足以引人注目。初始化失败的路径，
因为它是人迹罕至，而更糟糕的是需要处理多个入口点。


So, many low level drivers end up leaking resources on driver detach
and having half broken failure path implementation in ->probe() which
would leak resources or even cause oops when failure occurs.  iomap
adds more to this mix.  So do msi and msix.


所以，许多低级别的驱动程序最终在驱动分离时泄漏资源并在->probe()会有一般的故障
路径出现 会泄漏资源，甚至发生故障。iomap这个组合会出现更多。所以使用msi和MSIX。


  2. Devres
  ---------


devres is basically linked list of arbitrarily sized memory areas
associated with a struct device.  Each devres entry is associated with
a release function.  A devres can be released in several ways.  No
matter what, all devres entries are released on driver detach.  On
release, the associated release function is invoked and then the
devres entry is freed.


 2.Devres


 ------------


devres基本上是链接列表的任意大小的内存区域关联到一个结构体装置。每个
devres条目相关联的一个释放功能。一个devres可以以多种方式发布。没有不
管发生什么,都devres条目发布的驱动程序分离。在释放,释放的相关函数被调
用,然后devres条目被释放。




Managed interface is created for resources commonly used by device
drivers using devres.  For example, coherent DMA memory is acquired
using dma_alloc_coherent().  The managed version is called
dmam_alloc_coherent().  It is identical to dma_alloc_coherent() except
for the DMA memory allocated using it is managed and will be
automatically released on driver detach.  Implementation looks like
the following.


常用的设备资源管理界面创建司机使用devres。例如，获得一致DMA内存使用的
dma_alloc_coherent（）。被称为托管版本dmam_alloc_coherent（）。这是
和dma_alloc_coherent（）是一样的，除非为DMA内存分配管理，并将于自动释
放驱动程序的分离。实现代码如下以下。
  struct dma_devres {
 size_t  size;
 void  *vaddr;
 dma_addr_t dma_handle;
  };


  static void dmam_coherent_release(struct device *dev, void *res)
  {
 struct dma_devres *this = res;


 dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle);
  }


  dmam_alloc_coherent(dev, size, dma_handle, gfp)
  {
 struct dma_devres *dr;
 void *vaddr;


 dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp);
 ...


 /* alloc DMA memory as usual */
 vaddr = dma_alloc_coherent(...);
 ...


 /* record size, vaddr, dma_handle in dr */
 dr->vaddr = vaddr;
 ...


 devres_add(dev, dr);


 return vaddr;
  }


If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
freed whether initialization fails half-way or the device gets
detached.  If most resources are acquired using managed interface, a
driver can have much simpler init and exit code.  Init path basically
looks like the following.


如果一个驱动使用dmam_alloc_coherent，该区域必须保证得到释放无论是否初始
化失败或设备分离。如果大部分资源使用管理接口，一个驱动可以有更简单的初始
化和退出代码。初始化路径基本上和一下类似。


  my_init_one()
  {
 struct mydev *d;


 d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL);
 if (!d)
  return -ENOMEM;


 d->ring = dmam_alloc_coherent(...);
 if (!d->ring)
  return -ENOMEM;


 if (check something)
  return -EINVAL;
 ...


 return register_to_upper_layer(d);
  }


And exit path,


  my_remove_one()
  {
 unregister_from_upper_layer(d);
 shutdown_my_hardware();
  }


As shown above, low level drivers can be simplified a lot by using
devres.  Complexity is shifted from less maintained low level drivers
to better maintained higher layer.  Also, as init failure path is
shared with exit path, both can get more testing.


如上所示，使用devres可以使低级别的驱动程序简化了很多。复杂性可以从少维
护的底层驱动转移到更好地维护的较高的层。另外，作为初始化失败路径是与退
出路径共享，都可以得到更多的测试。




  3. Devres group
  ---------------
  3.Devres组
  
Devres entries can be grouped using devres group.  When a group is
released, all contained normal devres entries and properly nested
groups are released.  One usage is to rollback series of acquired
resources on failure.  For example,


可以使用devres组分组Devres条目。当一组被释放，所有包含正常devres的条目，
并正确地嵌套组被释放。一种用法是回滚系列收购失败的资源。例如，


  if (!devres_open_group(dev, NULL, GFP_KERNEL))
 return -ENOMEM;


  acquire A;
  if (failed)
 goto err;


  acquire B;
  if (failed)
 goto err;
  ...


  devres_remove_group(dev, NULL);
  return 0;


 err:
  devres_release_group(dev, NULL);
  return err_code;


As resource acquisition failure usually means probe failure, constructs
like above are usually useful in midlayer driver (e.g. libata core
layer) where interface function shouldn't have side effect on failure.
For LLDs, just returning error code suffices in most cases.


由于资源获取失败通常意味着探测失败，结构通常是有用在midlayer驱动程
序（例如的libata核心层）它的的接口函数不应该有负面影响。对于LLDS，
在大多数情况下，只需返回错误代码足以。


Each group is identified by void *id.  It can either be explicitly
specified by @id argument to devres_open_group() or automatically
created by passing NULL as @id as in the above example.  In both
cases, devres_open_group() returns the group's id.  The returned id
can be passed to other devres functions to select the target group.
If NULL is given to those functions, the latest open group is
selected.


每个组是由void * ID确定的。它既可以由@ id参数明确指定devres_open_group（）
或自动创建传递NULL@ ID像上面的例子。 在这两种情况下，devres_open_group（）
返回组的ID。返回的ID可以传递给其他devres功能的选择目标群体。如果这些函数返
回NULL，则选择最新组。


For example, you can do something like the following.


例如，你可以做类似下面的东西。


  int my_midlayer_create_something()
  {
 if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL))
  return -ENOMEM;


 ...


 devres_close_group(dev, my_midlayer_create_something);
 return 0;
  }


  void my_midlayer_destroy_something()
  {
 devres_release_group(dev, my_midlayer_create_something);
  }




  4. Details
  ----------


Lifetime of a devres entry begins on devres allocation and finishes
when it is released or destroyed (removed and freed) - no reference
counting.


 4.详细信息
  ----------


一个devres条目的寿命从分配devres开始，结束于当它被释放或销毁（删除并
释放） - 无参考计数。


devres core guarantees atomicity to all basic devres operations and
has support for single-instance devres types (atomic
lookup-and-add-if-not-found).  Other than that, synchronizing
concurrent accesses to allocated devres data is caller's
responsibility.  This is usually non-issue because bus ops and
resource allocations already do the job.


devres核心保证原子性devres所有基本操作和支持单实例devres类型(原子查
找和添加如果没有找到)。除此之外,同步并发访问分配devres数据调用方的
责任。这通常不是问题,因为总线操作和资源分配已经做这项工作。




For an example of single-instance devres type, read pcim_iomap_table()
in lib/devres.c.


对于一个单实例的例子devres类型read pcim_iomap_table()
in lib/devres.c.


All devres interface functions can be called without context if the
right gfp mask is given.


如果给出正确的gfp mask，所有devres接口函数可以被调用在没有上下文的情
况下。




  5. Overhead
  -----------


  5.开销
  
Each devres bookkeeping info is allocated together with requested data
area.  With debug option turned off, bookkeeping info occupies 16
bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded
up to ull alignment).  If singly linked list is used, it can be
reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit).


每个devres簿记信息请求的数据一起被分配区域。调试选项关闭，簿记信息占用16
字节32位机和24字节64位（三分球四舍五入ULL对齐）。如果使用单链表，它可以是
减少到两个指针在32位（8个字节，16字节64位）。


Each devres group occupies 8 pointers.  It can be reduced to 6 if
singly linked list is used.


每个devres组使用8个指针。它可以减少到6如果使用单链表。


Memory space overhead on ahci controller with two ports is between 300
and 400 bytes on 32bit machine after naive conversion (we can
certainly invest a bit more effort into libata core layer).


在32位机上，在转换后有两个端口的AHCI控制器上存储空间开销在300和400字节（我
们可以当然投资的libata核心层的努力多一点）。
 


  6. List of managed interfaces
  -----------------------------


  6.管理接口一览
  
MEM
  devm_kzalloc()
  devm_kfree()


IO region
  devm_request_region()
  devm_request_mem_region()
  devm_release_region()
  devm_release_mem_region()


IRQ
  devm_request_irq()
  devm_free_irq()


DMA
  dmam_alloc_coherent()
  dmam_free_coherent()
  dmam_alloc_noncoherent()
  dmam_free_noncoherent()
  dmam_declare_coherent_memory()
  dmam_pool_create()
  dmam_pool_destroy()


PCI
  pcim_enable_device() : after success, all PCI ops become managed
  pcim_pin_device() : keep PCI device enabled after release


IOMAP
  devm_ioport_map()
  devm_ioport_unmap()
  devm_ioremap()
  devm_ioremap_nocache()
  devm_iounmap()
  devm_ioremap_resource() : checks resource, requests memory region, ioremaps
  devm_request_and_ioremap() : obsoleted by devm_ioremap_resource()
  pcim_iomap()
  pcim_iounmap()
  pcim_iomap_table() : array of mapped addresses indexed by BAR
  pcim_iomap_regions() : do request_region() and iomap() on multiple BARs


REGULATOR
  devm_regulator_get()
  devm_regulator_put()
  devm_regulator_bulk_get()


CLOCK
  devm_clk_get()
  devm_clk_put()


PINCTRL
  devm_pinctrl_get()
  devm_pinctrl_put()


PWM
  devm_pwm_get()
  devm_pwm_put()


PHY
  devm_usb_get_phy()
  devm_usb_put_phy()