Documentation/console/console.txt

Chinese translated version ofDocumentation/console/console.txt

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: 林天智 <lintianzhi1992@gmail.com>

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

Documentation/console/console.txt的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文

交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻

译存在问题，请联系中文版维护者。

中文版维护者： 林天智 <lintianzhi1992@gmail.com>

以下为正文

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

Console Drivers

===============

The linux kernel has 2 general types of console drivers.  The first type is

assigned by the kernel to all the virtual consoles during the boot process.

This type will be called 'system driver', and only one system driver is allowed

to exist. The system driver is persistent and it can never be unloaded, though

it may become inactive.

Linux内核有两种类型的终端驱动。第一种是在启动期间，由内核定义的所有虚拟终端。

这种类型成为“系统驱动”，并且只能存在一个系统驱动。系统驱动是一直存在并且不可以被解除的，虽然它可能会变得无法响应。

The second type has to be explicitly loaded and unloaded. This will be called

'modular driver' by this document. Multiple modular drivers can coexist at

any time with each driver sharing the console with other drivers including

the system driver. However, modular drivers cannot take over the console

that is currently occupied by another modular driver. (Exception: Drivers that

call do_take_over_console() will succeed in the takeover regardless of the type

of driver occupying the consoles.) They can only take over the console that is

occupied by the system driver. In the same token, if the modular driver is

released by the console, the system driver will take over.

第二种类型是必须明确地被装载与卸载的。这个在这份文档里面会被称为“模块驱动”。多个模块驱动可以在任何时间同时存在，有些驱动共享着终端有些驱动包含着系统驱动。然而，模块驱动无法接管那些已经被其他模块驱动占据着的终端。（例外：do_take_over_console() 的时候可以成功返回，除非无视占据着终端的驱动类型）模块驱动只能接管那些被系统驱动占据着的终端。同样的情况下，如果终端被模块驱动被终端释放了，就会被系统驱动接收。

Modular drivers, from the programmer's point of view, has to call:

        do_take_over_console() - load and bind driver to console layer

        give_up_console() - unload driver, it will only work if driver is fully unbond

模块驱动，从编程的角度来看：

do_take_over_console() - 加载以及绑定接驱动到终端层面

give_up_console() - 卸载驱动，只有在驱动完全释放的情况下才会成功

In newer kernels, the following are also available:

        do_register_con_driver()

        do_unregister_con_driver()

在新的内核下，以下的函数也是有效的：

do_register_con_driver()

do_unregister_con_driver()

If sysfs is enabled, the contents of /sys/class/vtconsole can be

examined. This shows the console backends currently registered by the

system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:

      ls /sys/class/vtconsole

      .  ..  vtcon0  vtcon1

如果sysfs是允许的，/sys/class/vtconsole 里的内容会被检验。

他显示了当前注册了终端后端的名叫vton<n>的系统，<n>是一个0到15的整数。因此：

ls /sys/class/vtconsole

. .. vton0 vton1

Each directory in /sys/class/vtconsole has 3 files:

    ls /sys/class/vtconsole/vtcon0

    .  ..  bind  name  uevent

每个在/sys/class/vtconsole里面的目录有三个文件：

ls /sys/class/vtconsole/vtcon0

. .. bind name uevent

What do these files signify?

    1. bind - this is a read/write file. It shows the status of the driver if

       read, or acts to bind or unbind the driver to the virtual consoles

       when written to. The possible values are:

       0 - means the driver is not bound and if echo'ed, commands the driver

           to unbind

       1 - means the driver is bound and if echo'ed, commands the driver to

           bind

    2. name - read-only file. Shows the name of the driver in this format:

       cat /sys/class/vtconsole/vtcon0/name

       (S) VGA+

           '(S)' stands for a (S)ystem driver, ie, it cannot be directly

           commanded to bind or unbind

           'VGA+' is the name of the driver

       cat /sys/class/vtconsole/vtcon1/name

       (M) frame buffer device

           In this case, '(M)' stands for a (M)odular driver, one that can be

           directly commanded to bind or unbind.

    3. uevent - ignore this file

这些文件表示着什么？

1. bind - 这是一个可读可写的文件，读的情况他显示了驱动的状态，写的状态可以控制绑定或者解除驱动的和终端的关系。可能的值：

0 - 意味着驱动没有绑定（读），控制驱动解除绑定（写）

1 - 意味着驱动已经绑定（读），控制驱动绑定（写）

2. name - 只读文件，以这样的格式显示驱动的名字：

cat /sys/class/vtconsole/vtcon0/name

(S) VGA+

'(S)' 表示系统(‘S’ystem)驱动，它不能被直接绑定或者解除

‘VGA’是驱动的名称

cat /sys/class/vtconsole/vtcon1/name

(M) frame buffer device

这里’M’表示模块(‘M’odular)驱动，可以被直接命令绑定或者解除

3. uenent - 忽略这个文件

When unbinding, the modular driver is detached first, and then the system

driver takes over the consoles vacated by the driver. Binding, on the other

hand, will bind the driver to the consoles that are currently occupied by a

system driver.

在解除绑定的时候，模块驱动首先分离然后系统驱动会占据腾空出来的终端。

绑定的时候，会把驱动和被系统驱动占据着的终端绑定起来。

NOTE1: Binding and unbinding must be selected in Kconfig. It's under:

注1：绑定和解绑必须在Kconfig中选择，如下：

Device Drivers -> Character devices -> Support for binding and unbinding

console drivers

设备驱动 -> 字符驱动 -> 支持绑定和节绑的终端驱动

NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or

unbinding will not succeed. An example of an application that sets the console

to KD_GRAPHICS is X.

注2：任何在KD_GRAPHICS模式下的虚拟终端，它的绑定和解绑都不会成功，一个典型的例子是应用把KD_GRAPHICS设置成X。

How useful is this feature? This is very useful for console driver

developers. By unbinding the driver from the console layer, one can unload the

driver, make changes, recompile, reload and rebind the driver without any need

for rebooting the kernel. For regular users who may want to switch from

framebuffer console to VGA console and vice versa, this feature also makes

this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb

for more details).

这些特性是多有用？对终端驱动开发者来说是非常有用的。对于把驱动从终端层解绑，可以在不需要重启内核的情况下上传驱动，做修改，重新编译，重新加载驱动。着让想要帧缓冲终端和VGA终端互相切换的用户实现了梦想！

（注 注 注： 请阅读在Documentation/fb下面的fbcon.txt以获得更详细的资料）

Notes for developers:

=====================

注（为开发者）：

=============

do_take_over_console() is now broken up into:

    do_register_con_driver()

    do_bind_con_driver() - private function

do_take_over_console() 现在被分成两个：

do_register_con_driver()

do_bind_con_driver() - 私有函数

give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must

be fully unbound for this call to succeed. con_is_bound() will check if the

driver is bound or not.

give_up_console() 是 do_unregisiter_con_driver() 的包装，一个驱动必须被完全节绑才能令这个调用成功，con_is_bound() 可以核对这个驱动是否成功节绑。

Guidelines for console driver writers:

=====================================

终端驱动作者的指南：

===============

In order for binding to and unbinding from the console to properly work,

console drivers must follow these guidelines:

为了让绑定和节绑可以正确地工作，终端作者必须遵守以下指南：

1. All drivers, except system drivers, must call either do_register_con_driver()

  or do_take_over_console(). do_register_con_driver() will just add the driver to

  the console's internal list. It won't take over the

  console. do_take_over_console(), as it name implies, will also take over (or

  bind to) the console.

1. 所有的驱动，除了系统驱动，一定要调用do_register_con_driver() 或者 do_take_over_console()，do_regisiter_con_driver() 仅仅会把驱动加入到终端的内部列表，它不会占据这个终端。do_take_over_console()，就像它的名字一样，会占据（或者绑定）这个终端

2. All resources allocated during con->con_init() must be released in

  con->con_deinit().

2. 所有在con->con_init()期间被分配的资源必须在con->con_deinit()中被释放

3. All resources allocated in con->con_startup() must be released when the

  driver, which was previously bound, becomes unbound.  The console layer

  does not have a complementary call to con->con_startup() so it's up to the

  driver to check when it's legal to release these resources. Calling

  con_is_bound() in con->con_deinit() will help.  If the call returned

  false(), then it's safe to release the resources.  This balance has to be

  ensured because con->con_startup() can be called again when a request to

  rebind the driver to the console arrives.

3. 当驱动原先绑定，后来解绑的时候，所有在con->con_startup()中分配的资源必须被释放。终端层没有一个和con-con_startup()互补的函数，所以这需要驱动去判断什么时候释放资源是合法的。通过在con->con_deinit()中调用con_is_bound()来实现，如果调用返回false()，那么释放这些资源就是合法的，必须保持平衡，因为当有请求希望重新绑定驱动和终端时，con->con_startup()可能会被重新调用。

4. Upon exit of the driver, ensure that the driver is totally unbound. If the

  condition is satisfied, then the driver must call do_unregister_con_driver()

  or give_up_console().

4. 驱动退出时，确保驱动完全节绑。如果这个条件成立的话，驱动必须调用do_unregister_con_driver() 或者 give_up_console()

5. do_unregister_con_driver() can also be called on conditions which make it

  impossible for the driver to service console requests.  This can happen

  with the framebuffer console that suddenly lost all of its drivers.

5.在驱动不可能为控制台请求服务的情况下，do_unregister_con_driver()也能被调用。这发生在帧缓冲终端突然丢失了它所有的驱动的情况下。

The current crop of console drivers should still work correctly, but binding

and unbinding them may cause problems. With minimal fixes, these drivers can

be made to work correctly.

当前终端驱动的修改应该继续正确地工作，但是绑定和节绑他们可能会出现问题。一些小的修复可以让他们正确地工作。

==========================

Antonino Daplas <adaplas@pol.net>